tiny-metaio 0.2.0__tar.gz → 0.4.0__tar.gz

{tiny_metaio-0.2.0 → tiny_metaio-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiny-metaio
-Version: 0.2.0
+Version: 0.4.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
@@ -26,6 +26,8 @@ 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`.
@@ -57,6 +59,64 @@ array([0., 0.])
 
 ```
 
+### Custom format
+
+#### Integers
+
+Integers are stored without loss in a very compact way.
+
+```python
+>>> 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.
+
+```python
+>>> 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.
+
+```python
+>>> 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.
@@ -67,6 +127,8 @@ array([0., 0.])
 ## 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.

tiny_metaio-0.4.0/README.md

@@ -0,0 +1,117 @@
+# 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 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
+
+#### Integers
+
+Integers are stored without loss in a very compact way.
+
+```python
+>>> 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.
+
+```python
+>>> 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.
+
+```python
+>>> 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.

{tiny_metaio-0.2.0 → tiny_metaio-0.4.0}/pyproject.toml

@@ -23,6 +23,9 @@ Homepage = "https://gitlab.inria.fr/ncedilni/metaio"
 Issues = "https://gitlab.inria.fr/ncedilni/metaio/-/issues"
 Repository = "https://gitlab.inria.fr/ncedilni/metaio"
 
+[project.scripts]
+metaio = "metaio.__main__:main"
+
 [build-system]
 requires = ["setuptools>=64", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
@@ -55,7 +58,7 @@ ruff = "ruff check"
 typos = "typos"
 lint = ["ty", "ruff", "typos"]
 autofix = "ruff check --fix"
-test = "coverage run -m pytest --doctest-glob='*.md' --junitxml=report.xml"
+test = "coverage run -m pytest --doctest-modules --doctest-glob='*.md' --junitxml=report.xml"
 coverage-report = "coverage report"
 coverage-xml = "coverage xml"
 coverage-html = "coverage html"

{tiny_metaio-0.2.0 → tiny_metaio-0.4.0}/src/metaio/__init__.py

@@ -1,8 +1,7 @@
 from pathlib import Path
 
+from . import mha, nifti, quant
 from .image import MetaImage
-from .mha import read_mha
-from .nifti import load
 
 
 def read(path: Path | str) -> MetaImage:
@@ -13,11 +12,14 @@ def read(path: Path | str) -> MetaImage:
         if len(split) == 3:
             suffix = ".".join(split[-2:])
 
+    if suffix in (".metaq"):
+        return quant.load(path)
+
     if suffix in (".mha", ".mhd"):
-        return read_mha(path)
+        return mha.load(path)
 
     if suffix in (".nii", "nii.gz"):
-        return load(path)
+        return nifti.load(path)
 
     raise RuntimeError(f"Unsupported file format: {path.suffix}")
 

tiny_metaio-0.4.0/src/metaio/__main__.py

@@ -0,0 +1,43 @@
+from argparse import ArgumentParser
+from pathlib import Path
+
+from . import read
+
+
+def main() -> int:
+    parser = ArgumentParser()
+    parser.add_argument("INPUT", help="Path to a file with a supported format.")
+    parser.add_argument(
+        "OUTPUT",
+        help="Path to the output file. It must have a '.mha' or '.metaq' extension.",
+        type=Path,
+    )
+    parser.add_argument(
+        "--no-compression",
+        help="Disable compression of the output. Only used for '.mha'.",
+        dest="compression",
+        action="store_false",
+    )
+    parser.add_argument(
+        "--quantization-range",
+        help="Quantization range. Only used for '.metaq', and only for floating point data types.",
+        type=float,
+        nargs=2,
+        default=(None, None),
+    )
+    parser.add_argument(
+        "--mask",
+        help="Boolean mask to use. Only used for '.metaq' and floating point data types.",
+        type=Path,
+    )
+    args = parser.parse_args()
+    img = read(args.INPUT)
+    if args.OUTPUT.suffix == ".metaq":
+        mask = None if args.mask is None else read(args.mask).data.astype(bool)
+        img.save_compact(args.OUTPUT, *args.quantization_range, mask=mask)
+    else:
+        img.save(args.OUTPUT, compress=args.compression)
+    return 0
+
+
+exit(main())

{tiny_metaio-0.2.0 → tiny_metaio-0.4.0}/src/metaio/image.py

@@ -1,11 +1,15 @@
-import os
+from __future__ import annotations
+
+import shutil
 import zlib
+from collections.abc import Mapping
 from pathlib import Path
+from typing import Any
 
 import numpy as np
 import numpy.typing as npt
 
-from . import write
+from . import pack, write
 
 
 class MetaImage:
@@ -26,7 +30,7 @@ class MetaImage:
         self.origin = origin
         self.direction = direction
 
-        self.metadata: dict[str, str] = {}
+        self.metadata: dict[str, str] = metadata or {}
 
     @property
     def size(self) -> tuple[int, ...]:
@@ -81,7 +85,7 @@ class MetaImage:
     def ndim(self) -> int:
         return self.data.ndim - (1 if self.vector else 0)
 
-    def save(self, path: os.PathLike[str], compress: bool = False) -> None:
+    def save(self, path: Path | str, compress: bool = False) -> None:
         path = Path(path)
         data = np.asarray(self.data)
 
@@ -132,3 +136,63 @@ class MetaImage:
             line("ElementDataFile", element_data_file)
 
             hfh.write(pixel_bytes)
+
+    def save_compact(
+        self,
+        path: Path | str,
+        min_: float | None = None,
+        max_: float | None = None,
+        *,
+        mask: npt.NDArray[np.bool] | None = None,
+    ) -> None:
+        path = Path(path)
+        if not path.suffix == ".metaq":
+            raise ValueError(
+                "For quantized images, the file extension must be '.metaq'", path.name
+            )
+        if mask is None:
+            kwargs: Mapping[str, npt.NDArray[Any] | float | int] = {}
+            data = self.data.astype(np.float32)
+        else:
+            kwargs = {"mask": np.packbits(mask.astype(bool)), "mask_shape": mask.shape}
+            data = self.data[mask].astype(np.float32)
+        if np.issubdtype(self.data.dtype, np.floating):
+            if min_ is None:
+                min_ = np.nanmin(self.data)
+            if max_ is None:
+                max_ = np.nanmax(self.data)
+            kwargs["data"] = _quantize(data, min_, max_)
+            kwargs["min"] = min_  # ty:ignore
+            kwargs["max"] = max_  # ty:ignore
+        elif np.issubdtype(self.data.dtype, np.integer):
+            if min_ is not None or max_ is not None:
+                raise TypeError("min and max should only be used for float datatypes")
+            kwargs["packed"] = pack.pack_compact(self.data)
+            kwargs["packed_shape"] = self.data.shape
+            kwargs["packed_dtype"] = self.data.dtype.str
+        else:
+            raise ValueError
+        np.savez_compressed(
+            path,
+            spacing=self.spacing,
+            direction=self.direction,
+            origin=self.origin,
+            meta=_dict_to_structured_array(self.metadata),
+            **kwargs,
+            allow_pickle=False,
+        )
+        # numpy automatically adds the `.npz` suffix, we don't want that
+        shutil.move(str(path) + ".npz", path)
+
+
+def _quantize(
+    arr: npt.NDArray[np.floating], min_: float = 0, max_: float = 20
+) -> npt.NDArray[np.uint8]:
+    clamped = np.clip(arr, min_, max_)
+    scaled = (clamped - min_) / (max_ - min_) * 255
+    return np.round(scaled).astype(np.uint8)
+
+
+def _dict_to_structured_array(dct: dict[str, str]) -> npt.NDArray[np.void]:
+    dtype = [(key, f"U{len(v)}") for key, v in dct.items()]
+    return np.array([tuple(dct.values())], dtype=dtype)

{tiny_metaio-0.2.0 → tiny_metaio-0.4.0}/src/metaio/mha.py

@@ -1,4 +1,3 @@
-import os
 import zlib
 from pathlib import Path
 from typing import BinaryIO
@@ -53,7 +52,7 @@ def _parse_header(src: BinaryIO) -> tuple[dict[str, str], int]:
 
 def _require(header: dict[str, str], key: str) -> str:
     try:
-        return header[key]
+        return header.pop(key)
     except KeyError:
         raise KeyError(f"Required MetaIO key '{key}' not found in header.") from None
 
@@ -66,7 +65,7 @@ def _parse_int_list(s: str) -> list[int]:
     return [int(x) for x in s.split()]
 
 
-def read_mha(path: str | os.PathLike[str]) -> MetaImage:
+def load(path: Path | str) -> MetaImage:
     """
     Read a MetaIO image file (``.mha`` or ``.mhd``).
 
@@ -109,34 +108,34 @@ def read_mha(path: str | os.PathLike[str]) -> MetaImage:
 
         spacing: list[float] = []
         if "ElementSpacing" in header:
-            spacing = _parse_float_list(header["ElementSpacing"])
+            spacing = _parse_float_list(header.pop("ElementSpacing"))
         elif "ElementSize" in header:
-            spacing = _parse_float_list(header["ElementSize"])
+            spacing = _parse_float_list(header.pop("ElementSize"))
 
         origin: list[float] = []
         if "Offset" in header:
-            origin = _parse_float_list(header["Offset"])
+            origin = _parse_float_list(header.pop("Offset"))
         elif "Position" in header:
-            origin = _parse_float_list(header["Position"])
+            origin = _parse_float_list(header.pop("Position"))
 
         transform_matrix: list[float] | None = None
         if "TransformMatrix" in header:
-            transform_matrix = _parse_float_list(header["TransformMatrix"])
+            transform_matrix = _parse_float_list(header.pop("TransformMatrix"))
         elif "Rotation" in header:
-            transform_matrix = _parse_float_list(header["Rotation"])
+            transform_matrix = _parse_float_list(header.pop("Rotation"))
 
         transform_matrix = (
             np.array(transform_matrix).reshape((ndim, ndim)).ravel(order="F")
         ).tolist()
 
-        big_endian_str = header.get("BinaryDataByteOrderMSB", "False").strip()
+        big_endian_str = header.pop("BinaryDataByteOrderMSB", "False").strip()
         big_endian = big_endian_str.lower() in ("true", "1")
         dtype = dtype.newbyteorder(">" if big_endian else "<")
 
-        n_channels = int(header.get("ElementNumberOfChannels", "1"))
+        n_channels = int(header.pop("ElementNumberOfChannels", "1"))
 
         element_data_file = _require(header, "ElementDataFile").strip()
-        compressed = header.get("CompressedData", "False").strip().lower() in (
+        compressed = header.pop("CompressedData", "False").strip().lower() in (
             "true",
             "1",
         )

tiny_metaio-0.4.0/src/metaio/pack.py

@@ -0,0 +1,291 @@
+"""
+Pack/unpack arrays of unsigned integers into a dense x-bit stream,
+stored in a uint8 byte array -- like numpy.packbits, but for any width.
+"""
+
+import numpy as np
+import numpy.typing as npt
+
+_IS_LITTLE_ENDIAN = np.array([1], dtype=np.uint16).view(np.uint8)[0] == 1
+
+
+def packbits_x(a: npt.ArrayLike, width: int) -> npt.NDArray[np.uint8]:
+    """
+    Pack an array of unsigned integers into a dense `width`-bit stream.
+
+    Parameters
+    ----------
+    a     : array_like of non-negative integers, each value < 2**width
+    width : int, bits per element (1-32)
+
+    Returns
+    -------
+    packed : npt.NDArray[np.uint8]
+        Bit-packed bytes; length = ceil(len(a) * width / 8).
+        Bit order is big-endian (MSB first within each element).
+
+    Examples
+    --------
+    >>> packbits_x([0b000000, 0b111111, 0b000001, 0b111110], width=6)
+    array([  3, 240, 126], dtype=uint8)
+
+    # 000000 111111 000001 111110  ->  00000011 11110000 01111110
+    """
+    # uint64 is required: the left-shift may exceed 32 bits, and .view(uint8).reshape(n,8)
+    # assumes exactly 8 bytes per element.
+    a = np.asarray(a, dtype=np.uint64).ravel()
+    if not (1 <= width <= 32):
+        raise ValueError(f"width must be 1-32, got {width}")
+    if np.any(a >= (np.uint64(1) << np.uint64(width))):
+        raise ValueError(
+            f"all values must be < {1 << width} (i.e. fit in {width} bits)"
+        )
+
+    n = len(a)
+    padded_width = int(np.ceil(width / 8)) * 8  # round width up to whole bytes
+    nbytes_per = padded_width // 8
+
+    # Left-align each value into the top `width` bits of a padded_width-wide field,
+    # then view the backing memory as individual bytes.
+    # On little-endian machines the bytes are reversed; flip to get big-endian order
+    # so that np.unpackbits yields MSB-first bits.
+    shifted = (a << np.uint64(padded_width - width)).view(np.uint8).reshape(n, 8)
+    be_bytes = (
+        shifted[:, :nbytes_per][:, ::-1]
+        if _IS_LITTLE_ENDIAN
+        else shifted[:, :nbytes_per]
+    )
+
+    # Unpack all bits at once -> (n, padded_width), trim to (n, width), stream & repack
+    bits = np.unpackbits(be_bytes.reshape(-1)).reshape(n, padded_width)[:, :width]
+    flat = bits.ravel()
+    pad = (-len(flat)) % 8
+    if pad:
+        flat = np.concatenate([flat, np.zeros(pad, np.uint8)])
+    return np.packbits(flat)
+
+
+def unpackbits_x(
+    packed: npt.NDArray[np.uint8],
+    width: int,
+    count: int | None = None,
+) -> npt.NDArray[np.unsignedinteger]:
+    """
+    Unpack a uint8 byte array produced by :func:`packbits_x` back into integers.
+
+    Parameters
+    ----------
+    packed : npt.NDArray[np.uint8], 1-D
+    width  : int, bits per element (must match the width used to pack)
+    count  : int | None, optional -- number of elements; defaults to all complete elements
+
+    Returns
+    -------
+    out : npt.NDArray[np.unsignedinteger]
+        dtype is uint8 / uint16 / uint32 / uint64, whichever is smallest for ``width``.
+
+    Examples
+    --------
+    >>> unpackbits_x(packbits_x([0, 63, 1, 62], 6), 6, count=4)
+    array([ 0, 63,  1, 62], dtype=uint8)
+    """
+    if not isinstance(packed, np.ndarray):
+        raise TypeError(
+            f"packed must be a 1-D ndarray of uint8, got {type(packed).__name__}"
+        )
+    if packed.dtype != np.uint8:
+        raise TypeError(f"packed must have dtype uint8, got {packed.dtype}")
+    if packed.ndim != 1:
+        raise TypeError(f"packed must be 1-D, got shape {packed.shape}")
+    if not (1 <= width <= 32):
+        raise ValueError(f"width must be 1-32, got {width}")
+
+    max_count = (len(packed) * 8) // width
+    if count is None:
+        count = max_count
+    elif count > max_count:
+        raise ValueError(f"count={count} exceeds available elements ({max_count})")
+
+    dtype = next(
+        dt
+        for dt in (np.uint8, np.uint16, np.uint32, np.uint64)
+        if np.iinfo(dt).bits >= width
+    )
+    bits = np.unpackbits(packed)[: count * width].reshape(count, width)
+    # Place-value vector [2^(width-1), ..., 2^1, 2^0] matching the MSB-first bit columns.
+    # dtype(1) seeds the shift in the output type to avoid numpy upcasting to int64.
+    # Row-wise dot product with bits gives the integer value: [1,0,1,1] . [8,4,2,1] = 11.
+    powers = dtype(1) << np.arange(width - 1, -1, -1, dtype=dtype)
+    return (bits.astype(dtype) * powers).sum(axis=1).astype(dtype)
+
+
+# Header layout (all big-endian):
+#   [0]      : magic      = 0xB1 (1 byte)
+#   [1]      : index_bits = bits per index into the unique-value table (1 byte)
+#   [2:6]    : count      = number of elements (uint32, 4 bytes)
+#   [6:8]    : n_unique   = number of unique values (uint16, 2 bytes)
+#   [8]      : signed     = 1 if table values are int64, 0 if uint64 (1 byte)
+#   [9:16]   : reserved   = 7 zero bytes (alignment padding)
+#   [16:]    : table      = sorted unique values, each stored as int64 or uint64 (8 bytes each)
+# Payload (after header): bit-packed indices, index_bits bits each.
+#
+# Strategy: encode each element as its rank in the sorted unique-value table,
+# then pack those indices.  [0, 5, 15799] has 3 unique values -> indices need
+# only 2 bits each, regardless of how large the actual values are.
+# Signed arrays are handled identically -- the table just uses int64 instead.
+_MAGIC = np.uint8(0xB1)
+_HEADER_BASE_DTYPE = np.dtype(
+    [
+        ("magic", ">u1"),  # 1 byte
+        ("index_bits", ">u1"),  # 1 byte
+        ("count", ">u4"),  # 4 bytes
+        ("n_unique", ">u2"),  # 2 bytes
+        ("signed", ">u1"),  # 1 byte  -- 1 = int64 table, 0 = uint64 table
+        ("reserved", ">u1", (7,)),  # 7 bytes padding
+    ]
+)  # 16 bytes before the table
+
+
+def pack_compact(a: npt.ArrayLike) -> npt.NDArray[np.uint8]:
+    """
+    Pack an integer array into the most compact representation possible.
+
+    Each element is stored as its index into a sorted table of unique values.
+    The number of index bits is `ceil(log2(n_unique))`, so an array whose
+    values come from a small alphabet is compressed far more than raw
+    bit-packing would allow.  Example: `[0, 5, 15799`` repeated 1000 times
+    needs only 2 bits per element instead of 14.  Signed integers are fully
+    supported: the table is stored as int64 when the input contains negative
+    values.
+
+    The output is fully self-describing: the unique-value table and all
+    metadata are stored in the header, so `unpack_compact` needs no
+    extra arguments.
+
+    Header layout (big-endian):
+        byte  0      : magic 0xB1
+        byte  1      : index_bits (bits per index, 1-32)
+        bytes 2-5    : count (uint32, number of elements)
+        bytes 6-7    : n_unique (uint16, number of unique values)
+        byte  8      : signed flag (1 = int64 table, 0 = uint64 table)
+        bytes 9-15   : reserved (zero)
+        bytes 16+    : table of n_unique int64/uint64 values (8 bytes each, sorted)
+    Payload (after header): bit-packed indices, index_bits bits per element.
+
+    Examples
+    --------
+    >>> unpack_compact(pack_compact([0, 5, 15799, 5, 0]))
+    array([    0,     5, 15799,     5,     0], dtype=uint16)
+    >>> unpack_compact(pack_compact([-3, 0, 1, -3, 1]))
+    array([-3,  0,  1, -3,  1], dtype=int8)
+    """
+    a = np.asarray(a).ravel()
+    # Decide signedness from dtype or presence of negative values
+
+    if len(a) == 0:
+        raise ValueError("input array must not be empty")
+    if len(a) > np.iinfo(np.uint32).max:
+        raise ValueError(f"array too long for header uint32 count: {len(a)}")
+
+    # Build sorted unique-value table and replace each element with its index
+    unique_vals, indices = np.unique(a, return_inverse=True)
+    n_unique = len(unique_vals)
+    if n_unique > np.iinfo(np.uint16).max:
+        raise ValueError(f"too many unique values for header uint16: {n_unique}")
+    is_signed = bool(np.any(unique_vals < 0))
+
+    # Bits needed to represent indices 0..n_unique-1
+    index_bits = max(1, (n_unique - 1).bit_length())
+
+    header = np.zeros(1, dtype=_HEADER_BASE_DTYPE)
+    header["magic"] = _MAGIC  # ty:ignore
+    header["index_bits"] = index_bits  # ty:ignore
+    header["count"] = len(a)  # ty:ignore
+    header["n_unique"] = n_unique  # ty:ignore
+    header["signed"] = np.uint8(is_signed)  # ty:ignore
+
+    # Store table as int64 or uint64; view as uint8 for concatenation
+    table = unique_vals.astype(np.int64 if is_signed else np.uint64)
+
+    return np.concatenate(
+        [
+            header.view(np.uint8),
+            table.view(np.uint8),
+            packbits_x(indices.astype(np.uint64), index_bits),
+        ]
+    )
+
+
+def unpack_compact(blob: npt.NDArray[np.uint8]) -> npt.NDArray[np.integer]:
+    """
+    Unpack a uint8 array produced by :func:`pack_compact`.
+
+    Parameters
+    ----------
+    blob : npt.NDArray[np.uint8], 1-D
+
+    Returns
+    -------
+    out : npt.NDArray[np.integer]
+        Values restored from the unique-value table; dtype is the smallest
+        signed or unsigned type that fits the range of values in the table.
+
+    Examples
+    --------
+    >>> unpack_compact(pack_compact([0, 5, 15799, 5, 0]))
+    array([    0,     5, 15799,     5,     0], dtype=uint16)
+    >>> unpack_compact(pack_compact([-3, 0, 1, -3, 1]))
+    array([-3,  0,  1, -3,  1], dtype=int8)
+    """
+    if not isinstance(blob, np.ndarray):
+        raise TypeError(
+            f"blob must be a 1-D ndarray of uint8, got {type(blob).__name__}"
+        )
+    if blob.dtype != np.uint8:
+        raise TypeError(f"blob must have dtype uint8, got {blob.dtype}")
+    if blob.ndim != 1:
+        raise TypeError(f"blob must be 1-D, got shape {blob.shape}")
+
+    base_size = _HEADER_BASE_DTYPE.itemsize  # 16 bytes
+    if len(blob) < base_size:
+        raise ValueError(
+            f"blob too short to contain header ({len(blob)} < {base_size} bytes)"
+        )
+
+    header = blob[:base_size].view(_HEADER_BASE_DTYPE)[0]
+    if header["magic"] != _MAGIC:
+        raise ValueError(
+            f"invalid magic byte: expected 0x{_MAGIC:02X}, got 0x{int(header['magic']):02X}"
+        )
+
+    index_bits = int(header["index_bits"])
+    count = int(header["count"])
+    n_unique = int(header["n_unique"])
+    is_signed = bool(header["signed"])
+    table_bytes = n_unique * 8  # each value is 8 bytes (int64 or uint64)
+
+    header_size = base_size + table_bytes
+    if len(blob) < header_size:
+        raise ValueError(
+            f"blob too short to contain table ({len(blob)} < {header_size} bytes)"
+        )
+
+    table_dtype = np.int64 if is_signed else np.uint64
+    table = blob[base_size:header_size].view(table_dtype)
+    indices = unpackbits_x(blob[header_size:], index_bits, count=count)
+
+    # choose the smallest dtype that fits the full range of the table
+    lo, hi = int(table.min()), int(table.max())
+    if is_signed:
+        dtype = next(
+            dt
+            for dt in (np.int8, np.int16, np.int32, np.int64)
+            if np.iinfo(dt).min <= lo and np.iinfo(dt).max >= hi
+        )
+    else:
+        dtype = next(
+            dt
+            for dt in (np.uint8, np.uint16, np.uint32, np.uint64)
+            if np.iinfo(dt).max >= hi
+        )
+    return table[indices].astype(dtype)

tiny_metaio-0.4.0/src/metaio/quant.py

@@ -0,0 +1,44 @@
+from pathlib import Path
+
+import numpy as np
+import numpy.typing as npt
+
+from . import pack
+from .image import MetaImage
+
+
+def load(path: Path | str) -> MetaImage:
+    npz = np.load(path, allow_pickle=False)
+    if "data" in npz:
+        arr = _dequantize(npz["data"], npz["min"], npz["max"])
+    else:
+        arr = (
+            pack.unpack_compact(npz["packed"])
+            .reshape(npz["packed_shape"])
+            .astype(np.dtype(str(npz["packed_dtype"])))
+        )
+    mask = npz.get("mask")
+    if mask is not None:
+        shape = npz["mask_shape"]
+        mask = np.unpackbits(mask, count=np.prod(shape)).reshape(shape).astype(bool)
+        data = np.full_like(mask, np.nan, dtype=arr.dtype)
+        data[mask] = arr
+        arr = data
+    return MetaImage(
+        arr,
+        spacing=npz["spacing"],
+        direction=npz["direction"],
+        origin=npz["origin"],
+        metadata=_structured_array_to_dict(npz["meta"]),
+    )
+
+
+def _dequantize(
+    arr: npt.NDArray[np.uint8], min_: float = 0, max_: float = 20
+) -> npt.NDArray[np.float32]:
+    scaled = arr.astype(np.float32) / 255
+    return scaled * np.float32(max_ - min_) + np.float32(min_)
+
+
+def _structured_array_to_dict(arr: npt.NDArray[np.void]) -> dict[str, str]:
+    return {field_name: str(arr[field_name].item()) for field_name in arr.dtype.names}  # ty:ignore[not-iterable]

{tiny_metaio-0.2.0 → tiny_metaio-0.4.0}/src/tiny_metaio.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiny-metaio
-Version: 0.2.0
+Version: 0.4.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
@@ -26,6 +26,8 @@ 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`.
@@ -57,6 +59,64 @@ array([0., 0.])
 
 ```
 
+### Custom format
+
+#### Integers
+
+Integers are stored without loss in a very compact way.
+
+```python
+>>> 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.
+
+```python
+>>> 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.
+
+```python
+>>> 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.
@@ -67,6 +127,8 @@ array([0., 0.])
 ## 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.

{tiny_metaio-0.2.0 → tiny_metaio-0.4.0}/src/tiny_metaio.egg-info/SOURCES.txt

@@ -6,16 +6,23 @@ README.md
 pyproject.toml
 uv.lock
 src/metaio/__init__.py
+src/metaio/__main__.py
 src/metaio/image.py
 src/metaio/mha.py
 src/metaio/nifti.py
+src/metaio/pack.py
 src/metaio/py.typed
+src/metaio/quant.py
 src/metaio/write.py
 src/tiny_metaio.egg-info/PKG-INFO
 src/tiny_metaio.egg-info/SOURCES.txt
 src/tiny_metaio.egg-info/dependency_links.txt
+src/tiny_metaio.egg-info/entry_points.txt
 src/tiny_metaio.egg-info/requires.txt
+src/tiny_metaio.egg-info/scm_file_list.json
+src/tiny_metaio.egg-info/scm_version.json
 src/tiny_metaio.egg-info/top_level.txt
 tests/conftest.py
+tests/test_quantization.py
 tests/test_symmetry.py
 tests/test_vs_simpleitk.py

tiny_metaio-0.4.0/src/tiny_metaio.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+metaio = metaio.__main__:main

tiny_metaio-0.4.0/src/tiny_metaio.egg-info/scm_file_list.json

@@ -0,0 +1,24 @@
+{
+  "files": [
+    ".gitlab-ci.yml",
+    "pyproject.toml",
+    "Containerfile",
+    "uv.lock",
+    "README.md",
+    ".gitignore",
+    ".pre-commit-config.yaml",
+    "src/metaio/nifti.py",
+    "src/metaio/mha.py",
+    "src/metaio/__init__.py",
+    "src/metaio/__main__.py",
+    "src/metaio/py.typed",
+    "src/metaio/image.py",
+    "src/metaio/quant.py",
+    "src/metaio/pack.py",
+    "src/metaio/write.py",
+    "tests/test_symmetry.py",
+    "tests/test_vs_simpleitk.py",
+    "tests/conftest.py",
+    "tests/test_quantization.py"
+  ]
+}

tiny_metaio-0.4.0/src/tiny_metaio.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.4.0",
+  "distance": 0,
+  "node": "g6400fde85c37e549dd6571a725a32656bbed64b2",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-23"
+}

{tiny_metaio-0.2.0 → tiny_metaio-0.4.0}/tests/conftest.py

@@ -8,8 +8,9 @@ import pytest
 @pytest.fixture(scope="session", autouse=True)
 def _rm_doctest_file() -> Iterator[None]:
     yield
-    if Path("some-name.mha").exists():
-        Path("some-name.mha").unlink()
+    for ext in "mha", "metaq":
+        if Path(f"some-name.{ext}").exists():
+            Path(f"some-name.{ext}").unlink()
 
 
 def get_rotation_matrix(ndim: int) -> np.typing.NDArray[np.floating]:

tiny_metaio-0.4.0/tests/test_quantization.py

@@ -0,0 +1,135 @@
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from metaio import MetaImage, pack, read
+from metaio.image import _dict_to_structured_array, _quantize
+from metaio.quant import _dequantize, _structured_array_to_dict
+
+
+@pytest.mark.parametrize("dtype", [np.float16, np.float32, np.float64, np.float128])
+@pytest.mark.parametrize("shape", [(10, 11), (3, 4, 5)])
+@pytest.mark.parametrize("min_,max_", [(0, 35), (-10, 700), (-150, 800)])
+def test_symmetry(
+    tmp_path: Path, dtype: np.dtype, shape: tuple[int, ...], min_: float, max_: float
+) -> None:
+    path = tmp_path / "image.metaq"
+    meta = {"k1": "v1", "k2": "v2", "k3": "v3"}
+
+    arr1 = np.linspace(-100, 500, np.prod(shape)).astype(dtype).reshape(shape)
+    img1 = MetaImage(
+        arr1,
+        spacing=np.array([0.5] * len(shape)),
+        origin=np.array([-4] * len(shape)),
+        direction=np.eye(len(shape)).ravel(),
+        metadata=meta,
+    )
+    img1.save_compact(path, min_, max_)
+
+    below_mask = arr1 <= min_
+    above_mask = arr1 >= max_
+    preserved_mask = ~(below_mask | above_mask)
+
+    # ensure we are actually testing something
+    assert np.any(below_mask) or np.any(above_mask) or np.any(preserved_mask)
+
+    img2 = read(path)
+    arr2 = img2.data
+
+    assert np.all(arr2[below_mask] == min_)
+    assert np.all(arr2[above_mask] == max_)
+    assert np.allclose(
+        arr1[preserved_mask], arr2[preserved_mask], atol=(max_ - min_) / 256
+    )
+
+    assert img2.data.dtype == np.float32
+    assert np.all(img1.spacing == img2.spacing)
+    assert np.all(img1.origin == img2.origin)
+    assert np.all(img1.direction == img2.direction)
+
+    for k, v in meta.items():
+        assert img2.metadata[k] == v
+
+
+@pytest.mark.parametrize(
+    "dtype",
+    [
+        # np.uint8,
+        # np.uint16,
+        # np.uint32,
+        # np.uint64,
+        np.int8,
+        np.int16,
+        np.int64,
+    ],
+)
+@pytest.mark.parametrize("shape", [(10, 11), (3, 4, 5)])
+@pytest.mark.parametrize("random_range", [10, 20, 1000, 10000, 100000, 1000000])
+def test_pack(
+    tmp_path: Path, dtype: np.dtype, shape: tuple[int, ...], random_range: int
+) -> None:
+    path = tmp_path / "image.metaq"
+    meta = {"k1": "v1", "k2": "v2", "k3": "v3"}
+
+    arr1 = np.random.randint(
+        0,
+        random_range if np.issubdtype(dtype, np.unsignedinteger) else random_range // 2,
+        size=shape,
+    ).astype(dtype)
+
+    if np.issubdtype(dtype, np.signedinteger):
+        arr1 -= min(np.iinfo(dtype).max, random_range // 2)
+
+    img1 = MetaImage(
+        arr1,
+        spacing=np.array([0.5] * len(shape)),
+        origin=np.array([-4] * len(shape)),
+        direction=np.eye(len(shape)).ravel(),
+        metadata=meta,
+    )
+    img1.save_compact(path)
+
+    img2 = read(path)
+    arr2 = img2.data
+
+    assert np.all(arr1 == arr2)
+
+    assert arr1.dtype == arr2.dtype
+    assert np.all(img1.spacing == img2.spacing)
+    assert np.all(img1.origin == img2.origin)
+    assert np.all(img1.direction == img2.direction)
+
+    for k, v in meta.items():
+        assert img2.metadata[k] == v
+
+
+def test_quantize() -> None:
+    assert np.all(_quantize(np.array([1, 2, 3, 4, 5]), 2, 4) == [0, 0, 128, 255, 255])
+    assert np.all(_quantize(np.array([-4, 0, 4]), -4, 4) == [0, 128, 255])
+
+
+def test_dequantize() -> None:
+    arr = np.array([0, 0, 127, 255, 255])
+    arr_q = _dequantize(arr, 2, 4)
+    assert np.all(np.round(arr_q) == [2, 2, 3, 4, 4])
+
+
+def test_integer() -> None:
+    arr = np.array([0, 1, 2, 3, 4])
+    quantized = _quantize(arr, 0, 4)
+    deq = _dequantize(quantized, 0, 4)
+    assert np.allclose(arr, deq, atol=4 / 256), quantized
+
+
+def test_dict_to_struct() -> None:
+    dct1 = {"k1": "v1", "k2": "vvvv2"}
+    arr = _dict_to_structured_array(dct1)
+    dct2 = _structured_array_to_dict(arr)
+    assert dct1 == dct2
+
+
+def test_pack_unpack() -> None:
+    assert np.all(
+        pack.unpack_compact(pack.pack_compact([-3, 0, 1, -3, 1])) == [-3, 0, 1, -3, 1]
+    )

{tiny_metaio-0.2.0 → tiny_metaio-0.4.0}/tests/test_vs_simpleitk.py

@@ -90,3 +90,32 @@ def test_write(
     assert np.allclose(img_us.direction, img.GetDirection())
     assert np.all(img_us.data == array)
     assert np.all(img_us.data == sitk.GetArrayViewFromImage(img))
+
+
+@pytest.mark.parametrize("key", ["key1", "Key2"])
+@pytest.mark.parametrize("value", ["some-other-string", "some-string"])
+def test_metadata_reader(tmp_path: Path, key: str, value: str) -> None:
+    sitk_img = sitk.GetImageFromArray(np.empty([5, 5]))
+    sitk_img.SetMetaData(key, value)
+    path = tmp_path / "image.mha"
+    sitk.WriteImage(sitk_img, path)
+
+    img = read(path)
+    assert img.metadata.pop(key) == value
+    # these keys are automatically added by simpleITK
+    assert set(img.metadata.keys()) == {
+        "AnatomicalOrientation",
+        "ObjectType",
+        "BinaryData",
+        "CenterOfRotation",
+    }
+
+
+def test_metadata_writer(tmp_path: Path) -> None:
+    path = tmp_path / "image.mha"
+    meta = {"key1": "value1", "key2": "value2"}
+    img = MetaImage(np.empty([5, 5]), metadata=meta)
+    img.save(path)
+    img = read(path)
+    for k, v in meta.items():
+        assert img.metadata[k] == v

tiny_metaio-0.2.0/README.md

@@ -1,55 +0,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.
-
-## 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.])
-
-```
-
-## 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,
-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.