medio

Medical image I/O for Python — read and write NIfTI, DICOM, MetaImage, and more in one consistent API.

• One function reads any format; format auto-detected from path
• Returns a NumPy array + rich MetaData (affine, orientation, spacing) — no format-specific objects to unwrap
• Transparent coordinate system normalization between ITK and NiBabel conventions
• Metadata-only reads (read_meta) for large files when you only need spatial info

Installation

pip install medio

Usage

Read and save any format

import medio

arr, meta = medio.read_img('scan.nii.gz')
print(meta.ornt, meta.spacing)   # e.g. 'LPI', [0.5, 0.5, 1.0]

medio.save_img('out.mhd', arr, meta)

Read metadata only — no pixel data loaded

meta = medio.read_meta('large_scan.nii.gz')
print(meta.spatial_shape)    # (256, 256, 128)
print(meta.affine.spacing)   # [0.98, 0.98, 1.5]

Reorient to a standard orientation

arr, meta = medio.read_img('scan.nii.gz', desired_ornt='RAS')
# arr axes are reordered; meta.affine updated to match

Write a DICOM series from a 3D array

arr, meta = medio.read_img('scan.mhd')
medio.save_dir('dicom_out/', arr, meta)

DICOM series geometry is validated

A DICOM directory is only a valid 3D volume if its slices agree geometrically. Series Instance UID does not guarantee that: scanners emit a localizer/scout under the same Series Instance UID as the acquisition, and reading it as part of the volume silently corrupts the derived slice spacing. read_img and read_meta therefore refuse an inconsistent series instead of returning a wrong image:

medio.read_img('dicom_dir/')
# InconsistentSeriesError: DICOM series mixes slice orientations: 1 of 325 slice(s) are not
# parallel to the first ... typically a localizer/scout slice sharing the Series Instance UID.

# read only the slices that share the dominant geometry (drops the localizer):
arr, meta = medio.read_img('dicom_dir/', keep_dominant_geometry=True)

# opt out entirely and get the previous, unchecked behaviour:
arr, meta = medio.read_img('dicom_dir/', validate_series=False)

The checks are the invariants any single volume must satisfy — one orientation, one in-plane geometry, uniformly spaced slice positions — and they catch missing or duplicated slices as well as localizers. SliceThickness is deliberately not required to equal the slice spacing: gapped and overlapping reconstructions are legitimate.

keep_dominant_geometry filters first and then still validates what remains, so it discards off-geometry slices without hiding a genuine gap in the rest.

Spatial slicing with automatic affine update

from medio.medimg import MedImg

mimg = MedImg(arr, meta)
cropped      = mimg[2:8, 3:7, :]    # origin updated
downsampled  = mimg[::2, ::2, ::1]  # spacing updated

Supported Formats

API Reference

read_img

medio.read_img(input_path, desired_ornt=None, backend=None, dtype=None,
               header=False, channels_axis=-1, coord_sys='itk', **kwargs)
→ tuple[np.ndarray, MetaData]

**kwargs are passed to the backend. DICOM directories (both backends): series, validate_series, keep_dominant_geometry. ITK-specific: pixel_type, fallback_only. pydicom-specific: globber, allow_default_affine.

read_meta

medio.read_meta(input_path, desired_ornt=None, backend=None,
                header=False, coord_sys='itk', **kwargs)
→ MetaData

See read_img for parameters. Reads only spatial metadata without loading pixel data.

save_img

medio.save_img(filename, np_image, metadata, use_original_ornt=True,
               backend=None, dtype=None, channels_axis=None,
               mkdir=False, parents=False, **kwargs)

save_dir

medio.save_dir(dirname, np_image, metadata, use_original_ornt=True,
               dtype=None, channels_axis=None, parents=False,
               exist_ok=False, allow_dcm_reorient=False, **kwargs)

Saves a 3D array as a DICOM series of 2D slices.

MetaData

medio.MetaData(affine, coord_sys='itk', orig_ornt=None, header=None, spatial_shape=None)

Methods: .convert(dest_coord_sys) — in-place convention switch; .clone() — deep copy.

Affine

A 4×4 NumPy array subclass with named spatial accessors.

from medio import Affine
import numpy as np

aff = Affine(np.eye(4))
aff = Affine(direction=np.eye(3), spacing=[0.5, 0.5, 1.0], origin=[0., 0., 0.])
coord = aff.index2coord([4, 0, 9])   # map voxel index → physical coordinate

Properties: .spacing, .origin, .direction (all gettable and settable). Method: .clone().

For a mathematical background see NiBabel's affine documentation.

MedImg

Container for an image array + metadata with spatially-aware indexing.

from medio.medimg.medimg import MedImg

mimg = MedImg(arr, meta)                         # from array + metadata
mimg = MedImg.from_file('scan.mhd')   # load from file

Indexing crops or downsamples the array and updates the affine automatically:

Properties: .np_image, .metadata. Method: .save(filename).

Orientation conventions

medio uses ITK convention by default (coord_sys='itk'). Pass coord_sys='nib' to read_img / read_meta to work in NiBabel convention throughout.

License

Apache 2.0 — see LICENSE.

Issues and contributions: github.com/RSIP-Vision/medio/issues