tomojax.io

Raw detector frames are read with tomojax.load_frames and corrected with tomojax.corrections. Expert helpers (acquisition readers, NXtomo containers, inspection, JSON) are in tomojax.io.api.

ProjectionDatasetCopy Anchor Link

class ProjectionDataset(
    projections: np.ndarray,
    angles: np.ndarray,
    volume: np.ndarray | jax.Array | None = None,
    detector: Detector | None = None,
    grid: Grid | None = None,
    geometry_type: str = 'parallel',
    geometry_metadata: dict[str, Any] = dict(),
    angle_offset_deg: np.ndarray | None = None,
    align_params: np.ndarray | None = None,
    align_gauge: dict[str, JsonValue] | None = None,
    misalign_spec: dict[str, JsonValue] | None = None,
    source_path: str | None = None,
    source_format: str | None = None,
    sample_name: str | None = None,
    _metadata: NXTomoMetadata | None = None,
)

Standard public in-memory projection dataset.

This is the current IO boundary. It contains measured projection data, normalized metadata needed by reconstruction/alignment code, and the optional reconstructed volume when a processed container stores one. angles holds each view's rotation angle, in degrees.

Parameters

• projections (numpy.ndarray): Measured projections in (view, v, u) order.
• angles (numpy.ndarray): One rotation angle per view, in degrees.
• volume (numpy.ndarray, jax.Array or None, optional): Reconstructed volume in (x, y, z) order, when present.
• detector (Detector or None, optional): Detector pixel counts, pitches and physical centre.
• grid (Grid or None, optional): Reconstruction voxel grid.
• geometry_type (str, optional): Geometry family, such as parallel, lamino or cone.
• geometry_metadata (dict, optional): Additional geometry and acquisition metadata.
• angle_offset_deg (numpy.ndarray or None, optional): Per-view angular corrections in degrees.
• align_params (numpy.ndarray or None, optional): Saved per-view alignment parameters, with convention in align_gauge.
• align_gauge (dict or None, optional): Gauge and frame metadata for saved alignment parameters.
• misalign_spec (dict or None, optional): Simulation misalignment record; angles already include simulated offsets.
• source_path (str or None, optional): Original input path.
• source_format (str or None, optional): Original container format.
• sample_name (str or None, optional): Sample name retained on output.
• _metadata (NXTomoMetadata or None, optional): Internal retained acquisition metadata; normally populated by from_nxtomo.

ProjectionDataset.from_nxtomoCopy Anchor Link

@classmethod
from_nxtomo(
    payload: LoadedNXTomo,
    *,
    source_path: PathLike | None = None,
) -> ProjectionDataset

Build a public dataset from the lower-level NXtomo payload.

Parameters

• payload (LoadedNXTomo): NXtomo projection payload and persistence metadata.
• source_path (str, pathlib.Path or None, optional): Input path retained as provenance.

Returns

• ProjectionDataset: Normalized in-memory dataset with arrays and typed grid/detector metadata.

Raises

• ValueError: If grid or detector metadata have invalid coordinate dimensions.

ProjectionDataset.to_nxtomo_metadataCopy Anchor Link

to_nxtomo_metadata() -> NXTomoMetadata

Return NXtomo metadata for saving this public dataset.

Returns

• NXTomoMetadata: Persistence metadata reflecting the dataset's current fields.

ProjectionDataset.copy_metadataCopy Anchor Link

copy_metadata() -> NXTomoMetadata

Return writable persistence metadata for save/update workflows.

Returns

• NXTomoMetadata: Writable metadata with copied arrays and retained acquisition information.

ProjectionDataset.geometry_inputsCopy Anchor Link

geometry_inputs() -> dict[str, Any]

Return normalized geometry metadata for reconstruction/alignment.

Returns

• dict: Normalized geometry, detector, angle and alignment metadata.

Raises

• ValueError: If detector metadata are missing.

ProjectionDataset.prepare_center_seedCopy Anchor Link

prepare_center_seed() -> ProjectionDataset

Prepare axial centre inference from recorded pitches, without reading pixels.

The pending seed is not calibrated; loading must estimate its centre before returning frames. Inspection can check the remaining required metadata.

Returns

• ProjectionDataset: Original record or a copy with an internal pending detector seed.

ValidationReportCopy Anchor Link

class ValidationReport()

Public dataset validation result.

Attributes

• issues (list of str): Validation problems; an empty list means none were found.

build_geometry_from_dataset_metadataCopy Anchor Link

build_geometry_from_dataset_metadata(
    meta: Mapping[str, Any],
    *,
    grid_override: Grid | tuple[int, int, int] | list[int] | None = None,
    poses: bool = False,
    volume_shape: Sequence[int] | None = None,
) -> tuple[Grid, Detector, ScanGeometry]

Build geometry objects from normalized dataset metadata.

poses applies the per-view corrections and angle offsets saved with the data. Keeping this wrapper in tomojax.io makes the command/data dependency explicit and gives the ProjectionDataset solver contract one replacement point.

Parameters

• meta (mapping): Normalized geometry metadata, as returned by geometry_inputs.
• grid_override (Grid, tuple of int, list of int or None, optional): Replacement grid or (nx, ny, nz) dimensions.
• poses (bool, optional): Apply saved per-view alignment and angle corrections; defaults to False.
• volume_shape (sequence of int or None, optional): Fallback (nx, ny, nz) dimensions when no grid is recorded.

Returns

• grid (Grid): Resolved reconstruction grid.
• detector (Detector): Resolved detector geometry.
• geometry (ScanGeometry): Per-view geometry, with saved corrections when requested.

Raises

• ValueError: If geometry metadata are incomplete or inconsistent.

load_datasetCopy Anchor Link

load_dataset(path: PathLike) -> ProjectionDataset

Load a standard TomoJAX projection dataset.

Supported direct inputs are NXtomo/HDF5 (.nx, .nxs, .h5, .hdf, .hdf5) and TomoJAX .npz payloads. TIFF stacks need explicit angle metadata, so use load_tiff_stack.

Parameters

• path (str or pathlib.Path): NXtomo/HDF5 or TomoJAX NPZ dataset to read.

Returns

• ProjectionDataset: Measured projections, normalized metadata and any saved volume.

Raises

• ValueError: If the format is unsupported or TIFF angles must be supplied separately.
• KeyError: If required datasets are missing.
• OSError: If the input cannot be opened.

load_tiff_stackCopy Anchor Link

load_tiff_stack(
    path: PathLike,
    *,
    angles: Sequence[float] | np.ndarray,
    detector: Detector | None = None,
    grid: Grid | None = None,
    geometry_type: str = 'parallel',
    geometry_metadata: Mapping[str, Any] | None = None,
) -> ProjectionDataset

Load grayscale TIFF pages with explicit view angles, in degrees.

Parameters

• path (str or pathlib.Path): Multipage TIFF or folder of naturally sorted TIFF files.
• angles (array-like): Finite one-dimensional view angles in degrees, one per grayscale page.
• detector (Detector or None, optional): Detector geometry to attach to the dataset.
• grid (Grid or None, optional): Reconstruction grid to attach to the dataset.
• geometry_type (str, optional): Geometry family; defaults to parallel.
• geometry_metadata (mapping or None, optional): Additional geometry metadata.

Returns

• ProjectionDataset: Float32 TIFF samples and supplied metadata; no intensity correction is applied.

Raises

• ValueError: If pages are not consistent grayscale frames or angles do not match them.
• FileNotFoundError: If the input contains no TIFF frames.

save_datasetCopy Anchor Link

save_dataset(path: PathLike, dataset: ProjectionDataset) -> None

Save a public projection dataset as NXtomo/HDF5 or NPZ.

Parameters

• path (str or pathlib.Path): NXtomo/HDF5 or NPZ output path; existing files are overwritten.
• dataset (ProjectionDataset): Projections, geometry and optional volume to persist.

Returns

• None: Write the dataset to disk without changing its metadata.

Raises

• ValueError: If the output suffix is not supported.
• OSError: If the output cannot be written.

validate_datasetCopy Anchor Link

validate_dataset(path: PathLike) -> ValidationReport

Validate a user dataset path using the public IO boundary.

Parameters

• path (str or pathlib.Path): Dataset path to inspect for structural validity and missing raw calibration.

Returns

• ValidationReport: Issues found in the file or format; an empty issues list means none were found.