voidspace 0.1.3__tar.gz → 0.1.5__tar.gz

{voidspace-0.1.3/src/voidspace.egg-info → voidspace-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voidspace
-Version: 0.1.3
+Version: 0.1.5
 Summary: Spacing-aware voidspace analysis for HR-pQCT segmentations
 Author: Matthias Walle
 License-Expression: MIT
@@ -36,8 +36,10 @@ Dynamic: license-file
 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.
+scans or create common regions. It expects inputs already in the same physical
+space. File workflows place cropped masks on the reference grid with
+nearest-neighbor resampling using origin, spacing, and direction; this does not
+estimate registration between scans.
 
 The command line interface reads common SimpleITK image formats and Scanco AIM
 masks. AIM masks are read in native scaling, interpreted as foreground where
@@ -55,8 +57,19 @@ nonzero, and written back as native binary AIM masks using the input geometry.
 
 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.
+connected to lateral (in-plane) image borders, not the two scan ends. Supplying
+an explicit full bone mask remains preferred, especially for breached cortex.
+
+Closing and erosion use edge continuation along the scan axis before cropping
+back to the acquired volume. This assumes the endpoint cross-sections continue
+beyond the scan, rather than treating acquisition ends as empty biological space.
+Physical morphology radii and volume thresholds are unchanged. This boundary
+policy is not a validation of exact scanner/IPL equivalence.
+
+All voidspace includes large voidspace: the large map is a size-filtered subset.
+For common-region reporting, compute maps on the full bone domain with `run-case`,
+then use `analyze-maps` to clip and measure without recomputing morphology at the
+common-region boundaries. Force-rerun old outputs to apply these corrections.
 
 ## Algorithm
 

{voidspace-0.1.3 → voidspace-0.1.5}/README.md

@@ -3,8 +3,10 @@
 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.
+scans or create common regions. It expects inputs already in the same physical
+space. File workflows place cropped masks on the reference grid with
+nearest-neighbor resampling using origin, spacing, and direction; this does not
+estimate registration between scans.
 
 The command line interface reads common SimpleITK image formats and Scanco AIM
 masks. AIM masks are read in native scaling, interpreted as foreground where
@@ -22,8 +24,19 @@ nonzero, and written back as native binary AIM masks using the input geometry.
 
 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.
+connected to lateral (in-plane) image borders, not the two scan ends. Supplying
+an explicit full bone mask remains preferred, especially for breached cortex.
+
+Closing and erosion use edge continuation along the scan axis before cropping
+back to the acquired volume. This assumes the endpoint cross-sections continue
+beyond the scan, rather than treating acquisition ends as empty biological space.
+Physical morphology radii and volume thresholds are unchanged. This boundary
+policy is not a validation of exact scanner/IPL equivalence.
+
+All voidspace includes large voidspace: the large map is a size-filtered subset.
+For common-region reporting, compute maps on the full bone domain with `run-case`,
+then use `analyze-maps` to clip and measure without recomputing morphology at the
+common-region boundaries. Force-rerun old outputs to apply these corrections.
 
 ## Algorithm
 

{voidspace-0.1.3 → voidspace-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "voidspace"
-version = "0.1.3"
+version = "0.1.5"
 description = "Spacing-aware voidspace analysis for HR-pQCT segmentations"
 readme = "README.md"
 requires-python = ">=3.11"

{voidspace-0.1.3 → voidspace-0.1.5}/src/voidspace/__init__.py

@@ -12,7 +12,7 @@ from voidspace.models import (
 from voidspace.segment import segment_voidspace
 from voidspace.workflows import analyze_maps, compare, intersect_masks, run_case
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"
 
 __all__ = [
     "VoidspaceChangeMasks",

{voidspace-0.1.3 → voidspace-0.1.5}/src/voidspace/morphology.py

@@ -66,7 +66,7 @@ def remove_small_components(mask: np.ndarray, min_voxels: int, connectivity: int
     return keep[labels]
 
 
-def remove_border_connected_components(mask: np.ndarray, connectivity: int = 3) -> np.ndarray:
+def remove_border_connected_components(mask: np.ndarray, connectivity: int = 3, *, axes=(0, 1, 2)) -> np.ndarray:
     mask = np.asarray(mask, dtype=bool)
     if mask.ndim != 3:
         raise ValueError("mask must be a 3D array")
@@ -75,12 +75,10 @@ def remove_border_connected_components(mask: np.ndarray, connectivity: int = 3)
     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 = set()
+    for axis in axes:
+        border_labels.update(np.unique(np.take(labels, 0, axis=axis)))
+        border_labels.update(np.unique(np.take(labels, -1, axis=axis)))
     border_labels.discard(0)
     remove = np.zeros(count + 1, dtype=bool)
     if border_labels:

{voidspace-0.1.3 → voidspace-0.1.5}/src/voidspace/segment.py

@@ -25,6 +25,17 @@ def _validate_same_shape(*arrays: np.ndarray) -> None:
         raise ValueError(f"all masks must have the same shape, got {sorted(shapes)}")
 
 
+def _continue_scan_ends(mask, footprint, operation):
+    """Continue the endpoint slices, without continuing lateral exterior background."""
+    radius = footprint.shape[0] // 2
+    if radius == 0:
+        return operation(mask, structure=footprint, border_value=0)
+    # Closing contains a dilation and an erosion; retain both operations' support.
+    padding = 2 * radius
+    padded = np.pad(mask, ((padding, padding), (0, 0), (0, 0)), mode="edge")
+    return operation(padded, structure=footprint, border_value=0)[padding:-padding]
+
+
 def segment_voidspace(
     segmentation: np.ndarray,
     spacing_mm: tuple[float, float, float],
@@ -35,7 +46,7 @@ def segment_voidspace(
     bone = _validate_3d("segmentation", segmentation)
     if mask is None:
         domain = np.ones_like(bone, dtype=bool)
-        domain_source = "segmentation_border_background"
+        domain_source = "segmentation_lateral_background"
     else:
         domain = _validate_3d("mask", mask)
         _validate_same_shape(bone, domain)
@@ -47,11 +58,12 @@ def segment_voidspace(
         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
+    filled_bone = _continue_scan_ends(bone_in_domain, closing_fp, ndi.binary_closing) & domain
     if mask is None:
         interior_background = remove_border_connected_components(
             ~filled_bone,
             connectivity=params.connectivity,
+            axes=(1, 2),
         )
         domain = filled_bone | interior_background
         filled_bone = filled_bone & domain
@@ -59,7 +71,7 @@ def segment_voidspace(
 
     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 = _continue_scan_ends(candidate_void, erosion_fp, ndi.binary_erosion)
     candidate_void = candidate_void & domain
 
     all_void = remove_small_components(
@@ -81,5 +93,6 @@ def segment_voidspace(
             "min_large_void_volume_mm3": params.min_large_void_volume_mm3,
             "structuring_element": "spacing_aware_ellipsoid",
             "domain_source": domain_source,
+            "scan_end_policy": "edge_continuation",
         },
     )

{voidspace-0.1.3 → voidspace-0.1.5}/src/voidspace/workflows.py

@@ -34,7 +34,10 @@ def _reference_image(reference) -> sitk.Image:
 def _array_on_reference_grid(array, source_reference, target_reference) -> np.ndarray:
     source_image = _reference_image(source_reference)
     target_image = _reference_image(target_reference)
-    if source_image.GetSize() == target_image.GetSize() and source_image.GetOrigin() == target_image.GetOrigin():
+    if source_image.GetSize() == target_image.GetSize() and all(
+        np.allclose(getattr(source_image, getter)(), getattr(target_image, getter)(), rtol=0, atol=1e-6)
+        for getter in ("GetOrigin", "GetSpacing", "GetDirection")
+    ):
         return np.asarray(array, dtype=bool)
     image = sitk.GetImageFromArray(np.asarray(array, dtype=np.uint8))
     image.CopyInformation(source_image)
@@ -66,8 +69,14 @@ def intersect_masks(
     intersection, spacing, reference = read_mask(paths[0])
     for path in paths[1:]:
         mask, mask_spacing, mask_reference = read_mask(path)
-        if mask_spacing != spacing:
-            raise ValueError("all masks must have the same spacing")
+        # AIM header quantization and NIfTI float storage can differ below 1 nm.
+        # Tolerate that rounding, but do not silently mix scan resolutions.
+        if not np.allclose(mask_spacing, spacing, rtol=0, atol=1e-6):
+            raise ValueError(
+                f"mask spacing mismatch (z, y, x; mm): {paths[0]} has {spacing}; "
+                f"{path} has {mask_spacing}. Expected the matching native-space "
+                "common region at the same scan resolution."
+            )
         mask = _array_on_reference_grid(mask, mask_reference, reference)
         if mask.shape != intersection.shape:
             raise ValueError("all masks must overlap the reference image space")
@@ -98,9 +107,8 @@ def run_case(
         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")
+        domain_mask, _mask_spacing, mask_reference = read_mask(mask_path)
+        domain_mask = _array_on_reference_grid(domain_mask, mask_reference, reference)
     else:
         domain_mask = None
 
@@ -137,12 +145,10 @@ def analyze_maps(
     if existing_outputs and not force:
         raise FileExistsError(f"output already exists: {existing_outputs[0]}")
 
-    all_void, all_spacing, _all_reference = read_mask(all_void_path)
-    if all_spacing != spacing or all_void.shape != large_void.shape:
-        raise ValueError("large and all void masks must be in the same space")
-    domain_mask, mask_spacing, _mask_reference = read_mask(mask_path)
-    if mask_spacing != spacing or domain_mask.shape != large_void.shape:
-        raise ValueError("mask must be aligned with the void masks")
+    all_void, _all_spacing, all_reference = read_mask(all_void_path)
+    all_void = _array_on_reference_grid(all_void, all_reference, reference)
+    domain_mask, _mask_spacing, mask_reference = read_mask(mask_path)
+    domain_mask = _array_on_reference_grid(domain_mask, mask_reference, reference)
 
     masked_large_void = large_void & domain_mask
     masked_all_void = all_void & domain_mask
@@ -177,15 +183,13 @@ def compare(
     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")
+    followup, _followup_spacing, followup_reference = read_mask(followup_void_path)
+    followup = _array_on_reference_grid(followup, followup_reference, reference)
 
     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")
+        domain_mask, _mask_spacing, mask_reference = read_mask(mask_path)
+        domain_mask = _array_on_reference_grid(domain_mask, mask_reference, reference)
 
     change = classify_voidspace_change(baseline, followup, mask=domain_mask)
     write_mask_like(change.stable, reference, stable_path)

{voidspace-0.1.3 → voidspace-0.1.5/src/voidspace.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voidspace
-Version: 0.1.3
+Version: 0.1.5
 Summary: Spacing-aware voidspace analysis for HR-pQCT segmentations
 Author: Matthias Walle
 License-Expression: MIT
@@ -36,8 +36,10 @@ Dynamic: license-file
 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.
+scans or create common regions. It expects inputs already in the same physical
+space. File workflows place cropped masks on the reference grid with
+nearest-neighbor resampling using origin, spacing, and direction; this does not
+estimate registration between scans.
 
 The command line interface reads common SimpleITK image formats and Scanco AIM
 masks. AIM masks are read in native scaling, interpreted as foreground where
@@ -55,8 +57,19 @@ nonzero, and written back as native binary AIM masks using the input geometry.
 
 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.
+connected to lateral (in-plane) image borders, not the two scan ends. Supplying
+an explicit full bone mask remains preferred, especially for breached cortex.
+
+Closing and erosion use edge continuation along the scan axis before cropping
+back to the acquired volume. This assumes the endpoint cross-sections continue
+beyond the scan, rather than treating acquisition ends as empty biological space.
+Physical morphology radii and volume thresholds are unchanged. This boundary
+policy is not a validation of exact scanner/IPL equivalence.
+
+All voidspace includes large voidspace: the large map is a size-filtered subset.
+For common-region reporting, compute maps on the full bone domain with `run-case`,
+then use `analyze-maps` to clip and measure without recomputing morphology at the
+common-region boundaries. Force-rerun old outputs to apply these corrections.
 
 ## Algorithm
 

{voidspace-0.1.3 → voidspace-0.1.5}/tests/test_segment.py

@@ -3,6 +3,33 @@ import numpy as np
 from voidspace import VoidspaceParameters, segment_voidspace
 
 
+def _open_tube():
+    yy, xx = np.indices((65, 65))
+    radius = np.sqrt((xx - 32) ** 2 + (yy - 32) ** 2)
+    full = np.broadcast_to(radius < 25, (31, 65, 65)).copy()
+    cavity = np.broadcast_to(radius < 15, full.shape)
+    params = VoidspaceParameters(closing_radius_mm=1, boundary_erosion_radius_mm=1,
+                                min_large_void_volume_mm3=10,
+                                bone_speckle_min_voxels=1, void_speckle_min_voxels=1)
+    return full & ~cavity, full, params
+
+
+def test_open_end_void_survives_without_explicit_domain():
+    bone, full, params = _open_tube()
+    result = segment_voidspace(bone, (1, 1, 1), parameters=params)
+    assert result.large_void[:, 32, 32].all()
+    assert not result.all_void[~full].any()
+    assert not np.any(result.large_void & ~result.all_void)
+
+
+def test_end_slices_match_interior_for_uniform_tube():
+    bone, full, params = _open_tube()
+    result = segment_voidspace(bone, (1, 1, 1), mask=full, parameters=params)
+    assert np.array_equal(result.filled_bone[0], result.filled_bone[15])
+    assert np.array_equal(result.all_void[0], result.all_void[15])
+    assert np.array_equal(result.all_void[-1], result.all_void[15])
+
+
 def _solid_cube_with_cavity(size=31, cavity_radius=4):
     bone = np.zeros((size, size, size), dtype=bool)
     bone[4:-4, 4:-4, 4:-4] = True
@@ -65,6 +92,6 @@ def test_segment_voidspace_derives_internal_domain_without_periosteal_mask():
 
     result = segment_voidspace(bone, (0.061, 0.061, 0.061), parameters=params)
 
-    assert result.metadata["domain_source"] == "segmentation_border_background"
+    assert result.metadata["domain_source"] == "segmentation_lateral_background"
     assert result.large_void[cavity].any()
     assert not result.all_void[~peri].any()

{voidspace-0.1.3 → voidspace-0.1.5}/tests/test_workflows.py

@@ -2,6 +2,23 @@ import numpy as np
 import SimpleITK as sitk
 
 from voidspace import VoidspaceParameters, analyze_maps, compare, intersect_masks, run_case
+import pytest
+
+
+@pytest.mark.parametrize("size, origin", [(3, (1, 1, 1)), (5, (1, 0, 0))])
+def test_run_case_places_analysis_mask_on_segmentation_grid(tmp_path, size, origin):
+    segmentation = np.zeros((5, 5, 5), dtype=np.uint8)
+    _write_mask(tmp_path / "seg.nii.gz", segmentation)
+    mask_image = sitk.GetImageFromArray(np.ones((size,) * 3, dtype=np.uint8))
+    mask_image.SetOrigin(origin)
+    sitk.WriteImage(mask_image, str(tmp_path / "domain.nii.gz"))
+    result = run_case(segmentation_path=tmp_path / "seg.nii.gz",
+                      mask_path=tmp_path / "domain.nii.gz", output_dir=tmp_path / "out",
+                      parameters=VoidspaceParameters(closing_radius_mm=0, boundary_erosion_radius_mm=0,
+                          min_large_void_volume_mm3=0, bone_speckle_min_voxels=1, void_speckle_min_voxels=1))
+    assert result.metrics.total_volume_mm3 == (27 if size == 3 else 100)
+    output = sitk.GetArrayFromImage(sitk.ReadImage(str(result.all_mask_path)))
+    assert not output[:, :, 0].any()
 
 
 def _write_mask(path, array):
@@ -99,6 +116,47 @@ def test_intersect_masks_writes_boolean_intersection(tmp_path):
     assert np.array_equal(result, full & common)
 
 
+@pytest.mark.parametrize("shift", [0.0, 0.0607])
+@pytest.mark.parametrize("source_spacing, common_spacing", [
+    ((0.0607,) * 3, (float(np.float32(0.0607)),) * 3),
+    ((0.06069900095462799, 0.06069900095462799, 0.06069599837064743),
+     (0.06069965288043022, 0.06069965288043022, 0.06069643050432205)),
+])
+def test_intersect_masks_accepts_header_rounding_and_preserves_physical_placement(
+    tmp_path, shift, source_spacing, common_spacing,
+):
+    full = sitk.GetImageFromArray(np.ones((5, 5, 5), dtype=np.uint8))
+    full.SetSpacing(source_spacing)
+    sitk.WriteImage(full, str(tmp_path / "full.mha"))
+    common = sitk.GetImageFromArray(np.ones((3, 3, 3), dtype=np.uint8))
+    common.SetSpacing(common_spacing)
+    common.SetOrigin((shift,) * 3)
+    sitk.WriteImage(common, str(tmp_path / "common.nii.gz"))
+
+    output = intersect_masks(
+        [tmp_path / "full.mha", tmp_path / "common.nii.gz"],
+        output_path=tmp_path / "intersection.nii.gz",
+    )
+    image = sitk.ReadImage(str(output))
+    expected = np.zeros((5, 5, 5), dtype=bool)
+    start = 0 if shift == 0 else 1
+    expected[start:start + 3, start:start + 3, start:start + 3] = True
+    assert np.array_equal(sitk.GetArrayFromImage(image).astype(bool), expected)
+    assert np.allclose(image.GetSpacing(), source_spacing, rtol=0, atol=1e-8)
+
+
+def test_intersect_masks_reports_genuinely_different_resolution(tmp_path):
+    for name, spacing in [("full", 0.0607), ("common", 0.082)]:
+        image = sitk.GetImageFromArray(np.ones((3, 3, 3), dtype=np.uint8))
+        image.SetSpacing((spacing,) * 3)
+        sitk.WriteImage(image, str(tmp_path / f"{name}.mha"))
+    with pytest.raises(ValueError, match="spacing.*full.*common"):
+        intersect_masks(
+            [tmp_path / "full.mha", tmp_path / "common.mha"],
+            output_path=tmp_path / "intersection.nii.gz",
+        )
+
+
 def test_intersect_masks_resamples_cropped_mask_to_reference_grid(tmp_path):
     full = np.ones((5, 5, 5), dtype=bool)
     common = np.ones((3, 3, 3), dtype=bool)
@@ -119,3 +177,28 @@ def test_intersect_masks_resamples_cropped_mask_to_reference_grid(tmp_path):
     expected[1:4, 1:4, 1:4] = True
     assert image.GetSize() == (5, 5, 5)
     assert np.array_equal(result, expected)
+
+
+def test_analyze_maps_honors_direction_with_matching_sizes_and_origins(tmp_path):
+    full = np.ones((5, 5, 5), dtype=bool)
+    _write_mask(tmp_path / "all.nii.gz", full)
+    _write_mask(tmp_path / "large.nii.gz", full)
+    mask = sitk.GetImageFromArray(full.astype(np.uint8))
+    mask.SetDirection((-1, 0, 0, 0, 1, 0, 0, 0, 1))
+    sitk.WriteImage(mask, str(tmp_path / "domain.nii.gz"))
+    result = analyze_maps(large_void_path=tmp_path / "large.nii.gz", all_void_path=tmp_path / "all.nii.gz",
+                          mask_path=tmp_path / "domain.nii.gz", output_dir=tmp_path / "out")
+    assert result.metrics.total_volume_mm3 == 25
+
+
+def test_compare_places_cropped_maps_in_same_physical_space(tmp_path):
+    baseline = np.zeros((5, 5, 5), dtype=bool)
+    baseline[2, 2, 2] = True
+    _write_mask(tmp_path / "baseline.nii.gz", baseline)
+    cropped = sitk.GetImageFromArray(np.ones((1, 1, 1), dtype=np.uint8))
+    cropped.SetOrigin((2, 2, 2))
+    sitk.WriteImage(cropped, str(tmp_path / "followup.nii.gz"))
+    result = compare(baseline_void_path=tmp_path / "baseline.nii.gz",
+                     followup_void_path=tmp_path / "followup.nii.gz", output_dir=tmp_path / "out")
+    assert result.metrics.stable_volume_mm3 == 1
+    assert result.metrics.expanded_volume_mm3 == result.metrics.contracted_volume_mm3 == 0