synthbold.splines

Optional spline-based vessel geometry generator.

Unlinke the label maps found in synthbold.geometies, this module is a thin wrapper of the spline-based vessel geometry generator synthspline (https://github.com/balbasty/synthspline). The module is intentionally kept separate so that import synthbold does not require synthspline to be installed; the dependency is only imported lazily, at the point a SplineVessels instance is actually constructed. Install synthspline` with pip install synthbold[splines].

class synthbold.splines.SplineVessels(shape: tuple[int, int, int] = (128, 128, 128), fov: tuple[float, float, float] = (32.0, 32.0, 32.0), nb_levels: int = 2, tree_density: tuple[float, float] = (0.01, 0.01), tortuosity: tuple[float, float] = (5.0, 3.0), radius: tuple[float, float] = (0.1, 0.02), radius_change: tuple[float, float] = (1.0, 0.1), nb_children: tuple[float, float] = (5.0, 5.0), radius_ratio: tuple[float, float] = (0.7, 0.1), device: str | device = 'cpu', seed: int | None = None)

Bases: BaseGeometry

Random vessel-tree mask generator based on synthspline.

Generates a single hierarchical, branching vessel tree per sample using synthspline’s SynthSplineBlock, as an alternative to the straight-cylinder and cylinder-tree geometries in synthbold.geometries. Unlike those, tree topology and shape parameters (density, tortuosity, radius, branching) are drawn from log-normal distributions defined by synthspline itself rather than sampled here.

Requires the optional synthspline package; install with pip install synthbold[splines]. The dependency is only imported when this class is instantiated, so importing synthbold never requires it.

Parameters:

  • shape – Matrix size of the spline label map (X, Y, Z).

  • fov – Field of view in mm, used to compute voxel size.

  • nb_levels – Number of hierarchical levels in the tree.

  • tree_density – (mean, std) of the log-normal distribution of trees/mm^3.

  • tortuosity – (mean, std) of the log-normal distribution of tortuosity (cord / length).

  • radius – (mean, std) of the log-normal distribution of the root radius in mm.

  • radius_change – (mean, std) of the log-normal distribution of radius variation along a spline.

  • nb_children – (mean, std) of the log-normal distribution of the number of branches per spline.

  • radius_ratio – (mean, std) of the log-normal distribution of the child/parent radius ratio.

  • device – Target compute device, e.g. ‘cuda’ or ‘cpu’.

  • seed – Random seed for reproducibility.

Notes

synthspline draws from PyTorch’s global RNG rather than an explicit torch.Generator, so this class seeds torch.manual_seed once at construction time (if seed is given) as a best effort for reproducibility. Unlike the other geometries in this package, samples are therefore not reproducible if other unseeded PyTorch random calls are interleaved on the same process between samples.

Raises:

ImportError – If synthspline is not installed.

Examples

Create 100 random spline vessel-tree label maps and save to disk:

>>> shape = (128, 128, 128)
>>> fov = (32.0, 32.0, 32.0)
>>> fname = "<fname.zarr>"
>>> vessel_map = SplineVessels(shape, fov)
>>> vessel_map(100, fname)
property attrs: dict[str, Any]

Metadata for ZARR/NIfTI storage.

forward() → Tensor

Generate a single random spline vessel-tree label map.

classmethod from_config(config: Config) → Self

Constructs spline vessel-tree label map instance from configuration object.