bone-contouring 0.1.0__tar.gz

bone_contouring-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+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.
+

bone_contouring-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: bone-contouring
+Version: 0.1.0
+Summary: SimpleITK-first bone contour and mask generation for volumetric bone images
+Author: Matthias Walle
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3.0,>=1.26
+Requires-Dist: SimpleITK>=2.3
+Provides-Extra: geodesic
+Requires-Dist: hrpqct-geodesic-contour>=0.1.2; extra == "geodesic"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# bone-contouring
+
+SimpleITK-first bone contouring and mask generation for volumetric bone images.
+
+```python
+from bone_contouring import generate_masks_from_image, resolve_preset
+
+masks = generate_masks_from_image(image, resolve_preset(modality="xct1", site="radius"))
+```

bone_contouring-0.1.0/README.md

@@ -0,0 +1,9 @@
+# bone-contouring
+
+SimpleITK-first bone contouring and mask generation for volumetric bone images.
+
+```python
+from bone_contouring import generate_masks_from_image, resolve_preset
+
+masks = generate_masks_from_image(image, resolve_preset(modality="xct1", site="radius"))
+```

bone_contouring-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bone-contouring"
+version = "0.1.0"
+description = "SimpleITK-first bone contour and mask generation for volumetric bone images"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Matthias Walle" }]
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+  "numpy>=1.26,<3.0",
+  "SimpleITK>=2.3",
+]
+
+[project.optional-dependencies]
+geodesic = ["hrpqct-geodesic-contour>=0.1.2"]
+test = ["pytest>=8"]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

bone_contouring-0.1.0/setup.cfg

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

bone_contouring-0.1.0/src/bone_contouring/__init__.py

@@ -0,0 +1,22 @@
+"""SimpleITK-first contour and bone-mask generation."""
+
+from .parameters import (
+    ContourParameters,
+    InnerContourParameters,
+    OuterContourParameters,
+    SegmentationParameters,
+)
+from .presets import load_preset, resolve_preset
+from .api import GeneratedMasks, generate_bone_segmentation, generate_masks_from_image
+
+__all__ = [
+    "ContourParameters",
+    "GeneratedMasks",
+    "InnerContourParameters",
+    "OuterContourParameters",
+    "SegmentationParameters",
+    "generate_bone_segmentation",
+    "generate_masks_from_image",
+    "load_preset",
+    "resolve_preset",
+]

bone_contouring-0.1.0/src/bone_contouring/_arrays.py

@@ -0,0 +1,303 @@
+"""Internal x/y/z array algorithms and SimpleITK conversion helpers."""
+
+from __future__ import annotations
+
+import numpy as np
+import SimpleITK as sitk
+
+from .laplace_hamming import LaplaceHammingParameters, laplace_hamming_binarize_xyz
+from .parameters import InnerContourParameters, OuterContourParameters, SegmentationParameters
+
+
+def sitk_to_numpy_xyz(image: sitk.Image) -> np.ndarray:
+    """Convert a SimpleITK image from z/y/x storage to contiguous x/y/z data."""
+    return np.ascontiguousarray(np.transpose(sitk.GetArrayFromImage(image), (2, 1, 0)))
+
+
+def numpy_xyz_to_sitk_binary(mask_xyz: np.ndarray, reference: sitk.Image) -> sitk.Image:
+    """Create a uint8 binary image with geometry copied from ``reference``."""
+    image = sitk.GetImageFromArray(np.transpose(np.asarray(mask_xyz, dtype=np.uint8), (2, 1, 0)))
+    image.CopyInformation(reference)
+    return sitk.Cast(image > 0, sitk.sitkUInt8)
+
+
+def numpy_xyz_to_sitk_scalar(
+    image_xyz: np.ndarray, spacing_xyz: tuple[float, float, float] | None = None
+) -> sitk.Image:
+    """Create a float32 image from x/y/z scalar data."""
+    image = sitk.GetImageFromArray(np.transpose(np.asarray(image_xyz, dtype=np.float32), (2, 1, 0)))
+    if spacing_xyz is not None:
+        image.SetSpacing(tuple(float(value) for value in spacing_xyz))
+    return image
+
+
+def remove_small_components_xyz(mask_xyz: np.ndarray, min_size_voxels: int) -> np.ndarray:
+    """Remove 6-connected components smaller than ``min_size_voxels``."""
+    mask = np.asarray(mask_xyz, dtype=bool)
+    if min_size_voxels <= 0 or not np.any(mask):
+        return np.ascontiguousarray(mask)
+    image = sitk.GetImageFromArray(np.transpose(mask.astype(np.uint8), (2, 1, 0)))
+    labels = sitk.ConnectedComponent(image, False)
+    retained = sitk.RelabelComponent(labels, minimumObjectSize=int(min_size_voxels), sortByObjectSize=False)
+    return np.ascontiguousarray(np.transpose(sitk.GetArrayFromImage(retained > 0), (2, 1, 0)).astype(bool))
+
+
+def largest_component_xyz(mask_xyz: np.ndarray) -> np.ndarray:
+    """Return the largest 6-connected component, preserving an empty mask."""
+    mask = np.asarray(mask_xyz, dtype=bool)
+    if not np.any(mask):
+        return np.ascontiguousarray(mask)
+    image = sitk.GetImageFromArray(np.transpose(mask.astype(np.uint8), (2, 1, 0)))
+    labels = sitk.RelabelComponent(sitk.ConnectedComponent(image, False), sortByObjectSize=True)
+    return np.ascontiguousarray(np.transpose(sitk.GetArrayFromImage(labels == 1), (2, 1, 0)).astype(bool))
+
+
+def smooth_xyz(
+    image_xyz: np.ndarray,
+    *,
+    sigma: float,
+    spacing_xyz: tuple[float, float, float] | None = None,
+) -> np.ndarray:
+    """Smooth an image with the same voxel-relative sigma convention as Timelapsed."""
+    if sigma <= 0:
+        return np.asarray(image_xyz, dtype=np.float32).copy()
+    image = numpy_xyz_to_sitk_scalar(image_xyz, spacing_xyz)
+    spacing = image.GetSpacing()
+    smoothed = sitk.SmoothingRecursiveGaussian(image, float(sigma) * min(spacing))
+    return sitk_to_numpy_xyz(smoothed)
+
+
+def adaptive_threshold_xyz(
+    density_xyz: np.ndarray,
+    *,
+    spacing_xyz: tuple[float, float, float] | None = None,
+    low_threshold: float = 190.0,
+    high_threshold: float = 450.0,
+    block_size: int = 13,
+    min_size_voxels: int = 64,
+) -> np.ndarray:
+    """Apply Schulte-style combined adaptive thresholding in x/y/z order."""
+    density = np.asarray(density_xyz, dtype=np.float32)
+    if density.ndim != 3:
+        raise ValueError(f"adaptive_threshold_xyz expects a 3D array, got ndim={density.ndim}.")
+    if block_size % 2 == 0:
+        raise ValueError(f"block_size must be odd, got {block_size}.")
+    image = numpy_xyz_to_sitk_scalar(density, spacing_xyz)
+    local_mean = sitk_to_numpy_xyz(sitk.BoxMean(image, [block_size // 2] * 3))
+    filtered = smooth_xyz(density, sigma=1.0, spacing_xyz=spacing_xyz)
+    low_mask = filtered > float(low_threshold)
+    result = (filtered * low_mask > local_mean * low_mask) | (filtered > float(high_threshold))
+    return remove_small_components_xyz(result, min_size_voxels)
+
+
+def _laplace_hamming_parameters(params: SegmentationParameters) -> LaplaceHammingParameters:
+    return LaplaceHammingParameters(
+        low_pass_cutoff=params.laplace_hamming_low_pass_cutoff,
+        high_pass_cutoff=params.laplace_hamming_high_pass_cutoff,
+        laplace_epsilon=params.laplace_hamming_epsilon,
+        hamming_amplitude=params.laplace_hamming_amplitude,
+        amplification=params.laplace_hamming_amplification,
+        input_offset=params.laplace_hamming_input_offset,
+        ipl_float_max=params.laplace_hamming_ipl_float_max,
+        int16_max=params.laplace_hamming_int16_max,
+        threshold=params.laplace_hamming_threshold,
+        min_size_voxels=params.laplace_hamming_min_size_voxels,
+        backend=params.laplace_hamming_backend,
+    )
+
+
+def segment_bone_xyz(
+    image_xyz: np.ndarray,
+    full_mask_xyz: np.ndarray,
+    trab_mask_xyz: np.ndarray,
+    cort_mask_xyz: np.ndarray,
+    parameters: SegmentationParameters,
+    *,
+    spacing_xyz: tuple[float, float, float] | None = None,
+) -> np.ndarray:
+    """Generate a cleaned bone segmentation constrained to the full mask."""
+    full = np.asarray(full_mask_xyz, dtype=bool)
+    if not parameters.enabled:
+        return np.ascontiguousarray(full)
+    method = parameters.method.strip().lower()
+    if method in {"global", "seg_gauss"}:
+        method = "gauss"
+    if method == "gauss":
+        filtered = smooth_xyz(image_xyz, sigma=parameters.gaussian_sigma, spacing_xyz=spacing_xyz)
+        segmentation = ((filtered >= parameters.trab_threshold) & np.asarray(trab_mask_xyz, dtype=bool)) | (
+            (filtered >= parameters.cort_threshold) & np.asarray(cort_mask_xyz, dtype=bool)
+        )
+    elif method == "adaptive":
+        segmentation = adaptive_threshold_xyz(
+            image_xyz,
+            spacing_xyz=spacing_xyz,
+            low_threshold=parameters.adaptive_low_threshold,
+            high_threshold=parameters.adaptive_high_threshold,
+            block_size=parameters.adaptive_block_size,
+            min_size_voxels=parameters.min_size_voxels,
+        )
+    elif method == "laplace_hamming":
+        segmentation = laplace_hamming_binarize_xyz(
+            image_xyz,
+            full_mask_xyz=full,
+            spacing_xyz=spacing_xyz,
+            parameters=_laplace_hamming_parameters(parameters),
+        )
+    else:
+        raise ValueError(f"Unsupported segmentation method: {parameters.method!r}.")
+    segmentation = remove_small_components_xyz(segmentation & full, parameters.min_size_voxels)
+    if method != "laplace_hamming" and parameters.keep_largest_component:
+        segmentation = largest_component_xyz(segmentation)
+    return np.ascontiguousarray(segmentation, dtype=bool)
+
+
+def contour_support_xyz(
+    image_xyz: np.ndarray,
+    parameters: SegmentationParameters,
+    *,
+    spacing_xyz: tuple[float, float, float] | None = None,
+    full_mask_xyz: np.ndarray | None = None,
+    role: str = "outer",
+) -> np.ndarray | None:
+    """Create a temporary contour-support mask from the selected segmentation method."""
+    if not parameters.enabled:
+        return None
+    method = parameters.method.strip().lower()
+    if method in {"global", "seg_gauss"}:
+        method = "gauss"
+    if full_mask_xyz is None:
+        full_mask = np.ones(np.asarray(image_xyz).shape, dtype=bool)
+    else:
+        full_mask = np.asarray(full_mask_xyz, dtype=bool)
+    if method == "gauss":
+        filtered = smooth_xyz(image_xyz, sigma=parameters.gaussian_sigma, spacing_xyz=spacing_xyz)
+        threshold = parameters.trab_threshold if role == "outer" else parameters.cort_threshold
+        support = filtered >= float(threshold)
+    elif method == "adaptive":
+        support = adaptive_threshold_xyz(
+            image_xyz,
+            spacing_xyz=spacing_xyz,
+            low_threshold=parameters.adaptive_low_threshold,
+            high_threshold=parameters.adaptive_high_threshold,
+            block_size=parameters.adaptive_block_size,
+            min_size_voxels=parameters.min_size_voxels,
+        )
+    elif method == "laplace_hamming":
+        support = laplace_hamming_binarize_xyz(
+            image_xyz,
+            full_mask_xyz=full_mask,
+            spacing_xyz=spacing_xyz,
+            parameters=_laplace_hamming_parameters(parameters),
+        )
+    else:
+        return None
+    return np.ascontiguousarray(np.asarray(support, dtype=bool) & full_mask)
+
+
+def _apply_xy_morphology(mask_xyz: np.ndarray, radius: int, operation: str) -> np.ndarray:
+    """Apply a 2D binary morphology operation independently to every stack slice."""
+    mask = np.asarray(mask_xyz, dtype=bool)
+    if radius <= 0:
+        return np.ascontiguousarray(mask)
+    output = np.zeros_like(mask)
+    for z_index in range(mask.shape[2]):
+        slice_image = sitk.GetImageFromArray(mask[:, :, z_index].T.astype(np.uint8))
+        if operation == "close":
+            processed = sitk.BinaryMorphologicalClosing(slice_image, [radius, radius])
+        elif operation == "open":
+            processed = sitk.BinaryMorphologicalOpening(slice_image, [radius, radius])
+        elif operation == "erode":
+            processed = sitk.BinaryErode(slice_image, [radius, radius])
+        else:  # pragma: no cover - private caller supplies fixed operations
+            raise ValueError(f"Unsupported morphology operation: {operation}.")
+        output[:, :, z_index] = sitk.GetArrayFromImage(processed).T > 0
+    return output
+
+
+def fill_holes_xy(mask_xyz: np.ndarray) -> np.ndarray:
+    """Fill holes in each axial slice, including holes at terminal slices."""
+    mask = np.asarray(mask_xyz, dtype=bool)
+    output = np.zeros_like(mask)
+    for z_index in range(mask.shape[2]):
+        slice_image = sitk.GetImageFromArray(mask[:, :, z_index].T.astype(np.uint8))
+        output[:, :, z_index] = sitk.GetArrayFromImage(sitk.BinaryFillhole(slice_image)).T > 0
+    return output
+
+
+def outer_contour_xyz(
+    density_xyz: np.ndarray,
+    parameters: OuterContourParameters,
+    *,
+    spacing_xyz: tuple[float, float, float] | None = None,
+    support_mask_xyz: np.ndarray | None = None,
+) -> np.ndarray:
+    """Create a component-cleaned, hole-filled periosteal mask in x/y/z order."""
+    density = np.asarray(density_xyz, dtype=np.float32)
+    if density.ndim != 3:
+        raise ValueError(f"outer_contour_xyz expects a 3D array, got ndim={density.ndim}.")
+    if support_mask_xyz is None and not np.any(density != 0):
+        return np.zeros_like(density, dtype=bool)
+    if support_mask_xyz is not None:
+        thresholded = np.asarray(support_mask_xyz, dtype=bool)
+        if thresholded.shape != density.shape:
+            raise ValueError("support_mask_xyz shape must match density_xyz shape.")
+    elif parameters.use_adaptive_threshold:
+        thresholded = adaptive_threshold_xyz(density, spacing_xyz=spacing_xyz, min_size_voxels=0)
+    else:
+        thresholded = smooth_xyz(density, sigma=parameters.gaussian_sigma, spacing_xyz=spacing_xyz) >= float(
+            parameters.periosteal_threshold
+        )
+    if support_mask_xyz is None:
+        thresholded &= density != 0
+    thresholded = largest_component_xyz(thresholded)
+    thresholded = _apply_xy_morphology(thresholded, parameters.periosteal_kernel_size, "close")
+    thresholded = _apply_xy_morphology(thresholded, parameters.periosteal_open_radius, "open")
+    if parameters.fill_holes:
+        thresholded = fill_holes_xy(thresholded)
+    return np.ascontiguousarray(thresholded, dtype=bool)
+
+
+def _site_trabecular_close_radius(site: str) -> int:
+    return 15 if site.strip().lower() == "radius" else 25
+
+
+def inner_contour_xyz(
+    density_xyz: np.ndarray,
+    full_mask_xyz: np.ndarray,
+    parameters: InnerContourParameters,
+    *,
+    spacing_xyz: tuple[float, float, float] | None = None,
+    support_mask_xyz: np.ndarray | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Derive trabecular and cortical masks within a full periosteal mask."""
+    density = np.asarray(density_xyz, dtype=np.float32)
+    full = np.asarray(full_mask_xyz, dtype=bool)
+    if density.shape != full.shape:
+        raise ValueError("density_xyz and full_mask_xyz must have matching shapes.")
+    if not np.any(full):
+        empty = np.zeros_like(full)
+        return empty, empty
+    if support_mask_xyz is not None:
+        cortical = np.asarray(support_mask_xyz, dtype=bool)
+        if cortical.shape != full.shape:
+            raise ValueError("support_mask_xyz shape must match density_xyz shape.")
+    elif parameters.use_adaptive_threshold:
+        cortical = adaptive_threshold_xyz(density, spacing_xyz=spacing_xyz, min_size_voxels=0)
+    else:
+        cortical = smooth_xyz(density, sigma=parameters.gaussian_sigma, spacing_xyz=spacing_xyz) >= float(
+            parameters.endosteal_threshold
+        )
+    cortical &= full
+    if parameters.peel >= min(full.shape[:2]):
+        inner_support = np.zeros_like(full)
+    else:
+        inner_support = _apply_xy_morphology(full, parameters.peel, "erode")
+    trabecular = largest_component_xyz(inner_support & ~cortical)
+    close_radius = parameters.trabecular_close_radius
+    if close_radius is None:
+        close_radius = _site_trabecular_close_radius(parameters.site)
+    if close_radius > 0 and np.any(trabecular):
+        trabecular = _apply_xy_morphology(trabecular, close_radius, "close")
+        trabecular &= inner_support
+    cortical_mask = full & ~trabecular
+    return np.ascontiguousarray(trabecular), np.ascontiguousarray(cortical_mask)

bone_contouring-0.1.0/src/bone_contouring/api.py

@@ -0,0 +1,218 @@
+"""SimpleITK-first public contour and mask-generation API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import SimpleITK as sitk
+
+from ._arrays import (
+    contour_support_xyz,
+    inner_contour_xyz,
+    numpy_xyz_to_sitk_binary,
+    outer_contour_xyz,
+    segment_bone_xyz,
+    sitk_to_numpy_xyz,
+)
+from .parameters import ContourParameters
+from .presets import resolve_preset
+
+
+@dataclass(slots=True)
+class GeneratedMasks:
+    """Geometry-preserving masks generated from one input image."""
+
+    seg: sitk.Image
+    full: sitk.Image
+    trab: sitk.Image
+    cort: sitk.Image
+    mask_provenance: dict[str, str]
+    metadata: dict[str, Any]
+
+
+def _validate_image(image: sitk.Image, label: str) -> None:
+    if not isinstance(image, sitk.Image):
+        raise TypeError(f"{label} must be a SimpleITK.Image.")
+    if image.GetDimension() != 3:
+        raise ValueError(f"{label} must be three-dimensional, got {image.GetDimension()}D.")
+
+
+def _geodesic_outer_contour(
+    density_xyz: np.ndarray,
+    parameters: ContourParameters,
+    spacing_xyz: tuple[float, float, float],
+) -> tuple[np.ndarray, dict[str, Any]]:
+    try:
+        from hrpqct_geodesic_contour import contour
+    except ImportError as exc:
+        raise RuntimeError(
+            "Geodesic outer contouring requires the optional 'hrpqct-geodesic-contour' dependency."
+        ) from exc
+    full_mask, support_masks = contour(
+        density_xyz,
+        voxel_size_mm=spacing_xyz,
+        bone_threshold=parameters.outer.geodesic_bone_threshold,
+        fill_holes=parameters.outer.geodesic_fill_holes,
+    )
+    full = np.asarray(full_mask, dtype=bool)
+    if full.shape != density_xyz.shape:
+        raise ValueError("Geodesic contour output shape must match the input image shape.")
+    return full, {"support_mask_count": len(support_masks)}
+
+
+def _valid_partition(full: np.ndarray, trab: np.ndarray, cort: np.ndarray) -> tuple[bool, str | None]:
+    if not np.any(full):
+        return True, None
+    if not np.any(trab):
+        return False, "empty_trabecular_mask"
+    if np.any(trab & cort) or np.any((trab | cort) & ~full):
+        return False, "invalid_compartment_partition"
+    if float(trab.sum()) / float(full.sum()) < 0.01:
+        return False, "implausibly_small_trabecular_fraction"
+    return True, None
+
+
+def generate_masks_from_image(
+    image: sitk.Image,
+    parameters: ContourParameters | None = None,
+    *,
+    segmentation_image: sitk.Image | None = None,
+) -> GeneratedMasks:
+    """Generate `seg`, `full`, `trab`, and `cort` masks from a 3D SimpleITK image."""
+    _validate_image(image, "image")
+    params = parameters or resolve_preset()
+    density_xyz = sitk_to_numpy_xyz(image)
+    spacing_xyz = tuple(float(value) for value in image.GetSpacing())
+    segmentation_source = image if segmentation_image is None else segmentation_image
+    _validate_image(segmentation_source, "segmentation_image")
+    segmentation_xyz = sitk_to_numpy_xyz(segmentation_source)
+    if segmentation_xyz.shape != density_xyz.shape:
+        raise ValueError("segmentation_image size must match image size.")
+    aligned_support_enabled = bool(params.segmentation.use_segmentation_aligned_contour_support)
+    segmentation_method = params.segmentation.method.strip().lower()
+    if segmentation_method in {"global", "seg_gauss"}:
+        segmentation_method = "gauss"
+    reusable_segmentation_support = None
+
+    outer_method = params.outer.contour_method.strip().lower()
+    outer_metadata: dict[str, Any] = {}
+    if outer_method == "standard":
+        outer_support = None
+        if aligned_support_enabled:
+            outer_support = contour_support_xyz(
+                segmentation_xyz,
+                params.segmentation,
+                spacing_xyz=spacing_xyz,
+                role="outer",
+            )
+            if segmentation_method == "laplace_hamming":
+                reusable_segmentation_support = outer_support
+        full_xyz = outer_contour_xyz(
+            density_xyz,
+            params.outer,
+            spacing_xyz=spacing_xyz,
+            support_mask_xyz=outer_support,
+        )
+        outer_metadata = {
+            "support": "segmentation_aligned" if outer_support is not None else "image_threshold",
+            "outer_method": segmentation_method if outer_support is not None else None,
+        }
+    elif outer_method == "geodesic":
+        full_xyz, outer_metadata = _geodesic_outer_contour(density_xyz, params, spacing_xyz)
+    else:
+        raise ValueError(f"Unsupported outer contour method: {params.outer.contour_method!r}.")
+
+    inner_method = params.inner.contour_method.strip().lower()
+    fallback = {"applied": False, "reason": None}
+    if inner_method == "none":
+        trab_xyz = full_xyz.copy()
+        cort_xyz = np.zeros_like(full_xyz)
+    elif inner_method == "standard":
+        inner_support = None
+        if aligned_support_enabled:
+            if segmentation_method == "laplace_hamming" and reusable_segmentation_support is not None:
+                inner_support = np.asarray(reusable_segmentation_support, dtype=bool) & full_xyz
+            else:
+                inner_support = contour_support_xyz(
+                    segmentation_xyz,
+                    params.segmentation,
+                    spacing_xyz=spacing_xyz,
+                    full_mask_xyz=full_xyz,
+                    role="inner",
+                )
+        trab_xyz, cort_xyz = inner_contour_xyz(
+            density_xyz,
+            full_xyz,
+            params.inner,
+            spacing_xyz=spacing_xyz,
+            support_mask_xyz=inner_support,
+        )
+        valid_partition, reason = _valid_partition(full_xyz, trab_xyz, cort_xyz)
+        if not valid_partition:
+            trab_xyz = full_xyz.copy()
+            cort_xyz = np.zeros_like(full_xyz)
+            fallback = {"applied": True, "reason": reason}
+    else:
+        raise ValueError(f"Unsupported inner contour method: {params.inner.contour_method!r}.")
+
+    if segmentation_method == "laplace_hamming" and reusable_segmentation_support is not None:
+        seg_xyz = np.asarray(reusable_segmentation_support, dtype=bool) & full_xyz
+    else:
+        seg_xyz = segment_bone_xyz(
+            segmentation_xyz,
+            full_xyz,
+            trab_xyz,
+            cort_xyz,
+            params.segmentation,
+            spacing_xyz=spacing_xyz,
+        )
+    metadata = {
+        "modality": params.modality,
+        "site": params.site,
+        "segmentation_method": params.segmentation.method,
+        "periosteal_contour_method": outer_method,
+        "endosteal_contour_method": inner_method,
+        "endosteal_fallback": fallback,
+        "outer_contour": outer_metadata,
+        "contour_support": outer_metadata,
+    }
+    return GeneratedMasks(
+        seg=numpy_xyz_to_sitk_binary(seg_xyz, image),
+        full=numpy_xyz_to_sitk_binary(full_xyz, image),
+        trab=numpy_xyz_to_sitk_binary(trab_xyz, image),
+        cort=numpy_xyz_to_sitk_binary(cort_xyz, image),
+        mask_provenance={"seg": "generated", "full": "generated", "trab": "generated", "cort": "generated"},
+        metadata=metadata,
+    )
+
+
+def generate_bone_segmentation(
+    image: sitk.Image,
+    parameters: ContourParameters | None = None,
+    *,
+    full_mask: sitk.Image | None = None,
+    trab_mask: sitk.Image | None = None,
+    cort_mask: sitk.Image | None = None,
+) -> sitk.Image:
+    """Generate a binary bone segmentation, optionally within supplied masks."""
+    _validate_image(image, "image")
+    params = parameters or resolve_preset()
+    if full_mask is None and trab_mask is None and cort_mask is None:
+        return generate_masks_from_image(image, params).seg
+    if full_mask is None or trab_mask is None or cort_mask is None:
+        raise ValueError("full_mask, trab_mask, and cort_mask must be supplied together.")
+    for label, mask in (("full_mask", full_mask), ("trab_mask", trab_mask), ("cort_mask", cort_mask)):
+        _validate_image(mask, label)
+        if mask.GetSize() != image.GetSize():
+            raise ValueError(f"{label} size must match image size.")
+    segmentation_xyz = segment_bone_xyz(
+        sitk_to_numpy_xyz(image),
+        sitk_to_numpy_xyz(full_mask) > 0,
+        sitk_to_numpy_xyz(trab_mask) > 0,
+        sitk_to_numpy_xyz(cort_mask) > 0,
+        params.segmentation,
+        spacing_xyz=tuple(float(value) for value in image.GetSpacing()),
+    )
+    return numpy_xyz_to_sitk_binary(segmentation_xyz, image)

bone_contouring-0.1.0/src/bone_contouring/laplace_hamming.py

@@ -0,0 +1,123 @@
+"""Laplace-Hamming HR-pQCT segmentation on x/y/z NumPy arrays."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import SimpleITK as sitk
+
+
+@dataclass(slots=True)
+class LaplaceHammingParameters:
+    """Parameters for the IPL-style Laplace-Hamming binarization."""
+
+    low_pass_cutoff: float = 0.3
+    high_pass_cutoff: float = 0.0
+    laplace_epsilon: float = 0.45
+    hamming_amplitude: float = 1.0
+    amplification: float = 1.0
+    input_offset: float = 0.0
+    ipl_float_max: float = 200000.0
+    int16_max: float = 32767.0
+    threshold: float = 15564.0
+    min_size_voxels: int = 70
+    backend: str = "cpu"
+
+
+def _remove_small_components_6(binary: np.ndarray, min_size_voxels: int) -> np.ndarray:
+    if min_size_voxels <= 0 or not np.any(binary):
+        return np.ascontiguousarray(binary, dtype=bool)
+    image = sitk.GetImageFromArray(np.transpose(np.asarray(binary, dtype=np.uint8), (2, 1, 0)))
+    labels = sitk.ConnectedComponent(image, False)
+    retained = sitk.RelabelComponent(labels, minimumObjectSize=int(min_size_voxels), sortByObjectSize=False)
+    array = sitk.GetArrayFromImage(retained > 0)
+    return np.ascontiguousarray(np.transpose(array.astype(bool), (2, 1, 0)))
+
+
+def _mirror_pad_to_power_of_two(array: np.ndarray) -> tuple[np.ndarray, tuple[slice, slice, slice]]:
+    pad_widths: list[tuple[int, int]] = []
+    slices: list[slice] = []
+    for size in array.shape:
+        target = 1 if size <= 1 else 2 ** int(np.ceil(np.log2(size)))
+        total = target - size
+        lower = total // 2
+        pad_widths.append((lower, total - lower))
+        slices.append(slice(lower, lower + size))
+    return np.pad(array, pad_widths, mode="reflect"), tuple(slices)  # type: ignore[return-value]
+
+
+def laplace_hamming_filter_xyz(
+    image_xyz: np.ndarray,
+    *,
+    spacing_xyz: tuple[float, float, float] | None = None,
+    parameters: LaplaceHammingParameters | None = None,
+) -> np.ndarray:
+    """Apply the Laplace-Hamming frequency-domain filter to an x/y/z image."""
+    p = parameters or LaplaceHammingParameters()
+    backend = p.backend.strip().lower()
+    if backend not in {"cpu", "auto"}:
+        raise RuntimeError("Only the CPU Laplace-Hamming backend is available in bone-contouring.")
+
+    pixels = np.asarray(image_xyz, dtype=np.float64) + float(p.input_offset)
+    if pixels.ndim != 3:
+        raise ValueError(f"Laplace-Hamming expects a 3D array, got ndim={pixels.ndim}.")
+    spacing = np.asarray(spacing_xyz or (0.0607, 0.0607, 0.0607), dtype=np.float64)
+    if spacing.shape != (3,) or np.any(spacing <= 0):
+        raise ValueError("spacing_xyz must contain three positive values.")
+    nyquist_min = 1.0 / (2.0 * float(np.min(spacing)))
+    low_pass_frequency = float(p.low_pass_cutoff) * 2.0 * nyquist_min
+    high_pass_frequency = float(p.high_pass_cutoff) * 2.0 * nyquist_min
+    if low_pass_frequency <= 0:
+        raise ValueError("Laplace-Hamming low_pass_cutoff must be positive.")
+
+    axes = [np.fft.fftfreq(size, d=float(spacing[index])) for index, size in enumerate(pixels.shape)]
+    kx, ky, kz = np.meshgrid(*axes, indexing="ij")
+    frequency_squared = kx * kx + ky * ky + kz * kz
+    frequency = np.sqrt(frequency_squared)
+    in_band = (frequency < low_pass_frequency) & (frequency >= high_pass_frequency)
+    half_amplitude = float(p.hamming_amplitude) * 0.5
+    window = np.where(
+        in_band,
+        (1.0 - half_amplitude) + half_amplitude * np.cos(np.pi * frequency / low_pass_frequency),
+        0.0,
+    )
+    kernel = (
+        float(p.amplification)
+        * ((2.0 * np.pi) ** 2)
+        * ((1.0 - float(p.laplace_epsilon)) + float(p.laplace_epsilon) * frequency_squared)
+        * window
+    )
+    return np.real(np.fft.ifftn(np.fft.fftn(pixels) * kernel))
+
+
+def laplace_hamming_binarize_xyz(
+    image_xyz: np.ndarray,
+    *,
+    full_mask_xyz: np.ndarray | None = None,
+    spacing_xyz: tuple[float, float, float] | None = None,
+    parameters: LaplaceHammingParameters | None = None,
+) -> np.ndarray:
+    """Return a component-cleaned Laplace-Hamming bone mask in x/y/z order."""
+    p = parameters or LaplaceHammingParameters()
+    original = np.asarray(image_xyz)
+    if original.ndim != 3:
+        raise ValueError(f"Laplace-Hamming expects a 3D array, got ndim={original.ndim}.")
+    extended = np.pad(original, ((1, 1), (1, 1), (1, 1)), mode="edge")
+    padded, original_slices = _mirror_pad_to_power_of_two(extended)
+    filtered = laplace_hamming_filter_xyz(padded, spacing_xyz=spacing_xyz, parameters=p)
+    scaled = np.rint(
+        np.clip(
+            filtered * (float(p.int16_max) / float(p.ipl_float_max)),
+            -float(p.int16_max),
+            float(p.int16_max),
+        )
+    ).astype(np.int16)
+    binary = (scaled >= float(p.threshold)) & (scaled <= float(p.int16_max))
+    binary = binary[original_slices][1:-1, 1:-1, 1:-1]
+    if full_mask_xyz is not None:
+        full_mask = np.asarray(full_mask_xyz, dtype=bool)
+        if full_mask.shape != binary.shape:
+            raise ValueError("full_mask_xyz shape must match image_xyz shape.")
+        binary &= full_mask
+    return _remove_small_components_6(binary, int(p.min_size_voxels))

bone_contouring-0.1.0/src/bone_contouring/parameters.py

@@ -0,0 +1,73 @@
+"""Stable configuration types for contour and mask generation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(slots=True)
+class OuterContourParameters:
+    """Controls periosteal (full-mask) contour generation."""
+
+    contour_method: str = "standard"
+    periosteal_threshold: float = 300.0
+    periosteal_kernel_size: int = 5
+    periosteal_open_radius: int = 2
+    gaussian_sigma: float = 1.5
+    use_adaptive_threshold: bool = True
+    fill_holes: bool = True
+    geodesic_bone_threshold: float = 250.0
+    geodesic_fill_holes: bool = True
+
+
+@dataclass(slots=True)
+class InnerContourParameters:
+    """Controls endosteal contour generation and compartment partitioning."""
+
+    contour_method: str = "standard"
+    site: str = "radius"
+    endosteal_threshold: float = 500.0
+    endosteal_kernel_size: int = 3
+    gaussian_sigma: float = 1.5
+    use_adaptive_threshold: bool = False
+    peel: int = 3
+    trabecular_close_radius: int | None = None
+
+
+@dataclass(slots=True)
+class SegmentationParameters:
+    """Controls final bone segmentation within the full mask."""
+
+    enabled: bool = True
+    method: str = "gauss"
+    gaussian_sigma: float = 0.8
+    trab_threshold: float = 320.0
+    cort_threshold: float = 450.0
+    adaptive_low_threshold: float = 190.0
+    adaptive_high_threshold: float = 450.0
+    adaptive_block_size: int = 13
+    min_size_voxels: int = 64
+    keep_largest_component: bool = True
+    laplace_hamming_low_pass_cutoff: float = 0.3
+    laplace_hamming_high_pass_cutoff: float = 0.0
+    laplace_hamming_threshold: float = 15564.0
+    laplace_hamming_epsilon: float = 0.45
+    laplace_hamming_amplitude: float = 1.0
+    laplace_hamming_amplification: float = 1.0
+    laplace_hamming_input_offset: float = 0.0
+    laplace_hamming_ipl_float_max: float = 200000.0
+    laplace_hamming_int16_max: float = 32767.0
+    laplace_hamming_min_size_voxels: int = 70
+    laplace_hamming_backend: str = "cpu"
+    use_segmentation_aligned_contour_support: bool = False
+
+
+@dataclass(slots=True)
+class ContourParameters:
+    """Complete configuration for full, compartment, and bone masks."""
+
+    modality: str = "xct1"
+    site: str = "radius"
+    outer: OuterContourParameters = field(default_factory=OuterContourParameters)
+    inner: InnerContourParameters = field(default_factory=InnerContourParameters)
+    segmentation: SegmentationParameters = field(default_factory=SegmentationParameters)

bone_contouring-0.1.0/src/bone_contouring/presets.py

@@ -0,0 +1,71 @@
+"""Composable presets for supported bone contouring choices."""
+
+from __future__ import annotations
+
+from .parameters import ContourParameters
+
+_MODALITIES = {"xct1", "xct2"}
+_SITES = {"radius", "tibia", "knee"}
+_SEGMENTATION_METHODS = {"laplace_hamming", "gauss", "adaptive"}
+_OUTER_CONTOUR_METHODS = {"standard", "geodesic"}
+_INNER_CONTOUR_METHODS = {"standard", "none"}
+
+
+def _choice(value: str, allowed: set[str], label: str) -> str:
+    normalized = value.strip().lower()
+    if normalized not in allowed:
+        choices = ", ".join(sorted(allowed))
+        raise ValueError(f"Unsupported {label} {value!r}; choose one of: {choices}.")
+    return normalized
+
+
+def resolve_preset(
+    *,
+    modality: str = "xct1",
+    site: str = "radius",
+    segmentation: str = "laplace_hamming",
+    outer_contour: str = "standard",
+    inner_contour: str = "standard",
+) -> ContourParameters:
+    """Compose a fresh parameter object from supported method dimensions."""
+    modality = _choice(modality, _MODALITIES, "modality")
+    site = _choice(site, _SITES, "site")
+    segmentation = _choice(segmentation, _SEGMENTATION_METHODS, "segmentation")
+    outer_contour = _choice(outer_contour, _OUTER_CONTOUR_METHODS, "outer contour")
+    inner_contour = _choice(inner_contour, _INNER_CONTOUR_METHODS, "inner contour")
+
+    params = ContourParameters(modality=modality, site=site)
+    params.inner.site = site
+    params.segmentation.method = segmentation
+    params.segmentation.use_segmentation_aligned_contour_support = True
+    params.outer.contour_method = outer_contour
+    params.outer.use_adaptive_threshold = False
+    params.inner.contour_method = inner_contour
+    params.inner.use_adaptive_threshold = False
+
+    if modality == "xct1":
+        params.outer.periosteal_kernel_size = 12
+        params.outer.periosteal_open_radius = 1
+        if site in {"radius", "tibia"} and segmentation == "laplace_hamming":
+            params.segmentation.laplace_hamming_threshold = 15000.0
+    else:
+        params.outer.periosteal_kernel_size = 5
+        params.outer.periosteal_open_radius = 2
+    return params
+
+
+def load_preset(name: str) -> ContourParameters:
+    """Load a preset encoded as ``modality-site-segmentation-outer-inner``."""
+    parts = name.strip().lower().split("-")
+    if len(parts) != 5:
+        raise ValueError(
+            "Preset names use 'modality-site-segmentation-outer-inner', for example "
+            "'xct1-radius-laplace_hamming-standard-standard'."
+        )
+    return resolve_preset(
+        modality=parts[0],
+        site=parts[1],
+        segmentation=parts[2],
+        outer_contour=parts[3],
+        inner_contour=parts[4],
+    )

bone_contouring-0.1.0/src/bone_contouring.egg-info/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: bone-contouring
+Version: 0.1.0
+Summary: SimpleITK-first bone contour and mask generation for volumetric bone images
+Author: Matthias Walle
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3.0,>=1.26
+Requires-Dist: SimpleITK>=2.3
+Provides-Extra: geodesic
+Requires-Dist: hrpqct-geodesic-contour>=0.1.2; extra == "geodesic"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# bone-contouring
+
+SimpleITK-first bone contouring and mask generation for volumetric bone images.
+
+```python
+from bone_contouring import generate_masks_from_image, resolve_preset
+
+masks = generate_masks_from_image(image, resolve_preset(modality="xct1", site="radius"))
+```

bone_contouring-0.1.0/src/bone_contouring.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/bone_contouring/__init__.py
+src/bone_contouring/_arrays.py
+src/bone_contouring/api.py
+src/bone_contouring/laplace_hamming.py
+src/bone_contouring/parameters.py
+src/bone_contouring/presets.py
+src/bone_contouring.egg-info/PKG-INFO
+src/bone_contouring.egg-info/SOURCES.txt
+src/bone_contouring.egg-info/dependency_links.txt
+src/bone_contouring.egg-info/requires.txt
+src/bone_contouring.egg-info/top_level.txt
+tests/test_api.py
+tests/test_presets.py
+tests/test_segmentation.py

bone_contouring-0.1.0/src/bone_contouring.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bone_contouring-0.1.0/src/bone_contouring.egg-info/requires.txt

@@ -0,0 +1,8 @@
+numpy<3.0,>=1.26
+SimpleITK>=2.3
+
+[geodesic]
+hrpqct-geodesic-contour>=0.1.2
+
+[test]
+pytest>=8

bone_contouring-0.1.0/src/bone_contouring.egg-info/top_level.txt

@@ -0,0 +1 @@
+bone_contouring

bone_contouring-0.1.0/tests/test_api.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import sys
+import types
+
+import numpy as np
+import SimpleITK as sitk
+
+from bone_contouring import ContourParameters, generate_bone_segmentation, generate_masks_from_image
+from bone_contouring._arrays import sitk_to_numpy_xyz
+
+
+def _image_from_xyz(values: np.ndarray) -> sitk.Image:
+    image = sitk.GetImageFromArray(np.transpose(values.astype(np.float32), (2, 1, 0)))
+    image.SetSpacing((0.061, 0.062, 0.063))
+    image.SetOrigin((1.0, 2.0, 3.0))
+    image.SetDirection((1.0, 0.0, 0.0, 0.0, 0.0, -1.0, 0.0, 1.0, 0.0))
+    return image
+
+
+def _ring_image() -> sitk.Image:
+    shape = (33, 33, 7)
+    x, y, _z = np.indices(shape)
+    radius = np.sqrt((x - 16) ** 2 + (y - 16) ** 2)
+    values = np.zeros(shape, dtype=np.float32)
+    values[(radius >= 8) & (radius <= 11)] = 900.0
+    return _image_from_xyz(values)
+
+
+def _standard_outer_parameters() -> ContourParameters:
+    params = ContourParameters()
+    params.outer.use_adaptive_threshold = False
+    params.outer.periosteal_threshold = 300.0
+    params.outer.periosteal_kernel_size = 1
+    params.outer.periosteal_open_radius = 0
+    params.segmentation.method = "gauss"
+    params.segmentation.gaussian_sigma = 0.0
+    params.segmentation.trab_threshold = 500.0
+    params.segmentation.cort_threshold = 500.0
+    params.segmentation.min_size_voxels = 0
+    return params
+
+
+def test_generate_masks_fills_full_mask_holes_and_preserves_geometry() -> None:
+    """A periosteal ring must become a solid geometry-preserving full mask."""
+    image = _ring_image()
+    params = _standard_outer_parameters()
+    params.inner.contour_method = "none"
+
+    masks = generate_masks_from_image(image, params)
+
+    full = sitk_to_numpy_xyz(masks.full) > 0
+    assert full[16, 16, 3]
+    for mask in (masks.seg, masks.full, masks.trab, masks.cort):
+        assert mask.GetSpacing() == image.GetSpacing()
+        assert mask.GetOrigin() == image.GetOrigin()
+        assert mask.GetDirection() == image.GetDirection()
+
+
+def test_standard_outer_contour_can_use_gaussian_segmentation_support() -> None:
+    """Aligned contour support should use the Gaussian bone-support threshold, not adaptive support."""
+    values = np.zeros((21, 21, 3), dtype=np.float32)
+    values[5:16, 5:16, :] = 310.0
+    image = _image_from_xyz(values)
+    params = ContourParameters()
+    params.outer.contour_method = "standard"
+    params.outer.use_adaptive_threshold = True
+    params.outer.periosteal_threshold = 900.0
+    params.outer.periosteal_kernel_size = 0
+    params.outer.periosteal_open_radius = 0
+    params.inner.contour_method = "none"
+    params.segmentation.method = "gauss"
+    params.segmentation.gaussian_sigma = 0.0
+    params.segmentation.trab_threshold = 300.0
+    params.segmentation.use_segmentation_aligned_contour_support = True
+
+    masks = generate_masks_from_image(image, params)
+
+    full = sitk_to_numpy_xyz(masks.full) > 0
+    assert full[10, 10, 1]
+    assert masks.metadata["contour_support"]["outer_method"] == "gauss"
+
+
+def test_standard_outer_contour_can_use_laplace_hamming_segmentation_source(monkeypatch) -> None:
+    """Laplace-Hamming support should be computed from the supplied native segmentation image."""
+    from bone_contouring import _arrays
+
+    density = np.zeros((11, 11, 3), dtype=np.float32)
+    native = np.zeros_like(density)
+    native[3:8, 3:8, :] = 20000.0
+    image = _image_from_xyz(density)
+    segmentation_image = _image_from_xyz(native)
+    seen = {}
+
+    def fake_lh(image_xyz, *, full_mask_xyz, spacing_xyz, parameters):
+        seen["max"] = float(np.max(image_xyz))
+        return image_xyz > 10000
+
+    monkeypatch.setattr(_arrays, "laplace_hamming_binarize_xyz", fake_lh)
+    params = ContourParameters()
+    params.outer.contour_method = "standard"
+    params.outer.periosteal_kernel_size = 0
+    params.outer.periosteal_open_radius = 0
+    params.inner.contour_method = "none"
+    params.segmentation.method = "laplace_hamming"
+    params.segmentation.use_segmentation_aligned_contour_support = True
+
+    masks = generate_masks_from_image(image, params, segmentation_image=segmentation_image)
+
+    full = sitk_to_numpy_xyz(masks.full) > 0
+    assert seen["max"] == 20000.0
+    assert full[5, 5, 1]
+    assert masks.metadata["contour_support"]["outer_method"] == "laplace_hamming"
+
+
+def test_laplace_hamming_aligned_support_is_reused_for_final_segmentation(monkeypatch) -> None:
+    """When LH support drives contours and segmentation, the expensive filter should run once."""
+    from bone_contouring import _arrays
+
+    density = np.zeros((11, 11, 5), dtype=np.float32)
+    native = np.zeros_like(density)
+    native[3:8, 3:8, :] = 20000.0
+    image = _image_from_xyz(density)
+    segmentation_image = _image_from_xyz(native)
+    calls = {"count": 0}
+
+    def fake_lh(image_xyz, *, full_mask_xyz, spacing_xyz, parameters):
+        calls["count"] += 1
+        return image_xyz > 10000
+
+    monkeypatch.setattr(_arrays, "laplace_hamming_binarize_xyz", fake_lh)
+    params = ContourParameters()
+    params.outer.contour_method = "standard"
+    params.outer.periosteal_kernel_size = 0
+    params.outer.periosteal_open_radius = 0
+    params.inner.contour_method = "none"
+    params.segmentation.method = "laplace_hamming"
+    params.segmentation.use_segmentation_aligned_contour_support = True
+
+    masks = generate_masks_from_image(image, params, segmentation_image=segmentation_image)
+
+    assert calls["count"] == 1
+    assert np.array_equal(sitk_to_numpy_xyz(masks.seg) > 0, sitk_to_numpy_xyz(masks.full) > 0)
+
+
+def test_none_inner_contour_assigns_full_mask_to_trabecular_compartment() -> None:
+    """The explicit `none` choice must not synthesize a cortical compartment."""
+    params = _standard_outer_parameters()
+    params.inner.contour_method = "none"
+
+    masks = generate_masks_from_image(_ring_image(), params)
+
+    assert np.array_equal(sitk_to_numpy_xyz(masks.trab), sitk_to_numpy_xyz(masks.full))
+    assert not np.any(sitk_to_numpy_xyz(masks.cort))
+    assert masks.metadata["endosteal_contour_method"] == "none"
+
+
+def test_implausible_endosteal_result_uses_recorded_full_mask_fallback() -> None:
+    """An empty trabecular partition must not escape as an unannotated result."""
+    params = _standard_outer_parameters()
+    params.inner.contour_method = "standard"
+    params.inner.peel = 100
+
+    masks = generate_masks_from_image(_ring_image(), params)
+
+    assert np.array_equal(sitk_to_numpy_xyz(masks.trab), sitk_to_numpy_xyz(masks.full))
+    assert not np.any(sitk_to_numpy_xyz(masks.cort))
+    assert masks.metadata["endosteal_fallback"]["applied"] is True
+    assert masks.metadata["endosteal_fallback"]["reason"] == "empty_trabecular_mask"
+
+
+def test_generate_bone_segmentation_returns_a_geometry_preserving_mask() -> None:
+    """The standalone segmentation entry point must retain the input image geometry."""
+    values = np.zeros((9, 9, 5), dtype=np.float32)
+    values[2:6, 2:6, 1:4] = 800.0
+    image = _image_from_xyz(values)
+    params = _standard_outer_parameters()
+
+    segmentation = generate_bone_segmentation(image, params)
+
+    assert sitk_to_numpy_xyz(segmentation)[3, 3, 2] == 1
+    assert segmentation.GetSpacing() == image.GetSpacing()
+    assert segmentation.GetOrigin() == image.GetOrigin()
+
+
+def test_geodesic_outer_contour_uses_optional_adapter_output(monkeypatch) -> None:
+    """The geodesic choice must use the optional package result as the full mask."""
+    image = _ring_image()
+    expected = np.zeros((33, 33, 7), dtype=bool)
+    expected[8:25, 8:25, :] = True
+
+    def contour(_density: np.ndarray, **_kwargs: object) -> tuple[np.ndarray, list[np.ndarray]]:
+        return expected, [expected]
+
+    monkeypatch.setitem(sys.modules, "hrpqct_geodesic_contour", types.SimpleNamespace(contour=contour))
+    params = _standard_outer_parameters()
+    params.outer.contour_method = "geodesic"
+    params.inner.contour_method = "none"
+
+    masks = generate_masks_from_image(image, params)
+
+    assert np.array_equal(sitk_to_numpy_xyz(masks.full) > 0, expected)
+    assert masks.metadata["periosteal_contour_method"] == "geodesic"

bone_contouring-0.1.0/tests/test_presets.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from bone_contouring import (
+    ContourParameters,
+    InnerContourParameters,
+    OuterContourParameters,
+    SegmentationParameters,
+    load_preset,
+    resolve_preset,
+)
+
+
+def test_root_api_exports_parameter_types_and_preset_helpers() -> None:
+    """A missing root export would make the advertised stable API unusable."""
+    assert ContourParameters is not None
+    assert SegmentationParameters is not None
+    assert OuterContourParameters is not None
+    assert InnerContourParameters is not None
+    assert callable(load_preset)
+    assert callable(resolve_preset)
+
+
+def test_resolve_preset_composes_each_requested_dimension() -> None:
+    """Independent preset dimensions must not silently override one another."""
+    params = resolve_preset(
+        modality="xct1",
+        site="radius",
+        segmentation="laplace_hamming",
+        outer_contour="geodesic",
+        inner_contour="none",
+    )
+
+    assert params.modality == "xct1"
+    assert params.site == "radius"
+    assert params.segmentation.method == "laplace_hamming"
+    assert params.outer.contour_method == "geodesic"
+    assert params.inner.contour_method == "none"
+    assert params.inner.site == "radius"
+    assert params.segmentation.use_segmentation_aligned_contour_support is True
+
+
+def test_xct1_preset_uses_standard_periosteal_contour_defaults() -> None:
+    """XtremeCT I full-mask contouring uses the scanner-specific kernel/open defaults."""
+    params = resolve_preset(
+        modality="xct1",
+        site="radius",
+        segmentation="laplace_hamming",
+        outer_contour="standard",
+        inner_contour="standard",
+    )
+
+    assert params.outer.periosteal_threshold == 300.0
+    assert params.outer.periosteal_kernel_size == 12
+    assert params.outer.periosteal_open_radius == 1
+    assert params.outer.use_adaptive_threshold is False
+    assert params.segmentation.laplace_hamming_threshold == 15000.0
+
+
+def test_resolved_presets_are_independent_instances() -> None:
+    """A caller's parameter edit must not contaminate later preset resolution."""
+    first = load_preset("xct2-tibia-gauss-standard-standard")
+    first.outer.periosteal_threshold = 999.0
+    second = load_preset("xct2-tibia-gauss-standard-standard")
+
+    assert first.segmentation.method == "gauss"
+    assert second.outer.periosteal_threshold != 999.0
+
+
+def test_xct1_knee_keeps_default_laplace_hamming_threshold() -> None:
+    """The more inclusive XCT1 LH threshold is scoped to radius/tibia."""
+    params = resolve_preset(
+        modality="xct1",
+        site="knee",
+        segmentation="laplace_hamming",
+        outer_contour="standard",
+        inner_contour="standard",
+    )
+
+    assert params.segmentation.laplace_hamming_threshold == 15564.0

bone_contouring-0.1.0/tests/test_segmentation.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from bone_contouring import SegmentationParameters
+from bone_contouring._arrays import adaptive_threshold_xyz, segment_bone_xyz
+from bone_contouring.laplace_hamming import LaplaceHammingParameters, laplace_hamming_binarize_xyz
+
+
+def test_gaussian_segmentation_cleans_small_components_and_stays_in_full_mask() -> None:
+    """A segmentation regression must not keep isolated noise or escape `full`."""
+    image = np.zeros((9, 9, 9), dtype=np.float32)
+    image[2:5, 2:5, 2:5] = 800.0
+    image[7, 7, 7] = 800.0
+    full = np.zeros_like(image, dtype=bool)
+    full[1:6, 1:6, 1:6] = True
+    params = SegmentationParameters(
+        method="gauss",
+        gaussian_sigma=0.0,
+        trab_threshold=500.0,
+        cort_threshold=500.0,
+        min_size_voxels=4,
+    )
+
+    result = segment_bone_xyz(image, full, full, full, params, spacing_xyz=(1.0, 1.0, 1.0))
+
+    assert result[2:5, 2:5, 2:5].all()
+    assert not result[7, 7, 7]
+    assert not np.any(result & ~full)
+
+
+def test_laplace_hamming_binarization_respects_full_mask_and_component_limit() -> None:
+    """Laplace-Hamming output must be constrained even when bright voxels exist outside full."""
+    image = np.zeros((8, 8, 8), dtype=np.float32)
+    image[2:4, 2:4, 2:4] = 900.0
+    image[6, 6, 6] = 900.0
+    full = np.zeros_like(image, dtype=bool)
+    full[1:5, 1:5, 1:5] = True
+    params = LaplaceHammingParameters(
+        low_pass_cutoff=1.0,
+        laplace_epsilon=0.0,
+        hamming_amplitude=0.0,
+        ipl_float_max=10000.0,
+        int16_max=10000.0,
+        threshold=500.0,
+        min_size_voxels=2,
+    )
+
+    result = laplace_hamming_binarize_xyz(
+        image,
+        full_mask_xyz=full,
+        spacing_xyz=(1.0, 1.0, 1.0),
+        parameters=params,
+    )
+
+    assert result[2:4, 2:4, 2:4].all()
+    assert not result[6, 6, 6]
+
+
+def test_adaptive_threshold_rejects_even_window_sizes() -> None:
+    """An even local window has no center voxel and must fail explicitly."""
+    with pytest.raises(ValueError, match="odd"):
+        adaptive_threshold_xyz(
+            np.zeros((5, 5, 5), dtype=np.float32),
+            block_size=4,
+        )