brain_deer.infrastructure.io.volume_proxy¶

Full-resolution caches for ultra-large NIfTI (esp. .nii.gz).

Random slice I/O from gzip is multi-second. Display must stay at native resolution, so we decompress once to an uncompressed .nii on disk and mmap it. Optional strided LOD helpers remain for stats / drag previews only — never as the primary displayed volume.

Functions¶

`suggest_proxy_stride`(→ int)	Integer stride so `prod(shape[::stride])` is near `target_voxels`.
`needs_fullres_cache`(→ bool)	True when we should decompress `.nii.gz` to an uncompressed mmap cache.
`needs_display_proxy`(→ bool)	Deprecated name — prefer `needs_fullres_cache()` for display path.
`proxy_affine`(→ numpy.ndarray)	Affine for a strided volume so world-mm of voxel i maps like full-res `i*stride`.
`ensure_uncompressed_nifti`(→ Tuple[str, bool])	Return `(path_to_load, from_cache)` at full resolution.
`load_or_build_proxy`(→ Tuple[nibabel.Nifti1Image, int, ...)	Optional strided LOD (stats / previews). Not used as primary display.
`maybe_load_fullres_into_ram`(→ nibabel.Nifti1Image)	If RAM allows, copy the volume into a contiguous ndarray (all slice orientations fast).
`prepare_array_for_3d`(→ tuple[numpy.ndarray, ...)	Stride-downsample a volume for VTK 3D. Returns `(data, affine, stride)`.

Module Contents¶

brain_deer.infrastructure.io.volume_proxy.suggest_proxy_stride(shape: Sequence[int], *, target_voxels: int = DEFAULT_PROXY_TARGET_VOXELS) → int¶: Integer stride so prod(shape[::stride]) is near target_voxels.

brain_deer.infrastructure.io.volume_proxy.needs_fullres_cache(shape: Sequence[int], path: str | None = None) → bool¶: True when we should decompress .nii.gz to an uncompressed mmap cache.

brain_deer.infrastructure.io.volume_proxy.needs_display_proxy(shape: Sequence[int], path: str | None = None) → bool¶: Deprecated name — prefer needs_fullres_cache() for display path.

brain_deer.infrastructure.io.volume_proxy.proxy_affine(affine: numpy.ndarray, stride: int) → numpy.ndarray¶: Affine for a strided volume so world-mm of voxel i maps like full-res i*stride.

brain_deer.infrastructure.io.volume_proxy.ensure_uncompressed_nifti(path: str, *, progress: Callable[[str], None] | None = None) → Tuple[str, bool]¶

Return (path_to_load, from_cache) at full resolution.

For large .nii.gz, streams a one-time decompress into ~/.cache/brain_deer/fullres/. Uncompressed .nii is returned as-is.

brain_deer.infrastructure.io.volume_proxy.load_or_build_proxy(img: nibabel.Nifti1Image, path: str, *, stride: int | None = None, target_voxels: int = DEFAULT_PROXY_TARGET_VOXELS, progress: Callable[[str], None] | None = None) → Tuple[nibabel.Nifti1Image, int, bool]¶: Optional strided LOD (stats / previews). Not used as primary display.

brain_deer.infrastructure.io.volume_proxy.maybe_load_fullres_into_ram(img: nibabel.Nifti1Image, *, progress: Callable[[str], None] | None = None, min_free_bytes_factor: float = 1.35) → nibabel.Nifti1Image¶

If RAM allows, copy the volume into a contiguous ndarray (all slice orientations fast).

Uncompressed mmap is fast for the contiguous axis but sagittal/coronal can still be multi-second on huge volumes. A one-time uint8 RAM load (~volume size) fixes that.

brain_deer.infrastructure.io.volume_proxy.prepare_array_for_3d(data: numpy.ndarray, affine: numpy.ndarray, *, max_voxels: int = MAX_3D_DISPLAY_VOXELS) → tuple[numpy.ndarray, numpy.ndarray, int]¶

Stride-downsample a volume for VTK 3D. Returns (data, affine, stride).

Keeps native dtype until the caller casts; never expands a mega volume to float32.