tomojax.datasets

DetectorModelCopy Anchor Link

class DetectorModel(
    *,
    signal: ArrayLike,
    dark: ArrayLike,
    photon_gain: float,
    read_noise: float,
)

Independent-pixel Poisson/read-noise detector in recorded count units.

Static sensitivity is shared by sample and flat measurements and cancels under exact calibration. Finite reference noise persists across all views. Spatially correlated noise and time-dependent illumination are not modelled.

Parameters

• signal, dark (array_like): Expected flat signal above dark, and dark offset, in counts; both have shape (row, column). signal must be positive.
• photon_gain (float): Recorded counts per detected photon, nonnegative. Zero disables shot noise, useful for testing deterministic response changes.
• read_noise (float): Per-frame dark/read-noise standard deviation in counts, nonnegative.

DetectorModel.from_flatsCopy Anchor Link

@classmethod
from_flats(
    flats: ArrayLike,
    darks: ArrayLike,
    *,
    read_noise: float | None = None,
) -> DetectorModel

Estimate a count model from repeated flat and dark images.

Adjacent-frame differences remove static sensitivity. Flat images are normalized to their common mean flux before estimating temporal noise. The normalized variance includes the rescaled shot/read noise and the shared dark-reference error, which does not cancel at unequal fluxes. This single-exposure estimate assumes independent pixels and frames.

Parameters

• flats, darks (array_like): Repeated images in counts, shape (frame, row, column). At least two flats are required, and two darks unless read_noise is supplied.
• read_noise (float, optional): Known per-frame read-noise standard deviation in counts. Supplying zero explicitly assumes negligible dark noise, not measured zero.

Returns

• DetectorModel: Mean response maps and scalar effective photon gain/read noise.

Raises

• ValueError: Too few reference images to estimate the requested noise terms.

DetectorModel.simulateCopy Anchor Link

simulate(
    line_integrals: ArrayLike,
    *,
    flat_frames: int,
    dark_frames: int,
    seed: int,
    gain_change: ArrayLike = 1.0,
    offset_change: ArrayLike = 0.0,
) -> DetectorSimulation

Simulate counts and apply finite flat/dark calibration references.

Parameters

• line_integrals (array_like): Noise-free line integrals, shape (view, row, column). Projection discretisation is the caller's choice, independent of this model.
• flat_frames, dark_frames (int): Positive numbers of frames averaged into the two reference maps.
• seed (int): Reproducible seed for independent sample, flat and dark draws.
• gain_change (array_like, optional): Positive sample/calibration photon-rate ratio (optical throughput or quantum efficiency), broadcastable to (view, row, column). One means unchanged response. Counts per detected photon stays fixed; this is not a change in electronic conversion gain.
• offset_change (array_like, optional): Sample minus calibration dark offset in counts, broadcastable to (view, row, column). Zero means unchanged offset.

Returns

• DetectorSimulation: Counts, calibration references, corrected data, and conditional truth. Nonpositive corrected transmission produces NaN or infinity; it is not clipped into apparently valid line integrals.

Raises

• ValueError: Reference frame counts are not positive.

DetectorSimulationCopy Anchor Link

class DetectorSimulation(
    *,
    projections: NDArray[np.float64],
    expected: NDArray[np.float64],
    ideal: NDArray[np.float64],
    counts: NDArray[np.float64],
    flat: NDArray[np.float64],
    dark: NDArray[np.float64],
    seed: int,
    model: DetectorModel,
)

Detector measurements with their calibration references and conditional truth.

Parameters

• projections, expected, ideal (numpy.ndarray): Corrected line integrals, shape (view, row, column). expected applies the sampled flat/dark references to noiseless sample counts; it is not the expectation of a logarithm of noisy counts. ideal uses noiseless references but includes the imposed gain and offset changes.
• counts (numpy.ndarray): Noisy sample counts, shape (view, row, column).
• flat, dark (numpy.ndarray): Sampled calibration means in counts, shape (row, column).
• seed (int): Random seed used for all measurements.
• model (DetectorModel): Count model used to generate the measurements.

SimConfigCopy Anchor Link

class SimConfig(
    *,
    nx: int,
    ny: int,
    nz: int,
    nu: int,
    nv: int,
    n_views: int,
    du: float = 1.0,
    dv: float = 1.0,
    vx: float = 1.0,
    vy: float = 1.0,
    vz: float = 1.0,
    rotation_deg: float | None = None,
    geometry: str = 'parallel',
    tilt_deg: float = 30.0,
    tilt_about: str = 'x',
    source_to_axis: float | None = None,
    source_to_detector: float | None = None,
    phantom: str = 'shepp',
    single_size: float = 0.5,
    single_value: float = 1.0,
    single_rotate: bool = True,
    n_cubes: int = 8,
    n_spheres: int = 7,
    min_size: int = 4,
    max_size: int = 32,
    min_value: float = 0.1,
    max_value: float = 1.0,
    max_rot_deg: float = 180.0,
    artefacts: SimulationArtefacts | None = None,
    seed: int = 0,
    lamino_thickness_ratio: float = 0.2,
)

Configuration for deterministic synthetic dataset generation.

SimulatedDataCopy Anchor Link

class SimulatedData()

Generated projections, geometry metadata, and ground-truth volume.

SimulationArtefactsCopy Anchor Link

class SimulationArtefacts(
    poisson_scale: float = 0.0,
    gaussian_sigma: float = 0.0,
    dead_pixel_fraction: float = 0.0,
    dead_pixel_value: float = 0.0,
    hot_pixel_fraction: float = 0.0,
    hot_pixel_value: float = 1.0,
    zinger_fraction: float = 0.0,
    zinger_value: float = 1.0,
    stripe_fraction: float = 0.0,
    stripe_gain_sigma: float = 0.0,
    dropped_view_fraction: float = 0.0,
    dropped_view_fill: float = 0.0,
    detector_blur_sigma: float = 0.0,
    intensity_drift_amplitude: float = 0.0,
    intensity_drift_mode: IntensityDriftMode = 'none',
)

Configurable projection-domain artefacts for synthetic tomography data.

SimulationArtefacts.to_dictCopy Anchor Link

to_dict() -> JsonObject

Return a JSON-compatible artefact configuration.

SimulationArtefacts.has_enabledCopy Anchor Link

has_enabled() -> bool

Return whether any artefact field will alter projections.

blobsCopy Anchor Link

blobs(
    nx: int,
    ny: int,
    nz: int,
    *,
    n_blobs: int = 5,
    seed: int | None = 0,
) -> np.ndarray

Random Gaussian blobs normalized to [0, 1]. Deterministic with seed.

Returns float32 array (nx, ny, nz).

cubeCopy Anchor Link

cube(
    nx: int,
    ny: int,
    nz: int,
    *,
    size: float = 0.5,
    value: float = 1.0,
    seed: int | None = None,
) -> np.ndarray

Axis-aligned cube in a zero background with side length = size * min(nx,ny,nz).

Centered in the volume. Returns float32 array of shape (nx, ny, nz).

lamino_diskCopy Anchor Link

lamino_disk(
    nx: int,
    ny: int,
    nz: int,
    *,
    thickness_ratio: float = 0.2,
    seed: int = 0,
    n_cubes: int = 8,
    n_spheres: int = 7,
    min_size: int = 4,
    max_size: int = 32,
    min_value: float = 0.1,
    max_value: float = 1.0,
    max_rot_degrees: float = 180.0,
) -> np.ndarray

Random cubes+spheres phantom constrained to a thin central slab.

Sample-frame convention: the reconstructed/object volume is in (x, y, z) coordinates, and the nominal rotation axis is the +z axis. The thin slab is therefore orthogonal to +z, i.e., confined to the central few z-slices.

make_phantomCopy Anchor Link

make_phantom(cfg: SimConfig) -> jnp.ndarray

Construct the configured phantom volume.

random_cubes_spheresCopy Anchor Link

random_cubes_spheres(
    nx: int,
    ny: int,
    nz: int,
    *,
    n_cubes: int = 8,
    n_spheres: int = 7,
    min_size: int = 4,
    max_size: int = 32,
    min_value: float = 0.1,
    max_value: float = 1.0,
    max_rot_degrees: float = 180.0,
    use_inscribed_fov: bool = True,
    radial_exponent: float = 0.75,
    seed: int = 0,
) -> np.ndarray

Random rotated cubes + spheres phantom (deterministic).

Ensures objects fit within FOV if use_inscribed_fov=True.

rotated_centered_cubeCopy Anchor Link

rotated_centered_cube(
    nx: int,
    ny: int,
    nz: int,
    *,
    size: float = 0.5,
    value: float = 1.0,
    angles: tuple[float, float, float] | None = None,
    seed: int | None = 0,
    edge_softness: float = 1.0,
) -> np.ndarray

Centered cube with random 3D rotation.

• size is side length as a fraction of min(nx, ny, nz) (matches cube).
• If angles is None, sample rx, ry, rz uniformly in [-pi, pi] using seed.

shepp_logan_3dCopy Anchor Link

shepp_logan_3d(nx: int, ny: int, nz: int) -> np.ndarray

Simplified 3D Shepp-Logan-like phantom using stacked ellipsoids.

Not a strict reference, but adequate for testing filters and reconstruction.

simulateCopy Anchor Link

simulate(cfg: SimConfig) -> SimulatedData

Generate projections and metadata from a simulation config.

simulate_to_fileCopy Anchor Link

simulate_to_file(cfg: SimConfig, out_path: str) -> str

Generate a synthetic dataset and save it as NXtomo.

sphereCopy Anchor Link

sphere(
    nx: int,
    ny: int,
    nz: int,
    *,
    size: float = 0.5,
    value: float = 1.0,
) -> np.ndarray

Centered solid sphere in a zero background.

The sphere diameter is size * min(nx, ny, nz) so that size matches the semantics of cube (whose side length uses the same scale). The sphere is centered in the volume and clamped to fit. Returns float32 array of shape (nx, ny, nz).