brain_deer.infrastructure.io.nifti

NIfTI loading and reorientation (parity with BrainDeer 1.0 data.loader).

Orientation logic lives in brain_deer.infrastructure.orientation, the single source of truth for the RAS world frame. This module keeps the file-facing loader API and delegates all reorientation to that module so there is exactly one canonicaliser in the codebase.

Functions

load_nifti(→ nibabel.Nifti1Image)	Load a NIfTI file (.nii/.nii.gz) and reorient to RAS.
reorient_to_ras(→ nibabel.Nifti1Image)	Reorient an in-memory NIfTI image to RAS.
reference_grid_for_resample(...)	Return (target_grid, stride) for resample_from_to.
resample_to_reference(→ nibabel.Nifti1Image)	Resample moving to reference grid, NN for labels, linear otherwise.
resample_to_reference_with_stride(...)	Like resample_to_reference(), also returning the proxy stride (1 = full).

Module Contents

brain_deer.infrastructure.io.nifti.load_nifti(path: str, *, use_mmap: bool = True) → nibabel.Nifti1Image

Load a NIfTI file (.nii/.nii.gz) and reorient to RAS.

mmap=True (default) asks nibabel to memory-map the array where supported, which speeds up opening many atlases and keeps RSS lower until slices are read.

Large 4-D series: after canonicalization, we avoid a redundant second full-array reorientation when the affine is already RAS (see _to_ras), which greatly reduces load time and peak memory versus always calling as_reoriented.

brain_deer.infrastructure.io.nifti.reorient_to_ras(img: nibabel.Nifti1Image) → nibabel.Nifti1Image

Reorient an in-memory NIfTI image to RAS.

brain_deer.infrastructure.io.nifti.reference_grid_for_resample(reference_img: nibabel.Nifti1Image, *, max_voxels: int = MAX_RESAMPLE_OUTPUT_VOXELS) → tuple[nibabel.Nifti1Image, int]

Return (target_grid, stride) for resample_from_to.

Mega references (e.g. 7T 100µm) are replaced by a strided proxy grid so overlays stay aligned in world space without allocating tens of GB.

brain_deer.infrastructure.io.nifti.resample_to_reference(moving_img: nibabel.Nifti1Image, reference_img: nibabel.Nifti1Image, is_label: bool = False, *, max_voxels: int = MAX_RESAMPLE_OUTPUT_VOXELS) → nibabel.Nifti1Image

Resample moving to reference grid, NN for labels, linear otherwise.

If the reference grid exceeds max_voxels, resamples onto a strided proxy of that grid (same world alignment) instead of materialising a multi-billion-voxel array.

brain_deer.infrastructure.io.nifti.resample_to_reference_with_stride(moving_img: nibabel.Nifti1Image, reference_img: nibabel.Nifti1Image, is_label: bool = False, *, max_voxels: int = MAX_RESAMPLE_OUTPUT_VOXELS) → tuple[nibabel.Nifti1Image, int]

Like resample_to_reference(), also returning the proxy stride (1 = full).