tomio 0.1.0__py3-none-any.whl

tomio/__init__.py

@@ -0,0 +1,21 @@
+from . import volume, configfile, labelfile, interp
+
+# backward compatible name
+config = configfile
+
+volread = volume.read
+volwrite = volume.write
+read_volume = volume.read
+write_volume = volume.write
+tovolume = volume.tovolume
+asvolume = volume.asvolume
+resample = volume.resample
+Volume = volume.Volume
+Geometry = volume.Geometry
+
+read_config = configfile.read
+write_config = configfile.write
+
+read_labels = labelfile.read
+write_labels = labelfile.write
+

tomio/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

tomio/cli.py

@@ -0,0 +1,154 @@
+""" command-line interface
+
+    tomio convert IN OUT
+    tomio resample IN OUT (--like REF | --spacing SX SY SZ) [--method METHOD]
+    tomio info IN
+"""
+import sys
+import argparse
+from pathlib import Path
+
+import numpy as np
+
+from . import volume, imagefile
+
+METHODS = ["nearest", "linear", "spline3", "labels", "roi"]
+
+
+class UserError(Exception):
+    """error reported to the user without traceback"""
+
+
+def main(argv=None):
+    """run the command line, return the exit code"""
+    parser = get_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        # --help, or invalid arguments (argparse message already printed)
+        return exc.code
+    try:
+        args.func(args)
+    except (UserError, FileNotFoundError, ValueError, RuntimeError, ImportError, NotImplementedError) as exc:
+        print(f"tomio: error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def get_parser():
+    parser = argparse.ArgumentParser(prog="tomio", description="Convert, resample and inspect medical image volumes.")
+    commands = parser.add_subparsers(title="commands", required=True, metavar="COMMAND")
+
+    # convert
+    convert = commands.add_parser("convert", help="convert an image file to another format", description=(
+        "Convert an image file to another format (from the file extensions, e.g. .mha, .nii.gz, .nrrd). "
+        "Pixel data, geometry, metadata, vector and complex pixels are kept."))
+    convert.add_argument("input", help="input image file")
+    convert.add_argument("output", help="output image file")
+    add_output_options(convert)
+    convert.set_defaults(func=run_convert)
+
+    # resample
+    resample = commands.add_parser("resample", help="resample a volume to a new geometry", description=(
+        "Resample a volume to the geometry of another volume, or to a new spacing (same extent)."))
+    resample.add_argument("input", help="input image file")
+    resample.add_argument("output", help="output image file")
+    target = resample.add_mutually_exclusive_group(required=True)
+    target.add_argument("--like", metavar="REF", help="reference image file: use its geometry (header only)")
+    target.add_argument("--spacing", metavar=("SX", "SY", "SZ"), nargs=3, type=float, help="new spacing")
+    resample.add_argument("--method", choices=METHODS, help=(
+        "interpolation method; default: nearest for integer data, spline3 otherwise; "
+        "labels: label maps, label by label; roi: masks/ROIs"))
+    resample.add_argument("--fill", type=float, default=0.0, help="value outside the input volume (default: 0, may be nan)")
+    add_output_options(resample)
+    resample.set_defaults(func=run_resample)
+
+    # info
+    info = commands.add_parser("info", help="print the header of an image file", description=(
+        "Print shape, pixel type and geometry of an image file (the pixel data is not read)."))
+    info.add_argument("input", help="input image file")
+    info.add_argument("--metadata", action="store_true", help="also print the metadata")
+    info.set_defaults(func=run_info)
+    return parser
+
+
+def add_output_options(parser):
+    parser.add_argument("--dtype", help="cast the output pixel values (numpy dtype, e.g. float32, uint8)")
+    parser.add_argument("--compression-level", type=int, metavar="N", help="compression level (e.g. 1-9 for .nii.gz)")
+    parser.add_argument("-f", "--force", action="store_true", help="overwrite the output file if it exists")
+
+
+# commands
+
+def run_convert(args):
+    check_files(args)
+    imagefile.convert_image(args.input, args.output, dtype=get_dtype(args.dtype), compression_level=args.compression_level)
+
+
+def run_resample(args):
+    check_files(args)
+    # complex data: 2-component vector image (as written by tomio)
+    as_complex = imagefile.read_info(args.input)["components"] == 2
+    vol = volume.read(args.input, as_complex=as_complex)
+    if args.like is not None:
+        check_input(args.like)
+        header = volume.read_header(args.like)
+        target = dict(like=volume.Geometry(shape=header["shape"][:3], spacing=header["spacing"], origin=header["origin"], transform=header["transform"]))
+    else:
+        target = dict(spacing=args.spacing)
+    kwargs = {} if args.method in ("labels", "roi") else dict(fill=args.fill)
+    out = volume.resample(vol, method=args.method, **target, **kwargs)
+    dtype = get_dtype(args.dtype)
+    if dtype is not None:
+        out = out.astype(dtype)
+    volume.write(args.output, out, compression_level=args.compression_level)
+
+
+def run_info(args):
+    check_input(args.input)
+    header = volume.read_header(args.input)
+    info = imagefile.read_info(args.input)
+    geometry = volume.Geometry(shape=header["shape"][:3], spacing=header["spacing"], origin=header["origin"], transform=header["transform"])
+    lines = [
+        ("file", args.input),
+        ("shape", " x ".join(str(n) for n in header["shape"])),
+        ("pixel type", info["pixel_type"]),
+        ("spacing", format_values(geometry.spacing)),
+        ("origin", format_values(geometry.origin)),
+        ("orientation", f'{volume.get_orientation(geometry)} ("from" convention), {volume.get_orientation(geometry, convention="to")} ("to" convention)'),
+        ("directions", "; ".join(format_values(vec) for vec in geometry.transform)),
+        ("extent", format_values(geometry.extent)),
+        ("metadata", f"{len(header['metadata'])} keys"),
+    ]
+    width = max(len(name) for name, _ in lines)
+    for name, value in lines:
+        print(f"{name:<{width}}  {value}")
+    if args.metadata:
+        for key, value in sorted(header["metadata"].items()):
+            print(f"  {key} = {value}")
+
+
+# utilities
+
+def check_input(filename):
+    if not Path(filename).is_file():
+        raise UserError(f"input file not found: {filename}")
+
+
+def check_files(args):
+    check_input(args.input)
+    if Path(args.output).exists() and not args.force:
+        raise UserError(f"output file exists (use --force to overwrite): {args.output}")
+
+
+def get_dtype(name):
+    if name is None:
+        return None
+    try:
+        return np.dtype(name)
+    except TypeError:
+        raise UserError(f"invalid dtype: {name}") from None
+
+
+def format_values(values):
+    return "(" + ", ".join(f"{v:.6g}" for v in values) + ")"

tomio/configfile.py

@@ -0,0 +1,138 @@
+# coding=utf-8
+""" config file i/o (JSON, YAML; TOML: read only) """
+import re
+import json
+import math
+import numbers
+import yaml
+from collections import abc
+from pathlib import Path
+import numpy as np
+
+
+KINDS = {"json": "json", "yaml": "yaml", "yml": "yaml", "toml": "toml"}
+
+
+def get_kind(path):
+    """config file type ("json", "yaml" or "toml") from path suffix"""
+    ext = path.suffix[1:].lower()
+    if ext not in KINDS:
+        raise ValueError(f"Unknown config file type: {path}")
+    return KINDS[ext]
+
+
+def read(path):
+    """read config file (.json, .yaml, .yml or .toml; no suffix: .json)"""
+    path = Path(path)
+    if not path.suffix:
+        path = path.with_suffix(".json")
+    kind = get_kind(path)
+
+    if kind == "toml":
+        tomllib = import_tomllib()
+        with open(path, "rb") as fp:
+            return untame(tomllib.load(fp))
+
+    with open(path, "r", encoding="utf-8") as fp:
+        if kind == "json":
+            return untame(json.load(fp))
+        else:
+            # safe: no Python-specific tags
+            return untame(yaml.safe_load(fp))
+
+
+def import_tomllib():
+    """TOML parser: tomllib (Python >= 3.11), or tomli (same API)"""
+    try:
+        import tomllib
+    except ImportError:
+        try:
+            import tomli as tomllib
+        except ImportError:
+            raise ImportError("Reading TOML files requires Python >= 3.11, or `tomli` (pip install tomli)") from None
+    return tomllib
+
+
+def write(path, config, kind="json"):
+    """write config file
+
+    The file type is set by the path suffix (.json, .yaml or .yml; .toml is read-only).
+    If the path has no suffix, `kind` is used and added as suffix.
+    """
+    path = Path(path)
+    if not path.suffix:
+        path = path.with_suffix(f".{kind}")
+    kind = get_kind(path)
+    if kind == "toml":
+        raise ValueError(f"Writing TOML files is not supported (read-only): {path}")
+    config = tame(config)
+
+    with open(path, "w", encoding="utf-8") as fp:
+        if kind == "json":
+            json.dump(config, fp)
+        else:
+            yaml.safe_dump(config, fp, default_flow_style=False)
+
+
+def tame(element):
+    """convert config elements to standard types
+
+    dict, list, str, None, bool, int, float
+    numpy arrays become lists, complex numbers become strings: "3 + 4i"
+    """
+    if element is None or isinstance(element, str):
+        return element
+    elif isinstance(element, (bool, np.bool_)):  # before int: bool is an int
+        return bool(element)
+    elif isinstance(element, numbers.Integral):
+        return int(element)
+    elif isinstance(element, numbers.Real):
+        return float(element)
+    elif isinstance(element, numbers.Complex):
+        return format_complex(element)
+    elif isinstance(element, np.ndarray):
+        # tolist: nested lists, or a scalar for 0-d arrays
+        return tame(element.tolist())
+    elif isinstance(element, abc.Mapping):
+        return {tame(key): tame(value) for key, value in element.items()}
+    elif isinstance(element, abc.Sequence):
+        return [tame(item) for item in element]
+    else:
+        return str(element)
+
+
+def untame(element):
+    """reverse of tame: convert complex number strings ("3 + 4i") to complex"""
+    if isinstance(element, str):
+        return parse_complex(element, default=element)
+    elif isinstance(element, dict):
+        return {key: untame(value) for key, value in element.items()}
+    elif isinstance(element, list):
+        return [untame(item) for item in element]
+    return element
+
+
+# complex numbers
+
+_NUMBER = r"(?:(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?|inf|nan)"
+_RE_COMPLEX = re.compile(rf"^\s*([-+]?{_NUMBER})\s*([-+])\s*({_NUMBER})i\s*$")
+
+
+def format_complex(value):
+    """format complex number as "3 + 4i" """
+    value = complex(value)
+
+    def fmt(x):
+        return str(int(x)) if x.is_integer() else repr(x)
+
+    sign = "-" if math.copysign(1, value.imag) < 0 else "+"
+    return f"{fmt(value.real)} {sign} {fmt(abs(value.imag))}i"
+
+
+def parse_complex(string, default=None):
+    """parse complex number formatted as "3 + 4i" (return `default` if not one)"""
+    match = _RE_COMPLEX.match(string)
+    if not match:
+        return default
+    real, sign, imag = match.groups()
+    return complex(float(real), float(sign + imag))

tomio/imagefile.py

@@ -0,0 +1,141 @@
+""" image file i/o with SimpleITK
+
+arrays are in ITK index order (x, y, z, ...); vector images have the components in the last axis
+"""
+import SimpleITK as sitk
+import numpy as np
+
+
+def write_image(filename, array, *, use_compression=True, compression_level=None, **kwargs):
+    """write array (x, y, z, ...) to image file
+
+    kwargs: spacing, origin, transform, metadata, is_vector (see `to_image`)
+    compression_level: if set (format-dependent, e.g. 1-9 for gzip), implies use_compression
+    """
+    im = to_image(array, **kwargs)
+    if compression_level is None:
+        sitk.WriteImage(im, str(filename), useCompression=use_compression)
+    else:
+        sitk.WriteImage(im, str(filename), useCompression=True, compressionLevel=compression_level)
+
+
+def to_image(array, *, spacing=None, origin=None, transform=None, metadata=None, is_vector=False):
+    """convert array (x, y, z, ...) to sitk Image
+
+    is_vector: the last axis of `array` contains the components of a vector image
+    spacing, origin, transform: 3d geometry (identity for the extra dimensions)
+    """
+    array = np.asarray(array)
+    if np.issubdtype(array.dtype, np.bool_):
+        array = array.astype('uint8')
+    if is_vector:
+        # numpy order: reversed image axes, then components
+        n = array.ndim - 1
+        im = sitk.GetImageFromArray(np.transpose(array, (*reversed(range(n)), n)), isVector=True)
+    else:
+        # isVector=False: otherwise SimpleITK may guess a vector image from the shape
+        im = sitk.GetImageFromArray(array.T, isVector=False)
+    ndim = im.GetDimension()
+    if spacing is not None:
+        im.SetSpacing(pad(spacing, ndim, 1))
+    if origin is not None:
+        im.SetOrigin(pad(origin, ndim, 0))
+    if transform is not None:
+        # transform: columns of the direction matrix D
+        direction = np.eye(max(ndim, 3))
+        direction[:3, :3] = np.asarray(transform).reshape(3, 3).T
+        im.SetDirection(direction[:ndim, :ndim].ravel())
+    if metadata is not None:
+        for key, value in metadata.items():
+            im.SetMetaData(str(key), str(value))
+    return im
+
+
+def read_image(filename):
+    """read image file, return array (x, y, z, ...) and header (3d geometry and metadata)
+
+    vector images: components are in the last axis
+    """
+    return from_image(sitk.ReadImage(str(filename)))
+
+
+def from_image(im):
+    """convert sitk Image to array (x, y, z, ...) and header (3d geometry and metadata)
+
+    vector images: components are in the last axis
+    """
+    ndim = im.GetDimension()
+
+    array = sitk.GetArrayFromImage(im)
+    if array.ndim > ndim:
+        # vector image: (reversed image axes, components)
+        array = np.transpose(array, (*reversed(range(ndim)), ndim))
+    else:
+        array = array.T
+
+    return array, get_header(im)
+
+
+def read_header(filename):
+    """read image file header only (no pixel data)
+
+    returns: shape (x, y, z, ..., [components]), 3d geometry and metadata
+    """
+    reader = sitk.ImageFileReader()
+    reader.SetFileName(str(filename))
+    reader.ReadImageInformation()
+
+    shape = tuple(reader.GetSize())
+    if reader.GetNumberOfComponents() > 1:
+        shape += (reader.GetNumberOfComponents(),)
+    return dict(shape=shape, **get_header(reader))
+
+
+def convert_image(source, target, *, dtype=None, use_compression=True, compression_level=None):
+    """convert image file to another format (from the file extensions)
+
+    pixel data, geometry, metadata, vector and complex pixels are kept
+    dtype: cast pixel values (numpy dtype)
+    """
+    im = sitk.ReadImage(str(source))
+    if dtype is not None:
+        array = sitk.GetArrayFromImage(im).astype(dtype)
+        is_vector = im.GetNumberOfComponentsPerPixel() > 1 and array.ndim > im.GetDimension()
+        cast = sitk.GetImageFromArray(array, isVector=is_vector)
+        cast.CopyInformation(im)
+        for key in im.GetMetaDataKeys():
+            cast.SetMetaData(key, im.GetMetaData(key))
+        im = cast
+    if compression_level is None:
+        sitk.WriteImage(im, str(target), useCompression=use_compression)
+    else:
+        sitk.WriteImage(im, str(target), useCompression=True, compressionLevel=compression_level)
+
+
+def read_info(filename):
+    """pixel type (e.g. "32-bit float"), number of components and image dimension (header only)"""
+    reader = sitk.ImageFileReader()
+    reader.SetFileName(str(filename))
+    reader.ReadImageInformation()
+    return dict(
+        pixel_type=sitk.GetPixelIDValueAsString(reader.GetPixelID()),
+        components=reader.GetNumberOfComponents(),
+        dimension=reader.GetDimension(),
+    )
+
+
+def get_header(src):
+    """3d geometry and metadata of a sitk Image or ImageFileReader"""
+    ndim = src.GetDimension()
+    spacing = src.GetSpacing()[:3]
+    origin = src.GetOrigin()[:3]
+    # GetDirection: direction matrix D, row-major; transform: columns of D
+    transform = np.reshape(src.GetDirection(), (ndim, ndim))[:3, :3].T
+    metadata = {key: src.GetMetaData(key) for key in src.GetMetaDataKeys()}
+    return dict(spacing=spacing, origin=origin, transform=transform, metadata=metadata)
+
+
+def pad(values, ndim, fill):
+    """pad 3d values for images with more than 3 dimensions"""
+    values = list(values)
+    return values + [fill] * (ndim - len(values))