FastSurferCNN.data_loader.conform

class FastSurferCNN.data_loader.conform.Criteria(value)[source]

An enumeration.

FastSurferCNN.data_loader.conform.check_affine_in_nifti(img, logger=None)[source]

Check the affine in nifti Image.

Sets affine with qform, if it exists and differs from sform. If qform does not exist, voxel sizes between header information and information in affine are compared. In case these do not match, the function returns False (otherwise True).

Parameters:
imgUnion[nib.Nifti1Image, nib.Nifti2Image]

Loaded nifti-image.

loggerOptional[logging.Logger]

Logger object or None (default) to log or print an info message to stdout (for None).

Returns:
bool

False, if voxel sizes in affine and header differ.

FastSurferCNN.data_loader.conform.conform(img, order=1, conform_vox_size=1.0, dtype=None, conform_to_1mm_threshold=None, criteria=frozenset({Criteria.FORCE_IMG_SIZE, Criteria.FORCE_ISO_VOX, Criteria.FORCE_LIA, Criteria.FORCE_LIA_STRICT}))[source]

Python version of mri_convert -c.

mri_convert -c by default turns image intensity values into UCHAR, reslices images to standard position, fills up slices to standard 256x256x256 format and enforces 1mm or minimum isotropic voxel sizes.

Parameters:
imgnib.analyze.SpatialImage

Loaded source image.

orderint

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

conform_vox_sizeVoxSizeOption

Conform image the image to voxel size 1. (default), a specific smaller voxel size (0-1, for high-res), or automatically determine the ‘minimum voxel size’ from the image (value ‘min’). This assumes the smallest of the three voxel sizes.

dtypeOptional[Type]

The dtype to enforce in the image (default: UCHAR, as mri_convert -c).

conform_to_1mm_thresholdOptional[float]

The threshold above which the image is conformed to 1mm (default: ignore).

criteriaset[Criteria], default in DEFAULT_CRITERIA

Whether to force the conforming to include a LIA data layout, an image size requirement and/or a voxel size requirement.

Returns:
nib.MGHImage

Conformed image.

Notes

Unlike mri_convert -c, we first interpolate (float image), and then rescale to uchar. mri_convert is doing it the other way around. However, we compute the scale factor from the input to increase similarity.

FastSurferCNN.data_loader.conform.find_img_size_by_fov(img, vox_size, min_dim=256)[source]

Find the cube dimension (>= 256) to cover the field of view of img.

If vox_size is one, the img_size MUST always be min_dim (the FreeSurfer standard).

Parameters:
imgnib.analyze.SpatialImage

Loaded source image.

vox_sizefloat

The target voxel size in mm.

min_dimint

Minimal image dimension in voxels (default 256).

Returns:
int

The number of voxels needed to cover field of view.

Notes

This function only needs the header (not the data).

FastSurferCNN.data_loader.conform.find_min_size(img, max_size=1)[source]

Find minimal voxel size <= 1mm.

Parameters:
imgnib.analyze.SpatialImage

Loaded source image.

max_sizefloat

Maximal voxel size in mm (default: 1.0).

Returns:
float

Rounded minimal voxel size.

Notes

This function only needs the header (not the data).

FastSurferCNN.data_loader.conform.get_conformed_vox_img_size(img, conform_vox_size, conform_to_1mm_threshold=None)[source]

Extract the voxel size and the image size.

This function only needs the header (not the data).

Parameters:
imgnib.analyze.SpatialImage

Loaded source image.

conform_vox_sizefloat, “min”

The voxel size parameter to use: either a voxel size as float, or the string “min” to automatically find a suitable voxel size (smallest per-dimension voxel size).

conform_to_1mm_thresholdfloat, optional

The threshold for which image voxel size should be conformed to 1mm instead of conformed to the smallest voxel size (default: None, never apply).

Returns:
conformed_vox_sizefloat

The determined voxel size to conform the image to.

conformed_img_sizeint

The size of the image adjusted to the conformed voxel size.

FastSurferCNN.data_loader.conform.getscale(data, dst_min, dst_max, f_low=0.0, f_high=0.999)[source]

Get offset and scale of image intensities to robustly rescale to dst_min..dst_max.

Equivalent to how mri_convert conforms images.

Parameters:
datanp.ndarray

Image data (intensity values).

dst_minfloat

Future minimal intensity value.

dst_maxfloat

Future maximal intensity value.

f_lowfloat, default=0.0

Robust cropping at low end (0.0=no cropping).

f_highfloat, default=0.999

Robust cropping at higher end (0.999=crop one thousandth of highest intensity).

Returns:
float src_min

(adjusted) offset.

float

Scale factor.

FastSurferCNN.data_loader.conform.is_conform(img, conform_vox_size=1.0, eps=1e-06, check_dtype=True, dtype=None, verbose=True, conform_to_1mm_threshold=None, criteria=frozenset({Criteria.FORCE_IMG_SIZE, Criteria.FORCE_ISO_VOX, Criteria.FORCE_LIA, Criteria.FORCE_LIA_STRICT}))[source]

Check if an image is already conformed or not.

Dimensions: 256x256x256, Voxel size: 1x1x1, LIA orientation, and data type UCHAR.

Parameters:
imgnib.analyze.SpatialImage

Loaded source image.

conform_vox_sizeVoxSizeOption, default=1.0

Which voxel size to conform to. Can either be a float between 0.0 and 1.0 or ‘min’ check, whether the image is conformed to the minimal voxels size, i.e. conforming to smaller, but isotropic voxel sizes for high-res.

epsfloat, default=1e-06

Allowed deviation from zero for LIA orientation check. Small inaccuracies can occur through the inversion operation. Already conformed images are thus sometimes not correctly recognized. The epsilon accounts for these small shifts.

check_dtypebool, default=True

Specifies whether the UCHAR dtype condition is checked for; this is not done when the input is a segmentation.

dtypeType, optional

Specifies the intended target dtype (default or None: uint8 = UCHAR).

verbosebool, default=True

If True, details of which conformance conditions are violated (if any) are displayed.

conform_to_1mm_thresholdfloat, optional

Above this threshold the image is conformed to 1mm (default or None: ignore).

criteriaset[Criteria], default in DEFAULT_CRITERIA

An enum/set of criteria to check.

Returns:
bool:

Whether the image is already conformed.

Notes

This function only needs the header (not the data).

FastSurferCNN.data_loader.conform.is_lia(affine, strict=True, eps=1e-06)[source]

Checks whether the affine is LIA-oriented.

Parameters:
affinenp.ndarray

The affine to check.

strictbool, default=True

Whether the orientation should be “exactly” LIA or just similar to LIA (i.e. it is more LIA than other directions).

epsfloat, default=1e-6

The threshold in strict mode.

Returns:
bool

Whether the affine is LIA-oriented.

FastSurferCNN.data_loader.conform.is_resampling_vox2vox(vox2vox, eps=1e-06)[source]

Check whether the affine is resampling or just reordering.

Parameters:
vox2voxnp.ndarray

The affine matrix.

epsfloat, default=1e-6

The epsilon for the affine check.

Returns:
bool

The result.

FastSurferCNN.data_loader.conform.map_image(img, out_affine, out_shape, ras2ras=None, order=1, dtype=None)[source]

Map image to new voxel space (RAS orientation).

Parameters:
imgnib.analyze.SpatialImage

The src 3D image with data and affine set.

out_affinenp.ndarray

Trg image affine.

out_shapetuple[int, …], np.ndarray

The trg shape information.

ras2rasnp.ndarray, optional

An additional mapping that should be applied (default=id to just reslice).

orderint, default=1

Order of interpolation (0=nearest,1=linear,2=quadratic,3=cubic).

dtypeType, optional

Target dtype of the resulting image (relevant for reorientation, default=keep dtype of img).

Returns:
np.ndarray

Mapped image data array.

FastSurferCNN.data_loader.conform.options_parse()[source]

Command line option parser.

Returns:
options

Object holding options.

FastSurferCNN.data_loader.conform.rescale(data, dst_min, dst_max, f_low=0.0, f_high=0.999)[source]

Rescale image intensity values (0-255).

Parameters:
datanp.ndarray

Image data (intensity values).

dst_minfloat

Future minimal intensity value.

dst_maxfloat

Future maximal intensity value.

f_lowfloat, default=0.0

Robust cropping at low end (0.0=no cropping).

f_highfloat, default=0.999

Robust cropping at higher end (0.999=crop one thousandth of highest intensity).

Returns:
np.ndarray

Scaled image data.

FastSurferCNN.data_loader.conform.scalecrop(data, dst_min, dst_max, src_min, scale)[source]

Crop the intensity ranges to specific min and max values.

Parameters:
datanp.ndarray

Image data (intensity values).

dst_minfloat

Future minimal intensity value.

dst_maxfloat

Future maximal intensity value.

src_minfloat

Minimal value to consider from source (crops below).

scalefloat

Scale value by which source will be shifted.

Returns:
np.ndarray

Scaled image data.