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