MetaIO

Read MetaImages (.mha or .mhd) and NIFTI images (.nii or .nii.gz) and write .mha images in python with minimal dependencies.

Bonus: provides a custom MHA-like format when size matters: .metaq.

Installation

Available on pypi.org: pip install tiny-metaio.

Usage

Writing a MHA file

>>> import metaio
>>> img = metaio.MetaImage([[0, 1], [42, 43]], spacing=[1, 2])
>>> img.save("some-name.mha")

Reading a MHA file

>>> img = metaio.read("some-name.mha")
>>> img.spacing
array([1., 2.])
>>> img.data
array([[ 0,  1],
       [42, 43]])
>>> img.direction
array([1., 0., 0., 1.])
>>> img.origin
array([0., 0.])

Custom format

Integers

Integers are stored without loss in a very compact way.

>>> from pathlib import Path
>>> import numpy as np
>>> img = metaio.MetaImage([[-5] * 1000, [2] * 1000])
>>> img.save("some-name.mha")
>>> Path("some-name.mha").stat().st_size
16246
>>> img.save_compact("some-name.metaq")
>>> round(Path("some-name.metaq").stat().st_size / Path("some-name.mha").stat().st_size, 2)
0.09
>>> np.all(metaio.read("some-name.metaq").data == img.data)
np.True_

Floats

You need to specify a range of values covered by the quantization. Values outside this ranges will be clipped. A loss of precision is expected. NaNs will be implicitly converted to zero.

>>> img = metaio.MetaImage([[-0.5, 1], [2.5, 5]])
>>> img.save_compact("some-name.metaq", min_=0, max_=2.5)
>>> metaio.read("some-name.metaq").data
array([[0. , 1. ],
       [2.5, 2.5]], dtype=float32)

Additionally, if some values do not matter, you can specify a mask for further compression. The mask must be a binary array of the same shape as the image. Values where the mask is False will not be stored at all and restored as NaN on dequantization.

>>> img = metaio.MetaImage([[-0.5, 1], [2.5, 5]])
>>> img.save_compact("some-name.metaq", min_=0, max_=2.5, mask=img.data <= 2.5)
>>> metaio.read("some-name.metaq").data
array([[0. , 1. ],
       [2.5, nan]], dtype=float32)

Command-line interface

A command-line interface is available to convert supported input format to a MHA.

$ metaio /path/to/input.metaq /path/to/output.mha

Philosophy

• numpy as only runtime dependency.
• idiomatic python.
• similar behavior than SimpleITK's GetArrayFromImage, GetImageFromArray, GetDirection, GetOrigin, GetSpacing, ReadImage, WriteImage.

Why should I use this over SimpleITK?

If you just need the IO parts and do not want the large SimpleITK package, or if you need to efficiently store some large MetaImage-like data, this package might be for you.

If you do not care about having SimpleITK as a dependency for your project, this package is not for you.