Module `preprocessor.image`

Images preprocessing is for all sorts of "picture" data, including medical imaging.

Images come in a wide variety of file formats (common formats such as PNG, JPEG, GIF, as well as DICOM medical imaging). Even within the same file format there can be varying characteristics of image files like dimensions and color depth that need to be normalized before using as training data or in order to work with an existing algorithm.

The ImagePreprocessor allows input data to be standardized for a training. This can include changes to color space (e.g. forcing all images to grayscale), resizing images, and ensuring the order of color bytes is uniform.

More complex image transformation is also possible via PyTorch image manipulation commands. See the ImagePreprocessorBuilder.torch_image_transforms() and ImagePreprocessorBuilder.torch_tensor_transforms() for more on this.

Additionally, labeling of image data for training can be tricky. To simplify this, the preprocessor can associate the image filename with a label column in a tabular dataset that was included with the image file when the dataset was packaged. For example, the labeling file might look like:

records.csv

  "label", "paths"
  "cat",   "img_003.png"
  "doc",   "img_004.png"

Typical usage:

# Force images to a 128x128 RGB format
preprocessor = (
    tb.ImagePreprocessor.builder()
    .resize(128, 128)
    .channels_first()
    .target_column("label") # associate image with corresponding "label"
    .target_dtype("int64")
    .dtype("float32")
)

NOTE: The ImagePreprocessors can generate representations of data in multiple formats, such as numpy.ndarrays or a Torch.Dataset

Classes

class ImagePreprocessor (target_column: str, convert: str, resize: Tuple[int, int], channels_first: bool, dtype: Optional[str], dicom: bool, target_dtype: Optional[str], torch_image_transforms: Optional[List[str]], torch_tensor_transforms: Optional[List[str]], expand_target_dims: bool)

Subclasses

preprocessor.image.ImageNumpyPreprocessor
preprocessor.image.ImageTorchPreprocessor

Static methods

def builder() -> ImagePreprocessorBuilder

Instance variables

var target_column : str

Name of column in the image package containing a training target label

Returns

str: A column name from the Package's record file.

Methods

def preprocess_image(self, img: ) -> numpy.ndarray

Converts the image into a numpy.ndarray representation

Args

img : Image: The internal loaded representation of the image

Returns

np.ndarray: The image as an ndarray

def preprocess_target(self, target) -> numpy.ndarray

class ImagePreprocessorBuilder

Utility for defining an image preprocessing pipeline

Ancestors

Methods

def channels_first(self, val: bool = True) -> ImagePreprocessorBuilder

Transposes images so channels are the first dimension of the output.

True = (channel, width, height) False = (width, height, channel)

Args

val: Explicitly sets the channels_first property, if blank default is True

Returns

ImagePreprocessorBuilder: This class instance, useful for chaining.

def convert(self, val: str) -> ImagePreprocessorBuilder

Sets the format used by Pillow – RGB, RGBA, etc.

When translating a color image to greyscale (mode "L"), the library uses the ITU-R 601-2 luma transform:

L = R * 299/1000 + G * 587/1000 + B * 114/1000

Args

val: The target image format. Must be one of: "RGB", "L" (for luma, aka grayscale) or "CMYK".

Returns

ImagePreprocessorBuilder: This class instance, useful for chaining.

def dicom(self, dicom: bool = False) -> ImagePreprocessorBuilder

Sets data format as DICOM rather than a typical image format.

Args

dicom: Read the data as a medical image using the DICOM library. If False, data will be read as an autodetected image format using the PIL image library (default behavior).

Returns

ImagePreprocessorBuilder: This class instance, useful for chaining.

def dtype(self, dtype: Optional[str]) -> ImagePreprocessorBuilder

Casts output numpy.ndarray to the given dtype.

Args

dtype: The dtype that a numpy output will be cast into. If not set, the Protocol will choose. Ignored for non-numpy outputs.

Returns

ImagePreprocessorBuilder: This class instance, useful for chaining.

def expand_target_dims(self, expand=True)

Sets target array expansion flag.

Args

expand : bool, optional: Target array expansion flag. Defaults to True.

Returns

ImagePreprocessorBuilder: This class instance, useful for chaining.

def resize(self, width: int, height: int) -> ImagePreprocessorBuilder

Resizes images to the given dimensions.

Args

width: The desired width of the image. (Default 32)
height: The desired height of the image. (Default 32)

Returns

ImagePreprocessorBuilder: This class instance, useful for chaining.

def target_column(self, column_name: str) -> ImagePreprocessorBuilder

Sets which column from the asset's record data to use as a target.

Args

column_name: The name of the column to take as target information.

Returns

ImagePreprocessorBuilder: This class instance, useful for chaining.

def target_dtype(self, target_dtype: Optional[str]) -> ImagePreprocessorBuilder

Sets target data type for the output numpy.ndarray

Args

dtype: The dtype that a target value will be cast into. If not set, the operation will select type. Ignored for non-numpy outputs.

Returns

ImagePreprocessorBuilder: This class instance, useful for chaining.

def torch_image_transforms(self, transforms: List[str]) -> ImagePreprocessorBuilder

Create torch preprocessing pipeline utilizing torchvision library

Supported image transforms:

CenterCrop
ColorJitter
FiveCrop
Grayscale
Pad
RandomAffine
RandomCrop
RandomGrayscale
RandomHorizontalFlip
RandomPerspective
RandomResizedCrop
RandomRotation
RandomSizedCrop
RandomVerticalFlip
Resize
Scale
TenCrop

Usage pattern:

flip = tb.TorchEncoder.encode(
            transforms.RandomHorizontalFlip(p=0.5)
        )
tb.ImagePreprocessor.builder().torch_image_transforms([flip])

See PyTorch documentation for more details.

Args

transforms: list of transforms from torchvision.transforms library encoded using TorchEncoder

Returns

ImagePreprocessorBuilder: This class instance, useful for chaining.

def torch_tensor_transforms(self, transforms: List[str]) -> ImagePreprocessorBuilder

Creates torch preprocessing pipeline utilizing torchvision library

Supported tensor transforms:

LinearTransformation
Normalize
RandomErasing

Usage Pattern:

normalize = tb.TorchEncoder.encode(
                transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
            )
tb.ImagePreprocessor.builder().torch_tensor_transforms([normalize])

See PyTorch documentation for more details.

Args

transforms : List[str]: A list of torchvision.transforms encoded using TorchEncoder

Returns

ImagePreprocessorBuilder: This class instance, useful for chaining.

Inherited members

OutputNumpy:
- output_numpy
OutputTorchDataset:
- output_torch_dataset
IsDict:
- from_dict
- to_dict