tiny-metaio 0.1.1__tar.gz

tiny_metaio-0.1.1/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+report.xml
+.coverage

tiny_metaio-0.1.1/.gitlab-ci.yml

@@ -0,0 +1,64 @@
+image: ${CI_REGISTRY_IMAGE}:ci
+
+stages:
+  - build-ci-container
+  - test
+  - publish
+
+default:
+  tags:
+    - ci.inria.fr
+    - small
+
+build-ci-container:
+  stage: build-ci-container
+  image: docker:stable
+  before_script:
+    - docker info
+    - docker login -u gitlab-ci-token -p ${CI_JOB_TOKEN} ${CI_REGISTRY}
+  script:
+    - docker build --tag ${CI_REGISTRY_IMAGE}:ci -f Containerfile .
+    - docker push ${CI_REGISTRY_IMAGE}:ci
+  rules:
+    - changes:
+        - Containerfile
+        - uv.lock
+      if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+tests:
+  stage: test
+  script: uv run poe coverage
+  coverage: "/TOTAL.+ ([0-9]{1,3}%)/"
+  artifacts:
+    paths:
+      - htmlcov
+    reports:
+      junit: report.xml
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
+
+lint:
+  stage: test
+  script: uv run poe lint
+
+publish-gitlab:
+  stage: publish
+  variables:
+    UV_PUBLISH_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi"
+    UV_PUBLISH_USERNAME: "gitlab-ci-token"
+    UV_PUBLISH_PASSWORD: "${CI_JOB_TOKEN}"
+  script:
+    - uv build
+    - uv publish dist/*
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+    - if: $CI_COMMIT_TAG
+
+publish-pypi:
+  stage: publish
+  script:
+    - uv build
+    - uv publish --token $PYPI_TOKEN
+  rules:
+    - if: $CI_COMMIT_TAG

tiny_metaio-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,36 @@
+default_stages: [pre-commit]
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+        args: [--assume-in-merge]
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.11.2
+    hooks:
+      - id: uv-lock
+
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: v0.15.8
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/crate-ci/typos
+    rev: v1.44.0
+    hooks:
+      - id: typos
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty check
+        entry: ty check . --python .venv
+        language: python
+        files: ".*.py"

tiny_metaio-0.1.1/.python-version

@@ -0,0 +1 @@
+3.14

tiny_metaio-0.1.1/Containerfile

@@ -0,0 +1,20 @@
+# we use debian because there are no simpleitk wheels for musl and building
+# them is a hassle
+
+FROM ghcr.io/astral-sh/uv:python3.13-trixie-slim AS builder
+
+ENV UV_LINK_MODE=copy
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends git \
+  && rm -rf /var/lib/apt/lists/*
+COPY pyproject.toml uv.lock ./
+RUN uv sync --all-groups --all-extras --no-install-project
+
+FROM ghcr.io/astral-sh/uv:python3.13-trixie-slim AS ci
+
+ENV UV_LINK_MODE=copy
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends git \
+  && rm -rf /var/lib/apt/lists/*
+COPY --from=builder /root/.cache/uv /root/.cache/uv
+COPY pyproject.toml uv.lock ./

tiny_metaio-0.1.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,49 @@
+# 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/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "tiny-metaio"
+description = "Read and write MetaImages with minimal dependencies"
+readme = "README.md"
+authors = [
+    { name = "Nicolas Cedilnik", email = "nicolas.cedilnik@inria.fr" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy~=2.0",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://gitlab.inria.fr/ncedilni/metaio"
+Issues = "https://gitlab.inria.fr/ncedilni/metaio/-/issues"
+Repository = "https://gitlab.inria.fr/ncedilni/metaio"
+
+[build-system]
+requires = ["setuptools>=64", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "coverage>=7.13.5",
+    "poethepoet>=0.42.1",
+    "pytest>=9.0.2",
+    "ruff>=0.15.8",
+    "simpleitk>=2.5.3",
+    "ty>=0.0.26",
+    "typos>=1.44.0",
+]
+
+[tool.setuptools_scm]
+
+[tool.coverage.run]
+omit = ["./tests/*"]
+
+[tool.ruff.lint]
+extend-select = ["I", "ANN", "UP"]
+
+[tool.poe.tasks]
+ty = "ty check"
+ruff = "ruff check"
+typos = "typos"
+lint = ["ty", "ruff", "typos"]
+autofix = "ruff check --fix"
+test = "coverage run -m pytest --doctest-glob='*.md' --junitxml=report.xml"
+coverage-report = "coverage report"
+coverage-html = "coverage html"
+coverage = ["test", "coverage-report", "coverage-html"]

tiny_metaio-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tiny_metaio-0.1.1/src/metaio/__init__.py

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

tiny_metaio-0.1.1/src/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)

tiny_metaio-0.1.1/src/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,
+    )