Metadata-Version: 2.4
Name: tiny-metaio
Version: 0.3.0
Summary: Read and write MetaImages with minimal dependencies
Author-email: Nicolas Cedilnik <nicolas.cedilnik@inria.fr>
Project-URL: Homepage, https://gitlab.inria.fr/ncedilni/metaio
Project-URL: Issues, https://gitlab.inria.fr/ncedilni/metaio/-/issues
Project-URL: Repository, https://gitlab.inria.fr/ncedilni/metaio
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy~=2.0

# MetaIO

Read
[MetaImages](https://docs.itk.org/en/latest/learn/metaio.html)
(`.mha` or `.mhd`)
and
[NIFTI](https://en.wikipedia.org/wiki/Neuroimaging_Informatics_Technology_Initiative)
images (`.nii` or `.nii.gz`)
and write `.mha` images
in python with minimal dependencies.

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

## Installation

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

## Usage

### Writing a MHA file

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

```

### Reading a MHA file

```python
>>> 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

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.

```python
>>> img = metaio.MetaImage([[-0.5, 1], [2.5, 5]])
>>> img.save_quantized("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.

```python
>>> img = metaio.MetaImage([[-0.5, 1], [2.5, 5]])
>>> img.save_quantized("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.
