voidspace 0.1.0__tar.gz

voidspace-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthias Walle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

voidspace-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: voidspace
+Version: 0.1.0
+Summary: Spacing-aware voidspace analysis for HR-pQCT segmentations
+Author: Matthias Walle
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/wallematthias/voidspace
+Project-URL: Repository, https://github.com/wallematthias/voidspace
+Project-URL: Issues, https://github.com/wallematthias/voidspace/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3.0,>=1.26
+Requires-Dist: aimio-py>=0.1.8
+Requires-Dist: scipy>=1.10
+Requires-Dist: SimpleITK>=2.2
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# voidspace
+
+Spacing-aware voidspace analysis for HR-pQCT segmentations.
+
+`voidspace` is a standalone logic package. It does not segment bone, register
+scans, create common regions, or resample images. It expects inputs that are
+already in the image space to analyze.
+
+The command line interface reads common SimpleITK image formats and Scanco AIM
+masks. AIM masks are read in native scaling, interpreted as foreground where
+nonzero, and written back as native binary AIM masks using the input geometry.
+
+## Workflows
+
+- Cross-sectional: pass a segmented bone image.
+- Masked/common-region: pass a segmented bone image and a mask. If both a
+  periosteal contour and a common region are needed, combine them before calling
+  `voidspace`.
+- Registered: pass an already registered segmentation and optional registered
+  mask.
+- Dynamic change: pass already aligned baseline and follow-up voidspace masks.
+
+When no periosteal mask is supplied, the segmentation-only workflow estimates
+the analysis domain from the closed segmentation by excluding background
+connected to the image border. Supplying an explicit mask remains preferred
+when that contour is available.
+
+## Algorithm
+
+The algorithm follows the original IPL voidspace concept:
+
+1. Remove tiny disconnected bone components.
+2. Close segmented bone to fill normal trabecular spacing.
+3. Invert the closed bone region to candidate marrow void.
+4. Erode candidate void away from trabecular surfaces.
+5. Remove tiny candidate void components.
+6. Keep all surviving voids and large voids above a physical volume threshold.
+
+Unlike the IPL scripts, morphology uses a spacing-aware spherical or ellipsoidal
+footprint. The default XtremeCT II settings are:
+
+- closing radius: `0.738 mm`
+- boundary erosion radius: `0.366 mm`
+- minimum large-void volume: `16.5 mm3`
+- bone and void speckle cleanup: `6 voxels`
+
+The original IPL code used `72560` or `72660` voxels as scanner-specific large
+void thresholds in different script/paper contexts. This package treats
+`16.5 mm3` as the default source of truth and converts it from the supplied
+image spacing.
+
+## CLI
+
+```bash
+voidspace run-case \
+  --segmentation seg.AIM \
+  --mask analysis_domain.AIM \
+  --output-dir voidspace-out
+```
+
+```bash
+voidspace compare \
+  --baseline-void baseline_voidspace_large_mask.AIM \
+  --followup-void followup_voidspace_large_mask.AIM \
+  --mask analysis_domain.AIM \
+  --output-dir voidspace-change
+```
+
+`--mask` is optional for both commands. Use `--force` to overwrite existing
+outputs.
+
+## Python
+
+```python
+from voidspace import VoidspaceParameters, run_case
+
+result = run_case(
+    segmentation_path="seg.AIM",
+    mask_path="analysis_domain.AIM",
+    output_dir="voidspace-out",
+    parameters=VoidspaceParameters.xtremectii_defaults(),
+)
+print(result.metrics.volume_mm3)
+```
+
+```python
+from voidspace import compare
+
+result = compare(
+    baseline_void_path="baseline_voidspace_large_mask.AIM",
+    followup_void_path="followup_voidspace_large_mask.AIM",
+    mask_path="analysis_domain.AIM",
+    output_dir="voidspace-change",
+)
+print(result.metrics.net_change_volume_mm3)
+```
+
+## Citation
+
+For cross-sectional voidspace analysis, cite:
+
+Whittier DE, Burt LA, Boyd SK. A new approach for quantifying localized bone
+loss by measuring void spaces. Bone. 2021 Feb;143:115785.
+doi: [10.1016/j.bone.2020.115785](https://doi.org/10.1016/j.bone.2020.115785).
+Epub 2020 Dec 2. PMID: 33278655.
+
+For dynamic voidspace analysis, cite:
+
+Whittier DE, Walle M, Atkins PR, Collins CJ, Zumstein MA, Christen P, Lippuner
+K, Müller R. Structural alterations during fracture healing lead to void spaces
+developing in surrounding bone microarchitecture. Journal of Bone and Mineral
+Research. 2025 Jun;40(6):791-798.
+doi: [10.1093/jbmr/zjaf046](https://doi.org/10.1093/jbmr/zjaf046).

voidspace-0.1.0/README.md

@@ -0,0 +1,113 @@
+# voidspace
+
+Spacing-aware voidspace analysis for HR-pQCT segmentations.
+
+`voidspace` is a standalone logic package. It does not segment bone, register
+scans, create common regions, or resample images. It expects inputs that are
+already in the image space to analyze.
+
+The command line interface reads common SimpleITK image formats and Scanco AIM
+masks. AIM masks are read in native scaling, interpreted as foreground where
+nonzero, and written back as native binary AIM masks using the input geometry.
+
+## Workflows
+
+- Cross-sectional: pass a segmented bone image.
+- Masked/common-region: pass a segmented bone image and a mask. If both a
+  periosteal contour and a common region are needed, combine them before calling
+  `voidspace`.
+- Registered: pass an already registered segmentation and optional registered
+  mask.
+- Dynamic change: pass already aligned baseline and follow-up voidspace masks.
+
+When no periosteal mask is supplied, the segmentation-only workflow estimates
+the analysis domain from the closed segmentation by excluding background
+connected to the image border. Supplying an explicit mask remains preferred
+when that contour is available.
+
+## Algorithm
+
+The algorithm follows the original IPL voidspace concept:
+
+1. Remove tiny disconnected bone components.
+2. Close segmented bone to fill normal trabecular spacing.
+3. Invert the closed bone region to candidate marrow void.
+4. Erode candidate void away from trabecular surfaces.
+5. Remove tiny candidate void components.
+6. Keep all surviving voids and large voids above a physical volume threshold.
+
+Unlike the IPL scripts, morphology uses a spacing-aware spherical or ellipsoidal
+footprint. The default XtremeCT II settings are:
+
+- closing radius: `0.738 mm`
+- boundary erosion radius: `0.366 mm`
+- minimum large-void volume: `16.5 mm3`
+- bone and void speckle cleanup: `6 voxels`
+
+The original IPL code used `72560` or `72660` voxels as scanner-specific large
+void thresholds in different script/paper contexts. This package treats
+`16.5 mm3` as the default source of truth and converts it from the supplied
+image spacing.
+
+## CLI
+
+```bash
+voidspace run-case \
+  --segmentation seg.AIM \
+  --mask analysis_domain.AIM \
+  --output-dir voidspace-out
+```
+
+```bash
+voidspace compare \
+  --baseline-void baseline_voidspace_large_mask.AIM \
+  --followup-void followup_voidspace_large_mask.AIM \
+  --mask analysis_domain.AIM \
+  --output-dir voidspace-change
+```
+
+`--mask` is optional for both commands. Use `--force` to overwrite existing
+outputs.
+
+## Python
+
+```python
+from voidspace import VoidspaceParameters, run_case
+
+result = run_case(
+    segmentation_path="seg.AIM",
+    mask_path="analysis_domain.AIM",
+    output_dir="voidspace-out",
+    parameters=VoidspaceParameters.xtremectii_defaults(),
+)
+print(result.metrics.volume_mm3)
+```
+
+```python
+from voidspace import compare
+
+result = compare(
+    baseline_void_path="baseline_voidspace_large_mask.AIM",
+    followup_void_path="followup_voidspace_large_mask.AIM",
+    mask_path="analysis_domain.AIM",
+    output_dir="voidspace-change",
+)
+print(result.metrics.net_change_volume_mm3)
+```
+
+## Citation
+
+For cross-sectional voidspace analysis, cite:
+
+Whittier DE, Burt LA, Boyd SK. A new approach for quantifying localized bone
+loss by measuring void spaces. Bone. 2021 Feb;143:115785.
+doi: [10.1016/j.bone.2020.115785](https://doi.org/10.1016/j.bone.2020.115785).
+Epub 2020 Dec 2. PMID: 33278655.
+
+For dynamic voidspace analysis, cite:
+
+Whittier DE, Walle M, Atkins PR, Collins CJ, Zumstein MA, Christen P, Lippuner
+K, Müller R. Structural alterations during fracture healing lead to void spaces
+developing in surrounding bone microarchitecture. Journal of Bone and Mineral
+Research. 2025 Jun;40(6):791-798.
+doi: [10.1093/jbmr/zjaf046](https://doi.org/10.1093/jbmr/zjaf046).

voidspace-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "voidspace"
+version = "0.1.0"
+description = "Spacing-aware voidspace analysis for HR-pQCT segmentations"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{name = "Matthias Walle"}]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Image Processing",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+dependencies = [
+  "numpy>=1.26,<3.0",
+  "aimio-py>=0.1.8",
+  "scipy>=1.10",
+  "SimpleITK>=2.2",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+dev = [
+  "build",
+  "pytest>=8",
+  "twine",
+]
+
+[project.scripts]
+voidspace = "voidspace.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/wallematthias/voidspace"
+Repository = "https://github.com/wallematthias/voidspace"
+Issues = "https://github.com/wallematthias/voidspace/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

voidspace-0.1.0/setup.cfg

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

voidspace-0.1.0/src/voidspace/__init__.py

@@ -0,0 +1,32 @@
+from voidspace.change import classify_voidspace_change, measure_voidspace_change
+from voidspace.metrics import measure_voidspace
+from voidspace.models import (
+    VoidspaceChangeMasks,
+    VoidspaceChangeMetrics,
+    VoidspaceMasks,
+    VoidspaceMetrics,
+    VoidspaceParameters,
+    VoidspaceCompareResult,
+    VoidspaceRunResult,
+)
+from voidspace.segment import segment_voidspace
+from voidspace.workflows import compare, run_case
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "VoidspaceChangeMasks",
+    "VoidspaceChangeMetrics",
+    "VoidspaceCompareResult",
+    "VoidspaceMasks",
+    "VoidspaceMetrics",
+    "VoidspaceParameters",
+    "VoidspaceRunResult",
+    "__version__",
+    "classify_voidspace_change",
+    "compare",
+    "measure_voidspace",
+    "measure_voidspace_change",
+    "run_case",
+    "segment_voidspace",
+]

voidspace-0.1.0/src/voidspace/change.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import numpy as np
+
+from voidspace.models import VoidspaceChangeMasks, VoidspaceChangeMetrics
+from voidspace.morphology import voxel_volume_mm3
+
+
+def classify_voidspace_change(
+    baseline_void: np.ndarray,
+    followup_void: np.ndarray,
+    mask: np.ndarray | None = None,
+) -> VoidspaceChangeMasks:
+    baseline = np.asarray(baseline_void, dtype=bool)
+    followup = np.asarray(followup_void, dtype=bool)
+    if baseline.shape != followup.shape:
+        raise ValueError("baseline_void and followup_void must have the same shape")
+    if mask is not None:
+        mask = np.asarray(mask, dtype=bool)
+        if mask.shape != baseline.shape:
+            raise ValueError("mask must match void mask shape")
+        baseline = baseline & mask
+        followup = followup & mask
+
+    return VoidspaceChangeMasks(
+        stable=baseline & followup,
+        expanded=followup & ~baseline,
+        contracted=baseline & ~followup,
+    )
+
+
+def measure_voidspace_change(
+    change: VoidspaceChangeMasks,
+    spacing_mm: tuple[float, float, float],
+) -> VoidspaceChangeMetrics:
+    voxel_volume = voxel_volume_mm3(spacing_mm)
+    stable = float(np.asarray(change.stable, dtype=bool).sum() * voxel_volume)
+    expanded = float(np.asarray(change.expanded, dtype=bool).sum() * voxel_volume)
+    contracted = float(np.asarray(change.contracted, dtype=bool).sum() * voxel_volume)
+    return VoidspaceChangeMetrics(
+        stable_volume_mm3=stable,
+        expanded_volume_mm3=expanded,
+        contracted_volume_mm3=contracted,
+        net_change_volume_mm3=expanded - contracted,
+    )

voidspace-0.1.0/src/voidspace/cli.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Sequence
+
+from voidspace.models import VoidspaceParameters
+from voidspace.workflows import compare, run_case
+
+
+def _parameters_from_args(args: argparse.Namespace) -> VoidspaceParameters:
+    return VoidspaceParameters(
+        closing_radius_mm=args.closing_radius_mm,
+        boundary_erosion_radius_mm=args.boundary_erosion_radius_mm,
+        min_large_void_volume_mm3=args.min_large_void_volume_mm3,
+        bone_speckle_min_voxels=args.bone_speckle_min_voxels,
+        void_speckle_min_voxels=args.void_speckle_min_voxels,
+        connectivity=args.connectivity,
+    )
+
+
+def _add_parameter_arguments(parser: argparse.ArgumentParser) -> None:
+    defaults = VoidspaceParameters.xtremectii_defaults()
+    parser.add_argument("--closing-radius-mm", type=float, default=defaults.closing_radius_mm)
+    parser.add_argument(
+        "--boundary-erosion-radius-mm",
+        type=float,
+        default=defaults.boundary_erosion_radius_mm,
+    )
+    parser.add_argument(
+        "--min-large-void-volume-mm3",
+        type=float,
+        default=defaults.min_large_void_volume_mm3,
+    )
+    parser.add_argument(
+        "--bone-speckle-min-voxels",
+        type=int,
+        default=defaults.bone_speckle_min_voxels,
+    )
+    parser.add_argument(
+        "--void-speckle-min-voxels",
+        type=int,
+        default=defaults.void_speckle_min_voxels,
+    )
+    parser.add_argument("--connectivity", type=int, choices=(1, 2, 3), default=defaults.connectivity)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="voidspace",
+        description="Run spacing-aware voidspace analysis on prepared HR-pQCT masks.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    run_case = subparsers.add_parser("run-case", help="Segment and measure one prepared scan.")
+    run_case.add_argument("--segmentation", type=Path, required=True)
+    run_case.add_argument(
+        "--mask",
+        type=Path,
+        help="Optional analysis-domain mask. Combine periosteal/common-region masks before passing.",
+    )
+    run_case.add_argument("--output-dir", type=Path, required=True)
+    run_case.add_argument("--force", action="store_true")
+    _add_parameter_arguments(run_case)
+    run_case.set_defaults(func=_cmd_run_case)
+
+    compare = subparsers.add_parser("compare", help="Compare already aligned voidspace masks.")
+    compare.add_argument("--baseline-void", type=Path, required=True)
+    compare.add_argument("--followup-void", type=Path, required=True)
+    compare.add_argument(
+        "--mask",
+        type=Path,
+        help="Optional analysis-domain mask aligned with both voidspace masks.",
+    )
+    compare.add_argument("--output-dir", type=Path, required=True)
+    compare.add_argument("--force", action="store_true")
+    compare.set_defaults(func=_cmd_compare)
+
+    return parser
+
+
+def _cmd_run_case(args: argparse.Namespace) -> int:
+    run_case(
+        segmentation_path=args.segmentation,
+        mask_path=args.mask,
+        output_dir=args.output_dir,
+        parameters=_parameters_from_args(args),
+        force=args.force,
+    )
+    return 0
+
+
+def _cmd_compare(args: argparse.Namespace) -> int:
+    compare(
+        baseline_void_path=args.baseline_void,
+        followup_void_path=args.followup_void,
+        mask_path=args.mask,
+        output_dir=args.output_dir,
+        force=args.force,
+    )
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

voidspace-0.1.0/src/voidspace/io.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from pathlib import Path
+import re
+from typing import Any
+
+import numpy as np
+import SimpleITK as sitk
+
+
+@dataclass(frozen=True)
+class AimReference:
+    path: Path
+    metadata: dict[str, Any]
+    image: sitk.Image
+
+
+ImageReference = sitk.Image | AimReference
+
+
+def is_aim_path(path: Path | str) -> bool:
+    return re.search(r"\.aim(?:;\d+)?$", Path(path).name, re.IGNORECASE) is not None
+
+
+def _load_py_aimio():
+    try:
+        import py_aimio
+    except ImportError as exc:
+        raise RuntimeError(
+            "AIM files require the PyPI package 'aimio-py'. Install with "
+            "`python -m pip install aimio-py`."
+        ) from exc
+    return py_aimio
+
+
+def _spacing_zyx_from_image(image: sitk.Image) -> tuple[float, float, float]:
+    spacing_xyz = tuple(float(v) for v in image.GetSpacing())
+    return (spacing_xyz[2], spacing_xyz[1], spacing_xyz[0])
+
+
+def _as_zyx(array: np.ndarray, dimensions_xyz: tuple[int, int, int] | None) -> np.ndarray:
+    if array.ndim != 3:
+        raise ValueError(f"Expected a 3D AIM array, got shape {array.shape}.")
+    if dimensions_xyz is None:
+        return array
+    expected_zyx = (dimensions_xyz[2], dimensions_xyz[1], dimensions_xyz[0])
+    if tuple(array.shape) == expected_zyx:
+        return array
+    if tuple(array.shape) == dimensions_xyz:
+        return np.transpose(array, (2, 1, 0))
+    return array
+
+
+def _image_from_aim_array(array: np.ndarray, metadata: dict[str, Any]) -> sitk.Image:
+    image = sitk.GetImageFromArray(array)
+    spacing = metadata.get("element_size", metadata.get("spacing", (1.0, 1.0, 1.0)))
+    if not (isinstance(spacing, (tuple, list)) and len(spacing) == 3):
+        spacing = (1.0, 1.0, 1.0)
+    image.SetSpacing(tuple(float(v) for v in spacing))
+    origin = metadata.get("origin", (0.0, 0.0, 0.0))
+    if isinstance(origin, (tuple, list)) and len(origin) >= 3:
+        image.SetOrigin(tuple(float(v) for v in origin[:3]))
+    direction = metadata.get("direction")
+    if isinstance(direction, (tuple, list)) and len(direction) == 9:
+        image.SetDirection(tuple(float(v) for v in direction))
+    return image
+
+
+def _read_aim_mask(path: Path) -> tuple[np.ndarray, tuple[float, float, float], AimReference]:
+    py_aimio = _load_py_aimio()
+    array, metadata = py_aimio.read_aim(str(path), density=False, hu=False)
+    metadata = dict(metadata)
+    dimensions_raw = metadata.get("dimensions")
+    dimensions_xyz = (
+        tuple(int(v) for v in dimensions_raw)
+        if isinstance(dimensions_raw, (tuple, list)) and len(dimensions_raw) == 3
+        else None
+    )
+    array = _as_zyx(np.asarray(array), dimensions_xyz)
+    image = _image_from_aim_array(array, metadata)
+    return array.astype(bool), _spacing_zyx_from_image(image), AimReference(path, metadata, image)
+
+
+def read_mask(path: Path | str) -> tuple[np.ndarray, tuple[float, float, float], ImageReference]:
+    path = Path(path)
+    if is_aim_path(path):
+        return _read_aim_mask(path)
+
+    image = sitk.ReadImage(str(path))
+    array = sitk.GetArrayFromImage(image).astype(bool)
+    return array, _spacing_zyx_from_image(image), image
+
+
+def _write_aim_mask(mask: np.ndarray, reference: AimReference, path: Path) -> None:
+    py_aimio = _load_py_aimio()
+    image = sitk.GetImageFromArray(np.asarray(mask, dtype=np.uint8))
+    image.CopyInformation(reference.image)
+    metadata = dict(reference.metadata)
+    metadata["dimensions"] = tuple(int(v) for v in image.GetSize())
+    metadata["spacing"] = tuple(float(v) for v in image.GetSpacing())
+    metadata["element_size"] = tuple(float(v) for v in image.GetSpacing())
+    metadata["origin"] = tuple(float(v) for v in image.GetOrigin())
+    metadata["direction"] = tuple(float(v) for v in image.GetDirection())
+    metadata["unit"] = "native"
+    if isinstance(metadata.get("processing_log"), dict) and "processing_log_raw" not in metadata:
+        metadata["processing_log_raw"] = py_aimio.dict_to_log(metadata["processing_log"])
+    array = (127 * (sitk.GetArrayFromImage(image) > 0)).astype(np.int8)
+    py_aimio.write_aim(str(path), array, metadata, unit="native")
+
+
+def write_mask_like(mask: np.ndarray, reference: ImageReference, path: Path | str) -> Path:
+    output = Path(path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    if isinstance(reference, AimReference) or is_aim_path(output):
+        if not isinstance(reference, AimReference):
+            raise ValueError("AIM output requires an AIM reference image.")
+        _write_aim_mask(mask, reference, output)
+        return output
+
+    image = sitk.GetImageFromArray(np.asarray(mask, dtype=np.uint8))
+    image.CopyInformation(reference)
+    sitk.WriteImage(image, str(output))
+    return output
+
+
+def write_metrics_csv(path: Path | str, rows: list[dict[str, object]]) -> Path:
+    output = Path(path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    fieldnames: list[str] = []
+    for row in rows:
+        for key in row:
+            if key not in fieldnames:
+                fieldnames.append(key)
+    with output.open("w", newline="", encoding="utf-8") as stream:
+        writer = csv.DictWriter(stream, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(rows)
+    return output