bone-microarchitecture 0.1.0__tar.gz

bone_microarchitecture-0.1.0/LICENSE

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

bone_microarchitecture-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: bone-microarchitecture
+Version: 0.1.0
+Summary: Lightweight bone microarchitecture measurements from masks and calibrated grayscale arrays.
+Author: Matthias Walle
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/wallematthias/bone-microarchitecture
+Project-URL: Repository, https://github.com/wallematthias/bone-microarchitecture
+Project-URL: Issues, https://github.com/wallematthias/bone-microarchitecture/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.10
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: mps
+Requires-Dist: pyobjc-framework-Metal>=10; extra == "mps"
+Provides-Extra: opencl
+Requires-Dist: pyopencl>=2024.1; extra == "opencl"
+Provides-Extra: gpu
+Requires-Dist: pyobjc-framework-Metal>=10; sys_platform == "darwin" and extra == "gpu"
+Requires-Dist: pyopencl>=2024.1; sys_platform != "darwin" and extra == "gpu"
+Dynamic: license-file
+
+# Bone Microarchitecture
+
+Lightweight microarchitecture measurements from binary masks and optional calibrated grayscale arrays.
+
+This package intentionally has no Slicer dependency and no image I/O dependency. Callers are responsible for loading images, calibration, and putting masks on a common grid.
+
+## GPU Backends
+
+Exact Hildebrand sphere fitting supports three diameter-accumulation backends:
+
+- `cpu`: NumPy/SciPy fallback.
+- `mps`: native Apple Metal backend for macOS.
+- `opencl`: OpenCL backend for Windows/Linux systems with `pyopencl` and a working GPU OpenCL runtime.
+
+Use `thickness_backend="auto"` to select Metal on macOS when available, OpenCL on Windows/Linux when available, and CPU otherwise.
+
+Optional installs:
+
+```bash
+pip install "bone-microarchitecture[mps]"
+pip install "bone-microarchitecture[opencl]"
+pip install "bone-microarchitecture[gpu]"
+```
+
+## Parameter Definitions
+
+- `Tb.BMD`: mean calibrated grayscale value inside the trabecular compartment.
+- `Tb.BV/TV`: trabecular bone volume divided by trabecular total volume.
+- `Tb.Th`: maximal-sphere local thickness of trabecular bone.
+- `Tb.Sp`: maximal-sphere local thickness of non-bone space in the trabecular compartment.
+- `Tb.N`: inverse ridge-to-ridge spacing estimate in the trabecular compartment.
+- `Tb.1/N.SD`: standard deviation of ridge-to-ridge spacing.
+- `Tb.BV`: trabecular bone volume.
+- `Tb.TV`: trabecular compartment volume.
+- `Ct.BMD`: mean calibrated grayscale value inside the cortical compartment.
+- `Ct.Th`: maximal-sphere local thickness of cortical bone.
+- `Ct.Po`: cortical pore volume divided by cortical total volume.
+- `Ct.Po.V`: cortical pore volume.
+- `Ct.Po.Dm`: maximal-sphere local diameter of cortical pore space.
+- `Ct.BV`: cortical bone volume.
+- `Ct.TV`: cortical compartment volume.

bone_microarchitecture-0.1.0/README.md

@@ -0,0 +1,41 @@
+# Bone Microarchitecture
+
+Lightweight microarchitecture measurements from binary masks and optional calibrated grayscale arrays.
+
+This package intentionally has no Slicer dependency and no image I/O dependency. Callers are responsible for loading images, calibration, and putting masks on a common grid.
+
+## GPU Backends
+
+Exact Hildebrand sphere fitting supports three diameter-accumulation backends:
+
+- `cpu`: NumPy/SciPy fallback.
+- `mps`: native Apple Metal backend for macOS.
+- `opencl`: OpenCL backend for Windows/Linux systems with `pyopencl` and a working GPU OpenCL runtime.
+
+Use `thickness_backend="auto"` to select Metal on macOS when available, OpenCL on Windows/Linux when available, and CPU otherwise.
+
+Optional installs:
+
+```bash
+pip install "bone-microarchitecture[mps]"
+pip install "bone-microarchitecture[opencl]"
+pip install "bone-microarchitecture[gpu]"
+```
+
+## Parameter Definitions
+
+- `Tb.BMD`: mean calibrated grayscale value inside the trabecular compartment.
+- `Tb.BV/TV`: trabecular bone volume divided by trabecular total volume.
+- `Tb.Th`: maximal-sphere local thickness of trabecular bone.
+- `Tb.Sp`: maximal-sphere local thickness of non-bone space in the trabecular compartment.
+- `Tb.N`: inverse ridge-to-ridge spacing estimate in the trabecular compartment.
+- `Tb.1/N.SD`: standard deviation of ridge-to-ridge spacing.
+- `Tb.BV`: trabecular bone volume.
+- `Tb.TV`: trabecular compartment volume.
+- `Ct.BMD`: mean calibrated grayscale value inside the cortical compartment.
+- `Ct.Th`: maximal-sphere local thickness of cortical bone.
+- `Ct.Po`: cortical pore volume divided by cortical total volume.
+- `Ct.Po.V`: cortical pore volume.
+- `Ct.Po.Dm`: maximal-sphere local diameter of cortical pore space.
+- `Ct.BV`: cortical bone volume.
+- `Ct.TV`: cortical compartment volume.

bone_microarchitecture-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bone-microarchitecture"
+version = "0.1.0"
+description = "Lightweight bone microarchitecture measurements from masks and calibrated grayscale arrays."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{name = "Matthias Walle"}]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+dependencies = [
+  "numpy>=1.23",
+  "scipy>=1.10",
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8",
+  "pytest-cov",
+]
+dev = [
+  "build",
+  "pytest>=8",
+  "pytest-cov",
+  "twine",
+]
+mps = [
+  "pyobjc-framework-Metal>=10",
+]
+opencl = [
+  "pyopencl>=2024.1",
+]
+gpu = [
+  "pyobjc-framework-Metal>=10; sys_platform == 'darwin'",
+  "pyopencl>=2024.1; sys_platform != 'darwin'",
+]
+
+[project.urls]
+Homepage = "https://github.com/wallematthias/bone-microarchitecture"
+Repository = "https://github.com/wallematthias/bone-microarchitecture"
+Issues = "https://github.com/wallematthias/bone-microarchitecture/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

bone_microarchitecture-0.1.0/setup.cfg

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

bone_microarchitecture-0.1.0/src/bone_microarchitecture/__init__.py

@@ -0,0 +1,32 @@
+"""Direct 3D bone microarchitecture measurements from aligned arrays."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .opencl import opencl_hildebrand_thickness_map
+from .pipeline import compute_microarchitecture
+from .results import MicroarchitectureResult, PARAMETER_DEFINITIONS
+from .thickness import (
+    default_thickness_backend,
+    hildebrand_thickness_map,
+    local_thickness_map,
+    trabecular_number_map,
+)
+
+try:
+    __version__ = version("bone-microarchitecture")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "MicroarchitectureResult",
+    "PARAMETER_DEFINITIONS",
+    "__version__",
+    "compute_microarchitecture",
+    "default_thickness_backend",
+    "hildebrand_thickness_map",
+    "local_thickness_map",
+    "opencl_hildebrand_thickness_map",
+    "trabecular_number_map",
+]

bone_microarchitecture-0.1.0/src/bone_microarchitecture/geometry.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import numpy as np
+
+
+def as_bool_mask(mask, name: str) -> np.ndarray:
+    """Validate and convert an input array to a 3D boolean mask."""
+    array = np.asarray(mask)
+    if array.ndim != 3:
+        raise ValueError(f"{name} must be a 3D mask.")
+    return array > 0
+
+
+def validate_spacing(spacing) -> tuple[float, float, float]:
+    """Return spacing as three positive floats."""
+    values = tuple(float(value) for value in spacing)
+    if len(values) != 3 or any(value <= 0 for value in values):
+        raise ValueError("spacing must contain three positive values.")
+    return values
+
+
+def validate_same_shape(arrays: Mapping[str, np.ndarray]) -> tuple[int, int, int]:
+    """Validate that all supplied arrays share one shape."""
+    shapes = {name: tuple(array.shape) for name, array in arrays.items() if array is not None}
+    unique_shapes = set(shapes.values())
+    if len(unique_shapes) > 1:
+        detail = ", ".join(f"{name}={shape}" for name, shape in shapes.items())
+        raise ValueError(f"All masks and images must have the same shape: {detail}.")
+    if not unique_shapes:
+        raise ValueError("At least one mask is required.")
+    return next(iter(unique_shapes))
+
+
+def voxel_volume(spacing: tuple[float, float, float]) -> float:
+    """Return voxel volume in mm^3 for array-ordered spacing."""
+    return float(np.prod(np.asarray(spacing, dtype=float)))

bone_microarchitecture-0.1.0/src/bone_microarchitecture/metal.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import numpy as np
+
+
+METAL_SOURCE = r"""
+#include <metal_stdlib>
+using namespace metal;
+
+kernel void accumulate_local_diameters(
+    device const uint* seed_z [[buffer(0)]],
+    device const uint* seed_y [[buffer(1)]],
+    device const uint* seed_x [[buffer(2)]],
+    device const float* seed_radius [[buffer(3)]],
+    device atomic_uint* diameter_map [[buffer(4)]],
+    device const uint* volume_shape [[buffer(5)]],
+    device const float* spacing [[buffer(6)]],
+    constant float& diameter_margin [[buffer(7)]],
+    constant float& output_scale [[buffer(8)]],
+    constant float& inclusion_tolerance [[buffer(9)]],
+    uint gid [[thread_position_in_grid]]
+) {
+    const float radius = seed_radius[gid];
+    const float value_mm = max(2.0f * (radius - diameter_margin), 0.0f);
+    if (value_mm <= 0.0f) {
+        return;
+    }
+    const uint value = uint(round(value_mm * output_scale));
+
+    const int zc = int(seed_z[gid]);
+    const int yc = int(seed_y[gid]);
+    const int xc = int(seed_x[gid]);
+    const int z_extent = int(ceil(radius / spacing[0]));
+    const int y_extent = int(ceil(radius / spacing[1]));
+    const int x_extent = int(ceil(radius / spacing[2]));
+
+    const int z0 = max(0, zc - z_extent);
+    const int y0 = max(0, yc - y_extent);
+    const int x0 = max(0, xc - x_extent);
+    const int z1 = min(int(volume_shape[0]), zc + z_extent + 1);
+    const int y1 = min(int(volume_shape[1]), yc + y_extent + 1);
+    const int x1 = min(int(volume_shape[2]), xc + x_extent + 1);
+    const float r2 = radius * radius;
+
+    for (int z = z0; z < z1; ++z) {
+        const float dz = float(z - zc) * spacing[0];
+        for (int y = y0; y < y1; ++y) {
+            const float dy = float(y - yc) * spacing[1];
+            for (int x = x0; x < x1; ++x) {
+                const float dx = float(x - xc) * spacing[2];
+                if ((dx * dx + dy * dy + dz * dz) <= (r2 + inclusion_tolerance)) {
+                    const uint index = (uint(z) * volume_shape[1] + uint(y)) * volume_shape[2] + uint(x);
+                    atomic_fetch_max_explicit(&diameter_map[index], value, memory_order_relaxed);
+                }
+            }
+        }
+    }
+}
+"""
+
+
+def is_metal_available() -> bool:
+    """Return whether Apple Metal compute is available through PyObjC."""
+    try:
+        import Metal
+    except Exception:
+        return False
+    try:
+        return Metal.MTLCreateSystemDefaultDevice() is not None
+    except Exception:
+        return False
+
+
+def metal_hildebrand_thickness_map(
+    *,
+    shape: tuple[int, int, int],
+    seed_z,
+    seed_y,
+    seed_x,
+    seed_radius,
+    spacing: tuple[float, float, float],
+    diameter_margin: float,
+    inclusion_tolerance: float,
+    output_scale: float = 1_000_000.0,
+) -> np.ndarray:
+    """Accumulate maximal-sphere diameter values with a native Metal kernel.
+
+    Seed locations and inscribed radii are selected by :mod:`bone_microarchitecture.thickness`.
+    This backend only applies the corresponding diameters to the output volume
+    using atomic maximum updates.
+    """
+    try:
+        import Metal
+    except Exception as exc:
+        raise RuntimeError("Apple Metal backend requires PyObjC Metal bindings.") from exc
+
+    device = Metal.MTLCreateSystemDefaultDevice()
+    if device is None:
+        raise RuntimeError("Apple Metal backend is not available on this machine.")
+
+    seed_z = np.asarray(seed_z, dtype=np.uint32)
+    seed_y = np.asarray(seed_y, dtype=np.uint32)
+    seed_x = np.asarray(seed_x, dtype=np.uint32)
+    seed_radius = np.asarray(seed_radius, dtype=np.float32)
+    if not (seed_z.size == seed_y.size == seed_x.size == seed_radius.size):
+        raise ValueError("Seed coordinate and radius arrays must have the same length.")
+    if seed_radius.size == 0:
+        return np.zeros(tuple(shape), dtype=np.float32)
+
+    library, error = device.newLibraryWithSource_options_error_(METAL_SOURCE, None, None)
+    if library is None:
+        raise RuntimeError(f"Could not compile Metal sphere fitting kernel: {error}")
+    function = library.newFunctionWithName_("accumulate_local_diameters")
+    pipeline, error = device.newComputePipelineStateWithFunction_error_(function, None)
+    if pipeline is None:
+        raise RuntimeError(f"Could not create Metal sphere fitting pipeline: {error}")
+
+    queue = device.newCommandQueue()
+    if queue is None:
+        raise RuntimeError("Could not create Metal command queue.")
+
+    output = np.zeros(int(np.prod(shape)), dtype=np.uint32)
+    buffers = [
+        _readonly_buffer(device, seed_z),
+        _readonly_buffer(device, seed_y),
+        _readonly_buffer(device, seed_x),
+        _readonly_buffer(device, seed_radius),
+        _shared_buffer(device, output),
+        _readonly_buffer(device, np.asarray(shape, dtype=np.uint32)),
+        _readonly_buffer(device, np.asarray(spacing, dtype=np.float32)),
+        _readonly_buffer(device, np.asarray([diameter_margin], dtype=np.float32)),
+        _readonly_buffer(device, np.asarray([output_scale], dtype=np.float32)),
+        _readonly_buffer(device, np.asarray([inclusion_tolerance], dtype=np.float32)),
+    ]
+
+    command_buffer = queue.commandBuffer()
+    encoder = command_buffer.computeCommandEncoder()
+    encoder.setComputePipelineState_(pipeline)
+    for index, buffer in enumerate(buffers):
+        encoder.setBuffer_offset_atIndex_(buffer, 0, index)
+
+    threads_per_group = Metal.MTLSizeMake(min(int(pipeline.maxTotalThreadsPerThreadgroup()), 256), 1, 1)
+    grid = Metal.MTLSizeMake(int(seed_radius.size), 1, 1)
+    encoder.dispatchThreads_threadsPerThreadgroup_(grid, threads_per_group)
+    encoder.endEncoding()
+    command_buffer.commit()
+    command_buffer.waitUntilCompleted()
+    if command_buffer.error() is not None:
+        raise RuntimeError(f"Metal sphere fitting command failed: {command_buffer.error()}")
+
+    output_view = np.frombuffer(buffers[4].contents().as_buffer(output.nbytes), dtype=np.uint32)
+    return (output_view.reshape(tuple(shape)).astype(np.float32) / float(output_scale)).copy()
+
+
+def _readonly_buffer(device, array: np.ndarray):
+    array = np.ascontiguousarray(array)
+    return device.newBufferWithBytes_length_options_(array.tobytes(), array.nbytes, 0)
+
+
+def _shared_buffer(device, array: np.ndarray):
+    array = np.ascontiguousarray(array)
+    return device.newBufferWithBytes_length_options_(array.tobytes(), array.nbytes, 0)

bone_microarchitecture-0.1.0/src/bone_microarchitecture/metrics.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import numpy as np
+
+from .geometry import voxel_volume
+
+
+def count_volume(mask, spacing: tuple[float, float, float]) -> float:
+    """Return the physical volume represented by non-zero voxels.
+
+    Args:
+        mask: 3D binary mask. Non-zero values are counted.
+        spacing: Voxel spacing in millimetres, ordered like the array axes.
+
+    Returns:
+        Volume in mm^3.
+    """
+    return float(np.count_nonzero(mask) * voxel_volume(spacing))
+
+
+def masked_mean_sd(image, mask) -> tuple[float, float]:
+    """Return mean and standard deviation inside a mask.
+
+    Non-finite image values are ignored. Empty masks return ``(0.0, 0.0)``.
+    """
+    values = np.asarray(image, dtype=float)[np.asarray(mask) > 0]
+    values = values[np.isfinite(values)]
+    if values.size == 0:
+        return 0.0, 0.0
+    return float(values.mean()), float(values.std(ddof=0))
+
+
+def compartment_metrics(
+    *,
+    bone_mask,
+    periosteal_mask,
+    trabecular_mask,
+    cortical_mask=None,
+    spacing: tuple[float, float, float],
+    mean_tb_th: float = 0.0,
+) -> dict[str, float]:
+    """Calculate scalar compartment measures from binary masks.
+
+    The trabecular compartment is the intersection of ``trabecular_mask`` and
+    ``periosteal_mask``, excluding the cortical compartment when one is supplied.
+    Bone volume measures use ``bone_mask`` intersected with the relevant
+    compartment. Ratio outputs are unitless fractions.
+
+    Calculated parameters:
+        ``Tb.BV``: trabecular bone volume, in mm^3.
+        ``Tb.TV``: trabecular compartment volume, in mm^3.
+        ``Tb.BV/TV``: ``Tb.BV / Tb.TV``, as a fraction.
+        ``Ct.BV``: cortical bone volume, in mm^3.
+        ``Ct.TV``: cortical compartment volume, in mm^3.
+        ``Ct.Po.V``: ``Ct.TV - Ct.BV``, in mm^3.
+        ``Ct.Po``: ``Ct.Po.V / Ct.TV``, as a fraction.
+        ``Tb.N``: fallback scalar ``Tb.BV/TV / mean(Tb.Th)``. The pipeline
+        replaces this with the map-based trabecular number estimate.
+    """
+    trab_region = np.asarray(trabecular_mask) > 0
+    peri = np.asarray(periosteal_mask) > 0
+    bone = np.asarray(bone_mask) > 0 if bone_mask is not None else trab_region
+    cort = np.asarray(cortical_mask) > 0 if cortical_mask is not None else np.zeros_like(trab_region)
+    trab_region = trab_region & peri & ~cort
+    cort_region = cort
+    trab_bone = bone & trab_region
+    cortical_bone = bone & cort_region
+    tb_bv = count_volume(trab_bone, spacing)
+    tb_tv = count_volume(trab_region, spacing)
+    ct_bv = count_volume(cortical_bone, spacing)
+    ct_tv = count_volume(cort_region, spacing)
+    bvtv = tb_bv / tb_tv if tb_tv else 0.0
+    ct_po = max(ct_tv - ct_bv, 0.0) / ct_tv if ct_tv else 0.0
+    metrics = {
+        "Tb.BV/TV": bvtv,
+        "Tb.BV": tb_bv,
+        "Tb.TV": tb_tv,
+        "Ct.BV": ct_bv,
+        "Ct.TV": ct_tv,
+        "Ct.Po.V": max(ct_tv - ct_bv, 0.0),
+        "Ct.Po": ct_po,
+    }
+    metrics["Tb.N"] = bvtv / mean_tb_th if mean_tb_th else 0.0
+    return metrics