tiny-metaio 0.1.1__py3-none-any.whl

metaio/__init__.py

@@ -0,0 +1,4 @@
+from .image import MetaImage
+from .read import read_mha
+
+__all__ = "MetaImage", "read_mha"

metaio/image.py

@@ -0,0 +1,134 @@
+import os
+import zlib
+from pathlib import Path
+
+import numpy as np
+import numpy.typing as npt
+
+from . import write
+
+
+class MetaImage:
+    def __init__(
+        self,
+        data: npt.NDArray[np.generic],
+        *,
+        spacing: npt.NDArray[np.floating] | None = None,
+        origin: npt.NDArray[np.floating] | None = None,
+        direction: npt.NDArray[np.floating] | None = None,
+        metadata: dict[str, str] | None = None,
+        vector: bool = False,
+    ) -> None:
+        self.data = np.asarray(data)
+        self.vector = vector
+
+        self.spacing = spacing
+        self.origin = origin
+        self.direction = direction
+
+        self.metadata: dict[str, str] = {}
+
+    @property
+    def size(self) -> tuple[int, ...]:
+        if self.vector:
+            return self.data.shape[:-1][::-1]
+        else:
+            return self.data.shape[::-1]
+
+    @property
+    def spacing(self) -> npt.NDArray[np.floating]:
+        return self._spacing
+
+    @spacing.setter
+    def spacing(self, spacing: npt.NDArray[np.floating] | None) -> None:
+        if spacing is None:
+            spacing = np.ones(self.ndim)
+        else:
+            if len(spacing) != self.ndim:
+                raise ValueError
+            spacing = np.asarray(spacing)
+        self._spacing = spacing
+
+    @property
+    def origin(self) -> npt.NDArray[np.floating]:
+        return self._origin
+
+    @origin.setter
+    def origin(self, origin: npt.NDArray[np.floating] | None) -> None:
+        if origin is None:
+            origin = np.zeros(self.ndim)
+        else:
+            if len(origin) != self.ndim:
+                raise ValueError
+            origin = np.asarray(origin)
+        self._origin = origin
+
+    @property
+    def direction(self) -> npt.NDArray[np.floating]:
+        return self._direction
+
+    @direction.setter
+    def direction(self, direction: npt.NDArray[np.floating] | None) -> None:
+        if direction is None:
+            direction = np.eye(self.ndim).ravel(order="F")
+        else:
+            if len(direction) != self.ndim**2:
+                raise ValueError
+            direction = np.asarray(direction)
+        self._direction = direction
+
+    @property
+    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:
+        path = Path(path)
+        data = np.asarray(self.data)
+
+        native_dtype: np.dtype[np.generic] = data.dtype.newbyteorder("=")
+        data = data.astype(native_dtype, copy=False)
+        element_type = write.element_type_for(native_dtype)
+
+        le_dtype: np.dtype[np.generic] = native_dtype.newbyteorder("<")
+        pixel_bytes = data.astype(le_dtype, copy=False).tobytes()
+
+        if compress:
+            pixel_bytes = zlib.compress(pixel_bytes)
+
+        header_path = path.with_suffix(".mha")
+        element_data_file = "LOCAL"
+
+        def line(key: str, val: object) -> None:
+            hfh.write(f"{key} = {val}\n".encode("ascii"))
+
+        with header_path.open("wb") as hfh:
+            line("ObjectType", self.metadata.get("ObjectType", "Image"))
+            line("NDims", self.ndim)
+            line("BinaryData", "True")
+            line("BinaryDataByteOrderMSB", "False")
+            line("CompressedData", "True" if compress else "False")
+            if compress:
+                line("CompressedDataSize", len(pixel_bytes))
+            if self.vector:
+                line("ElementNumberOfChannels", self.ndim)
+            line(
+                "TransformMatrix",
+                write.fmt_floats(
+                    np.array(self.direction)
+                    .reshape((self.ndim, self.ndim))
+                    .ravel(order="F")
+                    .tolist()
+                ),
+            )
+            line("Offset", write.fmt_floats(self.origin))
+            line("ElementSpacing", write.fmt_floats(self.spacing))
+            line("DimSize", write.fmt_ints(self.size))
+
+            for k, v in self.metadata.items():
+                if k not in write.MANAGED:
+                    line(k, v)
+
+            line("ElementType", element_type)
+            line("ElementDataFile", element_data_file)
+
+            hfh.write(pixel_bytes)

metaio/read.py

@@ -0,0 +1,185 @@
+import os
+import zlib
+from pathlib import Path
+from typing import BinaryIO
+
+import numpy as np
+import numpy.typing as npt
+
+from .image import MetaImage
+
+_MET_DTYPE: dict[str, str] = {
+    "MET_CHAR": "int8",
+    "MET_UCHAR": "uint8",
+    "MET_SHORT": "int16",
+    "MET_USHORT": "uint16",
+    "MET_INT": "int32",
+    "MET_UINT": "uint32",
+    "MET_LONG": "int32",
+    "MET_ULONG": "uint32",
+    "MET_LONG_LONG": "int64",
+    "MET_ULONG_LONG": "uint64",
+    "MET_FLOAT": "float32",
+    "MET_DOUBLE": "float64",
+}
+
+
+def _parse_header(src: BinaryIO) -> tuple[dict[str, str], int]:
+    header: dict[str, str] = {}
+    line_buf = bytearray()
+
+    while True:
+        byte = src.read(1)
+        if not byte:
+            raise EOFError("Reached end of file before finding ElementDataFile.")
+        if byte == b"\n":
+            line = line_buf.decode("ascii", errors="replace").strip()
+            line_buf.clear()
+            if not line or line.startswith("#"):
+                continue
+            if "=" not in line:
+                continue
+            key_raw, _, val_raw = line.partition("=")
+            key = key_raw.strip()
+            val = val_raw.strip()
+            header[key] = val
+            if key == "ElementDataFile":
+                break
+        else:
+            line_buf.extend(byte)
+
+    return header, src.tell()
+
+
+def _require(header: dict[str, str], key: str) -> str:
+    try:
+        return header[key]
+    except KeyError:
+        raise KeyError(f"Required MetaIO key '{key}' not found in header.") from None
+
+
+def _parse_float_list(s: str) -> list[float]:
+    return [float(x) for x in s.split()]
+
+
+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:
+    """
+    Read a MetaIO image file (``.mha`` or ``.mhd``).
+
+    Parameters
+    ----------
+    path:
+        Path to the ``.mha`` or ``.mhd`` file.
+
+    Returns
+    -------
+    MhaImage
+        Parsed image with voxel ``data`` shaped ``(Z, Y, X[, C])`` and all
+        available spatial metadata populated.
+
+    Raises
+    ------
+    KeyError
+        If a required header field is absent.
+    ValueError
+        If the pixel type is unsupported or the data length is wrong.
+    FileNotFoundError
+        If the file (or its companion ``.raw``) cannot be found.
+    """
+    path = Path(path)
+    with path.open("rb") as fh:
+        header, _data_offset = _parse_header(fh)
+
+        element_type = _require(header, "ElementType").upper()
+        if element_type not in _MET_DTYPE:
+            raise ValueError(
+                f"Unsupported ElementType '{element_type}'. "
+                f"Supported: {list(_MET_DTYPE)}"
+            )
+        dtype = np.dtype(_MET_DTYPE[element_type])
+
+        ndim = int(_require(header, "NDims"))
+        sizes = _parse_int_list(_require(header, "DimSize"))
+        if len(sizes) != ndim:
+            raise ValueError(f"NDims={ndim} but DimSize has {len(sizes)} entries.")
+
+        spacing: list[float] = []
+        if "ElementSpacing" in header:
+            spacing = _parse_float_list(header["ElementSpacing"])
+        elif "ElementSize" in header:
+            spacing = _parse_float_list(header["ElementSize"])
+
+        origin: list[float] = []
+        if "Offset" in header:
+            origin = _parse_float_list(header["Offset"])
+        elif "Position" in header:
+            origin = _parse_float_list(header["Position"])
+
+        transform_matrix: list[float] | None = None
+        if "TransformMatrix" in header:
+            transform_matrix = _parse_float_list(header["TransformMatrix"])
+        elif "Rotation" in header:
+            transform_matrix = _parse_float_list(header["Rotation"])
+
+        transform_matrix = (
+            np.array(transform_matrix).reshape((ndim, ndim)).ravel(order="F")
+        ).tolist()
+
+        big_endian_str = header.get("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"))
+
+        element_data_file = _require(header, "ElementDataFile").strip()
+        compressed = header.get("CompressedData", "False").strip().lower() in (
+            "true",
+            "1",
+        )
+
+        if element_data_file == "LOCAL":
+            raw_bytes: bytes = fh.read()
+        else:
+            raw_path = path.parent / element_data_file
+            if not raw_path.exists():
+                raise FileNotFoundError(f"Companion data file not found: {raw_path}")
+            with raw_path.open("rb") as raw_fh:
+                raw_bytes = raw_fh.read()
+
+    if compressed:
+        raw_bytes = zlib.decompress(raw_bytes)
+
+    n_voxels = 1
+    for s in sizes:
+        n_voxels *= s
+    n_elements = n_voxels * n_channels
+    expected_bytes = n_elements * dtype.itemsize
+
+    if len(raw_bytes) < expected_bytes:
+        raise ValueError(
+            f"Expected {expected_bytes} bytes of pixel data but got {len(raw_bytes)}."
+        )
+
+    flat: npt.NDArray[np.generic] = np.frombuffer(
+        raw_bytes[:expected_bytes], dtype=dtype
+    )
+
+    shape: tuple[int, ...] = tuple(reversed(sizes))
+    if n_channels > 1:
+        shape = shape + (n_channels,)
+
+    data = flat.reshape(shape)
+    data = data.astype(data.dtype.newbyteorder("="), copy=False)
+
+    return MetaImage(
+        data=data,
+        spacing=np.asarray(spacing),
+        origin=np.asarray(origin),
+        direction=np.asarray(transform_matrix),
+        metadata=header,
+        vector=n_channels != 1,
+    )

metaio/write.py

@@ -0,0 +1,57 @@
+from collections.abc import Sequence
+
+import numpy as np
+import numpy.typing as npt
+
+_DTYPE_MET: dict[tuple[str, int], str] = {
+    ("u", 1): "MET_UCHAR",
+    ("i", 1): "MET_CHAR",
+    ("u", 2): "MET_USHORT",
+    ("i", 2): "MET_SHORT",
+    ("u", 4): "MET_UINT",
+    ("i", 4): "MET_INT",
+    ("u", 8): "MET_ULONG_LONG",
+    ("i", 8): "MET_LONG_LONG",
+    ("f", 4): "MET_FLOAT",
+    ("f", 8): "MET_DOUBLE",
+}
+
+MANAGED = {
+    "ObjectType",
+    "NDims",
+    "BinaryData",
+    "BinaryDataByteOrderMSB",
+    "CompressedData",
+    "CompressedDataSize",
+    "TransformMatrix",
+    "Offset",
+    "Position",
+    "ElementSpacing",
+    "ElementSize",
+    "DimSize",
+    "ElementNumberOfChannels",
+    "ElementType",
+    "ElementDataFile",
+}
+
+
+def fmt_floats(values: Sequence[float] | npt.NDArray[np.floating]) -> str:
+    if isinstance(values, np.ndarray):
+        values = values.tolist()
+    return " ".join(repr(v) for v in values)
+
+
+def fmt_ints(values: Sequence[int]) -> str:
+    return " ".join(str(v) for v in values)
+
+
+def element_type_for(dtype: np.dtype[np.generic]) -> str:
+    """Return the MetaIO ElementType string for *dtype*, raising on failure."""
+    key = (dtype.kind, dtype.itemsize)
+    if key not in _DTYPE_MET:
+        raise ValueError(
+            f"No MetaIO ElementType for dtype '{dtype}' "
+            f"(kind='{dtype.kind}', itemsize={dtype.itemsize}). "
+            f"Supported numpy kinds/sizes: {list(_DTYPE_MET)}"
+        )
+    return _DTYPE_MET[key]

tiny_metaio-0.1.1.dist-info/METADATA

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: tiny-metaio
+Version: 0.1.1
+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 and write [MetaImages](https://docs.itk.org/en/latest/learn/metaio.html)
+in python with minimal dependencies.
+
+## Installation
+
+Available on pypi.org: `pip install metaio`.
+
+## Usage
+
+### Writing a MHA file
+
+```python
+>>> from metaio import MetaImage, read_mha
+>>> img = MetaImage([[0, 1], [42, 43]], spacing=[1, 2])
+>>> img.save("some-name.mha")
+
+```
+
+### Reading a MHA file
+
+```python
+>>> img = read_mha("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.

tiny_metaio-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+metaio/__init__.py,sha256=ESxrAVQNytShMXAbnloV45CNK-DdoauwoeDrpL9obYU,91
+metaio/image.py,sha256=OUDB8BYP2AC4nfOzfpRjdzSOmvU0GshwFJH1CZQ4hTE,4208
+metaio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+metaio/read.py,sha256=Vqd-xfj8Gtwy05FMTN6fd1YYJUPkTzK1srpbujHf18Y,5591
+metaio/write.py,sha256=EALxGlvJzLWyJHfwaBlVhvIeOd3egLRNtUEXuF4JdQs,1474
+tiny_metaio-0.1.1.dist-info/METADATA,sha256=PJrC4rFwfR4fKoh5sR-9YjYBOxUOzmrjfV-lNzuUq2Q,1809
+tiny_metaio-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+tiny_metaio-0.1.1.dist-info/top_level.txt,sha256=mbuJhHfrVASzx9c0IbjP6llb_znhMzrsAYhM0KreOgw,7
+tiny_metaio-0.1.1.dist-info/RECORD,,

tiny_metaio-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tiny_metaio-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+metaio