FastSurferCNN.data_loader.data_utils¶

FastSurferCNN.data_loader.data_utils.as_mgh_image(data, affine, header, dtype=None)[source]¶

Build an MGHImage from data, affine and header, and set the two fields the conversion drops.

MGHHeader.from_header carries neither the field of view nor the data type over from a non-MGH header, so both are set here and the file does not depend on the container its header came from. The fov is the largest of the three extents, as FreeSurfer keeps it, taken from data so that it is right even where the header is inherited from a volume of a different shape.

Parameters:

datanp.ndarray: An array containing image data.
affineAffineMatrix4x4: Image affine information.
header_Header: Image header information; a non-MGH header is converted. Required, because every image we write is derived from one we read, and the header is the only carrier of the acquisition parameters and of the type to store.
dtypenpt.DTypeLike, optional: The type to store, overriding the one the header carries. Neither may lose data nor be one MGH cannot store, see choose_dtype.

Returns:

nib.MGHImage: The image, with fov and the data type set.

FastSurferCNN.data_loader.data_utils.bbox_3d(img)[source]¶

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.choose_dtype(array, header, dtype=None)[source]¶

The type to store array as: dtype if the caller gave one, else the header’s.

That type is used or nothing is. It may not lose data: narrowing that would round or clip is the caller’s to do, deliberately and outside, because only the caller knows whether to cast, to rescale or to refuse.

Whether the type can be stored at all is the output format’s answer, not this function’s, so it is asked when the type is applied. The byte order is dropped here for the same reason: an MGH file is always big-endian, whatever type it stores.

Parameters:

arraynp.ndarray: The data to store.
header_Header: The header, whose type is used when dtype is None.
dtypenpt.DTypeLike, optional: The type to store, overriding the header’s.

Returns:

np.dtype: The type to write, in native byte order.

Raises:

ValueError: If storing array as that type would round or clip a value.

FastSurferCNN.data_loader.data_utils.clean_cortex_labels(aparc)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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.fits_dtype(array, dtype)[source]¶

Whether every value of array survives being stored as dtype.

An integer loses its identity as surely by being rounded into a float as by being clipped, so a float target holds integers only as far as it counts exactly: 2**24 for float32, 2**53 for float64. Narrowing a value that was already floating-point counts as fitting, since a measurement losing digits is not a label becoming a different label.

Parameters:

arraynp.ndarray: The data to store.
dtypenpt.DTypeLike: The type to store it as.

Returns:

bool: False if storing array as dtype would round or clip a value.

FastSurferCNN.data_loader.data_utils.fuse_cortex_labels(aparc)[source]¶

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'))[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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, order=1, logger=<Logger FastSurferCNN.data_loader.data_utils (INFO)>, **conform_kwargs)[source]¶

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.
orderint, 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_kwargs: Additional parameters to conform and is_conform.

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: If input has multiple input frames or inconsistent nifti headers.

FastSurferCNN.data_loader.data_utils.load_image(file, name='image', **kwargs)[source]¶

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:

the_imagenibabelImage: The SpatialImage object from nibabel of the conformed image (including updated affine).
the_datanp.ndarray: The data of the conformed image.

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, **conform_kwargs)[source]¶

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.
**conform_kwargs: Additional parameters to conform and is_conform.

Returns:

Path: The path to the file.
nibabelImage: The file container object including the corrected header.
np.ndarray: The data loaded from the file.