bone-microarchitecture 0.1.0__py3-none-any.whl

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

bone_microarchitecture/opencl.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import numpy as np
+
+
+OPENCL_SOURCE = r"""
+__kernel void accumulate_local_diameters_kernel(
+    __global const unsigned int *seed_z,
+    __global const unsigned int *seed_y,
+    __global const unsigned int *seed_x,
+    __global const float *seed_radius,
+    const unsigned int seed_count,
+    __global volatile unsigned int *diameter_map,
+    __global const unsigned int *volume_shape,
+    __global const float *spacing,
+    const float diameter_margin,
+    const float output_scale,
+    const float inclusion_tolerance
+) {
+    const int gid = get_global_id(0);
+    if ((unsigned int)gid >= seed_count) {
+        return;
+    }
+    const float radius = seed_radius[gid];
+    const float value_mm = fmax(2.0f * (radius - diameter_margin), 0.0f);
+    if (value_mm <= 0.0f) {
+        return;
+    }
+    const unsigned int value = (unsigned int)rint(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 unsigned int index = ((unsigned int)z * volume_shape[1] + (unsigned int)y) * volume_shape[2] + (unsigned int)x;
+                    atomic_max(&diameter_map[index], value);
+                }
+            }
+        }
+    }
+}
+"""
+
+_OPENCL_CACHE = {}
+
+
+def is_opencl_available(prefer_gpu: bool = True) -> bool:
+    """Return whether an OpenCL device is available through PyOpenCL."""
+    try:
+        import pyopencl as cl
+    except Exception:
+        return False
+    try:
+        _select_device(cl, prefer_gpu=prefer_gpu)
+        return True
+    except Exception:
+        return False
+
+
+def opencl_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 an OpenCL 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 pyopencl as cl
+    except Exception as exc:
+        raise RuntimeError("OpenCL backend requires pyopencl and an OpenCL runtime.") from exc
+
+    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)
+
+    ctx, queue, program = _get_opencl_program(cl)
+    flags = cl.mem_flags
+    output = np.zeros(int(np.prod(shape)), dtype=np.uint32)
+    buffers = [
+        cl.Buffer(ctx, flags.READ_ONLY | flags.COPY_HOST_PTR, hostbuf=np.ascontiguousarray(seed_z)),
+        cl.Buffer(ctx, flags.READ_ONLY | flags.COPY_HOST_PTR, hostbuf=np.ascontiguousarray(seed_y)),
+        cl.Buffer(ctx, flags.READ_ONLY | flags.COPY_HOST_PTR, hostbuf=np.ascontiguousarray(seed_x)),
+        cl.Buffer(ctx, flags.READ_ONLY | flags.COPY_HOST_PTR, hostbuf=np.ascontiguousarray(seed_radius)),
+        np.uint32(seed_radius.size),
+        cl.Buffer(ctx, flags.READ_WRITE | flags.COPY_HOST_PTR, hostbuf=output),
+        cl.Buffer(ctx, flags.READ_ONLY | flags.COPY_HOST_PTR, hostbuf=np.asarray(shape, dtype=np.uint32)),
+        cl.Buffer(ctx, flags.READ_ONLY | flags.COPY_HOST_PTR, hostbuf=np.asarray(spacing, dtype=np.float32)),
+    ]
+
+    local_size = 256
+    global_size = int(((int(seed_radius.size) + local_size - 1) // local_size) * local_size)
+    program.accumulate_local_diameters_kernel(
+        queue,
+        (global_size,),
+        (local_size,),
+        *buffers,
+        np.float32(diameter_margin),
+        np.float32(output_scale),
+        np.float32(inclusion_tolerance),
+    )
+    cl.enqueue_copy(queue, output, buffers[5])
+    queue.finish()
+    return (output.reshape(tuple(shape)).astype(np.float32) / float(output_scale)).copy()
+
+
+def _get_opencl_program(cl):
+    key = "default"
+    if key in _OPENCL_CACHE:
+        return _OPENCL_CACHE[key]
+    device = _select_device(cl, prefer_gpu=True)
+    ctx = cl.Context([device])
+    command_queue = cl.CommandQueue(ctx)
+    program = cl.Program(ctx, OPENCL_SOURCE).build()
+    _OPENCL_CACHE[key] = (ctx, command_queue, program)
+    return _OPENCL_CACHE[key]
+
+
+def _select_device(cl, *, prefer_gpu: bool):
+    fallback = None
+    for platform in cl.get_platforms():
+        devices = platform.get_devices()
+        for device in devices:
+            if fallback is None:
+                fallback = device
+            if prefer_gpu and device.type & cl.device_type.GPU:
+                return device
+    if fallback is not None and not prefer_gpu:
+        return fallback
+    if fallback is not None:
+        return fallback
+    raise RuntimeError("No OpenCL devices are available.")

bone_microarchitecture/pipeline.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import numpy as np
+
+from .geometry import as_bool_mask, validate_same_shape, validate_spacing
+from .metrics import compartment_metrics, masked_mean_sd
+from .results import MicroarchitectureResult
+from .thickness import (
+    default_thickness_backend,
+    hildebrand_thickness_map,
+    local_thickness_map,
+    summary,
+    trabecular_number_map,
+)
+
+
+def compute_microarchitecture(
+    *,
+    periosteal_mask,
+    trabecular_mask,
+    spacing,
+    bone_mask=None,
+    cortical_mask=None,
+    grayscale=None,
+    thickness_method: str = "hildebrand",
+    thickness_backend: str = "auto",
+) -> MicroarchitectureResult:
+    """Compute HR-pQCT microarchitecture measurements from aligned arrays.
+
+    This function is intentionally image-I/O agnostic. Callers must load images,
+    calibrate grayscale data when BMD is desired, and resample all masks/images
+    to a shared voxel grid before calling it.
+
+    Masks are interpreted as:
+        ``periosteal_mask``: full analysis compartment.
+        ``trabecular_mask``: trabecular compartment.
+        ``cortical_mask``: optional cortical compartment.
+        ``bone_mask``: mineralized bone phase. If omitted, the trabecular mask is
+        treated as the bone phase for backward-compatible trabecular-only use.
+
+    Calculated trabecular outputs:
+        ``Tb.BMD``: mean grayscale/BMD inside the trabecular compartment.
+        ``Tb.BV/TV``: trabecular bone volume divided by trabecular total volume,
+        reported as a unitless fraction.
+        ``Tb.Th``: mean local thickness of trabecular bone, in mm.
+        ``Tb.Sp``: mean local thickness of non-bone space in the trabecular
+        compartment, in mm.
+        ``Tb.N``: mean inverse ridge-to-ridge spacing estimate, in 1/mm.
+        ``Tb.1/N.SD``: standard deviation of ridge-to-ridge spacing, in mm.
+        ``Tb.BV`` and ``Tb.TV``: trabecular bone and compartment volumes, in mm^3.
+
+    Calculated cortical outputs when ``cortical_mask`` is provided:
+        ``Ct.BMD``: mean grayscale/BMD inside the cortical compartment.
+        ``Ct.Th``: mean local thickness of cortical bone, in mm.
+        ``Ct.Po``: cortical pore volume divided by cortical total volume,
+        reported as a unitless fraction.
+        ``Ct.Po.V``: cortical pore volume, in mm^3.
+        ``Ct.Po.Dm``: mean local pore diameter, in mm.
+        ``Ct.BV`` and ``Ct.TV``: cortical bone and compartment volumes, in mm^3.
+
+    Map-backed parameters include distribution statistics in
+    :func:`bone_microarchitecture.results.measurement_rows`.
+    """
+    spacing = validate_spacing(spacing)
+    peri = as_bool_mask(periosteal_mask, "periosteal_mask")
+    trab = as_bool_mask(trabecular_mask, "trabecular_mask")
+    bone = as_bool_mask(bone_mask, "bone_mask") if bone_mask is not None else trab
+    cort = as_bool_mask(cortical_mask, "cortical_mask") if cortical_mask is not None else None
+    image = None if grayscale is None else np.asarray(grayscale, dtype=np.float32)
+    validate_same_shape(
+        {
+            "periosteal_mask": peri,
+            "trabecular_mask": trab,
+            "bone_mask": bone,
+            "cortical_mask": cort,
+            "grayscale": image,
+        }
+    )
+
+    thickness_method = str(thickness_method or "hildebrand").strip().lower()
+    thickness_backend = str(thickness_backend or "auto").strip().lower()
+    resolved_thickness_backend = default_thickness_backend() if thickness_backend == "auto" else thickness_backend
+    trab_region = trab & peri
+    if cort is not None:
+        trab_region = trab_region & ~cort
+        cort_region = cort & peri
+    else:
+        cort_region = None
+    trab_bone = bone & trab_region
+    cort_bone = None if cort_region is None else bone & cort_region
+    tb_th_map = _thickness_map(
+        trab_bone,
+        spacing,
+        thickness_method=thickness_method,
+        thickness_backend=resolved_thickness_backend,
+    )
+    tb_sp_map = _thickness_map(
+        trab_region & ~trab_bone,
+        spacing,
+        thickness_method=thickness_method,
+        thickness_backend=resolved_thickness_backend,
+    )
+    tb_th = summary(tb_th_map[trab_bone])
+    tb_sp = summary(tb_sp_map[trab_region & ~trab_bone])
+    tb_n_map = trabecular_number_map(
+        trab_bone,
+        trab_region,
+        spacing,
+        backend=resolved_thickness_backend,
+    )
+    tb_n = summary(tb_n_map[trab_region])
+    tb_inverse_number_map = np.zeros(trab_region.shape, dtype=np.float32)
+    valid_tb_n = trab_region & np.isfinite(tb_n_map) & (tb_n_map > 0)
+    tb_inverse_number_map[valid_tb_n] = (1.0 / tb_n_map[valid_tb_n]).astype(np.float32, copy=False)
+    tb_inverse_number = summary(tb_inverse_number_map[valid_tb_n])
+
+    metrics = compartment_metrics(
+        bone_mask=bone,
+        periosteal_mask=peri,
+        trabecular_mask=trab,
+        cortical_mask=cort,
+        spacing=spacing,
+        mean_tb_th=tb_th["mean"],
+    )
+    metrics["Tb.N"] = tb_n["mean"]
+    metrics.update(
+        {
+            "Tb.Th": tb_th["mean"],
+            "Tb.Th SD": tb_th["sd"],
+            "Tb.Th Min": tb_th["min"],
+            "Tb.Th Max": tb_th["max"],
+            "Tb.Sp": tb_sp["mean"],
+            "Tb.Sp SD": tb_sp["sd"],
+            "Tb.Sp Min": tb_sp["min"],
+            "Tb.Sp Max": tb_sp["max"],
+            "Tb.N Median": tb_n["median"],
+            "Tb.N SD": tb_n["sd"],
+            "Tb.N P5": tb_n["p5"],
+            "Tb.N P25": tb_n["p25"],
+            "Tb.N P75": tb_n["p75"],
+            "Tb.N P95": tb_n["p95"],
+            "Tb.N Min": tb_n["min"],
+            "Tb.N Max": tb_n["max"],
+            "Tb.1/N.SD": tb_inverse_number["sd"],
+        }
+    )
+
+    maps = {"Tb.Th": tb_th_map, "Tb.Sp": tb_sp_map, "Tb.N": tb_n_map}
+
+    if cort_bone is not None:
+        ct_th_map = _thickness_map(
+            cort_bone,
+            spacing,
+            thickness_method=thickness_method,
+            thickness_backend=resolved_thickness_backend,
+        )
+        ct_th = summary(ct_th_map[cort_bone])
+        metrics.update(
+            {
+                "Ct.Th": ct_th["mean"],
+                "Ct.Th SD": ct_th["sd"],
+                "Ct.Th Min": ct_th["min"],
+                "Ct.Th Max": ct_th["max"],
+            }
+        )
+        maps["Ct.Th"] = ct_th_map
+        pore_map = _thickness_map(
+            cort_region & ~cort_bone,
+            spacing,
+            thickness_method=thickness_method,
+            thickness_backend=resolved_thickness_backend,
+        )
+        pore_summary = summary(pore_map[cort_region & ~cort_bone])
+        metrics.update(
+            {
+                "Ct.Po.Dm": pore_summary["mean"],
+                "Ct.Po.Dm SD": pore_summary["sd"],
+                "Ct.Po.Dm Min": pore_summary["min"],
+                "Ct.Po.Dm Max": pore_summary["max"],
+            }
+        )
+        maps["Ct.Po.Dm"] = pore_map
+
+    if image is not None:
+        tb_mean, tb_sd = masked_mean_sd(image, trab_region)
+        metrics["Tb.BMD"] = tb_mean
+        metrics["Tb.BMD SD"] = tb_sd
+        maps["Tb.BMD"] = np.where(trab_region, image, 0).astype(np.float32)
+        if cort_region is not None:
+            ct_mean, ct_sd = masked_mean_sd(image, cort_region)
+            metrics["Ct.BMD"] = ct_mean
+            metrics["Ct.BMD SD"] = ct_sd
+            maps["Ct.BMD"] = np.where(cort_region, image, 0).astype(np.float32)
+
+    return MicroarchitectureResult(
+        measurements=metrics,
+        maps=maps,
+        metadata={
+            "thickness_method": thickness_method,
+            "thickness_backend": resolved_thickness_backend,
+        },
+    )
+
+
+def _thickness_map(mask, spacing, *, thickness_method: str, thickness_backend: str):
+    """Dispatch one binary mask to the requested thickness-map implementation."""
+    if thickness_method in {"edt", "distance", "distance_transform"}:
+        return local_thickness_map(mask, spacing)
+    if thickness_method in {"hildebrand", "sphere_fitting", "sphere-fitting", "exact"}:
+        return hildebrand_thickness_map(mask, spacing, backend=thickness_backend)
+    raise ValueError("Thickness method must be one of: edt or hildebrand.")

bone_microarchitecture/results.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import csv
+from pathlib import Path
+
+import numpy as np
+
+
+MEASUREMENT_ORDER = (
+    "Tb.BMD",
+    "Tb.BV/TV",
+    "Tb.Th",
+    "Tb.Sp",
+    "Tb.N",
+    "Tb.1/N.SD",
+    "Tb.BV",
+    "Tb.TV",
+    "Ct.BMD",
+    "Ct.Th",
+    "Ct.Po",
+    "Ct.Po.V",
+    "Ct.Po.Dm",
+    "Ct.BV",
+    "Ct.TV",
+)
+
+SUMMARY_COLUMNS = (
+    "Parameter",
+    "Mean",
+    "Median",
+    "SD",
+    "P5",
+    "P25",
+    "P75",
+    "P95",
+    "Min",
+    "Max",
+    "Units",
+)
+
+_DISTRIBUTION_STAT_KEYS = {
+    "Tb.Th": ("Tb.Th SD", "Tb.Th Min", "Tb.Th Max"),
+    "Tb.Sp": ("Tb.Sp SD", "Tb.Sp Min", "Tb.Sp Max"),
+    "Tb.N": (
+        "Tb.N Median",
+        "Tb.N SD",
+        "Tb.N P5",
+        "Tb.N P25",
+        "Tb.N P75",
+        "Tb.N P95",
+        "Tb.N Min",
+        "Tb.N Max",
+    ),
+    "Ct.Th": ("Ct.Th SD", "Ct.Th Min", "Ct.Th Max"),
+    "Ct.Po.Dm": ("Ct.Po.Dm SD", "Ct.Po.Dm Min", "Ct.Po.Dm Max"),
+    "Tb.BMD": ("Tb.BMD SD",),
+    "Ct.BMD": ("Ct.BMD SD",),
+}
+_SECONDARY_MEASUREMENTS = {name for names in _DISTRIBUTION_STAT_KEYS.values() for name in names}
+
+PARAMETER_DEFINITIONS = {
+    "Tb.BMD": "Mean grayscale/BMD value inside the trabecular compartment.",
+    "Tb.BV/TV": "Trabecular bone volume divided by trabecular total volume, reported as a fraction.",
+    "Tb.Th": "Mean maximal-sphere local thickness of trabecular bone.",
+    "Tb.Sp": "Mean maximal-sphere local thickness of non-bone space in the trabecular compartment.",
+    "Tb.N": "Mean inverse ridge-to-ridge spacing estimate in the trabecular compartment.",
+    "Tb.1/N.SD": "Standard deviation of ridge-to-ridge spacing used to estimate trabecular number.",
+    "Tb.BV": "Trabecular bone volume.",
+    "Tb.TV": "Trabecular compartment volume.",
+    "Ct.BMD": "Mean grayscale/BMD value inside the cortical compartment.",
+    "Ct.Th": "Mean maximal-sphere local thickness of cortical bone.",
+    "Ct.Po": "Cortical pore volume divided by cortical total volume, reported as a fraction.",
+    "Ct.Po.V": "Cortical pore volume.",
+    "Ct.Po.Dm": "Mean maximal-sphere local diameter of cortical pore space.",
+    "Ct.BV": "Cortical bone volume.",
+    "Ct.TV": "Cortical compartment volume.",
+}
+
+
+@dataclass(frozen=True)
+class MicroarchitectureResult:
+    """Container returned by :func:`compute_microarchitecture`.
+
+    Attributes:
+        measurements: Scalar parameter values and secondary distribution values.
+        maps: Parameter maps keyed by names such as ``"Tb.Th"`` and
+            ``"Ct.Po.Dm"``. Non-map scalar parameters are absent.
+        metadata: Calculation metadata, for example selected thickness backend.
+    """
+
+    measurements: dict[str, float]
+    maps: dict[str, np.ndarray] = field(default_factory=dict)
+    metadata: dict[str, str] = field(default_factory=dict)
+
+
+def units_for_measurement(name: str) -> str:
+    """Return display units for a measurement name."""
+    if name.endswith("BV/TV") or name.endswith(".Po"):
+        return "fraction"
+    if name.endswith(".BMD") or name.endswith("BMD SD"):
+        return "mgHA/cm^3"
+    if name.endswith(".BV") or name.endswith(".TV") or name.endswith(".V"):
+        return "mm^3"
+    if name == "Tb.N":
+        return "1/mm"
+    if ".Th" in name or ".Sp" in name or name.endswith(".Dm") or name == "Tb.1/N.SD":
+        return "mm"
+    return ""
+
+
+def measurement_rows(metrics: dict[str, float], maps: dict[str, np.ndarray] | None = None) -> list[dict[str, object]]:
+    """Format measurements as table rows for Slicer display or CSV export.
+
+    Scalar parameters place their value in the ``Mean`` column. Parameters with
+    an available map are summarized across positive finite map voxels and include
+    median, standard deviation, percentiles, and range.
+    """
+    ordered = [name for name in MEASUREMENT_ORDER if name in metrics]
+    ordered.extend(sorted(name for name in metrics if name not in set(ordered)))
+    return [
+        _measurement_row(name, metrics, maps or {})
+        for name in ordered
+        if name not in _SECONDARY_MEASUREMENTS
+    ]
+
+
+def write_measurement_csv(path, metrics: dict[str, float], maps: dict[str, np.ndarray] | None = None) -> None:
+    """Write formatted measurement rows to a CSV file."""
+    rows = measurement_rows(metrics, maps)
+    with Path(path).open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.DictWriter(handle, fieldnames=list(SUMMARY_COLUMNS))
+        writer.writeheader()
+        writer.writerows(rows)
+
+
+def _measurement_row(name: str, metrics: dict[str, float], maps: dict[str, np.ndarray]) -> dict[str, object]:
+    row = {column: "" for column in SUMMARY_COLUMNS}
+    row["Parameter"] = name
+    row["Mean"] = float(metrics[name])
+    row["Units"] = units_for_measurement(name)
+    if name in maps:
+        values = _map_values(maps[name])
+        if values.size:
+            row.update(
+                {
+                    "Mean": float(values.mean()),
+                    "Median": float(np.median(values)),
+                    "SD": float(values.std(ddof=0)),
+                    "P5": float(np.percentile(values, 5)),
+                    "P25": float(np.percentile(values, 25)),
+                    "P75": float(np.percentile(values, 75)),
+                    "P95": float(np.percentile(values, 95)),
+                    "Min": float(values.min()),
+                    "Max": float(values.max()),
+                }
+            )
+    return row
+
+
+def _map_values(array: np.ndarray) -> np.ndarray:
+    values = np.asarray(array, dtype=float)
+    values = values[np.isfinite(values) & (values != 0)]
+    return values

bone_microarchitecture/thickness.py

@@ -0,0 +1,343 @@
+from __future__ import annotations
+
+import sys
+
+import numpy as np
+from scipy import ndimage
+
+
+_NEIGHBOR_OFFSETS = tuple(
+    (dz, dy, dx)
+    for dz in (-1, 0, 1)
+    for dy in (-1, 0, 1)
+    for dx in (-1, 0, 1)
+    if (dz, dy, dx) != (0, 0, 0)
+)
+
+
+def local_thickness_map(mask, spacing: tuple[float, float, float]) -> np.ndarray:
+    """Return a bounded distance-transform thickness preview.
+
+    This fast map assigns each foreground voxel twice its distance to the
+    background. It is useful as a lightweight preview or fallback, but it is not
+    the maximal-sphere local thickness used for primary reporting.
+
+    Args:
+        mask: 3D binary object mask.
+        spacing: Voxel spacing in millimetres, ordered like the array axes.
+
+    Returns:
+        Float32 thickness map in millimetres, zero outside ``mask``.
+    """
+    binary = np.asarray(mask) > 0
+    if not binary.any():
+        return np.zeros(binary.shape, dtype=np.float32)
+    distance = ndimage.distance_transform_edt(binary, sampling=spacing)
+    distance *= 2.0
+    return distance.astype(np.float32, copy=False)
+
+
+def hildebrand_thickness_map(
+    mask,
+    spacing: tuple[float, float, float],
+    *,
+    backend: str = "auto",
+    center_dominance_mm: float | None = None,
+    diameter_margin_voxels: float = 0.5,
+) -> np.ndarray:
+    """Return a Hildebrand-style maximal-sphere local thickness map.
+
+    This follows the local-thickness concept used in ORMiR-XCT: compute the
+    Euclidean distance transform, keep non-dominated sphere centers, and assign
+    each object voxel the largest sphere diameter that contains it. The
+    implementation here is independent and keeps the candidate-selection rule
+    deliberately small: a center is skipped only when a neighboring center has a
+    clearly larger inscribed radius.
+
+    Args:
+        mask: 3D binary object mask.
+        spacing: Voxel spacing in millimetres, ordered like the array axes.
+        backend: Diameter-accumulation backend: ``"auto"``, ``"cpu"``, ``"mps"``, or
+            ``"opencl"``.
+        center_dominance_mm: Minimum radius advantage, in millimetres, required for a
+            neighboring center to dominate the current center. Defaults to
+            ``0.9 * min(spacing)``.
+        diameter_margin_voxels: Small voxel-scaled subtraction from sphere radius
+            before reporting diameter. This keeps assignment conservative at the
+            discretized boundary.
+
+    Returns:
+        Float32 local-thickness map in millimetres, zero outside ``mask``.
+    """
+    binary = np.asarray(mask) > 0
+    if not binary.any():
+        return np.zeros(binary.shape, dtype=np.float32)
+    spacing = tuple(float(value) for value in spacing)
+    distance = ndimage.distance_transform_edt(binary, sampling=spacing)
+    dominance_margin = float(center_dominance_mm if center_dominance_mm is not None else min(spacing) * 0.9)
+    medial_axis = _medial_axis(distance, dominance_margin)
+    backend = str(backend or "auto").strip().lower()
+    if backend == "auto":
+        backend = default_thickness_backend()
+    if backend == "mps":
+        return _mask_output(_accumulate_local_diameters_mps(distance, medial_axis, spacing, diameter_margin_voxels), binary)
+    if backend == "opencl":
+        return _mask_output(_accumulate_local_diameters_opencl(distance, medial_axis, spacing, diameter_margin_voxels), binary)
+    if backend == "cpu":
+        return _mask_output(_accumulate_local_diameters_cpu(distance, medial_axis, spacing, diameter_margin_voxels), binary)
+    raise ValueError("Thickness backend must be one of: auto, cpu, mps, or opencl.")
+
+
+def default_thickness_backend() -> str:
+    """Choose the fastest available diameter-accumulation backend for this machine."""
+    if sys.platform == "darwin":
+        try:
+            from .metal import is_metal_available
+
+            if is_metal_available():
+                return "mps"
+        except Exception:
+            pass
+    else:
+        try:
+            from .opencl import is_opencl_available
+
+            if is_opencl_available():
+                return "opencl"
+        except Exception:
+            pass
+    return "cpu"
+
+
+def separation_map(periosteal_mask, trabecular_mask, spacing: tuple[float, float, float]) -> np.ndarray:
+    """Return a marrow-space thickness map inside the periosteal compartment.
+
+    Args:
+        periosteal_mask: Full periosteal compartment mask.
+        trabecular_mask: Trabecular bone mask.
+        spacing: Voxel spacing in millimetres, ordered like the array axes.
+
+    Returns:
+        Fast distance-transform separation map in millimetres.
+    """
+    peri = np.asarray(periosteal_mask) > 0
+    trab = np.asarray(trabecular_mask) > 0
+    marrow = peri & ~trab
+    return local_thickness_map(marrow, spacing)
+
+
+def trabecular_number_map(
+    bone_mask,
+    domain_mask,
+    spacing: tuple[float, float, float],
+    *,
+    backend: str = "auto",
+    material_center_dominance_voxels: float = 0.5,
+    spacing_center_dominance_voxels: float = 0.9,
+    diameter_margin_voxels: float = 0.5,
+) -> np.ndarray:
+    """Estimate local trabecular number from ridge-to-ridge spacing.
+
+    The map is built in two stages. First, trabecular bone ridges are extracted
+    from the bone distance transform. Second, a local spacing field is estimated
+    in the trabecular domain after removing those ridges. Local trabecular number
+    is the inverse of that spacing field.
+
+    Args:
+        bone_mask: Trabecular bone phase mask.
+        domain_mask: Trabecular compartment mask.
+        spacing: Voxel spacing in millimetres, ordered like the array axes.
+        backend: Diameter-accumulation backend used for the local spacing field.
+        material_center_dominance_voxels: Voxel-scaled dominance threshold for extracting
+            trabecular material ridges.
+        spacing_center_dominance_voxels: Voxel-scaled dominance threshold for
+            extracting spacing-field centers.
+        diameter_margin_voxels: Voxel-scaled conservative radius adjustment for
+            sphere assignment.
+
+    Returns:
+        Float32 trabecular number map in 1/mm, zero outside valid domain voxels.
+    """
+    bone = np.asarray(bone_mask) > 0
+    domain = np.asarray(domain_mask) > 0
+    if not bone.any() or not domain.any():
+        return np.zeros(domain.shape, dtype=np.float32)
+    spacing = tuple(float(value) for value in spacing)
+    bone = bone & domain
+    bone_distance = ndimage.distance_transform_edt(bone, sampling=spacing)
+    material_ridge = _medial_axis(bone_distance, float(material_center_dominance_voxels) * min(spacing))
+    inter_axis = domain & ~material_ridge
+    spacing_map = hildebrand_thickness_map(
+        inter_axis,
+        spacing,
+        backend=backend,
+        center_dominance_mm=float(spacing_center_dominance_voxels) * min(spacing),
+        diameter_margin_voxels=diameter_margin_voxels,
+    )
+    number = np.zeros(domain.shape, dtype=np.float32)
+    valid = domain & np.isfinite(spacing_map) & (spacing_map > 0)
+    number[valid] = (1.0 / spacing_map[valid]).astype(np.float32, copy=False)
+    return number
+
+
+def summary(values) -> dict[str, float]:
+    """Summarize positive finite values with mean, percentiles, and range."""
+    array = np.asarray(values, dtype=float)
+    array = array[np.isfinite(array) & (array > 0)]
+    if array.size == 0:
+        return {
+            "mean": 0.0,
+            "median": 0.0,
+            "sd": 0.0,
+            "p5": 0.0,
+            "p25": 0.0,
+            "p75": 0.0,
+            "p95": 0.0,
+            "min": 0.0,
+            "max": 0.0,
+        }
+    return {
+        "mean": float(array.mean()),
+        "median": float(np.median(array)),
+        "sd": float(array.std(ddof=0)),
+        "p5": float(np.percentile(array, 5)),
+        "p25": float(np.percentile(array, 25)),
+        "p75": float(np.percentile(array, 75)),
+        "p95": float(np.percentile(array, 95)),
+        "min": float(array.min()),
+        "max": float(array.max()),
+    }
+
+
+def _medial_axis(distance: np.ndarray, dominance_margin: float) -> np.ndarray:
+    padded = np.pad(distance, 1, mode="constant", constant_values=0)
+    center = padded[1:-1, 1:-1, 1:-1]
+    inside = center > 0
+    dominated = _dominated_center_mask(padded, center, dominance_margin)
+    return inside & ~dominated
+
+
+def _dominated_center_mask(padded: np.ndarray, center: np.ndarray, dominance_margin: float) -> np.ndarray:
+    dominated = np.zeros(center.shape, dtype=bool)
+    for dz, dy, dx in _NEIGHBOR_OFFSETS:
+        neighbor = padded[
+            1 + dz : 1 + dz + center.shape[0],
+            1 + dy : 1 + dy + center.shape[1],
+            1 + dx : 1 + dx + center.shape[2],
+        ]
+        dominated |= (center + dominance_margin) <= neighbor
+    return dominated
+
+
+def _mask_output(thickness: np.ndarray, binary: np.ndarray) -> np.ndarray:
+    thickness = np.asarray(thickness, dtype=np.float32)
+    thickness[~binary] = 0
+    return thickness
+
+
+def _sphere_centers(distance: np.ndarray, medial_axis: np.ndarray):
+    z, y, x = np.nonzero(medial_axis)
+    radius = distance[medial_axis].astype(np.float32, copy=False)
+    if radius.size == 0:
+        return z, y, x, radius
+    order = np.argsort(radius)[::-1]
+    return z[order], y[order], x[order], radius[order]
+
+
+def _accumulate_local_diameters_cpu(
+    distance: np.ndarray,
+    medial_axis: np.ndarray,
+    spacing: tuple[float, float, float],
+    diameter_margin_voxels: float,
+) -> np.ndarray:
+    shape = distance.shape
+    thickness = np.zeros(shape, dtype=np.float32)
+    seed_z, seed_y, seed_x, seed_radius = _sphere_centers(distance, medial_axis)
+    diameter_margin = float(diameter_margin_voxels) * min(spacing)
+    inclusion_tolerance = _sphere_inclusion_tolerance(spacing)
+    for zc, yc, xc, radius in zip(seed_z, seed_y, seed_x, seed_radius):
+        value = np.float32(max(2.0 * (float(radius) - diameter_margin), 0.0))
+        if value <= 0:
+            continue
+        z0, z1, y0, y1, x0, x1 = _sphere_bounds(shape, int(zc), int(yc), int(xc), float(radius), spacing)
+        zz, yy, xx = _physical_offsets(z0, z1, y0, y1, x0, x1, int(zc), int(yc), int(xc), spacing)
+        in_sphere = (zz * zz + yy * yy + xx * xx) <= (float(radius) * float(radius) + inclusion_tolerance)
+        sub = thickness[z0:z1, y0:y1, x0:x1]
+        np.maximum(sub, np.where(in_sphere, value, 0).astype(np.float32, copy=False), out=sub)
+    return thickness
+
+
+def _accumulate_local_diameters_mps(
+    distance: np.ndarray,
+    medial_axis: np.ndarray,
+    spacing: tuple[float, float, float],
+    diameter_margin_voxels: float,
+) -> np.ndarray:
+    from .metal import metal_hildebrand_thickness_map
+
+    seed_z, seed_y, seed_x, seed_radius = _sphere_centers(distance, medial_axis)
+    return metal_hildebrand_thickness_map(
+        shape=distance.shape,
+        seed_z=seed_z,
+        seed_y=seed_y,
+        seed_x=seed_x,
+        seed_radius=seed_radius,
+        spacing=spacing,
+        diameter_margin=float(diameter_margin_voxels) * min(spacing),
+        inclusion_tolerance=_sphere_inclusion_tolerance(spacing),
+    )
+
+
+def _accumulate_local_diameters_opencl(
+    distance: np.ndarray,
+    medial_axis: np.ndarray,
+    spacing: tuple[float, float, float],
+    diameter_margin_voxels: float,
+) -> np.ndarray:
+    from .opencl import opencl_hildebrand_thickness_map
+
+    seed_z, seed_y, seed_x, seed_radius = _sphere_centers(distance, medial_axis)
+    return opencl_hildebrand_thickness_map(
+        shape=distance.shape,
+        seed_z=seed_z,
+        seed_y=seed_y,
+        seed_x=seed_x,
+        seed_radius=seed_radius,
+        spacing=spacing,
+        diameter_margin=float(diameter_margin_voxels) * min(spacing),
+        inclusion_tolerance=_sphere_inclusion_tolerance(spacing),
+    )
+
+
+def _sphere_bounds(shape, zc: int, yc: int, xc: int, radius: float, spacing: tuple[float, float, float]):
+    z_extent, y_extent, x_extent = (int(np.ceil(radius / value)) for value in spacing)
+    z0 = max(0, zc - z_extent)
+    z1 = min(shape[0], zc + z_extent + 1)
+    y0 = max(0, yc - y_extent)
+    y1 = min(shape[1], yc + y_extent + 1)
+    x0 = max(0, xc - x_extent)
+    x1 = min(shape[2], xc + x_extent + 1)
+    return z0, z1, y0, y1, x0, x1
+
+
+def _physical_offsets(
+    z0: int,
+    z1: int,
+    y0: int,
+    y1: int,
+    x0: int,
+    x1: int,
+    zc: int,
+    yc: int,
+    xc: int,
+    spacing: tuple[float, float, float],
+):
+    z_offsets = (np.arange(z0, z1, dtype=np.float32) - zc) * spacing[0]
+    y_offsets = (np.arange(y0, y1, dtype=np.float32) - yc) * spacing[1]
+    x_offsets = (np.arange(x0, x1, dtype=np.float32) - xc) * spacing[2]
+    return np.meshgrid(z_offsets, y_offsets, x_offsets, indexing="ij")
+
+
+def _sphere_inclusion_tolerance(spacing: tuple[float, float, float]) -> float:
+    spacing_min = min(float(value) for value in spacing)
+    return max(spacing_min * spacing_min, 1.0) * 1.0e-6

bone_microarchitecture-0.1.0.dist-info/METADATA

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

@@ -0,0 +1,13 @@
+bone_microarchitecture/__init__.py,sha256=zbUtxLJjBVFBXVyFSf4YEjBde9v7bPRHFOmRKq6Tvv4,880
+bone_microarchitecture/geometry.py,sha256=qVqmJTiPDh4z-MTZyrUsFqnR1soOytbubxXpzjDNuHc,1454
+bone_microarchitecture/metal.py,sha256=8d18vickLGhFVLJ6XwTeYxCA7kK-OXJZHDpNq9HgkF8,6410
+bone_microarchitecture/metrics.py,sha256=JM_lHlRdw-a8QPcvgCSPTZWQTW6W01nkSr2gQJ2fbos,3023
+bone_microarchitecture/opencl.py,sha256=kNEQf5Ol_53nw7oLQmVjIBOE5blDLfNAB3mzNkEV0w8,6054
+bone_microarchitecture/pipeline.py,sha256=l24PvYiuTxQS9YcNmqopp_7t4zy3G08c5YXtKgji6jo,8101
+bone_microarchitecture/results.py,sha256=SgBFlViVeTlvktk13uB3gkoS60Inhw2F9Cvv2SssEVw,5605
+bone_microarchitecture/thickness.py,sha256=8EKHjGV5HcDm5q-kCKrqg59zHH-Id-Jzxm6363gH7m8,12858
+bone_microarchitecture-0.1.0.dist-info/licenses/LICENSE,sha256=s4uvriA89nP0_DvvrvWoI7dplf8AtGVGOFp9yDO74IE,1071
+bone_microarchitecture-0.1.0.dist-info/METADATA,sha256=6amWY1OImOmx3UuOj--0Ih9wVdE4Cd842FlEb5WE3Ss,3462
+bone_microarchitecture-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+bone_microarchitecture-0.1.0.dist-info/top_level.txt,sha256=cDyY3x-M0kiZV7vMB5tnj_YrAu3hRYPVT76a7yty0Dg,23
+bone_microarchitecture-0.1.0.dist-info/RECORD,,

bone_microarchitecture-0.1.0.dist-info/WHEEL

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

bone_microarchitecture-0.1.0.dist-info/licenses/LICENSE

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

bone_microarchitecture-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bone_microarchitecture