tomio 0.1.0__tar.gz

tomio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pierre-Yves Baudin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tomio-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: tomio
+Version: 0.1.0
+Summary: I/O utilities for medical images: image volumes with geometry, interpolation, label and config files
+Author: Pierre-Yves Baudin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/py-baudin/tomio
+Project-URL: Repository, https://github.com/py-baudin/tomio
+Project-URL: Issues, https://github.com/py-baudin/tomio/issues
+Keywords: medical imaging,nifti,itk,simpleitk,volume,interpolation,itk-snap,labels
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyyaml
+Requires-Dist: SimpleITK
+Provides-Extra: interp
+Requires-Dist: scipy; extra == "interp"
+Provides-Extra: nibabel
+Requires-Dist: nibabel; extra == "nibabel"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: scipy; extra == "test"
+Requires-Dist: nibabel; extra == "test"
+Dynamic: license-file
+
+# tomio
+
+I/O utilities for medical images: image volumes (thin wrapper over SimpleITK), interpolation, label files (ITK-SNAP, FreeSurfer, 3D Slicer) and config files (JSON, YAML, TOML).
+
+## Installation
+
+```bash
+pip install tomio
+pip install tomio[interp]   # optional: scipy interpolation backend
+pip install tomio[nibabel]  # optional: conversion to/from nibabel images
+```
+
+Requires Python >= 3.10. Reading TOML files on Python 3.10 requires `tomli`.
+
+## Conventions
+
+- Arrays are indexed `(x, y, z, ...)`, in ITK index order (not the `(z, y, x)` order of `sitk.GetArrayFromImage`).
+- World coordinates are LPS (ITK, DICOM). Conversion to nibabel (RAS) is done by `to_nibabel`/`from_nibabel`.
+- `vol.transform` is a tuple of axis directions: `transform[i]` is the world direction of array axis `i`, i.e. column `i` of the ITK direction matrix.
+- Orientation codes use the ITK "from" convention by default (identity: `RAI`); the "to" convention (identity: `LPS`) is available with `convention="to"`.
+
+## Volumes
+
+```python
+import numpy as np
+from tomio import volume
+
+# read / write (formats: .nii, .nii.gz, .mha, .mhd, .nrrd...)
+vol = volume.read("vol.nii.gz")
+volume.write("vol2.mha", vol)
+
+# options
+vol = volume.read("vol.nii.gz", dtype=np.float32)  # cast
+vol = volume.read("complex.mha", as_complex=True)  # complex volume (written by volume.write)
+volume.write("vol2.nii.gz", vol, compression_level=9)
+header = volume.read_header("vol.nii.gz")  # shape, spacing, origin, transform, metadata (no pixel data)
+
+# Volume is a numpy ndarray
+isinstance(vol, np.ndarray)  # True
+vol.A  # plain np.ndarray
+
+# header
+vol.spacing  # (sx, sy, sz)
+vol.origin  # world coordinates of voxel (0, 0, 0)
+vol.transform  # axis directions
+vol.metadata  # dict[str, str], written to the file
+vol.header  # dict of spacing, origin, transform and metadata
+vol.affine  # 4x4 affine transform (indices -> LPS coordinates)
+
+# world coordinates <-> indices
+coords = vol.get_coords([1, 2, 3])
+indices = vol.get_indices(coords)
+
+# create volumes
+vol2 = volume.Volume(np.zeros((10, 20, 30)), spacing=(1, 1, 2), origin=(0, 0, 0))
+vol2 = volume.asvolume(array, ref=vol)  # copy the header of `vol`
+vol2 = volume.tovolume(values, mask=mask, ref=vol)  # fill the voxels of a mask
+```
+
+Volumes with more than 3 dimensions (e.g. time series `(x, y, z, t)`) and complex volumes can be read and written; the geometry applies to the first 3 axes.
+
+### Geometry
+
+```python
+geom = vol.geometry  # volume.Geometry: shape, spacing, origin, transform (immutable)
+geom.affine, geom.extent, geom.center, geom.voxel_volume
+geom.same_as(other_vol, tol=1e-4)
+vol2 = volume.Volume(array, geometry=geom)
+```
+
+### Slicing and numpy operations
+
+The geometry follows numpy operations when it makes sense:
+
+```python
+vol[2:].origin  # world coordinates of the first voxel of the slice
+vol[::2].spacing  # spacing x 2 in the first axis
+vol[::-1]  # axis direction flipped (also np.flip)
+vol.T, np.moveaxis(vol, 0, -1)  # spacing and directions permuted
+vol + 1, np.sqrt(vol)  # same geometry
+
+# no geometry: plain np.ndarray
+vol[0], vol[mask], vol.sum(axis=0), vol.mean()
+# time series: geometry kept
+vol4d[..., 0], vol4d.mean(axis=3)
+```
+
+### Orientation
+
+```python
+vol.anatomical_orientation  # e.g. "RAI" (ITK "from" convention)
+vol.get_orientation(convention="to")  # e.g. "LPS"
+vol2 = vol.reorient("RAS", convention="to")  # flip/permute the axes
+```
+
+### Interoperability
+
+```python
+image = vol.to_sitk()  # SimpleITK Image
+vol = volume.Volume.from_sitk(image)
+nifti = vol.to_nibabel()  # nibabel Nifti1Image (requires nibabel)
+vol = volume.Volume.from_nibabel(nifti)
+```
+
+## Interpolation
+
+```python
+import numpy as np
+from tomio import volume
+
+vol2 = volume.resample(vol, like=ref)  # geometry of another volume (or a Geometry)
+vol2 = volume.resample(vol, spacing=(1, 1, 1))  # new spacing, same extent
+vol2 = volume.resample(vol, geometry={"spacing": (1, 1, 1), "shape": (64, 64, 64)})
+vol2 = volume.resample(vol, like=ref, method="linear", fill=np.nan)  # value outside `vol`
+
+# label maps and masks
+labels2 = volume.resample(labelmap, like=ref, method="labels")  # label by label (smooth boundaries)
+roi2 = volume.resample(roi, like=ref, method="roi")  # no label lost when downsampling
+```
+
+- Methods: `nearest`, `linear`, `spline3` (and `splineN`), `labels`, `roi`. Default: `nearest` for integer and bool data (label maps), `spline3` otherwise. The output has the dtype of the input.
+- Backends: SimpleITK (default, multithreaded) or scipy (`backend="scipy"`, requires `tomio[interp]`). SimpleITK considers voxels inside the source up to half a voxel beyond the border voxel centers.
+- Lower-level functions: `interp.interpolate`, `interpolate_like`, `interpolate_to`, `interpolate_roi`, `interpolate_labels`.
+
+## Label files
+
+```python
+from tomio import labelfile
+
+labels = labelfile.read("labels.txt")  # ITK-SNAP label description file
+labels = labelfile.read("FreeSurferColorLUT.txt", format="freesurfer")
+labels = labelfile.read("labels.ctbl", format="slicer")  # 3D Slicer color table
+labelfile.write("labels.txt", labels)  # or labels.save("labels.txt"), ITK-SNAP format
+
+# Labels: mapping {index: description}, sorted by index
+labels = labelfile.Labels({1: "white matter", 2: "grey matter"})  # automatic colors
+labels = labelfile.Labels({1: {"LABEL": "white matter", "RGBA": (255, 255, 255, 1.0)}})
+labels = labelfile.Labels(["background", "white matter"])  # indices 0, 1
+
+labels[1]  # description
+labels[3] = "csf"  # add or rename (keeps the color)
+del labels[3]
+labels.getindex("grey matter")  # index of a description
+labels.indices, labels.descriptions  # lists, sorted by index (can be assigned)
+labels.colors  # {index: (R, G, B, A)}, RGB in 0..255, alpha in 0..1 (can be assigned)
+
+# label maps
+labels = labelfile.Labels.from_volume(labelmap)  # one label per value
+rgba = labels.lut[labelmap]  # RGBA image (uint8)
+labels2, mapping = labels.reindex()  # indices 1..N
+labelmap2 = labelfile.apply_mapping(labelmap, mapping)
+```
+
+Labels are validated: non-negative integer indices, unique descriptions without `"` or line breaks (`allow_duplicates=True` to allow duplicates), RGB in 0..255, alpha in 0..1. Label files are UTF-8.
+
+## Config files
+
+```python
+from tomio import configfile
+
+cfg = configfile.read("config.yml")  # .json, .yaml, .yml, .toml -> dict
+configfile.write("config.yml", cfg)  # .json, .yaml, .yml
+```
+
+- The format is set by the file extension (no extension: `.json`). TOML files are read-only.
+- Values are written as standard types: numpy arrays as lists, numpy scalars as numbers, complex numbers as strings `"3 + 4i"` (read back as complex numbers).
+- YAML files are loaded safely (no Python-specific tags).
+
+## Command line
+
+```bash
+tomio convert vol.mha vol.nii.gz                        # convert (format from the extensions)
+tomio convert vol.mha vol.nii.gz --dtype float32 --compression-level 9
+tomio resample vol.nii.gz out.nii.gz --spacing 1 1 1    # new spacing
+tomio resample labels.nii.gz out.nii.gz --like ref.nii.gz --method labels
+tomio info vol.nii.gz --metadata                        # header: shape, pixel type, geometry
+```
+
+Existing output files are not overwritten unless `--force` is given. See `tomio COMMAND --help`.

tomio-0.1.0/README.md

@@ -0,0 +1,179 @@
+# tomio
+
+I/O utilities for medical images: image volumes (thin wrapper over SimpleITK), interpolation, label files (ITK-SNAP, FreeSurfer, 3D Slicer) and config files (JSON, YAML, TOML).
+
+## Installation
+
+```bash
+pip install tomio
+pip install tomio[interp]   # optional: scipy interpolation backend
+pip install tomio[nibabel]  # optional: conversion to/from nibabel images
+```
+
+Requires Python >= 3.10. Reading TOML files on Python 3.10 requires `tomli`.
+
+## Conventions
+
+- Arrays are indexed `(x, y, z, ...)`, in ITK index order (not the `(z, y, x)` order of `sitk.GetArrayFromImage`).
+- World coordinates are LPS (ITK, DICOM). Conversion to nibabel (RAS) is done by `to_nibabel`/`from_nibabel`.
+- `vol.transform` is a tuple of axis directions: `transform[i]` is the world direction of array axis `i`, i.e. column `i` of the ITK direction matrix.
+- Orientation codes use the ITK "from" convention by default (identity: `RAI`); the "to" convention (identity: `LPS`) is available with `convention="to"`.
+
+## Volumes
+
+```python
+import numpy as np
+from tomio import volume
+
+# read / write (formats: .nii, .nii.gz, .mha, .mhd, .nrrd...)
+vol = volume.read("vol.nii.gz")
+volume.write("vol2.mha", vol)
+
+# options
+vol = volume.read("vol.nii.gz", dtype=np.float32)  # cast
+vol = volume.read("complex.mha", as_complex=True)  # complex volume (written by volume.write)
+volume.write("vol2.nii.gz", vol, compression_level=9)
+header = volume.read_header("vol.nii.gz")  # shape, spacing, origin, transform, metadata (no pixel data)
+
+# Volume is a numpy ndarray
+isinstance(vol, np.ndarray)  # True
+vol.A  # plain np.ndarray
+
+# header
+vol.spacing  # (sx, sy, sz)
+vol.origin  # world coordinates of voxel (0, 0, 0)
+vol.transform  # axis directions
+vol.metadata  # dict[str, str], written to the file
+vol.header  # dict of spacing, origin, transform and metadata
+vol.affine  # 4x4 affine transform (indices -> LPS coordinates)
+
+# world coordinates <-> indices
+coords = vol.get_coords([1, 2, 3])
+indices = vol.get_indices(coords)
+
+# create volumes
+vol2 = volume.Volume(np.zeros((10, 20, 30)), spacing=(1, 1, 2), origin=(0, 0, 0))
+vol2 = volume.asvolume(array, ref=vol)  # copy the header of `vol`
+vol2 = volume.tovolume(values, mask=mask, ref=vol)  # fill the voxels of a mask
+```
+
+Volumes with more than 3 dimensions (e.g. time series `(x, y, z, t)`) and complex volumes can be read and written; the geometry applies to the first 3 axes.
+
+### Geometry
+
+```python
+geom = vol.geometry  # volume.Geometry: shape, spacing, origin, transform (immutable)
+geom.affine, geom.extent, geom.center, geom.voxel_volume
+geom.same_as(other_vol, tol=1e-4)
+vol2 = volume.Volume(array, geometry=geom)
+```
+
+### Slicing and numpy operations
+
+The geometry follows numpy operations when it makes sense:
+
+```python
+vol[2:].origin  # world coordinates of the first voxel of the slice
+vol[::2].spacing  # spacing x 2 in the first axis
+vol[::-1]  # axis direction flipped (also np.flip)
+vol.T, np.moveaxis(vol, 0, -1)  # spacing and directions permuted
+vol + 1, np.sqrt(vol)  # same geometry
+
+# no geometry: plain np.ndarray
+vol[0], vol[mask], vol.sum(axis=0), vol.mean()
+# time series: geometry kept
+vol4d[..., 0], vol4d.mean(axis=3)
+```
+
+### Orientation
+
+```python
+vol.anatomical_orientation  # e.g. "RAI" (ITK "from" convention)
+vol.get_orientation(convention="to")  # e.g. "LPS"
+vol2 = vol.reorient("RAS", convention="to")  # flip/permute the axes
+```
+
+### Interoperability
+
+```python
+image = vol.to_sitk()  # SimpleITK Image
+vol = volume.Volume.from_sitk(image)
+nifti = vol.to_nibabel()  # nibabel Nifti1Image (requires nibabel)
+vol = volume.Volume.from_nibabel(nifti)
+```
+
+## Interpolation
+
+```python
+import numpy as np
+from tomio import volume
+
+vol2 = volume.resample(vol, like=ref)  # geometry of another volume (or a Geometry)
+vol2 = volume.resample(vol, spacing=(1, 1, 1))  # new spacing, same extent
+vol2 = volume.resample(vol, geometry={"spacing": (1, 1, 1), "shape": (64, 64, 64)})
+vol2 = volume.resample(vol, like=ref, method="linear", fill=np.nan)  # value outside `vol`
+
+# label maps and masks
+labels2 = volume.resample(labelmap, like=ref, method="labels")  # label by label (smooth boundaries)
+roi2 = volume.resample(roi, like=ref, method="roi")  # no label lost when downsampling
+```
+
+- Methods: `nearest`, `linear`, `spline3` (and `splineN`), `labels`, `roi`. Default: `nearest` for integer and bool data (label maps), `spline3` otherwise. The output has the dtype of the input.
+- Backends: SimpleITK (default, multithreaded) or scipy (`backend="scipy"`, requires `tomio[interp]`). SimpleITK considers voxels inside the source up to half a voxel beyond the border voxel centers.
+- Lower-level functions: `interp.interpolate`, `interpolate_like`, `interpolate_to`, `interpolate_roi`, `interpolate_labels`.
+
+## Label files
+
+```python
+from tomio import labelfile
+
+labels = labelfile.read("labels.txt")  # ITK-SNAP label description file
+labels = labelfile.read("FreeSurferColorLUT.txt", format="freesurfer")
+labels = labelfile.read("labels.ctbl", format="slicer")  # 3D Slicer color table
+labelfile.write("labels.txt", labels)  # or labels.save("labels.txt"), ITK-SNAP format
+
+# Labels: mapping {index: description}, sorted by index
+labels = labelfile.Labels({1: "white matter", 2: "grey matter"})  # automatic colors
+labels = labelfile.Labels({1: {"LABEL": "white matter", "RGBA": (255, 255, 255, 1.0)}})
+labels = labelfile.Labels(["background", "white matter"])  # indices 0, 1
+
+labels[1]  # description
+labels[3] = "csf"  # add or rename (keeps the color)
+del labels[3]
+labels.getindex("grey matter")  # index of a description
+labels.indices, labels.descriptions  # lists, sorted by index (can be assigned)
+labels.colors  # {index: (R, G, B, A)}, RGB in 0..255, alpha in 0..1 (can be assigned)
+
+# label maps
+labels = labelfile.Labels.from_volume(labelmap)  # one label per value
+rgba = labels.lut[labelmap]  # RGBA image (uint8)
+labels2, mapping = labels.reindex()  # indices 1..N
+labelmap2 = labelfile.apply_mapping(labelmap, mapping)
+```
+
+Labels are validated: non-negative integer indices, unique descriptions without `"` or line breaks (`allow_duplicates=True` to allow duplicates), RGB in 0..255, alpha in 0..1. Label files are UTF-8.
+
+## Config files
+
+```python
+from tomio import configfile
+
+cfg = configfile.read("config.yml")  # .json, .yaml, .yml, .toml -> dict
+configfile.write("config.yml", cfg)  # .json, .yaml, .yml
+```
+
+- The format is set by the file extension (no extension: `.json`). TOML files are read-only.
+- Values are written as standard types: numpy arrays as lists, numpy scalars as numbers, complex numbers as strings `"3 + 4i"` (read back as complex numbers).
+- YAML files are loaded safely (no Python-specific tags).
+
+## Command line
+
+```bash
+tomio convert vol.mha vol.nii.gz                        # convert (format from the extensions)
+tomio convert vol.mha vol.nii.gz --dtype float32 --compression-level 9
+tomio resample vol.nii.gz out.nii.gz --spacing 1 1 1    # new spacing
+tomio resample labels.nii.gz out.nii.gz --like ref.nii.gz --method labels
+tomio info vol.nii.gz --metadata                        # header: shape, pixel type, geometry
+```
+
+Existing output files are not overwritten unless `--force` is given. See `tomio COMMAND --help`.

tomio-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tomio"
+version = "0.1.0"
+description = "I/O utilities for medical images: image volumes with geometry, interpolation, label and config files"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Pierre-Yves Baudin" }]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=1.24",
+    "pyyaml",
+    "SimpleITK",
+]
+keywords = ["medical imaging", "nifti", "itk", "simpleitk", "volume", "interpolation", "itk-snap", "labels"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+
+[project.optional-dependencies]
+interp = ["scipy"]
+nibabel = ["nibabel"]
+test = ["pytest", "scipy", "nibabel"]
+
+[project.scripts]
+tomio = "tomio.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/py-baudin/tomio"
+Repository = "https://github.com/py-baudin/tomio"
+Issues = "https://github.com/py-baudin/tomio/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["test"]

tomio-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tomio-0.1.0/src/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-0.1.0/src/tomio/__main__.py

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

tomio-0.1.0/src/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) + ")"