FastSurferCNN.data_loader.data_utils

FastSurferCNN.data_loader.data_utils.bbox_3d(img)

Extract the three-dimensional bounding box coordinates.

Parameters:

imgnpt.NDArray

Mri image.

Returns:

np.ndarray

Rmin.

np.ndarray

Rmax.

np.ndarray

Cmin.

np.ndarray

Cmax.

np.ndarray

Zmin.

np.ndarray

Zmax.

FastSurferCNN.data_loader.data_utils.clean_cortex_labels(aparc)

Clean up aparc segmentations.

Map undetermined and optic chiasma to BKG Map Hypointensity classes to one Vessel to WM 5th Ventricle to CSF Remaining cortical labels to BKG.

Parameters:

aparcnpt.NDArray

Aparc segmentations.

Returns:

np.ndarray

Cleaned aparc.

FastSurferCNN.data_loader.data_utils.cortex_border_mask(label, structure, ctx_thresh=33)

Erode the cortex of a given mri image to create the inner gray matter mask (outer most cortex voxels).

Parameters:

labelnpt.NDArray

Ground truth labels.

structurenpt.NDArray

Structuring element to erode with.

ctx_threshint

Label value of cortex (above = cortical parcels). Defaults to 33.

Returns:

np.ndarray

Inner grey matter layer.

FastSurferCNN.data_loader.data_utils.create_weight_mask(mapped_aseg, max_weight=5, max_edge_weight=5, max_hires_weight=None, ctx_thresh=33, mean_filter=False, cortex_mask=True, gradient=True)

Create weighted mask - with median frequency balancing and edge-weighting.

Parameters:

mapped_asegnp.ndarray

Segmentation to create weight mask from.

max_weightint

Maximal weight on median weights (cap at this value). (Default value = 5).

max_edge_weightint

Maximal weight on gradient weight (cap at this value). (Default value = 5).

max_hires_weightint

Maximal weight on hires weight (cap at this value). (Default value = None).

ctx_threshint

Label value of cortex (above = cortical parcels). (Default value = 33).

mean_filterbool

Flag, set to add mean_filter mask (default = False).

cortex_maskbool

Flag, set to create cortex weight mask (default=True).

gradientbool

Flag, set to create gradient mask (default = True).

Returns:

np.ndarray

Weights.

FastSurferCNN.data_loader.data_utils.deep_sulci_and_wm_strand_mask(volume, structure, iteration=1, ctx_thresh=33)

Get a binary mask of deep sulci and small white matter strands by using binary closing (erosion and dilation).

Parameters:

volumenpt.NDArray

Loaded image (aseg, label space).

structurenpt.NDArray

Structuring element (e.g. np.ones((3, 3, 3))).

iterationint

Number of times mask should be dilated + eroded. Defaults to 1.

ctx_threshint

Label value of cortex (above = cortical parcels). Defaults to 33.

Returns:

np.ndarray

Sulcus + wm mask.

FastSurferCNN.data_loader.data_utils.fill_unknown_labels_per_hemi(gt, unknown_label, cortex_stop)

Replace label 1000 (lh unknown) and 2000 (rh unknown) with closest class for each voxel.

Parameters:

gtnpt.NDArray

Ground truth segmentation with class unknown.

unknown_labelint

Class label for unknown (lh: 1000, rh: 2000).

cortex_stopint

Class label at which cortical labels of this hemi stop (lh: 2000, rh: 3000).

Returns:

np.ndarray

Ground truth segmentation with all classes.

FastSurferCNN.data_loader.data_utils.filter_blank_slices_thick(img_vol, label_vol, weight_vol, threshold=50)

Filter blank slices from the volume using the label volume.

Parameters:

img_volnpt.NDArray

Orig image volume.

label_volnpt.NDArray

Label images (ground truth).

weight_volnpt.NDArray

Weight corresponding to labels.

thresholdint

Threshold for number of pixels needed to keep slice (below = dropped). (Default value = 50).

Returns:

filtered img_volnp.ndarray

Image volume with blank slices removed.

label_volnp.ndarray

Label volume with blank slices removed.

weight_volnp.ndarray

Weight volume with blank slices removed.

FastSurferCNN.data_loader.data_utils.fuse_cortex_labels(aparc)

Fuse cortical parcels on left/right hemisphere (reduce aparc classes).

Parameters:

aparcnpt.NDArray

Anatomical segmentation with cortical parcels.

Returns:

np.ndarray

Anatomical segmentation with reduced number of cortical parcels.

FastSurferCNN.data_loader.data_utils.get_labels_from_lut(lut, label_extract=('Left-', 'ctx-rh'))

Extract labels from the lookup tables.

Parameters:

lutUnion[str, pd.DataFrame]

FreeSurfer like LookUp Table (either path to it or already loaded as pandas DataFrame. Example entry: ID LabelName R G B A 0 Unknown 0 0 0 0 1 Left-Cerebral-Exterior 70 130 180 0.

label_extractTuple[str, str]

Suffix of label names to mask for sagittal labels Default: “Left-” and “ctx-rh”.

Returns:

np.ndarray

Full label list.

np.ndarray

Sagittal label list.

FastSurferCNN.data_loader.data_utils.get_largest_cc(segmentation)

Find the largest connected component of segmentation.

Parameters:

segmentationnpt.NDArray

Segmentation.

Returns:

np.ndarray

Largest connected component of segmentation (binary mask).

FastSurferCNN.data_loader.data_utils.get_thick_slices(img_data, slice_thickness=3)

Extract thick slices from the image.

Feed slice_thickness preceding and succeeding slices to network, label only middle one.

Parameters:

img_datanpt.NDArray

3D MRI image read in with nibabel.

slice_thicknessint

Number of slices to stack on top and below slice of interest (default=3).

Returns:

np.ndarray

Image data with the thick slices of the n-th axis appended into the n+1-th axis.

FastSurferCNN.data_loader.data_utils.infer_mapping_from_lut(num_classes_full, lut)

Guess the mapping from a lookup table.

Parameters:

num_classes_fullint

Number of classes.

lutUnion[str, pd.DataFrame]

Look-up table listing class labels.

Returns:

np.ndarray

List of indexes for.

FastSurferCNN.data_loader.data_utils.load_and_conform_image(img_filename, interpol=1, logger=<Logger FastSurferCNN.data_loader.data_utils (WARNING)>, conform_min=False)

Load MRI image and conform it to UCHAR, RAS orientation and 1mm or minimum isotropic voxels size.

Only, if it does not already have this format.

Parameters:

img_filenamePath, str

Path and name of volume to read.

interpolint, default=1

Interpolation order for image conformation (0=nearest, 1=linear(default), 2=quadratic, 3=cubic).

loggerlogging.Logger, default=<local logger>

Logger to write output to (default = STDOUT).

conform_minbool, default=False

Conform image to minimal voxel size (for high-res).

Returns:

nibabel.Header header_info

Header information of the conformed image.

numpy.ndarray affine_info

Affine information of the conformed image.

numpy.ndarray orig_data

Conformed image data.

Raises:

RuntimeError

Multiple input frames not supported.

RuntimeError

Inconsistency in nifti-header.

FastSurferCNN.data_loader.data_utils.load_image(file, name='image', **kwargs)

Load file ‘file’ with nibabel, including all data.

Parameters:

filePath, str

Path to the file to load.

namestr, default=”image”

Name of the file (optional), only effects error messages.

**kwargs

Additional keyword arguments.

Returns:

Tuple[nib.analyze.SpatialImage, np.ndarray]

The nibabel image object and a numpy array of the data.

Raises:

IOError

Failed loading the file nibabel releases the GIL, so the following is a parallel example. { >>> from concurrent.futures import ThreadPoolExecutor >>> with ThreadPoolExecutor() as pool: >>> future1 = pool.submit(load_image, filename1) >>> future2 = pool.submit(load_image, filename2) >>> image, data = future1.result() >>> image2, data2 = future2.result() }

FastSurferCNN.data_loader.data_utils.load_maybe_conform(file, alt_file, vox_size='min')

Load an image by file, check whether it is conformed to vox_size and conform to vox_size if it is not.

Parameters:

filePath, str

Path to the file to load.

alt_filePath, str

Alternative file to interpolate from.

vox_sizeVoxSizeOption, default=”min”

Voxel Size.

Returns:

Path

The path to the file.

nib.analyze.SpatialImage

The file container object including the corrected header.

np.ndarray

The data loaded from the file.

FastSurferCNN.data_loader.data_utils.map_aparc_aseg2label(aseg, labels, labels_sag, sagittal_lut_dict, aseg_nocc=None, processing='aparc')

Perform look-up table mapping of aparc.DKTatlas+aseg.mgz data to label space.

Parameters:

asegnpt.NDArray

Ground truth aparc+aseg.

labelsnpt.NDArray

Labels to use (extracted from LUT with get_labels_from_lut).

labels_sagnpt.NDArray

Sagittal labels to use (extracted from LUT with get_labels_from_lut).

sagittal_lut_dictMapping

Left-right label mapping (can be extracted with unify_lateralized_labels from LUT).

aseg_noccOptional[npt.NDArray]

Ground truth aseg without corpus callosum segmentation (Default value = None).

processingstr

Should be set to “aparc” or “aseg” for additional mappings (hard-coded) (Default value = “aparc”).

Returns:

np.ndarray

Mapped aseg for coronal and axial.

np.ndarray

Mapped aseg for sagittal.

FastSurferCNN.data_loader.data_utils.map_label2aparc_aseg(mapped_aseg, labels)

Perform look-up table mapping from sequential label space to LUT space.

Parameters:

mapped_asegtorch.Tensor

Label space segmentation (aparc.DKTatlas + aseg).

labelsUnion[torch.Tensor, npt.NDArray]

List of labels defining LUT space.

Returns:

torch.Tensor

Labels in LUT space.

FastSurferCNN.data_loader.data_utils.map_prediction_sagittal2full(prediction_sag, num_classes=51, lut=None)

Remap the prediction on the sagittal network to full label space used by coronal and axial networks.

Create full aparc.DKTatlas+aseg.mgz.

Parameters:

prediction_sagnpt.NDArray

Sagittal prediction (labels).

num_classesint

Number of SAGITTAL classes (96 for full classes, 51 for hemi split, 21 for aseg) (Default value = 51).

lutOptional[str]

Look-up table listing class labels (Default value = None).

Returns:

np.ndarray

Remapped prediction.

FastSurferCNN.data_loader.data_utils.read_classes_from_lut(lut_file)

Modify from datautils to allow support for FreeSurfer-distributed ColorLUTs.

Read in FreeSurfer-like LUT table.

Parameters:

lut_filePath, str

The path and name of FreeSurfer-style LUT file with classes of interest. Example entry: ID LabelName R G B A 0 Unknown 0 0 0 0 1 Left-Cerebral-Exterior 70 130 180 0 …

Returns:

pandas.DataFrame

DataFrame with ids present, name of ids, color for plotting.

FastSurferCNN.data_loader.data_utils.sagittal_coronal_remap_lookup(x)

Convert left labels to corresponding right labels for aseg with dictionary mapping.

Parameters:

xint

Label to look up.

Returns:

np.ndarray

Mapped label.

FastSurferCNN.data_loader.data_utils.save_image(header_info, affine_info, img_array, save_as, dtype=None)

Save an image (nibabel MGHImage), according to the desired output file format.

Supported formats are defined in supported_output_file_formats. Saves predictions to save_as.

Parameters:

header_info_Header

Image header information.

affine_infonpt.NDArray[float]

Image affine information.

img_arraynp.ndarray

An array containing image data.

save_asPath, str

Name under which to save prediction; this determines output file format.

dtypenpt.DTypeLike, optional

Image array type; if provided, the image object is explicitly set to match this type (Default value = None).

FastSurferCNN.data_loader.data_utils.split_cortex_labels(aparc)

Splot cortex labels to completely de-lateralize structures.

Parameters:

aparcnpt.NDArray

Anatomical segmentation and parcellation from network.

Returns:

np.ndarray

Re-lateralized aparc.

FastSurferCNN.data_loader.data_utils.transform_axial(vol, coronal2axial=True)

Transform volume into Axial axis and back.

Parameters:

volnpt.NDArray

Image volume to transform.

coronal2axialbool

Transform from coronal to axial = True (default).

Returns:

np.ndarray

Transformed image.

FastSurferCNN.data_loader.data_utils.transform_sagittal(vol, coronal2sagittal=True)

Transform volume into Sagittal axis and back.

Parameters:

volnpt.NDArray

Image volume to transform.

coronal2sagittalbool

Transform from coronal to sagittal = True (default).

Returns:

np.ndarray:

Transformed image.

FastSurferCNN.data_loader.data_utils.unify_lateralized_labels(lut, combi=('Left-', 'Right-'))

Generate lookup dictionary of left-right labels.

Parameters:

lutUnion[str, pd.DataFrame]

Either lut-file string to load or pandas dataframe Example entry: ID LabelName R G B A 0 Unknown 0 0 0 0 1 Left-Cerebral-Exterior 70 130 180 0.

combiTuple[str, str]

Prefix or labelnames to combine. Default: Left- and Right-.

Returns:

Mapping

Dictionary mapping between left and right hemispheres.