"""Chords, granulometry, local thickness, Euler characteristic and geometric tortuosity.
* *Chord lengths*: lengths of the runs of a phase along the lines of the grid (the
linear sections of the phase). On periodic images, runs wrap around the faces; on
other images, runs cut by the faces are left out.
* *Granulometry by openings*: fraction of the phase left by the opening with a ball of
radius r (erosion then dilation, both exact Euclidean balls through distance
transforms; Matheron 1975, Serra 1982). Its decrease with r is the size distribution of
the phase; the *local thickness* of a voxel is twice the largest radius of an opening
that keeps it (Hildebrand & Rüegsegger 1997): the pore sizes are the local thickness of
the pores.
* *Euler characteristic* of a phase (6-connected voxels): number of components - tunnels +
cavities, from the counts of voxels, pairs, squares and cubes of voxels (Ohser &
Mücklich 2000); its density, with the volume fraction and the specific surface, gives
three of the Minkowski functionals.
* *Geometric tortuosity*: shortest paths inside the phase (26-connected voxels, Euclidean
steps) from one face of the box to the opposite face, divided by the distance between
the faces.
"""
from __future__ import annotations
from dataclasses import dataclass
import numpy as np
from scipy import ndimage
from morphogen.analysis.basic import indicator
def _periodic(image, periodic) -> bool:
if periodic is not None:
return bool(periodic)
return bool(getattr(image, "periodic", False))
def _spacing(image) -> np.ndarray:
return np.asarray(getattr(image, "spacing", (1.0, 1.0, 1.0)), dtype=float)
# -- chords ----------------------------------------------------------------------------------
[docs]
def chord_lengths(image, phase: int = 1, axis: int = 0, *, periodic=None) -> np.ndarray:
"""Lengths of the chords of ``phase`` along ``axis`` (physical units)."""
data = indicator(image, phase)
lines = np.moveaxis(data, axis, -1).reshape(-1, data.shape[axis])
n = lines.shape[1]
h = _spacing(image)[axis]
if _periodic(image, periodic):
full = lines.all(axis=1)
lines = lines[~full] # lines inside the phase: chords longer than the box
if not len(lines):
return np.zeros(0)
# start every line on a voxel outside the phase: no run wraps around
shift = np.argmin(lines, axis=1)
idx = (np.arange(n)[None, :] + shift[:, None]) % n
lines = np.take_along_axis(lines, idx, axis=1)
padded = np.pad(lines, ((0, 0), (1, 1)))
d = np.diff(padded.astype(np.int8), axis=1)
starts = np.nonzero(d == 1)
ends = np.nonzero(d == -1)
return (ends[1] - starts[1]).astype(float) * h
padded = np.pad(lines, ((0, 0), (1, 1)))
d = np.diff(padded.astype(np.int8), axis=1)
_, s_col = np.nonzero(d == 1)
_, e_col = np.nonzero(d == -1)
keep = (s_col > 0) & (e_col < n) # runs cut by the faces are left out
return (e_col[keep] - s_col[keep]).astype(float) * h
[docs]
def mean_chord_length(image, phase: int = 1, *, periodic=None) -> float:
"""Mean chord length of ``phase`` over the three axes (all chords pooled)."""
chords = np.concatenate([chord_lengths(image, phase, a, periodic=periodic) for a in range(3)])
return float(chords.mean()) if chords.size else float("nan")
# -- openings, granulometry, local thickness -------------------------------------------------------
def _distance(mask: np.ndarray, spacing, periodic: bool, pad: int) -> np.ndarray:
"""Euclidean distance from every voxel of ``mask`` to the nearest voxel outside it
(periodic images: through the faces, up to ``pad`` voxels)."""
if periodic and pad > 0:
big = np.pad(mask, pad, mode="wrap")
dist = ndimage.distance_transform_edt(big, sampling=spacing)
return dist[pad:-pad, pad:-pad, pad:-pad]
return ndimage.distance_transform_edt(mask, sampling=spacing)
[docs]
@dataclass
class Granulometry:
"""Openings of a phase by balls of increasing radius."""
radii: np.ndarray # physical radii
fractions: np.ndarray # volume fraction of the phase kept by the opening of each radius
thickness: np.ndarray # local thickness (2 x largest opening radius) of each voxel
@property
def size_distribution(self) -> np.ndarray:
"""Volume fraction of the phase whose largest opening radius is each radius."""
f = np.append(self.fractions, 0.0)
return f[:-1] - f[1:]
@property
def mean_radius(self) -> float:
"""Mean of the radius of the largest ball (of the radii probed) containing a
point of the phase."""
dist = self.size_distribution
return float(np.sum(dist * self.radii) / dist.sum()) if dist.sum() > 0 else float("nan")
[docs]
def granulometry(image, phase: int = 1, radii=None, *, periodic=None) -> Granulometry:
"""Openings of ``phase`` by balls of the radii given (physical units; default: steps
of half a voxel up to the largest inscribed ball). The opening of radius r is the
union of the balls of radius r (the voxels closer than r to their centre) whose centre
is at least r from the voxels outside the phase, as in the local thickness of
Hildebrand & Rüegsegger (1997): a layer of n voxels has thickness n voxels. Each voxel
gets the largest radius whose opening keeps it, so that the fractions kept decrease
with the radius (discrete Euclidean balls do not make exact granulometries)."""
mask = indicator(image, phase)
h = _spacing(image)
per = _periodic(image, periodic)
vol = max(int(mask.sum()), 1)
hmin = float(h.min())
pad = 0
if per: # wrap the image by more than the largest ball (bounded by the plain transform)
rough = ndimage.distance_transform_edt(mask, sampling=h)
pad = min(int(np.ceil(rough.max() / hmin)) + 2, max(mask.shape))
dist = _distance(mask, h, per, pad)
if radii is None:
radii = hmin * (1.0 + 0.5 * np.arange(max(0, int(2.0 * (dist.max() / hmin - 1.0))) + 1))
radii = np.sort(np.asarray(radii, dtype=float))
radius = np.where(mask, 0.5 * hmin, 0.0) # largest opening radius of every voxel
for r in radii:
# balls of radius r centred on voxels at least r from the voxels outside the
# phase; each covers the voxels closer than r to its centre
centres = dist >= r
if not centres.any():
break
reach = _distance(~centres, h, per, pad) # distance to the nearest centre
radius[mask & (reach < r)] = r
kept = radius[mask]
fractions = np.array([np.count_nonzero(kept >= r) / vol for r in radii])
return Granulometry(radii=radii, fractions=fractions, thickness=2.0 * radius)
[docs]
def local_thickness(image, phase: int = 1, *, periodic=None) -> np.ndarray:
"""Local thickness of every voxel of ``phase`` (0 elsewhere)."""
return granulometry(image, phase, periodic=periodic).thickness
# -- Euler characteristic ---------------------------------------------------------------------
[docs]
def euler_characteristic(image, phase: int = 1, *, periodic=None) -> int:
"""Euler characteristic (number of components - tunnels + cavities) of ``phase``,
6-connected (its complement 26-connected): vertices - edges + squares - cubes of the
complex whose vertices are the voxels of the phase, edges their pairs of face
neighbours, squares and cubes their 2 x 2 and 2 x 2 x 2 blocks (Ohser & Mücklich
2000). Periodic images are counted on the torus. Objects closer than a voxel touch on
the image: the estimate is biased by their contacts (for random objects, about half
the number of pairs closer than a voxel)."""
x = indicator(image, phase)
if not _periodic(image, periodic):
x = np.pad(x, 1)
def nxt(a, axis):
return np.roll(a, -1, axis=axis)
vertices = int(x.sum())
edges = sum(int((x & nxt(x, a)).sum()) for a in range(3))
squares = 0
for a, b in ((0, 1), (0, 2), (1, 2)):
pair = x & nxt(x, a)
squares += int((pair & nxt(pair, b)).sum())
cubes = x & nxt(x, 0)
cubes = cubes & nxt(cubes, 1)
cubes = cubes & nxt(cubes, 2)
return vertices - edges + squares - int(cubes.sum())
[docs]
@dataclass
class Minkowski:
"""Densities of the four Minkowski functionals of a phase: ``V_V``, ``S_V``, the
integral of mean curvature ``M_V`` (``(1/2) int (1/R1 + 1/R2) dS`` per unit volume)
and the Euler characteristic ``chi_V``."""
volume_fraction: float
specific_surface: float
euler_density: float # Euler characteristic per unit volume
mean_curvature: float = float("nan")
[docs]
def minkowski(image, phase: int = 1, *, periodic=None) -> Minkowski:
"""The Minkowski densities of a phase of an image: its volume fraction, specific surface,
density of Euler characteristic and density of mean curvature."""
from morphogen.analysis.surface import specific_surface
from morphogen.analysis.topology import mean_curvature_density
volume = float(np.prod(np.asarray(indicator(image, phase).shape) * _spacing(image)))
return Minkowski(
volume_fraction=float(indicator(image, phase).mean()),
specific_surface=specific_surface(image, phase, periodic=periodic),
euler_density=euler_characteristic(image, phase, periodic=periodic) / volume,
mean_curvature=mean_curvature_density(image, phase, periodic=periodic),
)
# -- geometric tortuosity -----------------------------------------------------------------------
[docs]
def geodesic_distance(image, phase: int = 1, axis: int = 0) -> np.ndarray:
"""Length of the shortest path inside ``phase`` (26-connected voxels, Euclidean steps
between voxel centres) from the face ``axis = 0`` of the box to every voxel (inf: not
reached; NaN outside the phase)."""
from scipy.sparse import coo_matrix
from scipy.sparse.csgraph import dijkstra
mask = indicator(image, phase)
h = _spacing(image)
index = np.full(mask.shape, -1, dtype=np.int64)
index[mask] = np.arange(int(mask.sum()))
rows, cols, weights = [], [], []
def pair(d, n): # slices of the voxels and of their neighbours at offset d
return (slice(0, n - d), slice(d, n)) if d >= 0 else (slice(-d, n), slice(0, n + d))
for offset in np.ndindex(3, 3, 3):
d = np.array(offset) - 1
if tuple(d) <= (0, 0, 0):
continue # each pair of neighbours once
sa, sb = zip(*(pair(int(di), n) for di, n in zip(d, mask.shape, strict=True)), strict=True)
a, b = index[sa], index[sb]
ok = (a >= 0) & (b >= 0)
rows.append(a[ok])
cols.append(b[ok])
weights.append(np.full(int(ok.sum()), float(np.linalg.norm(d * h))))
n = int(mask.sum())
graph = coo_matrix(
(np.concatenate(weights), (np.concatenate(rows), np.concatenate(cols))), shape=(n, n)
).tocsr()
sources = np.take(index, 0, axis=axis)
sources = sources[sources >= 0]
out = np.full(mask.shape, np.nan)
if sources.size == 0:
out[mask] = np.inf
return out
dist = dijkstra(graph, directed=False, indices=sources, min_only=True)
out[mask] = dist + 0.5 * h[axis] # from the face, not from the first voxel centres
return out
[docs]
def geometric_tortuosity(image, phase: int = 1, axis: int = 0) -> float:
"""Mean length of the shortest paths through ``phase`` between the faces normal to
``axis``, divided by the edge of the box (inf when the phase does not percolate)."""
dist = geodesic_distance(image, phase, axis)
outlet = np.take(dist, -1, axis=axis)
outlet = outlet[np.isfinite(outlet) | np.isinf(outlet)]
reached = outlet[np.isfinite(outlet)]
if reached.size == 0:
return float("inf")
h = _spacing(image)[axis]
length = dist.shape[axis] * h
return float(np.mean(reached + 0.5 * h) / length)