forger package

Submodules

forger.forger module

A package for 3D image augmentation

class forger.forger.AdaptiveHistogramEqualization(alpha=1.0, beta=0.5, radius=2, p=1.0)[source]

Bases: forger.forger.Transformation

Histogram equalization modifies the contrast in an image.

This transformation uses the AdaptiveHistogramEqualizationImageFilter

from SimpleITK. AdaptiveHistogramEqualization can produce an adaptively equalized histogram or a version of unsharp mask (local mean subtraction). Instead of applying a strict histogram equalization in a window about a pixel, this filter prescribes a mapping function (power law) controlled by the parameters alpha and beta.

Parameters

  • alpha – This parameter controls the behaviour of the transformation. A value of alpha=0 makes the transformation act like classical histogram equalization and a value of alpha=1 makes the transformation act like a unsharp mask. The values between make a trade-off. The default is 0.5.

  • beta – This parameter controls the behaviour of the transformation. A value of beta=0 makes the transformations act like an unsharp mask and a value of beta=1 makes the transformation to act like a pass through filter (beta=1, with alpha=1). The default is 0.5.

  • radius – This value controls the size of the region over which the local statistics are calculated. The default value for radius is 2 in all directions.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.AdditiveGaussianNoise(mean: float = 0.01, std: float = 1.0, p: float = 1.0)[source]

Bases: forger.forger.Transformation

Apply additive Gaussian white noise to an image.

This transformation does not affect masks.

Parameters

  • mean – The mean value of the gaussian distribution used for noise generation. The default value is 0.0.

  • std – The standard deviation of the gaussian distribution used for noise generation. The default value is 1.0.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.Affine(angles: Tuple[float, float, float], translation: Optional[Tuple] = None, scales: Union[None, float, Tuple[float, float, float]] = None, interpolator=3, image_background=0, mask_background=0, image_type=2, mask_type=1, reference=None, spacing=None, direction=None, reshape=False)[source]

Bases: forger.forger.Transformation

The affine transformation applied to an image and its mask (if provided).

Parameters

  • angles – The rotation angles in degrees. This should be a tuple of length 3.

  • translation – The translation components. This should be a tuple of length 3. The default is None, representing no translation.

  • scales – A scale factor. The default is None, representing no scaling.

  • interpolator – The interpolator used by the transformation. The default is sitk.sitkBSpline.

  • image_background – The value used as the default for image voxels.

  • mask_background – The value used as the default for mask voxels.

  • reference – The reference grid used for resampling during the transformation. The default is None, meaning that the image (mask) itself is used for resampling.

  • spacing – The spacing used for the transformed image. Ignored if reference is not None.

  • direction – The direction used for the transformed image. Ignored if reference is not None.

  • reshape – Reshape the canvas for the transformed image to include the entire input image. The default value is False.

DIMENSION = 3
class forger.forger.BinaryDilate(background: int = 0, foreground: int = 1, radius: Tuple[int, int, int] = (1, 1, 1))[source]

Bases: forger.forger.Transformation

Dilate the mask.

class forger.forger.BinaryErode(background: int = 0, foreground: int = 1, radius: Tuple[int, int, int] = (1, 1, 1))[source]

Bases: forger.forger.Transformation

class forger.forger.BinaryFillHole(foreground_value=1, p: float = 1.0)[source]

Bases: forger.forger.Transformation

Fill holes that are not connected to the boundary of a binary image.

Parameters

  • foreground_value (float) – Set the value in the image to consider as foreground. Defaults to the maximum value of InputPixelType if this parameter is None.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.BinomialBlur(repetition=1, p=1.0)[source]

Bases: forger.forger.Transformation

Apply binomial blur filter to an image.

Parameters

  • repetition – The number of times to repeat the smoothing filter.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.Cast(out_image_dtype=None, out_mask_dtype=None)[source]

Bases: forger.forger.Transformation

Cast SimpleITK objects to new SimpleITK data types.

Parameters

  • out_image_dtype – The SimpleITK data type used as the type of the image. If None, the output data type is the same as the input data type.

  • out_mask_dtype – The SimpleITK data type used as the type of the mask. If None, the output data type is the same as the input data type.

class forger.forger.CenterCrop(size: Union[int, Tuple[int, int, int]], p: float = 1.0)[source]

Bases: forger.forger.Transformation

Crop an image and its mask (if provided) from the center.

Parameters

  • size – An integer or a tuple of 3 integer numbers to be used as the size of the crop across each dimension of an image. If an integer value is provided, it is considered as a tuple of 3 elements, all equal to the input image. Note: The dimension is in (x, y, z) order, which is (width, height, depth).

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.Clip(lower_bound, upper_bound, p: float = 1.0)[source]

Bases: forger.forger.Transformation

Clip voxel values to a specified range.

This transformation does not affect the masks.

Parameters

  • lower_bound – Any voxel values less than lower_bound will be clipped to lower_bound

  • upper_bound – Any voxel values greater than upper_bound will be clipped to upper_bound

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.Compose(transforms: Iterable)[source]

Bases: forger.forger.Transformation

Compose multiple transformations to a single transformation.

Parameters

transforms – A list of transformations.

class forger.forger.Crop(size: Tuple, index: Tuple = (0, 0, 0), p: float = 1.0)[source]

Bases: forger.forger.Transformation

Crop image based on given coordinates.

Parameters

  • size – A tuple representing the size of the region to be extracted. The coordinate is (x, y, z) order, i.e. (width, height, depth).

  • index – The starting index of the image to be extracted. The default value is [0, 0, 0]. The coordinate is (x, y, z) order, i.e. (width, height, depth).

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.Expand(expansion: tuple, interpolator=2, p: float = 1.0)[source]

Bases: forger.forger.Transformation

Enlarge an image by an integer factor in each dimension.

Given an image with size of (m, n, k), applying this transformation using an expansion factor of (a, b, c) results in an image of size (a * m, b * n, c * k). The transformed image (mask) is obtained by interpolating the input image (mask). The voxel will change after applying this transformation.

Parameters

  • expansion – A tuple of positive integer values representing the scale factors for each dimension.

  • interpolator – A SimpleITK interpolator function. The default interpolator for image is sitk.sitkLinear. Other options for interpolations are:

    • sitk.sitkBSpline

    • sitk.sitkGaussian

    • sitk.sitkNearestNeighbor

    • sitk.sitkHammingWindowedSinc

    • sitk.sitkBlackmanWindowedSinc

    • sitk.sitkCosineWindowedSinc

    • sitk.sitkWelchWindowedSinc

    • sitk.sitkLanczosWindowedSinc

    A mask is always interpolated using sitk.sitkNearestNeighbor to avoid introducing new labels.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.Factory(transformation: forger.forger.Transformation, parameters: dict, p: float = 1.0)[source]

Bases: object

Create a collection of transformations with different parameters.

Parameters

  • transformation – A forger transformation.

  • parameters – A dictionary containing the parameter values for the transformation. The keys of the dictionary should be the argument names for the transformation. The possible values for each argument should be in a list even if there is one option. The argument with default value could be skipped. In that case, the default value will be used for the transformation.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.Flip(axes: Tuple = (True, False, False), p=1.0)[source]

Bases: forger.forger.Transformation

Flips an image and it’s mask (if provided) across user specified axes.

Parameters

  • axes (tuple) – A list of boolean values for each dimension. Default value is [False, True, False] representing horizontal flip.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.ForegroundCrop(background: str = '<', bins=128)[source]

Bases: forger.forger.Transformation

A transformation for Cropping foreground of an image.

Parameters

  • background – The relationship of background and the Otsu threshold. For example, if background is ‘<’, after applying Otsu method, all image voxels less than the Otsu threshold will be considered as background. Acceptable values are ‘<’, ‘<=’, ‘>’, and ‘>=’.

  • bins – the number of bins used for Otsu thresholding. Default is 128.

class forger.forger.ForegroundMask(background: str = '<', bins=128)[source]

Bases: object

Create a mask for the foreground part of an image.

The foreground is detected through Otsu thresholding method.

Parameters

  • background – The relationship of background and the Otsu threshold. For example, if background is ‘<’, after applying Otsu method, all image voxels less than the Otsu threshold will be considered as background. Acceptable values are ‘<’, ‘<=’, ‘>’, and ‘>=’.

  • bins – the number of bins used for Otsu thresholding. Default is 128.

class forger.forger.From2DTo3D(repeat=1)[source]

Bases: forger.forger.Transformation

Convert a 2D SimpleITK image and mask to a 3D SimpleITK image and mask.

Convert 2D SimpleITK image (mask) to 3D SimpleITK image (mask) with user

defined depth. The 2D image will be copied, as a single layer of a 3D image, to produce each layer of the 3D image.

Parameters

repeat (int) – Number of times to replicate the 2D image. The default value is 1.

class forger.forger.From3DTo2D[source]

Bases: forger.forger.Transformation

Convert a 3D thin image and its mask to a 2D image and mask.

A thin image is an image where the components across Z-axis represent only

one pixel. Common thin images are grayscale, with dimension 1 across Z-axis, and RGB images, with dimension 3 across Z-axis.

static make_2d_image(image_3d)[source]
class forger.forger.FromNumpy(out_image_dtype=None, out_mask_dtype=None)[source]

Bases: forger.forger.Transformation

Convert arrays to objects of type SimpleITK.Image.

Parameters

  • out_image_dtype – The SimpleITK data type used as the type of the image. If None, the output data type is inferred from the image array.

  • out_mask_dtype – The SimpleITK data type used as the type of the mask. If None, the output data type is inferred from the mask array.

class forger.forger.Identity(copy: bool = False)[source]

Bases: forger.forger.Transformation

Apply identity transformation to an image and its mask (if provided).

This transformation does not change the image or its mask and is just for convenience.

Parameters

copy – If True create and return a copy of the image and mask (if provided); otherwise, the input image and mask objects will be returned.

class forger.forger.IntensityRangeTransfer(interval: tuple, cast=None, p=1.0)[source]

Bases: forger.forger.Transformation

Apply a linear transformation to the voxel values in a given range.

Applies a linear transformation to the image voxel values of an image that

are inside a user-defined range.

Parameters

  • interval – A tuple containing the lower bound and upper bound for the output image, (lower, upper).

  • cast – A data type used for casting the resulting image. If None, no casting will be applied. The default is None. Assuming that SimpleITK has been imported as sitk. The following options can be used:

    • sitk.sitkUInt8: Unsigned 8 bit integer

    • sitk.sitkInt8: Signed 8 bit integer

    • sitk.sitkUInt16: Unsigned 16 bit integer

    • sitk.sitkInt16: Signed 16 bit integer

    • sitk.sitkUInt32: Unsigned 32 bit integer

    • sitk.sitkInt32: Signed 32 bit integer

    • sitk.sitkUInt64: Unsigned 64 bit integer

    • sitk.sitkInt64: Signed 64 bit integer

    • sitk.sitkFloat32: 32 bit float

    • sitk.sitkFloat64: 64 bit float

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.Invert(maximum: Optional[Union[int, float]] = None, p: float = 1.0)[source]

Bases: forger.forger.Transformation

Invert the intensity of an image based on a constant value.

This transformation does not affect the mask.

Parameters

  • maximum – The maximum intensity value used for inverting voxel values. A voxel value v is transformed to maximum - v.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.IsolateRange(lower_bound, upper_bound, image_outside_value=0, mask_outside_value=0, recalculate_mask: bool = False, p: float = 1.0)[source]

Bases: forger.forger.Transformation

Set voxel values outside a given range to a given constant.

This object provides the option to manipulate the outside range in a mask

image. The outside region for the mask can be set to a specific value. Also, the region outside the clipped range can be set to a constant value. Note: The boundaries defined by the threshold values are considered as inside region and will not be affected.

Parameters

  • lower_bound – Any voxel values less than this parameter will be set to image_outside_value. If recalculate_mask is True, corresponding voxel values in the mask will be set to mask_outside_value.

  • upper_bound – Any voxel values greater than this parameter will be set to image_outside_value. If recalculate_mask is True, corresponding voxel values in the mask will be set to mask_outside_value.

  • image_outside_value – This value is used to set the value of outside voxels in the image. Any voxel with a value less than lower_bound or greater than upper_bound is considered to be in the outside region. The default is 0.

  • mask_outside_value – This value is used to set the value of outside voxels in the mask. Any voxel with a value less than lower_bound or greater than upper_bound is considered to be in the outside region. If recalculate_mask is False, this is ignored. The default is 0.

  • recalculate_mask – If True and the mask is not None, the voxel values mask representing the outside region are replaced with image_outside_value. If False, the mask is not affected by this transformation.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

Raises

ValueError – If recalculate_mask is True and mask is None.

class forger.forger.Isotropic(interpolator=2, output_spacing: float = 1, default_image_voxel_value=0, default_mask_voxel_value=0, output_image_voxel_type=None, output_mask_voxel_type=None, output_direction=None, output_origin=None, use_nearest_neighbor_extrapolator: bool = True, dimension: int = 3)[source]

Bases: forger.forger.Transformation

Make an image isotropic, i.e. equally spaced in all directions.

Parameters

  • interpolator= The interpolator used for resampling. The default is –

    sitk.sitkLinear. Other options for interpolations are:

    • sitk.sitkBSpline

    • sitk.sitkGaussian

    • sitk.sitkNearestNeighbor

    • sitk.sitkHammingWindowedSinc

    • sitk.sitkBlackmanWindowedSinc

    • sitk.sitkCosineWindowedSinc

    • sitk.sitkWelchWindowedSinc

    • sitk.sitkLanczosWindowedSinc

    The interpolation for mask is always sitk.sitkNearestNeighbor.

  • output_spacing – A single number representing the spacing in all directions. The default is 1.

  • default_image_voxel_value – The default value for new image voxels. The default is 0.

  • default_mask_voxel_value – The default value for new voxel mask voxels. The default is 0.

  • output_image_voxel_type – The voxel type of the output image. The default is None, meaning that the voxel type is the same as the image.

  • output_mask_voxel_type – The voxel type of the output mask. The default is None, meaning that the voxel type is the same as the mask.

  • output_direction – The direction of image and mask (both assumed to be the same). The default is None, meaning that the direction is inferred from the image and mask.

  • output_origin – The origin of image and mask (both assumed to be the same). The default is None, meaning that the origin is is inferred from the image and mask.

  • use_nearest_neighbor_extrapolator – Use the nearest neighbour for extrapolations. The default is True.

  • dimension – The dimension of the image and mask. The default is 3.

class forger.forger.Lambda(image_transformer: Optional[Callable] = None, mask_transformer: Optional[Callable] = None, p: float = 1.0)[source]

Bases: forger.forger.Transformation

Apply a customized transformation.

Parameters

  • image_transformer – A callable object, e.g. a Lambda function or a regular function used for transforming the image. Default is None, indicating identity transformation, i.e. no change in the image.

  • mask_transformer – A callable object, e.g. a Lambda function or a regular function used for transforming the mask. Default is None, indicating identity transformation, i.e. no change on the mask.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.MaskImage(segment_label=1, image_outside_value=0, mask_outside_label=0, p=1.0)[source]

Bases: forger.forger.Transformation

Erase the region outside a mask.

Parameters

  • segment_label – The label of the segment used for determining the region to be kept.

  • image_outside_value – All image voxel values that do not correspond to the segment_label are set to this value. The default is 0.

  • mask_outside_label – All mask voxel values that are not equal to the segment_label are set to this value. The default is 0.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.MaskLabelRemap(mapping: dict)[source]

Bases: forger.forger.Transformation

class forger.forger.MinMaxScaler(min_value=0, max_value=1, p: float = 1.0)[source]

Bases: forger.forger.Transformation

Linearly transform voxel values to a given range.

This transformation does not affect masks. This transformation converts an image, so that the voxels in the resulting image are equal to the provided maximum value.

Parameters

  • min_value (float) – The minimum value in the converted image. The default value is 0.

  • max_value (float) – The maximum value in the converted image. The default value is 1.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.OneOf(transforms)[source]

Bases: forger.forger.Transformation

Apply one of the provided transformations.

Parameters

transforms – A list of transformations. One transformation is selected randomly.

class forger.forger.Pad(padding: Union[int, Tuple[int, int, int]], method: str = 'constant', constant: Optional[Union[int, float]] = 0, background_label: int = 0, pad_lower_bound=True, pad_upper_bound=True, p=1.0)[source]

Bases: forger.forger.Transformation

Pad an image and a mask (if applicable).

The available options for padding are constant padding, mirror padding, and wrap padding.

Parameters

  • padding – The padding size. The acceptable values are a positive integer and a sequence of 3 positive integers, used for padding width (x), height (y), and depth (z) dimensions, respectively. If an integer value is provided, it will be considered as the padding value for all dimensions. Note that padding must be a positive integer.

  • method – The method used for padding. Supported options are as follows:

    • constant: Uses a constant value for padding. Default is constant.

    • mirror: Considers the image edge as mirror and use the

      reflection of values inside the image as the values for voxels in the padded area.

    • wrap: Uses a wrap padding.

  • constant – The constant value used for padding. This will be ignored if method is not constant. The default is 0.

  • background_label – The label used in the mask image for the padded region. The default is 0.

  • pad_lower_bound (bool) – if True padding will be applied to the lower-boundary of each dimension. Default is True.

  • pad_upper_bound (bool) – if True padding will be applied to the upper-boundary of each dimension. Default is True.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

Raises

ValueError – If padding value or method is not valid.

class forger.forger.RandomAffine(angles: Tuple[float, float, float], translation=None, scales=None, interpolator=3, image_background=0, mask_background=0, image_type=2, mask_type=1, reference=None, spacing=None, direction=None, reshape=True, p: float = 1)[source]

Bases: forger.forger.Transformation

A random affine applied to an image and its mask (if provided).

Parameters

  • angles – The interval for rotation angles in degrees. In a 3D context:

    • If angles is a scalar s, the boundary list will be

      [(-|s|, |s|), (-|s|, |s|), (-|s|, |s|)], where |s| represents the absolute value of s.

    • If angles is a list of 3 scalars [a, b, c], the boundary list

      will be [(-|a|, |a|), (-|b|, |b|), (-|c|, |c|)], where |a| represents the absolute value of a.

    • angles can also have the following form:

      [(x_min, x_max), (y_min, y_max), (z_min, z_max)]

    The default value is None representing no rotation.

  • translation – The interval for translation components. Similar formats to that of angles are allowed. The default is None, representing no translation.

  • scales – A scale factor. The default is None, representing no scaling. If it is not None, it should have the following format: [(x_min, x_max), (y_min, y_max), (z_min, z_max)]

  • interpolator – The interpolator used by the transformation. The default is sitk.sitkBSpline.

  • image_background – The value used as the default for image voxels.

  • mask_background – The value used as the default for mask voxels.

  • reference – The reference grid used for resampling during the transformation. The default is None, meaning that the image (mask) itself is used for resampling.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

DIMENSION = 3
class forger.forger.RandomChoices(transforms, k, keep_original_order=True)[source]

Bases: forger.forger.Transformation

Randomly select k transformations and apply them.

Parameters

  • transforms – A list of transformations.

  • k – The number of transformations to be selected.

  • keep_original_order – If True preserve the order of transformations when applying them. Otherwise, transformations will be applied in a random order.

class forger.forger.RandomCrop(size: Tuple, p: float = 1.0)[source]

Bases: forger.forger.Transformation

Crop an image and its mask (if provided) randomly but with a fixed size.

Parameters

  • size – The size of the region to be extracted.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.RandomFlipX(p: float = 0.5)[source]

Bases: forger.forger.Transformation

Flips an image and it’s mask (if provided) across x-axis (width).

Parameters

p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.RandomFlipY(p: float = 0.5)[source]

Bases: forger.forger.Transformation

Flips an image and it’s mask (if provided) across y-axis (height).

Parameters

p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.RandomFlipZ(p: float = 0.5)[source]

Bases: forger.forger.Transformation

Flips an image and its mask (if provided) across z-axis (depth).

Parameters

p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.RandomOrder(transforms)[source]

Bases: forger.forger.Transformation

Apply a list of transformations in a random order.

Parameters

transforms – List of selected transforms to be applied in random order.

class forger.forger.RandomRotation(angles: Union[float, Tuple[float, float, float]], interpolator=3, image_background=0, mask_background=0, image_type=2, mask_type=1, reference=None, spacing=None, direction=None, reshape=True, p: float = 1)[source]

Bases: forger.forger.Transformation

A random rotation applied to an image and its mask (if provided).

Parameters

  • angles – The interval for rotation angles in degrees. In a 3D context:

    • If angles is a scalar s, the boundary list will be

      [(-|s|, |s|), (-|s|, |s|), (-|s|, |s|)], where |s| represents the absolute value of s.

    • If angles is a list of 3 scalars [a, b, c], the boundary list

      will be [(-|a|, |a|), (-|b|, |b|), (-|c|, |c|)], where |a| represents the absolute value of a.

    • angles can also have the following form:

      [(x_min, x_max), (y_min, y_max), (z_min, z_max)]

    The default value is None representing no rotation.

  • interpolator – The interpolator used by the transformation. The default is sitk.sitkBSpline.

  • image_background – The value used as the default for image voxels.

  • mask_background – The value used as the default for mask voxels.

  • reference – The reference grid used for resampling during the transformation. The default is None, meaning that the image (mask) itself is used for resampling.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

DIMENSION = 3
class forger.forger.RandomSegmentSafeCrop(crop_size: Tuple, include: collections.abc.Sequence = (1,), p: float = 1.0)[source]

Bases: forger.forger.Transformation

Crop an image and a mask randomly while keeping some regions of interest.

Regions of interest can be defined using a mask. Unlike many other transformation, this transformation requires a mask. This transformation falls back to random crop when there region of interest is empty. If crop size is less than segment size (in any dimension), a random crop is made from the segment.

Parameters

  • crop_size – Minimum size of the cropped region. Like all parameters in this package, the dimension order is (x, y, z), i.e. (width, height, depth).

  • include – Sequence of unique ids for each segment of interest in the

  • image. Default is `tuple ([1])

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.Reader[source]

Bases: forger.forger.Transformation

Load image and its corresponding mask (if provided) from their addresses.

Each address could be a directory address or the DICOM file address.

class forger.forger.Resample(interpolator=2, output_spacing: tuple = (1, 1, 1), default_image_voxel_value=0, default_mask_voxel_value=0, output_image_voxel_type=None, output_mask_voxel_type=None, output_direction=None, output_origin=None, use_nearest_neighbor_extrapolator: bool = True)[source]

Bases: forger.forger.Transformation

Make an image isotropic, i.e. equally spaced in all directions.

Parameters

  • interpolator= The interpolator used for resampling. The default is –

    sitk.sitkLinear. Other options for interpolations are:

    • sitk.sitkBSpline

    • sitk.sitkGaussian

    • sitk.sitkNearestNeighbor

    • sitk.sitkHammingWindowedSinc

    • sitk.sitkBlackmanWindowedSinc

    • sitk.sitkCosineWindowedSinc

    • sitk.sitkWelchWindowedSinc

    • sitk.sitkLanczosWindowedSinc

    The interpolation for mask is always sitk.sitkNearestNeighbor.

  • output_spacing – A tuple representing the spacing in each directions. The order of directions is x (height), y (width), and z (depth). The default is (1, 1, 1).

  • default_image_voxel_value – The default value for new image voxels. The default is 0.

  • default_mask_voxel_value – The default value for new voxel mask voxels. The default is 0.

  • output_image_voxel_type – The voxel type of the output image. The default is None, meaning that the voxel type is the same as the image.

  • output_mask_voxel_type – The voxel type of the output mask. The default is None, meaning that the voxel type is the same as the mask.

  • output_direction – The direction of image and mask (both assumed to be the same). The default is None, meaning that the direction is inferred from the image and mask.

  • output_origin – The origin of image and mask (both assumed to be the same). The default is None, meaning that the origin is inferred from the image and mask.

  • use_nearest_neighbor_extrapolator – Use the nearest neighbor for extrapolations. The default is True.

class forger.forger.Resize(size: Tuple[int, int, int], interpolator=3, default_image_voxel_value=0, default_mask_voxel_value=0, p: float = 1.0)[source]

Bases: forger.forger.Transformation

Resize an image and its mask (if provided).

Parameters

  • size – A tuple of int values representing image size. The order of dimensions should be (x, y, z), i.e. (width, height, and depth).

  • interpolator – A SimpleITK interpolator function. The default interpolator for image is sitk.sitkBSpline. Other options for interpolations are:

    • sitk.sitkLinear

    • sitk.sitkGaussian

    • sitk.sitkNearestNeighbor

    • sitk.sitkHammingWindowedSinc

    • sitk.sitkBlackmanWindowedSinc

    • sitk.sitkCosineWindowedSinc

    • sitk.sitkWelchWindowedSinc

    • sitk.sitkLanczosWindowedSinc

    A mask is always interpolated using sitk.sitkNearestNeighbor to avoid introducing new labels.

  • default_image_voxel_value – Set the image voxel value when a transformed voxel is outside of the image volume. The default value is 0.

  • default_mask_voxel_value – Set the mask voxel value when a transformed voxel is outside of the mask volume. The default value is 0.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.Rotation(angles: Tuple[int, int, int], interpolator=3, image_background=0, mask_background=0, reference=None)[source]

Bases: forger.forger.Transformation

Rotation transformation applied to an image and its mask (if provided).

Parameters

  • angles – The rotation angles in degrees. This should be a tuple of length 3.

  • interpolator – The interpolator used by the transformation. The default is sitk.sitkBSpline.

  • image_background – The value used as the default for image voxels.

  • mask_background – The value used as the default for mask voxels.

  • reference – The reference grid used for resampling during the transformation. The default is None, meaning that the image (mask) itself is used for resampling.

DIMENSION = 3
class forger.forger.SaltPepperNoise(noise_prob: float = 0.01, noise_range: Optional[Tuple] = None, random_seed=None, p=1.0)[source]

Bases: forger.forger.Transformation

Changes the voxel values with fixed value impulse noise.

This transformation, which is often called salt and pepper noise does not

affect the mask.

Parameters

  • noise_prob – The noise probability to be applied on a image. The default is 0.01.

  • noise_range – A tuple of size 2 representing the lower and upper bounds of noise values.

  • random_seed (int) – Random integer number to set seed for random noise generation. Default is None.

  • p – The transformation is applied with a probability of p. The default

  • is `1.0`.

class forger.forger.SegmentCrop(include: collections.abc.Sequence = (1,), if_missing='raise', p: float = 1.0)[source]

Bases: forger.forger.Transformation

Crop a region of interest from an image and its mask.

Regions of interest is defined using a mask. Unlike many other transformations, this transformation requires a mask.

Parameters

  • include – Sequence of unique ids for each segment of interest in the image. Default is [1].

  • if_missing – If ‘raise’ raises a ValueError when the region of interest is empty; if ‘ignore’ the transformation does not have any effect on the image and mask.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.SequentialWriter(dir_path='.', image_prefix='image', image_postfix='', mask_prefix='mask', mask_postfix='', extension='nrrd', image_type=None, mask_type=None, compressor='', compression_level=None)[source]

Bases: forger.forger.Transformation

Write image and its corresponding mask (if provided) to files.

Each address should be a file address. The supported IO file formats include:

  • BMPImageIO (.bmp, .BMP)

  • BioRadImageIO (.PIC, .pic)

  • GiplImageIO (.gipl .gipl.gz)

  • JPEGImageIO (.jpg, .JPG, .jpeg, .JPEG)

  • LSMImageIO (.tif, .TIF, .tiff, .TIFF, .lsm, .LSM)

  • MINCImageIO (.mnc, .MNC)

  • MRCImageIO (.mrc, .rec)

  • MetaImageIO (.mha, .mhd)

  • NiftiImageIO (.nia, .nii, .nii.gz, .hdr, .img, .img.gz)

  • NrrdImageIO (.nrrd, .nhdr)

  • PNGImageIO (.png, .PNG)

  • TIFFImageIO (.tif, .TIF, .tiff, .TIFF)

  • VTKImageIO (.vtk)

Parameters

  • dir_path – The default is ., representing the current directory.

  • image_prefix – A string used as the prefix for the saved image names. The default is image.

  • image_postfix – A string used as the postfix for the saved image names. The default is empty string.

  • mask_prefix – A string used as the prefix for the saved mask names. The default is ‘mask’.

  • mask_postfix= – A string used as the postfix for the saved image names. The default is empty string.

  • extension – The file extension used for saving files. This determines the type of the saved file. The default is ‘nrrd’.

  • image_type – The image type used for casting the image. The default is None, meaning that no casting is applied by default.

  • mask_type – The mask type used for casting the image. The default is None, meaning that no casting is applied by default. If applied, for most cases this should be sitk.sitkUInt8. In case the labels used in the mask are larger than 255, sitk.sitkUInt16, sitk.sitkUInt32, or sitk.sitkUInt64 should be used. If negative values are included in the labels of the mask, use sitk.sitkInt8, sitk.sitkInt16, or sitk.sitkUInt32. Note that using larger data types lead to increase in memory usage and larger files sizes.

  • compressor – The compressor used for compression. The default is an empty string, representing the default compression. Note that not all file formats support compression.

  • compression_level – The compression level used for compression. The default is None, representing the default compression level.

generate_path()[source]
class forger.forger.Shrink(shrinkage: Tuple[int, int, int], p: float = 1.0)[source]

Bases: forger.forger.Transformation

Shrink an image by an integer factor in each dimension.

Given an image with size of (m, n, k), applying this transformation using an expansion factor of (a, b, c) results in an image of size (a // m, b // n, c // k), where // represents integer division. The voxel spacing will change after applying this transformation.

Parameters

  • shrinkage – A tuple of positive integer values representing the shrinkage factors for each dimension.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.ToNumpy(out_image_dtype=None, out_mask_dtype=None)[source]

Bases: forger.forger.Transformation

Convert an image and its mask (if provided) to Numpy arrays.

Parameters

  • out_image_dtype – The numpy datatype used as the type of the numpy array representing the image. If None, the output data type is inferred from the image.

  • out_mask_dtype – The numpy datatype used as the type of the numpy array representing the mask. If None, the output data type is inferred from the mask.

class forger.forger.Transformation[source]

Bases: abc.ABC

class forger.forger.UniformNoise(low, high, ratio=0.01, dtype=2, seed=None, p=1.0)[source]

Bases: forger.forger.Transformation

Add a scattered noise to an image.

Parameters

  • low – The lower-bound for the noise values. The noise values will be greater than or equal to this value

  • high – The upper-bound for the noise values. The noise values will be less than this value.

  • dtype – The data type used for generating the uniform random noise. Allowed data types are: sitk.sitkInt8, sitk.sitkUInt8, sitk.sitkInt16, sitk.sitkUInt16`, sitk.sitkInt32, sitk.sitkUInt32, sitk.sitkInt64, sitk.sitkUInt64, sitk.sitkFloat32, sitk.sitkFloat64.

  • seed – The seed used for random number generator. If None, a fresh value is used. The default is None.

class forger.forger.UnitNormalize(p: float = 1.0)[source]

Bases: forger.forger.Transformation

Normalize an image by transforming mean to 0 and variance to 1.

This transformation does not affect masks.

Parameters

p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.WindowLocationClip(location, window, p=1.0)[source]

Bases: forger.forger.Transformation

Clip the voxel values to a specified range.

Parameters

  • location – Central point of the window for clipping the image.

  • window – Positive integer value as window size, representing the range that any voxel values outside this range will be clipped to the lower bound and upper bound of this range. The center of the window is the location, i.e. the range will be: (location - window // 2, location + window // 2), where // is integer division.

  • p – The transformation is applied with a probability of p. The default value is 1.0.

class forger.forger.Writer[source]

Bases: forger.forger.Transformation

Write image and its corresponding mask (if provided) to file.

Each address should be a file address. The supported IO file formats include:

  • BMPImageIO (.bmp, .BMP)

  • BioRadImageIO (.PIC, .pic)

  • GiplImageIO (.gipl .gipl.gz)

  • JPEGImageIO (.jpg, .JPG, .jpeg, .JPEG)

  • LSMImageIO (.tif, .TIF, .tiff, .TIFF, .lsm, .LSM)

  • MINCImageIO (.mnc, .MNC)

  • MRCImageIO (.mrc, .rec)

  • MetaImageIO (.mha, .mhd)

  • NiftiImageIO (.nia, .nii, .nii.gz, .hdr, .img, .img.gz)

  • NrrdImageIO (.nrrd, .nhdr)

  • PNGImageIO (.png, .PNG)

  • TIFFImageIO (.tif, .TIF, .tiff, .TIFF)

  • VTKImageIO (.vtk)

forger.utils module

class forger.utils.Label(fully_connected: bool = False, input_foreground_value: int = 1, output_background_value: int = 0, dtype=1)[source]

Bases: object

Label a binary image.

Each distinct connected component (segment) is assigned a unique label. The

segment labels start from 1 and are consecutive. The order of label assignment is based on the the raster position of the segments in the binary image.

Parameters

  • fully_connected

  • input_foreground_value

  • output_background_value

  • dtype – The data type for the label map. Options include: * sitk.sitkUInt8 * sitk.sitkUInt16 * sitk.sitkUInt32 * sitk.sitkUInt64

forger.utils.check_dimensions(image, mask)[source]

Check if the size of the image and mask are equal.

Parameters

  • image – A sitk.Image.

  • mask – A sitk.Image.

Raises

ValueError – If image and mask are not None and their dimension are not the same.

forger.utils.get_stats(image)[source]
Computes minimum, maximum, sum, mean, variance, and standard deviation of

an image.

Parameters

image – A sitk.Image object.

Returns

returns statistical values of type dictionary include keys ‘min’,

’max’, ‘mean’, ‘std’, and ‘var’.

forger.utils.image_equal(image1: SimpleITK.SimpleITK.Image, image2: SimpleITK.SimpleITK.Image, type_check=True, tolerance=1e-06)[source]

Check if two images are equal.

Data type, size, and content are used for comparison. Two image with the L2 distance less than a tolerance value are considered equal.

Parameters

  • image1 – A SimpleITK image.

  • image2 – A SimpleITK image.

  • type_check – True if data type is used for comparison.

  • tolerance – The threshold used for the acceptable deviation between the euclidean distance of voxel values between the two images.

Returns

bool – True if two images are equal; otherwise, False.

forger.utils.read_image(image_path: Optional[str])[source]

Read an image.

Parameters

image_path – The path to the image file or the folder containing a DICOM image.

Returns

sitk.Image – A SimpleITK Image.

Raises

ValueError – if there exist more than one image series or if there is no DICOM file in the provided path.

forger.utils.referenced_3D_resample(image, transformation=None, interpolator=3, default_value=0, image_voxel_type=None, reference=None)[source]

Do resampling using a given reference.

Parameters

  • image – A simpleITK image.

  • transformation – A transformation to be applied to the image. The default is None, representing the identity transformation.

  • interpolator – The interpolator used for image interpolation after applying transformation. If None, the default value is used. The default value is sitk.sitkBSpline.

  • default_value – The default value used for voxel values. The default value is 0.

  • image_voxel_type – The data type used for casting the resampled image. If None, the voxel type of the image is used as the voxel type of the result.

  • reference – The image used as the reference for resampling. If None, the image itself is used as the reference.

Returns

sitk.Image – The resampled image.

forger.utils.refrence_free_3D_resample(image, transformation=None, interpolator=3, default_value=0, image_voxel_type=None, spacing=None, direction=None)[source]

Do resampling without reference.

Parameters

  • image – A SimpleITK image.

  • transformation – A transformation to be applied to the image. If None, The identity transformation is used.

  • interpolator – The interpolator used for image interpolation after applying transformation. The default is sitk.sitkBSpline.

  • default_value – The default values used for voxel values. The default is 0.

  • image_voxel_type – The data type used for casting the resampled image. If None, the voxel type of the image is used.

  • spacing – The spacing of the image after resampling.

  • direction – The direction of the image after resampling.

Returns

sitk.Image – The resampled image.

Module contents