Source code for morphogen.models.osteons

"""Haversian (cortical) bone: osteons remodelled one after another.

Cortical bone is renewed by basic multicellular units that tunnel along the bone axis,
resorb a cylinder of bone and refill it with concentric lamellae around a vascular
(Haversian) canal: a secondary osteon, bounded by a cement line. Each new osteon cuts
through the older ones, whose fragments, with the remains of older bone, form the
interstitial bone (Currey 2002). The model is a dead-leaves model of aligned cylinders
(Matheron 1968; Jeulin 1989): osteons of radius ``R`` arrive at Poisson positions of
the cross-section in random order, the last on top; a point covered by none is
interstitial bone. Within the top osteon, it lies in the canal (``d < rho R``), the
cement line (``d > R - c``) or the lamellar bone in between (``d``: its distance to
the axis of the osteon).

With ``lambda`` osteons per unit area chosen for a ``coverage`` ``p = 1 - exp(-lambda pi
E[R^2])``, the top osteon is an osteon weighted by its area, and a point falls in each
of its parts with the share of its area (exact):

* Haversian canals (the vascular porosity): ``p rho^2``;
* cement lines: ``p E[R^2 - max(R - c, rho R)^2] / E[R^2]``;
* lamellar bone of the osteons: the rest of ``p``; interstitial bone: ``1 - p``.
"""

from __future__ import annotations

import itertools
import math
from dataclasses import dataclass
from typing import ClassVar

import numpy as np
from numba import njit
from scipy.spatial import cKDTree

from morphogen._utils import check_fraction, check_positive
from morphogen.distributions import Distribution
from morphogen.domain import Domain, Grid
from morphogen.image import VoxelImage
from morphogen.models.base import Microstructure, Model, param, register, register_kind
from morphogen.models.planar import pixel_centres, plane_axes
from morphogen.seeding import SeedLike, make_rng

INTERSTITIAL, LAMELLAR, CEMENT, CANAL = 0, 1, 2, 3


@njit(cache=True)
def _osteon_levels(offsets, ptr, osteons, radii, canal_ratio, cement, reach, out):
    """The level sets of the lamellar bone, cement lines, canals and interstitial bone at
    points of the cross-section (``out``: (n, 4)), their candidate osteons from the top one down
    (``osteons[ptr[p]:ptr[p + 1]]``, the offsets of the points from their axes): for each
    phase, the minimum over the osteons ``i`` of ``max(s_i, -min_{j above i} (d_j -
    r_j))``, ``s_i`` the signed distance to the disc or annulus of the phase in osteon
    ``i``, within ``[-reach, reach]``."""
    for p in range(len(ptr) - 1):
        lowest = np.inf
        best0 = np.inf
        best1 = np.inf
        best2 = np.inf
        for k in range(ptr[p], ptr[p + 1]):
            i = osteons[k]
            d = math.hypot(offsets[k, 0], offsets[k, 1])
            r = radii[i]
            above = -lowest
            inner = canal_ratio * r
            outer = r - cement
            best0 = min(best0, max(max(inner - d, d - outer), above))  # lamellar
            best1 = min(best1, max(max(outer - d, d - r), above))  # cement line
            best2 = min(best2, max(d - inner, above))  # canal
            lowest = min(lowest, d - r)
            if lowest <= -reach:
                break
        out[p, 0] = min(max(best0, -reach), reach)
        out[p, 1] = min(max(best1, -reach), reach)
        out[p, 2] = min(max(best2, -reach), reach)
        out[p, 3] = min(max(-lowest, -reach), reach)  # interstitial: no osteon


[docs] @register_kind class OsteonStructure(Microstructure): """Osteons along ``axis``: discs of the cross-section (centres, radii) in the order of their arrival, the last on top, with a canal of ``canal_ratio`` times their radius and a cement line of ``cement`` thickness.""" kind = "osteons" def __init__(self, domain, axis, centres, radii, canal_ratio, cement, **kwargs): super().__init__(domain, **kwargs) self.axis = int(axis) self.centres = np.asarray(centres, dtype=float).reshape(-1, 2) self.radii = np.asarray(radii, dtype=float).reshape(-1) self.canal_ratio = float(canal_ratio) self.cement = float(cement) @property def n_osteons(self) -> int: return len(self.radii) def _top(self, plane: np.ndarray) -> tuple[np.ndarray, np.ndarray]: """The last osteon over each point of the cross-section (-1: none) and the distance of the point to its axis.""" b, c = plane_axes(self.axis) lower, lengths = self.domain.lower[[b, c]], self.domain.lengths[[b, c]] periodic = self.domain.periodic q = plane - lower if periodic: q = np.mod(q, lengths) q[q >= lengths] = 0.0 top = np.full(len(q), -1, dtype=np.int64) dist = np.full(len(q), np.inf) if not len(q) or not self.n_osteons: return top, dist tree = cKDTree(q, boxsize=lengths if periodic else None) centres = self.centres - lower if periodic: centres = np.mod(centres, lengths) centres[centres >= lengths] = 0.0 for i in range(self.n_osteons): # in order of arrival: the later on top hits = tree.query_ball_point(centres[i], self.radii[i], return_sorted=False) if not hits: continue hits = np.asarray(hits, dtype=np.int64) v = q[hits] - centres[i] if periodic: v -= lengths * np.round(v / lengths) top[hits] = i dist[hits] = np.hypot(v[:, 0], v[:, 1]) return top, dist def _phases(self, plane: np.ndarray) -> np.ndarray: top, dist = self._top(plane) out = np.full(len(plane), INTERSTITIAL, dtype=np.uint8) ok = top >= 0 r = self.radii[top[ok]] d = dist[ok] out[ok] = np.where( d < self.canal_ratio * r, CANAL, np.where(d > r - self.cement, CEMENT, LAMELLAR) ) return out
[docs] def phase_level_sets_at(self, points, reach: float = np.inf) -> dict[int, np.ndarray]: """The level sets of the lamellar bone (1), cement lines (2), canals (3) and interstitial bone (0) at points: in the cross-section, the parts of each osteon not covered by later ones, and the space no osteon covers (see :func:`_osteon_levels`), within ``[-reach, reach]`` (default: the largest radius).""" pts = np.asarray(points, dtype=float).reshape(-1, 3) b, c = plane_axes(self.axis) lower, lengths = self.domain.lower[[b, c]], self.domain.lengths[[b, c]] periodic = self.domain.periodic rmax = float(self.radii.max(initial=0.0)) reach = rmax if not np.isfinite(reach) else float(reach) out = np.full((len(pts), 4), reach) out[:, 3] = -reach # no osteon: interstitial if self.n_osteons: centres = self.centres - lower q = pts[:, [b, c]] - lower if periodic: centres = np.mod(centres, lengths) centres[centres >= lengths] = 0.0 q = np.mod(q, lengths) q[q >= lengths] = 0.0 tree = cKDTree(centres, boxsize=lengths if periodic else None) chunk = 8192 for s in range(0, len(q), chunk): lists = tree.query_ball_point(q[s : s + chunk], rmax + reach) counts = np.fromiter((len(x) for x in lists), dtype=np.int64, count=len(lists)) ost = np.fromiter(itertools.chain.from_iterable(lists), dtype=np.int64, count=int(counts.sum())) # fmt: skip owner = np.repeat(np.arange(len(lists)), counts) order = np.lexsort((-ost, owner)) # from the top osteon down ost, owner = ost[order], owner[order] offsets = q[s : s + chunk][owner] - centres[ost] if periodic: offsets -= lengths * np.round(offsets / lengths) ptr = np.concatenate([[0], np.cumsum(counts)]) _osteon_levels(np.ascontiguousarray(offsets), ptr, ost, self.radii, self.canal_ratio, self.cement, reach, out[s : s + chunk]) # fmt: skip return {INTERSTITIAL: out[:, 3], LAMELLAR: out[:, 0], CEMENT: out[:, 1], CANAL: out[:, 2]}
[docs] def level_set_at(self, points, reach: float = np.inf) -> np.ndarray: """The function of the lamellar bone (phase 1) at the points (:meth:`phase_level_sets_at`).""" return self.phase_level_sets_at(points, reach)[LAMELLAR]
[docs] def contains(self, points) -> np.ndarray: """Whether points lie in the lamellar bone of the osteons (phase 1).""" pts = np.asarray(points, dtype=float).reshape(-1, 3) b, c = plane_axes(self.axis) return self._phases(pts[:, [b, c]]) == LAMELLAR
# -- implicit functions ----------------------------------------------------------------
[docs] def implicit_phases(self) -> list[int]: return [INTERSTITIAL, LAMELLAR, CEMENT, CANAL]
def _implicit(self, grid: Grid) -> np.ndarray: """The implicit functions of the four phases in the cross-section of a grid (kept for the grid last asked): the rings of each osteon (its canal, its lamellae, its cement line: differences of distances to its axis) where no later osteon covers them, and the interstitial bone that none covers.""" from morphogen.models.implicit import band_of, grid_key, lattice_boxes, ordered_cover key = grid_key(grid) cached = getattr(self, "_fields", None) if cached is not None and cached[0] == key: return cached[1] band = band_of(grid) axes = plane_axes(self.axis) lengths = self.domain.lengths if self.domain.periodic else None shape = tuple(grid.shape[a] for a in axes) def objects(): for i in range(self.n_osteons - 1, -1, -1): # the later on top radius = self.radii[i] canal, cement = self.canal_ratio * radius, radius - self.cement reach = radius + band for slices, (du, dv) in lattice_boxes(self.centres[i], reach, grid, lengths, axes): r = np.hypot(du, dv).astype(np.float32) parts = [None] * 4 parts[LAMELLAR] = np.maximum(canal - r, r - cement) parts[CEMENT] = np.maximum(cement - r, r - radius) parts[CANAL] = r - canal yield slices, r - radius, parts parts, top = ordered_cover(shape, band, objects(), 4) parts[INTERSTITIAL] = -top self._fields = (key, parts) return parts
[docs] def phase_level_set( self, phase: int, shape=None, *, voxel_size=None, grid: Grid | None = None ) -> VoxelImage: """The implicit function of a phase (see :meth:`Microstructure.phase_level_set`), the same along the axis of the osteons.""" phase = int(phase) if phase not in self.implicit_phases(): raise ValueError(f"phase {phase}: the phases are {self.implicit_phases()}") grid = self.grid(shape, voxel_size=voxel_size, grid=grid) plane = self._implicit(grid)[phase] out = np.broadcast_to(plane[:, :, None], (*plane.shape, grid.shape[self.axis])) data = np.ascontiguousarray(np.moveaxis(out, 2, self.axis)) return VoxelImage.from_grid(data, grid, name="level_set", metadata=self.image_metadata())
[docs] def level_set(self, shape=None, *, voxel_size=None, grid: Grid | None = None) -> VoxelImage: """The implicit function of the lamellar bone of the osteons (phase 1).""" return self.phase_level_set(LAMELLAR, shape, voxel_size=voxel_size, grid=grid)
def _image(self, grid: Grid) -> np.ndarray: plane, shape = pixel_centres(grid, plane_axes(self.axis)) image = self._phases(plane).reshape(shape) out = np.broadcast_to(image[:, :, None], (*shape, grid.shape[self.axis])) return np.ascontiguousarray(np.moveaxis(out, 2, self.axis))
[docs] def voxelize(self, shape=None, *, voxel_size=None, grid: Grid | None = None, supersampling=1): grid = self.grid(shape, voxel_size=voxel_size, grid=grid) ss = int(supersampling) if ss == 1: data = self._image(grid) return VoxelImage.from_grid(data, grid, name="phase", metadata=self.image_metadata()) if not 1 <= ss <= 6: raise ValueError("supersampling must be an integer between 1 and 6") fine = Grid(grid.domain, tuple(n * ss for n in grid.shape)) ph = (self._image(fine) == LAMELLAR).astype(np.float32) nx, ny, nz = grid.shape data = ph.reshape(nx, ss, ny, ss, nz, ss).mean(axis=(1, 3, 5), dtype=np.float32) return VoxelImage.from_grid(data, grid, name="fraction", metadata=self.image_metadata())
[docs] def summary(self) -> dict: return {"n_osteons": self.n_osteons}
def _geometry(self) -> dict: return { "axis": self.axis, "centres": self.centres.tolist(), "radii": self.radii.tolist(), "canal_ratio": self.canal_ratio, "cement": self.cement, } @classmethod def _from_geometry(cls, domain, geometry, **kwargs): return cls( domain, geometry["axis"], geometry["centres"], geometry["radii"], geometry["canal_ratio"], geometry["cement"], **kwargs, )
[docs] @register @dataclass(frozen=True) class Osteons(Model): """Haversian bone: aligned osteons with canals and cement lines, remodelled one after another over a fraction ``coverage`` of the cross-section (a dead-leaves model of cylinders along ``axis``).""" name = "osteons" phases: ClassVar[dict[int, str]] = { INTERSTITIAL: "interstitial bone", LAMELLAR: "osteons (lamellar bone)", CEMENT: "cement lines", CANAL: "Haversian canals", } has_level_set = False count_label = "osteons" radius: Distribution = param( 1.0, doc="Radius of the osteons", kind="distribution", unit="length" ) coverage: float = param( 0.7, doc="Fraction of the cross-section remodelled into osteons", kind="fraction" ) canal_ratio: float = param( 0.2, doc="Radius of the Haversian canals, relative to the osteons", kind="fraction" ) cement_thickness: float = param(0.03, doc="Thickness of the cement lines", unit="length") axis: int = param(2, doc="Axis of the osteons (the bone axis: 0: x, 1: y, 2: z)", kind="int") def _validate(self) -> None: check_fraction(self.coverage, "coverage") check_fraction(self.canal_ratio, "canal_ratio") check_positive(self.cement_thickness, "cement_thickness", allow_zero=True) if self.axis not in (0, 1, 2): raise ValueError("axis: 0, 1 or 2") @property def intensity(self) -> float: """Osteons per unit area of the cross-section.""" return -math.log1p(-self.coverage) / (math.pi * self.radius.moment(2))
[docs] def generate(self, domain: Domain, seed: SeedLike = None) -> OsteonStructure: rng, seed_info = make_rng(seed) b, c = plane_axes(self.axis) rmax = self.radius.upper() margin = 0.0 if domain.periodic else rmax lower = domain.lower[[b, c]] - margin size = domain.lengths[[b, c]] + 2.0 * margin n = int(rng.poisson(self.intensity * size[0] * size[1])) centres = lower + rng.random((n, 2)) * size radii = self.radius.sample(rng, n) if domain.periodic and np.any(2.0 * radii > size.min()): raise ValueError("osteons: a periodic box wider than the osteons") return OsteonStructure( domain, self.axis, centres, radii, self.canal_ratio, self.cement_thickness, model=self, seed=seed_info, )
[docs] def expected_count(self, domain: Domain) -> float: """Mean number of osteons across the domain (cut ones included).""" b, c = plane_axes(self.axis) return float(self.intensity * domain.lengths[b] * domain.lengths[c])
[docs] def theory(self, domain: Domain | None = None) -> dict[str, float]: p, rho, t = self.coverage, self.canal_ratio, self.cement_thickness r2 = self.radius.moment(2) inner = self.radius.expect(lambda r: np.maximum(r - t, rho * r) ** 2) canal = p * rho * rho cement = p * (r2 - inner) / r2 return { "intensity": self.intensity, "volume_fraction_0": 1.0 - p, "volume_fraction_1": p - canal - cement, "volume_fraction_2": cement, "volume_fraction_3": canal, "porosity": canal, }