synthbold.base

Abstract base classes and mixins for the synthBOLD synthesis pipeline.

class synthbold.base.BaseGeometry(shape: tuple[int, ...], *, device: str | device = 'cpu', seed: int | None = None)

Bases: ABC, RandomGeneratorMixin

Abstract base for creating basic geometries.

Subclasses implement forward() to produce a single sample. This class provides the batch loop (__call__), optional save-to-disk (ZARR or NIfTI), cached coordinate grids, and serialisation of metadata via attrs.

Parameters:

  • shape – Spatial dimensions (X, Y, Z) of each generated volume.

  • device – PyTorch device for tensor allocation and RNG.

  • seed – Integer seed for reproducible output; None for random.

property attrs: dict[str, Any]

Metadata for ZARR/NIfTI storage.

dtype = torch.float32
abstractmethod forward() → Tensor

Generate random geometry labels.

abstractmethod classmethod from_config(config: Config) → Self

Constructs a geometry instance from a configuration object.

property normalized_grid: Tensor

Grid normalized to [-1, 1] of shape (X, Y, Z, 3).

property voxel_grid: Tensor

Creates target mesh grid of shape (X, Y, Z, 3).

class synthbold.base.Model(*, device: str = 'cpu', seed: int | None = None)

Bases: ABC, RandomGeneratorMixin

Abstract base class for making single models callable.

Parameters:

  • device – PyTorch device for tensor allocation and RNG.

  • seed – Integer seed for reproducible output; None for random.

property attrs: dict[str, Any]

Common metadata for ZARR/NIfTI storage.

abstractmethod forward(data: Tensor) → Tensor

Generate data.

Note

Call the instance (model(data)) instead of model.forward(data). In this implementation, __call__ transfers inputs to self.device before invoking forward.

class synthbold.base.ObjectGeometry(shape: tuple[int, int, int] = (128, 128, 128), fov: tuple[float, float, float] = (1.0, 1.0, 1.0), num_objects: int | None = None, vf_range: tuple[float, float] | None = (0.05, 0.1), diameter_range: tuple[float, float] = (0.05, 2.0), allow_overlap: bool = True, device: str = 'cpu', seed: int | None = None)

Bases: BaseGeometry, ABC

Abstract base for creating basic objects.

Parameters:

  • shape – Spatial dimensions (X, Y, Z) of each generated volume.

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

  • num_objects – Fixed number of objects to generate. Mutually exclusive with

  • vf_range.

  • vf_range – Range of target volume fractions. Objects are added until the volume fraction is reached. Mutually exclusive with num_objects.

  • diameter_range – Range of object diameters in mm.

  • allow_overlap – If False, objects are only added if they contribute new voxels.

  • device – PyTorch device for tensor allocation and RNG.

  • seed – Integer seed for reproducible output; None for random.

Raises:

ValueError – If neither or both of num_objects and vf_range are given.

Notes

num_objects and vf_range are mutually exclusive. If num_objects is set, objects are added iteratively until the specified number is reached. If vf_range is set, a target volume fraction is randomly sampled from the specified range and objects are added iteratively until the target fraction of occupied voxels is reached.

property attrs: dict[str, Any]

Metadata for ZARR/NIfTI storage.

forward() → Tensor

Generate a labeled 3D volume with random objects.

class synthbold.base.RandomGeneratorMixin(seed: int | None, device: str | device = 'cpu', **kwargs: Any)

Bases: object

Mixin that provides a paired PyTorch and NumPy RNG, both seedable for reproducibility, for device-aware random sampling.

Parameters:

  • seed – Integer seed for deterministic output. Pass None for non-deterministic behaviour.

  • device – PyTorch device on which generator is created.

class synthbold.base.Transform(device: str | device, seed: int | None = None)

Bases: ABC, RandomGeneratorMixin

Base class for single transformations on PyTorch tensors.

This abstract class provides the foundation for all data transformations. Subclasses are required to implement sample, apply, and from_config. The base implementation automatically handles moving input data to the target device and sequencing the sampling and application steps.

Parameters:

  • device – PyTorch device for tensor allocation and RNG.

  • seed – Integer seed for reproducible output; None for random.

abstractmethod static apply(x: Tensor, transform: Tensor) → Tensor

Apply pre-sampled transform parameters to the input tensor.

forward(data: Tensor) → Tensor

Generates transformation and applies to input tensor.

Note

Call the instance (transform(data)) instead of transform.forward(data). In this implementation, __call__ transfers inputs to self.device before invoking forward.

abstractmethod classmethod from_config(config: Config) → Self

Constructs a Transform instance from a configuration object.

abstractmethod sample(shape: tuple[int, ...]) → Tensor

Sample transform parameters for a tensor of the given shape.