FFCV Transforms

Image transformations for the fastxtend Loader

fastxtend provides multiple FFCV transforms, including existing FFCV transforms with harmonized arguments, fastai transforms implemented as FFCV transforms, and additional FFCV transforms.

By default, these transforms are imported under ft if using from fastxtend.ffcv.all import *.

FFCV Transforms Reference

These FFCV Transforms have had their initialization arguments harmonized and are otherwise identical to their FFCV counterparts. You can find the original versions and documentation at the FFCV API Reference.

---

RandomResizedCrop

 RandomResizedCrop (scale:Tuple[float,float], ratio:Tuple[float,float],
                    size:int)

Crop a random portion of image with random aspect ratio and resize it to a given size. Chances are you do not want to use this augmentation and instead want to include RRC as part of the decoder, by using the :cla:~ffcv.fields.rgb_image.ResizedCropRGBImageDecoder class.

	Type	Details
scale	typing.Tuple[float, float]	Lower and upper bounds for the ratio of random area of the crop.
ratio	typing.Tuple[float, float]	Lower and upper bounds for random aspect ratio of the crop.
size	int	Side length of the output.

While you can use RandomResizedCrop by itself, it’s probably better to use RandomResizedCropRGBImageDecoder which integrates the transform with image loading.

---

source

RandomHorizontalFlip

 RandomHorizontalFlip (prob:float=0.5)

Flip the image horizontally with probability prob. Operates on raw arrays (not tensors).

	Type	Default	Details
prob	float	0.5	The probability with which to flip each image in the batch horizontally.

---

Cutout

 Cutout (crop_size:int, fill:Tuple[int,int,int]=(0, 0, 0))

Cutout data augmentation (https://arxiv.org/abs/1708.04552).

	Type	Default	Details
crop_size	int		Size of the random square to cut out.
fill	typing.Tuple[int, int, int]	(0, 0, 0)	An RGB color ((0, 0, 0) by default) to fill the cutout square with. Useful for when a normalization layer follows cutout, in which case you can set the fill such that the square is zero post-normalization.

---

source

Translate

 Translate (padding:int, fill:Tuple[int,int,int]=(0, 0, 0))

Translate each image randomly in vertical and horizontal directions up to specified number of pixels.

	Type	Default	Details
padding	int		Max number of pixels to translate in any direction.
fill	Tuple[int, int, int]	(0, 0, 0)	An RGB color ((0, 0, 0) by default) to fill the area outside the shifted image.

fastxend’s Translate is FFCV’s RandomTranslate renamed, as it applies to all images in batch and not a random subset.

fastxtend’s RandomTranslate applies a random translatation to a random subset of images in a batch.

---

Poison

 Poison (mask:numpy.ndarray, alpha:numpy.ndarray, indices, clamp=(0, 255))

Poison specified images by adding a mask with given opacity. Operates on raw arrays (not tensors).

	Type	Default	Details
mask	ndarray		The mask to apply to each image.
alpha	ndarray
indices	Sequence[int]		The indices of images that should have the mask applied.
clamp	tuple	(0, 255)	Clamps the final pixel values between these two values (default: (0, 255)).

---

ReplaceLabel

 ReplaceLabel (indices, new_label:int)

Replace label of specified images.

	Type	Details
indices	Sequence[int]	The indices of images to relabel.
new_label	int	The new label to assign.

---

Squeeze

 Squeeze (*dims)

Remove given dimensions of input of size 1. Operates on tensors.

Color Transforms

These color transforms support both fastai-style logit space color transforms and TorchVision blending based color transforms.

Warning

Defaults for these transforms are for the fastai-style implementations.

Except for RandomHue¹, these transforms use the slightly slower fastai implementations. Users should test the fastai FFCV, TorchVision FFCV, and fastai batch transforms to determine which are most performant.

These transforms are also compatible with FFCV.

---

source

RandomBrightness

 RandomBrightness (prob:float=0.75, max_lighting:float=0.2,
                   fastai:bool=True)

Randomly adjust image brightness. Supports both TorchVision and fastai style brightness transforms.

	Type	Default	Details
prob	float	0.75	Probability of changing brightness
max_lighting	float	0.2	Maximum brightness change. Randomly choose factor on [0.5(1-magnitude), 0.5(1+magnitude)], or [max(0, 1-magnitude), 1+magnitude] if fastai=False.
fastai	bool	True	fastai-style transform or TorchVision. Defaults to fastai.

---

source

RandomContrast

 RandomContrast (prob:float=0.75, max_lighting:float=0.2,
                 fastai:bool=True)

Randomly adjust image contrast. Supports both TorchVision and fastai style contrast transforms.

	Type	Default	Details
prob	float	0.75	Probability of changing contrast
max_lighting	float	0.2	Maximum contrast change. Randomly choose factor on [1-max_lighting, 1/(1-max_lighting)] in log space, or [max(0, 1-magnitude), 1+magnitude] if fastai=False.
fastai	bool	True	fastai-style transform or TorchVision. Defaults to fastai.

---

source

RandomSaturation

 RandomSaturation (prob:float=0.75, max_lighting:float=0.2,
                   fastai:bool=True)

Randomly adjust image saturation. Supports both TorchVision and fastai style saturation transforms.

	Type	Default	Details
prob	float	0.75	Probability of changing saturation
max_lighting	float	0.2	Maximum saturation change. Randomly choose factor on [1-max_lighting, 1/(1-max_lighting)] in log space, or [max(0, 1-magnitude), 1+magnitude] if fastai=False.
fastai	bool	True	fastai-style transform or TorchVision. Defaults to fastai.

---

source

RandomLighting

 RandomLighting (prob:float=0.75, max_lighting:float=0.2,
                 max_brightness:float|None=None,
                 max_contrast:float|None=None,
                 max_saturation:float|None=None,
                 prob_brightness:float|None=None,
                 prob_contrast:float|None=None,
                 prob_saturation:float|None=None, fastai:bool=False)

Randomly adjust image brightness, contrast, and saturation. Combines all three into single transform for speed. Supports both TorchVision and fastai style lighting transforms.

	Type	Default	Details
prob	float	0.75	Default probability of changing brightness, contrast, and saturation. Individual probability overrides this value.
max_lighting	float	0.2	Default maximum lighting change. Individual lighting overrides this value. See max_brightness, max_contrast, and max_saturation for details.
max_brightness	float | None	None	Maximum brightness change. Randomly choose factor on [0.5(1-magnitude), 0.5(1+magnitude)], or [max(0, 1-magnitude), 1+magnitude] if fastai=False.
max_contrast	float | None	None	Maximum contrast change. Randomly choose factor on [1-max_lighting, 1/(1-max_lighting)] in log space, or [max(0, 1-magnitude), 1+magnitude] if fastai=False.
max_saturation	float | None	None	Maximum saturation change. Randomly choose factor on [1-max_lighting, 1/(1-max_lighting)] in log space, or [max(0, 1-magnitude), 1+magnitude] if fastai=False.
prob_brightness	float | None	None	Individual probability of changing brightness. Set to override prob.
prob_contrast	float | None	None	Individual probability of changing contrast. Set to override prob.
prob_saturation	float | None	None	Individual probability of changing saturation. Set to override prob.
fastai	bool	False	fastai-style transform or TorchVision. Defaults to fastai.

---

source

RandomHue

 RandomHue (prob:float=0.75, max_hue:float=0.1, fastai:bool=True)

Randomly adjust image Hue. Supports both TorchVision and fastai style contrast transforms.

	Type	Default	Details
prob	float	0.75	Probability of changing hue
max_hue	float	0.1	Maximum hue change. Randomly choose factor on [1-max_hue, 1/(1-max_hue)] in log space, or [-magnitude, magnitude] clipped to [-0.5, 0.5] if fastai=False.
fastai	bool	True	If True applies the slower, fastai-style transform. Defaults to TorchVision

Unlike the other color transformations, RandomHue uses the same implementation for both fastai and TorchVision versions, so performance should be the same. The only difference is the max_hue selection.

Additional FFCV Transforms

Contains both transforms which pending acceptance and/or release for the next version of FFCV² and fastxtend FFCV transforms.

Both are useable in fastxtend and FFCV.

RandomGrayscale

Randomly convert images to grayscale, using one of Luma601, Luma709, Average, or random per image choice of all three.

---

source

GrayscaleType

 GrayscaleType (value, names=None, module=None, qualname=None, type=None,
                start=1)

Grayscale Types for RandomGrayscale for typo-proof and autocompletion

---

source

RandomGrayscale

 RandomGrayscale (prob:float=0.1,
                  grayscale:GrayscaleType=<GrayscaleType.Random: 3>)

Random grayscale conversion augmentation.

	Type	Default	Details
prob	float	0.1	Probability of applying on each image.
grayscale	GrayscaleType	GrayscaleType.Random

---

source

RandomChannelDrop

 RandomChannelDrop (prob:float=0.1)

Randomly replace image channel with random value.

	Type	Default	Details
prob	float	0.1	Probability of applying on each image.

---

source

RandomCutout

 RandomCutout (prob:float, crop_size:int, fill:Tuple[int,int,int]=(0, 0,
               0))

Random cutout data augmentation (https://arxiv.org/abs/1708.04552).

	Type	Default	Details
prob	float		Probability of applying on each image.
crop_size	int		Size of the random square to cut out.
fill	Tuple[int, int, int]	(0, 0, 0)	An RGB color ((0, 0, 0) by default) to fill the cutout square with. Useful for when a normalization layer follows cutout, in which case you can set the fill such that the square is zero post-normalization.

---

source

RandomTranslate

 RandomTranslate (prob:float, padding:int, fill:Tuple[int,int,int]=(0, 0,
                  0))

Translate each image randomly in vertical and horizontal directions up to specified number of pixels.

	Type	Default	Details
prob	float		Probability of applying on each image.
padding	int		Max number of pixels to translate in any direction.
fill	Tuple[int, int, int]	(0, 0, 0)	An RGB color ((0, 0, 0) by default) to fill the area outside the shifted image.

Unlike FFCV’s RandomTranslate, which applies a random translatation to all images in a batch, fastxtend’s RandomTranslate randomly applies a random translatation to a subset of images in a batch with probability prob.

---

source

RandomErasing

 RandomErasing (prob:float=0.25, min_area:float=0.02, max_area:float=0.3,
                min_aspect:float=0.3, max_count:int=1,
                fill_mean:Tuple[int,int,int]=(124, 116, 103),
                fill_std:Tuple[int,int,int]=(58, 57, 57),
                fast_fill:bool=True)

Random erasing data augmentation (https://arxiv.org/abs/1708.04896).

	Type	Default	Details
prob	float	0.25	Probability of applying on each image.
min_area	float	0.02	Minimum erased area as percentage of image size.
max_area	float	0.3	Maximum erased area as percentage of image size.
min_aspect	float	0.3	Minimum aspect ratio of erased area.
max_count	int	1	Maximum number of erased blocks per image. Erased Area is scaled by max_count.
fill_mean	Tuple[int, int, int]	(124, 116, 103)	The RGB color mean (ImageNet’s (124, 116, 103) by default) to randomly fill the erased area with. Should be the mean of dataset or pretrained dataset.
fill_std	Tuple[int, int, int]	(58, 57, 57)	The RGB color standard deviation (ImageNet’s (58, 57, 57) by default) to randomly fill the erased area with. Should be the st. dev of dataset or pretrained dataset.
fast_fill	bool	True	Default of True is ~2X faster by generating noise once per batch and randomly selecting slices of the noise instead of generating unique noise per each image.

The implementation for RandomErasing was inspired by fastai.vision.augment.RandomErasing.

Footnotes

1. Unlike the other color transformations, RandomHue uses the same implementation for both fastai and TorchVision versions, so performance should be the same. The only difference is the max_hue selection.

2. If accepted, these will be converted to a documentation reference.