voidspace 0.1.0__py3-none-any.whl

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/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/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/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

voidspace/metrics.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import numpy as np
+from scipy import ndimage as ndi
+
+from voidspace.models import VoidspaceMetrics
+from voidspace.morphology import connectivity_structure, voxel_volume_mm3
+
+
+def _validate_same_shape(*arrays: np.ndarray) -> None:
+    shapes = {np.asarray(array).shape for array in arrays}
+    if len(shapes) != 1:
+        raise ValueError(f"all masks must have the same shape, got {sorted(shapes)}")
+
+
+def measure_voidspace(
+    void_mask: np.ndarray,
+    total_mask: np.ndarray,
+    spacing_mm: tuple[float, float, float],
+    mask: np.ndarray | None = None,
+    connectivity: int = 3,
+) -> VoidspaceMetrics:
+    void_mask = np.asarray(void_mask, dtype=bool)
+    total_mask = np.asarray(total_mask, dtype=bool)
+    if void_mask.ndim != 3 or total_mask.ndim != 3:
+        raise ValueError("void_mask and total_mask must be 3D arrays")
+    _validate_same_shape(void_mask, total_mask)
+
+    if mask is not None:
+        mask = np.asarray(mask, dtype=bool)
+        _validate_same_shape(void_mask, mask)
+        total = total_mask & mask
+    else:
+        total = total_mask
+
+    void = void_mask & total
+    voxel_volume = voxel_volume_mm3(spacing_mm)
+    void_volume = float(void.sum() * voxel_volume)
+    total_volume = float(total.sum() * voxel_volume)
+    _labels, component_count = ndi.label(void, structure=connectivity_structure(connectivity))
+    projected_voxels = int(np.any(void, axis=0).sum())
+    projected_area = float(projected_voxels * float(spacing_mm[1]) * float(spacing_mm[2]))
+    vstv = 0.0 if total_volume == 0 else float(100.0 * void_volume / total_volume)
+
+    return VoidspaceMetrics(
+        volume_mm3=void_volume,
+        total_volume_mm3=total_volume,
+        vstv_percent=vstv,
+        component_count=int(component_count),
+        projected_area_mm2=projected_area,
+    )

voidspace/models.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Mapping
+
+import numpy as np
+
+
+def _validate_non_negative(name: str, value: float | int) -> None:
+    if value < 0:
+        raise ValueError(f"{name} must be >= 0")
+
+
+@dataclass(frozen=True)
+class VoidspaceParameters:
+    closing_radius_mm: float = 0.738
+    boundary_erosion_radius_mm: float = 0.366
+    min_large_void_volume_mm3: float = 16.5
+    bone_speckle_min_voxels: int = 6
+    void_speckle_min_voxels: int = 6
+    connectivity: int = 3
+
+    def __post_init__(self) -> None:
+        for name in (
+            "closing_radius_mm",
+            "boundary_erosion_radius_mm",
+            "min_large_void_volume_mm3",
+            "bone_speckle_min_voxels",
+            "void_speckle_min_voxels",
+        ):
+            _validate_non_negative(name, getattr(self, name))
+        if self.connectivity not in (1, 2, 3):
+            raise ValueError("connectivity must be 1, 2, or 3")
+
+    @classmethod
+    def xtremectii_defaults(cls) -> "VoidspaceParameters":
+        return cls()
+
+
+@dataclass(frozen=True)
+class VoidspaceMasks:
+    all_void: np.ndarray
+    large_void: np.ndarray
+    filled_bone: np.ndarray
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class VoidspaceMetrics:
+    volume_mm3: float
+    total_volume_mm3: float
+    vstv_percent: float
+    component_count: int
+    projected_area_mm2: float
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class VoidspaceChangeMasks:
+    stable: np.ndarray
+    expanded: np.ndarray
+    contracted: np.ndarray
+
+
+@dataclass(frozen=True)
+class VoidspaceChangeMetrics:
+    stable_volume_mm3: float
+    expanded_volume_mm3: float
+    contracted_volume_mm3: float
+    net_change_volume_mm3: float
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class VoidspaceRunResult:
+    large_mask_path: Path
+    all_mask_path: Path
+    measurements_path: Path
+    metrics: VoidspaceMetrics
+
+
+@dataclass(frozen=True)
+class VoidspaceCompareResult:
+    stable_mask_path: Path
+    expanded_mask_path: Path
+    contracted_mask_path: Path
+    measurements_path: Path
+    metrics: VoidspaceChangeMetrics

voidspace/morphology.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import math
+
+import numpy as np
+from scipy import ndimage as ndi
+
+
+def _spacing_array(spacing_mm: tuple[float, float, float]) -> np.ndarray:
+    spacing = np.asarray(spacing_mm, dtype=float)
+    if spacing.shape != (3,):
+        raise ValueError("spacing_mm must contain exactly three values")
+    if np.any(spacing <= 0):
+        raise ValueError("spacing_mm values must be > 0")
+    return spacing
+
+
+def voxel_volume_mm3(spacing_mm: tuple[float, float, float]) -> float:
+    return float(np.prod(_spacing_array(spacing_mm)))
+
+
+def min_voxels_for_volume(volume_mm3: float, spacing_mm: tuple[float, float, float]) -> int:
+    if volume_mm3 < 0:
+        raise ValueError("volume_mm3 must be >= 0")
+    return int(math.ceil(float(volume_mm3) / voxel_volume_mm3(spacing_mm)))
+
+
+def ellipsoid_footprint(radius_mm: float, spacing_mm: tuple[float, float, float]) -> np.ndarray:
+    if radius_mm < 0:
+        raise ValueError("radius_mm must be >= 0")
+    spacing = _spacing_array(spacing_mm)
+    radii_voxels = np.ceil(radius_mm / spacing).astype(int)
+    if radius_mm == 0:
+        return np.ones(tuple(2 * radii_voxels + 1), dtype=bool)
+
+    grids = np.ogrid[
+        -radii_voxels[0] : radii_voxels[0] + 1,
+        -radii_voxels[1] : radii_voxels[1] + 1,
+        -radii_voxels[2] : radii_voxels[2] + 1,
+    ]
+    distance2 = np.zeros(tuple(2 * radii_voxels + 1), dtype=float)
+    for axis_grid, axis_spacing in zip(grids, spacing, strict=True):
+        distance2 = distance2 + ((axis_grid * axis_spacing) / radius_mm) ** 2
+    return distance2 <= 1.0
+
+
+def connectivity_structure(connectivity: int) -> np.ndarray:
+    if connectivity not in (1, 2, 3):
+        raise ValueError("connectivity must be 1, 2, or 3")
+    return ndi.generate_binary_structure(rank=3, connectivity=connectivity)
+
+
+def remove_small_components(mask: np.ndarray, min_voxels: int, connectivity: int = 3) -> np.ndarray:
+    mask = np.asarray(mask, dtype=bool)
+    if mask.ndim != 3:
+        raise ValueError("mask must be a 3D array")
+    if min_voxels <= 1:
+        return mask.copy()
+
+    labels, count = ndi.label(mask, structure=connectivity_structure(connectivity))
+    if count == 0:
+        return np.zeros_like(mask, dtype=bool)
+    sizes = np.bincount(labels.ravel())
+    keep = sizes >= int(min_voxels)
+    keep[0] = False
+    return keep[labels]
+
+
+def remove_border_connected_components(mask: np.ndarray, connectivity: int = 3) -> np.ndarray:
+    mask = np.asarray(mask, dtype=bool)
+    if mask.ndim != 3:
+        raise ValueError("mask must be a 3D array")
+
+    labels, count = ndi.label(mask, structure=connectivity_structure(connectivity))
+    if count == 0:
+        return np.zeros_like(mask, dtype=bool)
+
+    border_labels = set(np.unique(labels[0, :, :]))
+    border_labels.update(np.unique(labels[-1, :, :]))
+    border_labels.update(np.unique(labels[:, 0, :]))
+    border_labels.update(np.unique(labels[:, -1, :]))
+    border_labels.update(np.unique(labels[:, :, 0]))
+    border_labels.update(np.unique(labels[:, :, -1]))
+    border_labels.discard(0)
+    remove = np.zeros(count + 1, dtype=bool)
+    if border_labels:
+        remove[list(border_labels)] = True
+    return mask & ~remove[labels]

voidspace/segment.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import numpy as np
+from scipy import ndimage as ndi
+
+from voidspace.models import VoidspaceMasks, VoidspaceParameters
+from voidspace.morphology import (
+    ellipsoid_footprint,
+    min_voxels_for_volume,
+    remove_border_connected_components,
+    remove_small_components,
+)
+
+
+def _validate_3d(name: str, array: np.ndarray) -> np.ndarray:
+    mask = np.asarray(array, dtype=bool)
+    if mask.ndim != 3:
+        raise ValueError(f"{name} must be a 3D array")
+    return mask
+
+
+def _validate_same_shape(*arrays: np.ndarray) -> None:
+    shapes = {array.shape for array in arrays}
+    if len(shapes) != 1:
+        raise ValueError(f"all masks must have the same shape, got {sorted(shapes)}")
+
+
+def segment_voidspace(
+    segmentation: np.ndarray,
+    spacing_mm: tuple[float, float, float],
+    mask: np.ndarray | None = None,
+    parameters: VoidspaceParameters | None = None,
+) -> VoidspaceMasks:
+    params = parameters or VoidspaceParameters.xtremectii_defaults()
+    bone = _validate_3d("segmentation", segmentation)
+    if mask is None:
+        domain = np.ones_like(bone, dtype=bool)
+        domain_source = "segmentation_border_background"
+    else:
+        domain = _validate_3d("mask", mask)
+        _validate_same_shape(bone, domain)
+        domain_source = "mask"
+
+    bone_in_domain = remove_small_components(
+        bone & domain,
+        params.bone_speckle_min_voxels,
+        connectivity=params.connectivity,
+    )
+    closing_fp = ellipsoid_footprint(params.closing_radius_mm, spacing_mm)
+    filled_bone = ndi.binary_closing(bone_in_domain, structure=closing_fp) & domain
+    if mask is None:
+        interior_background = remove_border_connected_components(
+            ~filled_bone,
+            connectivity=params.connectivity,
+        )
+        domain = filled_bone | interior_background
+        filled_bone = filled_bone & domain
+    candidate_void = domain & ~filled_bone
+
+    if params.boundary_erosion_radius_mm > 0:
+        erosion_fp = ellipsoid_footprint(params.boundary_erosion_radius_mm, spacing_mm)
+        candidate_void = ndi.binary_erosion(candidate_void, structure=erosion_fp, border_value=0)
+    candidate_void = candidate_void & domain
+
+    all_void = remove_small_components(
+        candidate_void,
+        params.void_speckle_min_voxels,
+        connectivity=params.connectivity,
+    )
+    large_min_voxels = min_voxels_for_volume(params.min_large_void_volume_mm3, spacing_mm)
+    large_void = remove_small_components(all_void, large_min_voxels, connectivity=params.connectivity)
+
+    return VoidspaceMasks(
+        all_void=all_void,
+        large_void=large_void,
+        filled_bone=filled_bone,
+        metadata={
+            "spacing_mm": tuple(float(v) for v in spacing_mm),
+            "closing_radius_mm": params.closing_radius_mm,
+            "boundary_erosion_radius_mm": params.boundary_erosion_radius_mm,
+            "min_large_void_volume_mm3": params.min_large_void_volume_mm3,
+            "structuring_element": "spacing_aware_ellipsoid",
+            "domain_source": domain_source,
+        },
+    )

voidspace/workflows.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from voidspace.change import classify_voidspace_change, measure_voidspace_change
+from voidspace.io import AimReference, read_mask, write_mask_like, write_metrics_csv
+from voidspace.metrics import measure_voidspace
+from voidspace.models import VoidspaceCompareResult, VoidspaceParameters, VoidspaceRunResult
+from voidspace.segment import segment_voidspace
+
+
+def _metric_row(metrics, **context):
+    return {
+        **context,
+        "VS.TV": metrics.vstv_percent,
+        "VS.V": metrics.volume_mm3,
+        "Tt.V": metrics.total_volume_mm3,
+        "VS.N": metrics.component_count,
+        "VS.Ar": metrics.projected_area_mm2,
+    }
+
+
+def _mask_extension(reference) -> str:
+    return ".AIM" if isinstance(reference, AimReference) else ".nii.gz"
+
+
+def run_case(
+    *,
+    segmentation_path: Path | str,
+    output_dir: Path | str,
+    mask_path: Path | str | None = None,
+    parameters: VoidspaceParameters | None = None,
+    force: bool = False,
+) -> VoidspaceRunResult:
+    """Run cross-sectional voidspace segmentation and measurement for one scan."""
+    output_dir = Path(output_dir)
+    segmentation, spacing, reference = read_mask(segmentation_path)
+    mask_extension = _mask_extension(reference)
+    large_path = output_dir / f"voidspace_large_mask{mask_extension}"
+    all_path = output_dir / f"voidspace_all_mask{mask_extension}"
+    measurements_path = output_dir / "voidspace_measurements.csv"
+
+    existing_outputs = [path for path in (large_path, all_path, measurements_path) if path.exists()]
+    if existing_outputs and not force:
+        raise FileExistsError(f"output already exists: {existing_outputs[0]}")
+
+    if mask_path is not None:
+        domain_mask, mask_spacing, _mask_reference = read_mask(mask_path)
+        if mask_spacing != spacing or domain_mask.shape != segmentation.shape:
+            raise ValueError("mask must be in the same space as segmentation")
+    else:
+        domain_mask = None
+
+    params = parameters or VoidspaceParameters.xtremectii_defaults()
+    masks = segment_voidspace(segmentation, spacing, mask=domain_mask, parameters=params)
+    write_mask_like(masks.large_void, reference, large_path)
+    write_mask_like(masks.all_void, reference, all_path)
+
+    total_mask = domain_mask if domain_mask is not None else (masks.filled_bone | masks.all_void)
+    metrics = measure_voidspace(masks.large_void, total_mask, spacing, connectivity=params.connectivity)
+    write_metrics_csv(measurements_path, [_metric_row(metrics)])
+
+    return VoidspaceRunResult(large_path, all_path, measurements_path, metrics)
+
+
+def compare(
+    *,
+    baseline_void_path: Path | str,
+    followup_void_path: Path | str,
+    output_dir: Path | str,
+    mask_path: Path | str | None = None,
+    force: bool = False,
+) -> VoidspaceCompareResult:
+    """Compare already aligned baseline and follow-up voidspace masks."""
+    output_dir = Path(output_dir)
+    baseline, spacing, reference = read_mask(baseline_void_path)
+    mask_extension = _mask_extension(reference)
+    stable_path = output_dir / f"voidspace_stable_mask{mask_extension}"
+    expanded_path = output_dir / f"voidspace_expanded_mask{mask_extension}"
+    contracted_path = output_dir / f"voidspace_contracted_mask{mask_extension}"
+    measurements_path = output_dir / "voidspace_change_measurements.csv"
+    existing_outputs = [
+        path for path in (stable_path, expanded_path, contracted_path, measurements_path) if path.exists()
+    ]
+    if existing_outputs and not force:
+        raise FileExistsError(f"output already exists: {existing_outputs[0]}")
+
+    followup, followup_spacing, _followup_reference = read_mask(followup_void_path)
+    if followup_spacing != spacing or followup.shape != baseline.shape:
+        raise ValueError("baseline and followup void masks must already be aligned")
+
+    domain_mask = None
+    if mask_path is not None:
+        domain_mask, mask_spacing, _mask_reference = read_mask(mask_path)
+        if mask_spacing != spacing or domain_mask.shape != baseline.shape:
+            raise ValueError("mask must be aligned with the void masks")
+
+    change = classify_voidspace_change(baseline, followup, mask=domain_mask)
+    write_mask_like(change.stable, reference, stable_path)
+    write_mask_like(change.expanded, reference, expanded_path)
+    write_mask_like(change.contracted, reference, contracted_path)
+    metrics = measure_voidspace_change(change, spacing)
+    write_metrics_csv(
+        measurements_path,
+        [
+            {
+                "stable.VS.V": metrics.stable_volume_mm3,
+                "expanded.VS.V": metrics.expanded_volume_mm3,
+                "contracted.VS.V": metrics.contracted_volume_mm3,
+                "net.VS.V": metrics.net_change_volume_mm3,
+            }
+        ],
+    )
+    return VoidspaceCompareResult(
+        stable_path,
+        expanded_path,
+        contracted_path,
+        measurements_path,
+        metrics,
+    )
+
+
+run_voidspace_case = run_case
+run_voidspace_change_case = compare

voidspace-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+voidspace/__init__.py,sha256=lvcBRhs0JRNB5RDXGpE1hlDZ3MqRARFdZeqLJ6IW0hw,823
+voidspace/change.py,sha256=gI5y5NBOZj0MVTzkOGwCFMEcax_bTOO7YmX42XMEabo,1614
+voidspace/cli.py,sha256=KnDqWWM8qsLWNpiElFIPmbD7B4_yEfDMzzMQ1Xc_9TU,3702
+voidspace/io.py,sha256=GyoD_Ek_Z53ZgTuaUhnDZeqAX-WS-Xo2e7lopcaoESo,5293
+voidspace/metrics.py,sha256=9RaCi3ik_Ea8Ql_HZpZ3taA7KXUebmDrbuuWjZ9ij9M,1835
+voidspace/models.py,sha256=duy39QYj3xoo1TbGGmPX8FGkpHpbm3LxhXag2b5Nt44,2281
+voidspace/morphology.py,sha256=U03AbMzsB6uD1ehGl-ju0eivzQqX0d132qtcr8JE3Ps,3218
+voidspace/segment.py,sha256=XyifSLR9je46DCqD9VUcnhXSkDM57aqtI_jF_5_gr1s,3093
+voidspace/workflows.py,sha256=uqk0r3x_aYmtZzrGqN69TdHe3YIhFbVmdX6Ww3TMd7c,5029
+voidspace-0.1.0.dist-info/licenses/LICENSE,sha256=s4uvriA89nP0_DvvrvWoI7dplf8AtGVGOFp9yDO74IE,1071
+voidspace-0.1.0.dist-info/METADATA,sha256=VgI_UW-08BSqdSnSq1eyqKKyfwN6eaOwmPE0PRMmOV4,5086
+voidspace-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+voidspace-0.1.0.dist-info/entry_points.txt,sha256=7qlvG-szDtei8AJifqUjbIfvuyICJfqVVFaE3oIDweM,49
+voidspace-0.1.0.dist-info/top_level.txt,sha256=TXLDXiIXhXiYiJCImh9KpdNOqJDznV3tevg41-O4hOs,10
+voidspace-0.1.0.dist-info/RECORD,,

voidspace-0.1.0.dist-info/WHEEL

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

voidspace-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+voidspace = voidspace.cli:main

voidspace-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+voidspace