morphogen.models.deadleaves

Dead leaves models (Matheron 1968; Jeulin 1997).

Leaves fall one after the other, each hiding what it covers; after infinitely many, every point belongs to the last leaf that covered it. The perfect simulation of Kendall & Thönnes (1999) runs the time backwards: leaves are drawn one by one, each going under the earlier ones, so that a point belongs to the first leaf drawn that covers it, and the drawing stops once the domain is covered. Here it stops once the voxel centres of a check grid are covered, and a third more leaves are drawn, which leaves a negligible part uncovered; voxels left uncovered at finer resolutions take the leaf of the nearest centre.

The leaves are spheres, or spheroids (shape: spheroid: semi-axes a, a and aspect_ratio * a about an axis drawn from orientation), of random sizes. Each phase may have its own law of sizes (phase_radius: families of leaves, the multicomponent dead leaves of Jeulin), phase_fractions being the fractions of space of the phases: the leaves of phase i fall in the proportion p_i ∝ q_i / E[V_i]. A finite coverage c (the mean number of leaves falling on a point) stops the fall: the points that no leaf covers, a fraction exp(-c), keep the background phase (sequential dead leaves, from the Boolean model for small c to the dead leaves as c grows).

The visible parts of the leaves form a random tessellation with non-convex cells: the cell label of a voxel is the index of its leaf (the background, if any, is the last label), and the leaves can carry crystal orientations (polycrystals of interpenetrating grains).

Theory (Jeulin 1997). Let K_i(h) be the mean geometric covariogram of the leaves of family i (K_i(0) = E[V_i]), κ_i = K_i / K_i(0) and c_i = c q_i the mean number of its leaves over a point. Going back in time, the leaves hitting both x and x + h come at the rate a_i = c_i κ_i, those hitting x only at b_i = c_i (1 - κ_i), those hitting either at λ = Σ c_i (2 - κ_i), and those hitting x + h at μ = c:

  • P(x, x + h in the same leaf of i) = (a_i / λ) (1 - e^{-λ});

  • P(x in a leaf of i, x + h in another of j) = (b_i q_j + b_j q_i)(I_1 - I_2), with I_1 = (1 - e^{-λ}) / λ and I_2 = (e^{-λ} - e^{-μ}) / (μ - λ);

  • P(x in a leaf of i, x + h uncovered) = b_i I_2, P(both uncovered) = e^{-λ}.

With complete coverage (c → ∞) they become a_i / λ and (b_i q_j + b_j q_i) / λ: one family of phases of probabilities p_i gives the covariance p_i^2 + p_i (1 - p_i) r(h) of phase i, r(h) = K(h) / (2K(0) - K(h)). A sphere of radius R and volume V has K(h) = V (1 - 3h/(4R) + h^3/(16R^3)) up to 2R; a spheroid, an affine image of the ball, K(h w) = V k(h sqrt((1 - t^2)/a^2 + t^2/c^2)), with t = w · axis and k(s) = 1 - 3s/4 + s^3/16 (s < 2), the covariogram of the unit ball over its volume.

morphogen.models.deadleaves.SHAPES = ('sphere', 'spheroid')

Shapes of the leaves.

class morphogen.models.deadleaves.DeadLeaves(domain: Domain, centers, radii, leaf_phases, orientations=None, *, axes=None, aspect: float = 1.0, background: int | None = None, **kwargs)[source]

Bases: Microstructure

Leaves in the order they cover the space (the first one is on top), and the background that they leave uncovered (finite coverage; the last cell).

property n_leaves: int
labels(shape=None, *, voxel_size=None, grid: Grid | None = None) → VoxelImage[source]

Image of the visible leaves (int32 leaf indices; the background: n_leaves).

voxelize(shape=None, *, voxel_size=None, grid: Grid | None = None, supersampling=1)[source]

Phase image (uint8), or partial volume fractions of phase 1 (float32) when supersampling > 1 (supersampling**3 sub-samples per voxel).

leaf_of(points) → ndarray[source]

Visible cell at each point: its leaf, or the background (n_leaves).

contains(points) → ndarray[source]

Whether points lie in phase 1.

implicit_phases() → list[int][source]

The phases of the realization, each described by an implicit function (phase_level_set()), in increasing order: phase 1 and what surrounds it (the structures of more phases, or of others, say theirs).

phase_level_set(phase: int, shape=None, *, voxel_size=None, grid: Grid | None = None) → VoxelImage[source]

The implicit function of a phase (see Microstructure.phase_level_set()): the leaves of the phase outside the leaves on top of them, each by the distance to its sphere (spheroids: a function that vanishes on them), clipped to a band of four voxels.

level_set(shape=None, *, voxel_size=None, grid: Grid | None = None) → VoxelImage[source]

The implicit function of phase 1 (phase_level_set()).

level_set_at(points, reach: float = inf) → ndarray[source]

Two phases: the level set of the visible parts of the leaves of phase 1 (each leaf minus those above it), see _visible_levels(), within [-reach, reach] (default: the largest radius); the points that no leaf covers are of phase 0 (of the background phase, with a finite coverage). Its zero set is the boundary of phase 1, sharp edges included: the exact meshes follow it. More phases: one level set per phase (phase_level_sets_at()), of which this is that of phase 1.

phase_level_sets_at(points, reach: float = inf) → dict[int, ndarray][source]

The functions of all the phases at the points: the visible parts of the leaves of each phase (the uncovered points: of the background phase, or of none), see _visible_levels(), within [-reach, reach] (default: the largest radius).

summary() → dict[source]

Counts and sizes describing the realization.

class morphogen.models.deadleaves.DeadLeavesModel(radius: Distribution | None = None, phase_fractions: tuple[float, ...] = (0.5, 0.5), phase_radius: tuple[Distribution, ...] | None = None, shape: str = 'sphere', aspect_ratio: float = 1.0, orientation: OrientationDistribution = Isotropic(), coverage: float | None = None, background: int = 0, crystal_orientations: bool = False, *, anisotropy: Anisotropy | None = None)[source]

Bases: Model

Dead leaves of spheres or spheroids, of one or several families: each point belongs to the last leaf covering it (or to a background, with a finite coverage).

phases: ClassVar[dict[int, str]] = {0: 'leaves of phase 0', 1: 'leaves of phase 1'}

Meaning of the phase indices of the voxel images.

count_label: ClassVar[str] = 'leaves'

Objects counted by expected_count() (fibres, spheres, cells…).

property has_level_set: bool

one level set.

Type:

Leaves of the phase 1 among those of the phase 0

property aspect: float

spheres).

Type:

The polar over the equatorial semi-axis of the leaves (1

families() → list[tuple[int, Distribution, float, float]][source]

The families of leaves: their phase, the law of their radii, the fraction of space q of their leaves and their proportion p among the leaves.

mean_leaf_volume() → float[source]

The mean volume of a falling leaf, 1 / Σ q_i / E[V_i].

active_phases() → dict[int, str][source]

Phases the realizations of this model can contain, with their names (the phases of the model, unless its parameters choose them).

generate(domain: Domain, seed: int | SeedSequence | Generator | None = None) → DeadLeaves[source]

One realization of the model in domain.

normalized_covariogram(h, law: Distribution | None = None, direction=None)[source]

K(h) / K(0): the mean geometric covariogram of the leaves of a law of radii (that of the first family by default) over their mean volume, for the distances h along direction (or averaged over the directions).

bivariate(h, direction=None) → ndarray[source]

The joint probabilities of the families (and of the background, last, with a finite coverage) at x and x + h: shape (..., F, F) or (..., F + 1, F + 1).

covariance(h, phase: int = 1, direction=None) → ndarray[source]

P(x and x + h in the phase) (averaged over the directions without direction).

same_leaf_probability(h, direction=None) → ndarray[source]

Probability that two points at the distance h see the same leaf: Σ a_i / λ (times 1 - e^{-λ} with a finite coverage).

phase_fraction(phase: int) → float[source]

The fraction of space of a phase.

integral_range(phase: int = 1) → float[source]

∫ (C(h) - p^2) dh / (p (1 - p)) over the space, for the phase of fraction p (Gauss-Legendre in the distance, over 24 directions when the leaves are not isotropic).

theory(domain: Domain | None = None) → dict[str, float][source]

Theoretical morphological characteristics known in closed form (may be empty).

Some values depend on the domain (e.g. the intensity implied by a number of cells).