Source code for morphogen.analysis.surface

"""Specific surface area by the Cauchy-Crofton formula.

The number of boundary crossings per unit length of test lines, ``P_L``, is counted
along discrete directions of the voxel lattice; for any structure
``S_V = 2 <P_L>``, the mean being taken over isotropically distributed directions. It
is approximated by a weighted sum over 3 (axes) or 13 (axes, face and body diagonals)
directions, each weighted by the solid angle of its Voronoi cell on the unit sphere.
"""

from __future__ import annotations

import numpy as np
from scipy.spatial import SphericalVoronoi

from morphogen.analysis.basic import as_array, indicator
from morphogen.image import VoxelImage

DIRECTIONS_3 = ((1, 0, 0), (0, 1, 0), (0, 0, 1))
DIRECTIONS_13 = (
    *DIRECTIONS_3,
    (1, 1, 0),
    (1, -1, 0),
    (1, 0, 1),
    (1, 0, -1),
    (0, 1, 1),
    (0, 1, -1),
    (1, 1, 1),
    (1, 1, -1),
    (1, -1, 1),
    (-1, 1, 1),
)


[docs] def crofton_weights(directions, spacing=(1.0, 1.0, 1.0)) -> np.ndarray: """Solid-angle weights (summing to 1) of the physical directions ``d * spacing``.""" d = np.asarray(directions, dtype=float) * np.asarray(spacing, dtype=float) u = d / np.linalg.norm(d, axis=1, keepdims=True) pts = np.vstack([u, -u]) sv = SphericalVoronoi(pts, radius=1.0, threshold=1e-8) areas = sv.calculate_areas() n = len(u) w = areas[:n] + areas[n:] return w / w.sum()
def _pair_slices(d, shape): src, dst = [], [] for c, n in zip(d, shape, strict=True): if c > 0: src.append(slice(0, n - c)) dst.append(slice(c, n)) elif c < 0: src.append(slice(-c, n)) dst.append(slice(0, n + c)) else: src.append(slice(None)) dst.append(slice(None)) return tuple(src), tuple(dst)
[docs] def transitions(data: np.ndarray, d, periodic: bool) -> tuple[int, int]: """Number of pairs (x, x + d) with different values, and number of pairs.""" if periodic: shifted = np.roll(data, shift=tuple(-c for c in d), axis=(0, 1, 2)) return int(np.count_nonzero(data != shifted)), int(data.size) src, dst = _pair_slices(d, data.shape) a, b = data[src], data[dst] return int(np.count_nonzero(a != b)), int(a.size)
[docs] def interface_density(data: np.ndarray, spacing, *, periodic: bool, directions=13) -> float: """Area per unit volume of the boundaries between different values of ``data``.""" dirs = DIRECTIONS_13 if directions == 13 else DIRECTIONS_3 if directions == 3 else None if dirs is None: raise ValueError("directions: 3 or 13") spacing = np.asarray(spacing, dtype=float) weights = crofton_weights(dirs, spacing) total = 0.0 for w, d in zip(weights, dirs, strict=True): if not periodic and any(abs(c) >= n for c, n in zip(d, data.shape, strict=True)): continue n_cross, n_pairs = transitions(data, d, periodic) step = float(np.linalg.norm(np.asarray(d) * spacing)) if n_pairs: total += w * n_cross / (n_pairs * step) return 2.0 * total
[docs] def specific_surface(image, phase: int = 1, *, directions: int = 13, periodic=None) -> float: """Interface area of ``phase`` per unit volume of the image (Crofton estimate).""" data = as_array(image) if data.dtype.kind == "f": raise ValueError("specific_surface needs a phase image (not partial volumes)") spacing = image.spacing if isinstance(image, VoxelImage) else (1.0, 1.0, 1.0) if periodic is None: periodic = image.periodic if isinstance(image, VoxelImage) else False ind = indicator(data, phase) return interface_density(ind, spacing, periodic=periodic, directions=directions)
[docs] def boundary_density(labels, *, directions: int = 13, periodic=None) -> float: """Area of the boundaries between cells per unit volume, for a label image.""" data = as_array(labels) spacing = labels.spacing if isinstance(labels, VoxelImage) else (1.0, 1.0, 1.0) if periodic is None: periodic = labels.periodic if isinstance(labels, VoxelImage) else False return interface_density(data, spacing, periodic=periodic, directions=directions)