spectralbrain.io.preprocess#

Container-based DL preprocessing for raw anatomical images.

This module provides high-level functions that orchestrate Singularity/Apptainer containers for skull-stripping, tissue segmentation, and structure extraction. No DL dependencies are installed on the host — each tool runs inside its own immutable .sif container, downloaded once on first use.

All functions delegate to spectralbrain.runtime.ContainerManager.

Note

This module requires Singularity or Apptainer to be installed on the system. If neither is available, a clear error message is raised with installation instructions.

Examples

>>> from spectralbrain.io.preprocess import skull_strip, segment
>>> brain_path = skull_strip("sub-01_T1w.nii.gz")
>>> seg_path = segment(brain_path)

Functions

`clean`([tool])	Remove cached container(s).
`raw_to_pointcloud`(input_path, label_id, *[, ...])	End-to-end: raw T1w → skull-strip → segment → point cloud.
`run_fastsurfer`(input_path[, output_dir, gpu])	Run FastSurfer segmentation (seg_only mode).
`segment`(input_path[, output_path, gpu])	Segment a T1w (or T2w/FLAIR) image using SynthSeg.
`skull_strip`(input_path[, output_path, gpu])	Skull-strip a T1w image using HD-BET.
`status`()	Print the status of all preprocessing containers.

spectralbrain.io.preprocess.clean(tool=None)[source]#

Remove cached container(s).

Parameters:: tool (str or None) – Specific tool (e.g. "hdbet"), or None for all.
Return type:: None

spectralbrain.io.preprocess.raw_to_pointcloud(input_path, label_id, *, output_dir=None, gpu=None, jitter=True, jitter_scale=0.25, seed=None)[source]#

End-to-end: raw T1w → skull-strip → segment → point cloud.

Chains skull_strip(), segment(), and spectralbrain.io.labels_to_pointcloud() into a single call.

Parameters:

input_path (PathLike) – Raw T1w NIfTI.
label_id (int) – Target structure label (e.g. 17 for left hippocampus).
output_dir (PathLike, optional) – Working directory for intermediate files.
gpu (bool or None) – GPU passthrough.
jitter (bool) – Add sub-voxel jitter to the point cloud.
jitter_scale (float) – Jitter magnitude in voxel units.
seed (int, optional) – RNG seed.

Returns:

points (ndarray, shape (N, 3)) – World-space point cloud for the target structure.

Return type:

ndarray

Examples

>>> hippo = raw_to_pointcloud("sub-01_T1w.nii.gz", label_id=17)
>>> hippo.shape
(4231, 3)

spectralbrain.io.preprocess.run_fastsurfer(input_path, output_dir=None, *, gpu=None)[source]#

Run FastSurfer segmentation (seg_only mode).

Produces a FreeSurfer-compatible segmentation and cortical parcellation in a $SUBJECTS_DIR-like directory structure.

Parameters:

input_path (PathLike) – T1-weighted NIfTI.
output_dir (PathLike, optional) – FastSurfer output directory. Defaults to <input_dir>/fastsurfer/.
gpu (bool or None) – Force GPU on/off.

Returns:

Path – Path to the output directory.

Return type:

Path

spectralbrain.io.preprocess.segment(input_path, output_path=None, *, gpu=None)[source]#

Segment a T1w (or T2w/FLAIR) image using SynthSeg.

Produces a volumetric label map compatible with FreeSurfer’s aseg conventions. Works on any MRI contrast — SynthSeg is contrast-agnostic.

Parameters:

input_path (PathLike) – Anatomical NIfTI (skull-stripped or not — SynthSeg handles both).
output_path (PathLike, optional) – Output segmentation NIfTI. Defaults to <input_stem>_synthseg.nii.gz.
gpu (bool or None) – Force GPU on/off.

Returns:

Path – Path to the segmentation volume.

Return type:

Path

Examples

>>> seg = segment("sub-01_T1w_brain.nii.gz")
>>> data, affine = sb.io.load_nifti(seg)
>>> np.unique(data)  # FreeSurfer aseg labels

spectralbrain.io.preprocess.skull_strip(input_path, output_path=None, *, gpu=None)[source]#

Skull-strip a T1w image using HD-BET.

Parameters:

input_path (PathLike) – Raw T1-weighted NIfTI file.
output_path (PathLike, optional) – Output brain-extracted NIfTI. Defaults to <input_stem>_brain.nii.gz in the same directory.
gpu (bool or None) – Force GPU on/off. None = auto-detect.

Returns:

Path – Path to the brain-extracted image.

Raises:

EnvironmentError – If no container runtime is available.
RuntimeError – If the container exits with an error.

Return type:

Path

Examples

>>> brain = skull_strip("sub-01_T1w.nii.gz")
>>> brain
PosixPath('sub-01_T1w_brain.nii.gz')

spectralbrain.io.preprocess.status()[source]#

Print the status of all preprocessing containers.

Return type:: None