thelper.transforms package — thelper 0.3.8 documentation

### Navigation

- ☰
- thelper-0.3.8 »
- thelper package »

Fork me on GitHub

# thelper.transforms package

Transformation operations package.

This package contains data transformation classes and wrappers for preprocessing, augmentation, and normalization of data samples.

## Submodules

## thelper.transforms.composers module

Transformation composers module.

All transforms should aim to be compatible with both numpy arrays and PyTorch tensors. By default, images are processed using `__call__`, meaning that for a given transformation `t`, we apply it via:

    image_transformed = t(image)

All important parameters for an operation should also be passed in the constructor and exposed in the operation’s `__repr__` function so that external parsers can discover exactly how to reproduce their behavior. For now, these representations are used for debugging more than anything else.

class `thelper.transforms.composers.` `Compose`(transforms)

  Bases: `torchvision.transforms.transforms.Compose`

  Composes several transforms together (with support for invert ops).

  This interface is fully compatible with `torchvision.transforms.Compose`.

  See also

  `thelper.transforms.composers.CustomStepCompose`
  `__getitem__`(idx)

    Returns the idx-th operation wrapped by the composer.

  `__init__`(transforms)

    Forwards the list of transformations to the base class.

  `invert`(sample)

    Tries to invert the transformations applied to a sample.

    Will throw if one of the transformations cannot be inverted.

  `set_epoch`(epoch=0)

    Sets the current epoch number in order to change the behavior of some suboperations.

  `set_seed`(seed)

    Sets the internal seed to use for stochastic ops.

class `thelper.transforms.composers.` `CustomStepCompose`(milestones, last_epoch=-1)

  Bases: `torchvision.transforms.transforms.Compose`

  Composes several transforms together based on an epoch schedule.

  This interface is fully compatible with `torchvision.transforms.Compose`. It can be useful if some operations should change their behavior over the course of a training session. Note that all epoch indices are assumed to be 0-based.

  Usage example in Python:

      # We will scale the resolution of input patches based on an arbitrary schedule
      # dsize = (16, 16)   if epoch < 2         (16x16 patches before epoch 2)
      # dsize = (32, 32)   if 2 <= epoch < 4    (32x32 patches before epoch 4)
      # dsize = (64, 64)   if 4 <= epoch < 8    (64x64 patches before epoch 8)
      # dsize = (112, 112) if 8 <= epoch < 12   (112x112 patches before epoch 12)
      # dsize = (160, 160) if 12 <= epoch < 15  (160x160 patches before epoch 15)
      # dsize = (196, 196) if 15 <= epoch < 18  (196x196 patches before epoch 18)
      # dsize = (224, 224) if epoch >= 18       (224x224 patches past epoch 18)
      transforms = CustomStepCompose(milestones={
          0: thelper.transforms.Resize(dsize=(16, 16)),
          2: thelper.transforms.Resize(dsize=(32, 32)),
          4: thelper.transforms.Resize(dsize=(64, 64)),
          8: thelper.transforms.Resize(dsize=(112, 112)),
          12: thelper.transforms.Resize(dsize=(160, 160)),
          15: thelper.transforms.Resize(dsize=(196, 196)),
          18: thelper.transforms.Resize(dsize=(224, 224)),
      })
      for epoch in range(100):
          transforms.set_epoch(epoch)
          for sample in loader:
              sample = transforms(sample)
              train(...)

  Variables

    - stages – list of epochs where a new scaling factor is to be applied.

    - transforms – list of transformation to apply at each stage.

    - milestones – original milestones map provided in the constructor.

    - epoch – index of the current epoch.

  See also

  `thelper.transforms.composers.Compose`
  `__call__`(img)

    Applies the current stage of transformation operations to a sample.

  `__getitem__`(idx)

    Returns the idx-th operation wrapped by the composer.

  `__init__`(milestones, last_epoch=-1)

    Receives the milestone stages (or stage lists), and the initialization state.

    If the milestones do not include the first epoch (idx = 0), then no transform will be applied until the next specified epoch index. When last_epoch is -1, the training is assumed to start from scratch.

    Parameters

      - milestones – Map of epoch indices tied to transformation stages. Keys must be increasing.

      - last_epoch – The index of last epoch. Default: -1.

  `invert`(sample)

    Tries to invert the transformations applied to a sample.

    Will throw if one of the transformations cannot be inverted.

  `set_epoch`(epoch=0)

    Sets the current epoch number in order to change the behavior of some suboperations.

  `set_seed`(seed)

    Sets the internal seed to use for stochastic ops.

  `step`(epoch=None)

    Advances the epoch tracker in order to change the behavior of some suboperations.

## thelper.transforms.operations module

Transformation operations module.

All transforms should aim to be compatible with both numpy arrays and PyTorch tensors. By default, images are processed using `__call__`, meaning that for a given transformation `t`, we apply it via:

    image_transformed = t(image)

All important parameters for an operation should also be passed in the constructor and exposed in the operation’s `__repr__` function so that external parsers can discover exactly how to reproduce their behavior. For now, these representations are used for debugging more than anything else.

class `thelper.transforms.operations.` `Affine`(transf, out_size=None, flags=None, border_mode=None, border_val=None)

  Bases: `object`

  Warps a given image using an affine matrix via OpenCV and numpy.

  This operation is deterministic. The code relies on OpenCV, meaning the border arguments must be compatible with `cv2.warpAffine`.

  Variables

    - transf – the 2x3 transformation matrix passed to `cv2.warpAffine`.

    - out_size – target image size (tuple of width, height). If None, same as original.

    - flags – extra warp flags forwarded to `cv2.warpAffine`.

    - border_mode – border extrapolation mode forwarded to `cv2.warpAffine`.

    - border_val – border constant extrapolation value forwarded to `cv2.warpAffine`.

  `__call__`(sample)

    Warps a given image using an affine matrix.

    Parameters

      sample – the image to warp; should be a 2d or 3d numpy array.

    Returns

      The warped image.

  `__init__`(transf, out_size=None, flags=None, border_mode=None, border_val=None)

    Validates and initializes affine warp parameters.

    Parameters

      - transf – the 2x3 transformation matrix passed to `cv2.warpAffine`.

      - out_size – target image size (tuple of width, height). If None, same as original.

      - flags – extra warp flags forwarded to `cv2.warpAffine`.

      - border_mode – border extrapolation mode forwarded to `cv2.warpAffine`.

      - border_val – border constant extrapolation value forwarded to `cv2.warpAffine`.

  `invert`(sample)

    Inverts the warp transformation, but only is the output image has not been cropped before.

class `thelper.transforms.operations.` `CenterCrop`(size, bordertype=0, borderval=0)

  Bases: `object`

  Returns a center crop from a given image via OpenCV and numpy.

  This operation is deterministic. The code relies on OpenCV, meaning the border arguments must be compatible with `cv2.copyMakeBorder`.

  Variables

    - size – the size of the target crop (tuple of width, height).

    - relative – specifies whether the target crop size is relative to the image size or not.

    - bordertype – argument forwarded to `cv2.copyMakeBorder`.

    - borderval – argument forwarded to `cv2.copyMakeBorder`.

  `__call__`(sample)

    Extracts and returns a central crop from the provided image.

    Parameters

      sample – the image to generate the crop from; should be a 2d or 3d numpy array.

    Returns

      The center crop.

  `__init__`(size, bordertype=0, borderval=0)

    Validates and initializes center crop parameters.

    Parameters

      - size – size of the target crop, provided as tuple or list. If integer values are used, the size is assumed to be absolute. If floating point values are used, the size is assumed to be relative, and will be determined dynamically for each sample. If a tuple is used, it is assumed to be (width, height).

      - bordertype – border copy type to use when the image is too small for the required crop size. See `cv2.copyMakeBorder` for more information.

      - borderval – border value to use when the image is too small for the required crop size. See `cv2.copyMakeBorder` for more information.

  `invert`(sample)

    Specifies that this operation cannot be inverted, as data loss is incurred during image transformation.

class `thelper.transforms.operations.` `Duplicator`(count, deepcopy=False)

  Bases: `thelper.transforms.operations.NoTransform`

  Duplicates and returns a list of copies of the input sample.

  This operation is used in data augmentation pipelines that rely on probabilistic or preset transformations. It can produce a fixed number of simple copies or deep copies of the input samples as required.

  Warning

  Since the duplicates will be given directly to the data loader as part of the same minibatch, using too many copies can adversely affect gradient descent for that minibatch. To simply increase the total size of the training set while still allowing a proper shuffling of samples and/or to keep the minibatch size intact, we instead recommend setting the `train_scale` configuration value in the data loader. See `thelper.data.utils.create_loaders()` for more information.

  Variables

    - count – number of copies to generate.

    - deepcopy – specifies whether to deep-copy samples or not.

  `__call__`(sample)

    Generates and returns duplicates of the sample/object.

    If a dictionary is provided, its values will be expanded into lists that will contain all duplicates. Otherwise, the duplicates will be returned directly as a list.

    Parameters

      sample – the sample/object to duplicate.

    Returns

      A list of duplicated samples, or a dictionary of duplicate lists.

  `__init__`(count, deepcopy=False)

    Validates and initializes duplication parameters.

    Parameters

      - count – number of copies to generate.

      - deepcopy – specifies whether to deep-copy samples or not.

  `invert`(sample)

    Returns the first instance of the list of duplicates.

class `thelper.transforms.operations.` `NoTransform`

  Bases: `object`

  Used to flag some ops that should not be externally wrapped for sample/key handling.

  `__call__`(sample)

    Identity transform.

  `invert`(sample)

    Identity transform.

class `thelper.transforms.operations.` `NormalizeMinMax`(min, max, out_type=<class 'numpy.float32'>)

  Bases: `object`

  Normalizes a given image using a set of minimum and maximum values.

  The samples will be transformed such that `s = (s - min) / (max - min)`.

  Note that this operation is also not restricted to images.

  Variables

    - min – an array of minimum values to subtract with.

    - max – an array of maximum values to divide with.

    - out_type – the output data type to cast the normalization result to.

  `__call__`(sample)

    Normalizes a given sample.

    Parameters

      - sample – the sample to normalize. If given as a PIL image, it

      - will be converted to a numpy array first.

    Returns

      The warped sample, in a numpy array of type `self.out_type`.

  `__init__`(min, max, out_type=<class 'numpy.float32'>)

    Validates and initializes normalization parameters.

    Parameters

      - min – an array of minimum values to subtract with.

      - max – an array of maximum values to divide with.

      - out_type – the output data type to cast the normalization result to.

  `invert`(sample)

    Inverts the normalization.

class `thelper.transforms.operations.` `NormalizeZeroMeanUnitVar`(mean, std, out_type=<class 'numpy.float32'>)

  Bases: `object`

  Normalizes a given image using a set of mean and standard deviation parameters.

  The samples will be transformed such that `s = (s - mean) / std`.

  This can be used for whitening; see https://en.wikipedia.org/wiki/Whitening_transformation for more information. Note that this operation is also not restricted to images.

  Variables

    - mean – an array of mean values to subtract from data samples.

    - std – an array of standard deviation values to divide with.

    - out_type – the output data type to cast the normalization result to.

  `__call__`(sample)

    Normalizes a given sample.

    Parameters

      - sample – the sample to normalize. If given as a PIL image, it

      - will be converted to a numpy array first.

    Returns

      The warped sample, in a numpy array of type `self.out_type`.

  `__init__`(mean, std, out_type=<class 'numpy.float32'>)

    Validates and initializes normalization parameters.

    Parameters

      - mean – an array of mean values to subtract from data samples.

      - std – an array of standard deviation values to divide with.

      - out_type – the output data type to cast the normalization result to.

  `invert`(sample)

    Inverts the normalization.

class `thelper.transforms.operations.` `RandomResizedCrop`(output_size, input_size=(0.08, 1.0), ratio=(0.75, 1.33), probability=1.0, random_attempts=10, min_roi_iou=1.0, flags=1)

  Bases: `object`

  Returns a resized crop of a randomly selected image region.

  This operation is stochastic, and thus cannot be inverted. Each time the operation is called, a random check will determine whether a transformation is applied or not. The code relies on OpenCV, meaning the interpolation arguments must be compatible with `cv2.resize`.

  Variables

    - output_size – size of the output crop, provided as a single element (`edge_size`) or as a two-element tuple or list (`[width, height]`). If integer values are used, the size is assumed to be absolute. If floating point values are used (i.e. in [0,1]), the output size is assumed to be relative to the original image size, and will be determined at execution time for each sample. If set to `None`, the crop will not be resized.

    - input_size – range of the input region sizes, provided as a pair of elements (`[min_edge_size, max_edge_size]`) or as a pair of tuples or lists (`[[min_width, min_height], [max_width, max_height]]`). If the pair-of-pairs format is used, the `ratio` argument cannot be used. If integer values are used, the ranges are assumed to be absolute. If floating point values are used (i.e. in [0,1]), the ranges are assumed to be relative to the original image size, and will be determined at execution time for each sample.

    - ratio – range of minimum/maximum input region aspect ratios to use. This argument cannot be used if the pair-of-pairs format is used for the `input_size` argument.

    - probability – the probability that the transformation will be applied when called; if not applied, the returned image will be the original.

    - random_attempts – the number of random sampling attempts to try before reverting to center or most-probably-valid crop generation.

    - min_roi_iou – minimum roi intersection over union (IoU) required for accepting a tile (in [0,1]).

    - flags – interpolation flag forwarded to `cv2.resize`.

  `__call__`(image, roi=None, mask=None, bboxes=None)

    Extracts and returns a random (resized) crop from the provided image.

    Parameters

      - image – the image to generate the crop from. If given as a 2-element list, it is assumed to contain both the image and the roi (passed through a composer).

      - roi – the roi to check tile intersections with (may be `None`).

      - mask – a mask to crop simultaneously with the input image (may be `None`).

      - bboxes – a list or array of bounding boxes to crop with the input image (may be `None`).

    Returns

      The randomly selected and resized crop. If mask and/or bboxes is given, the output will be a dictionary containing the results under the `image`, `mask`, and `bboxes` keys.

  `__init__`(output_size, input_size=(0.08, 1.0), ratio=(0.75, 1.33), probability=1.0, random_attempts=10, min_roi_iou=1.0, flags=1)

    Validates and initializes center crop parameters.

    Parameters

      - output_size – size of the output crop, provided as a single element (`edge_size`) or as a two-element tuple or list (`[width, height]`). If integer values are used, the size is assumed to be absolute. If floating point values are used (i.e. in [0,1]), the output size is assumed to be relative to the original image size, and will be determined at execution time for each sample. If set to `None`, the crop will not be resized.

      - input_size – range of the input region sizes, provided as a pair of elements (`[min_edge_size, max_edge_size]`) or as a pair of tuples or lists (`[[min_width, min_height], [max_width, max_height]]`). If the pair-of-pairs format is used, the `ratio` argument cannot be used. If integer values are used, the ranges are assumed to be absolute. If floating point values are used (i.e. in [0,1]), the ranges are assumed to be relative to the original image size, and will be determined at execution time for each sample.

      - ratio – range of minimum/maximum input region aspect ratios to use. This argument cannot be used if the pair-of-pairs format is used for the `input_size` argument.

      - probability – the probability that the transformation will be applied when called; if not applied, the returned image will be the original.

      - random_attempts – the number of random sampling attempts to try before reverting to center or most-probably-valid crop generation.

      - min_roi_iou – minimum roi intersection over union (IoU) required for producing a tile.

      - flags – interpolation flag forwarded to `cv2.resize`.

  `invert`(image)

    Specifies that this operation cannot be inverted, as data loss is incurred during image transformation.

  `set_seed`(seed)

    Sets the internal seed to use for stochastic ops.

class `thelper.transforms.operations.` `RandomShift`(min, max, probability=1.0, flags=None, border_mode=None, border_val=None)

  Bases: `object`

  Randomly translates an image in a provided range via OpenCV and numpy.

  This operation is stochastic, and thus cannot be inverted. Each time the operation is called, a random check will determine whether a transformation is applied or not. The code relies on OpenCV, meaning the border arguments must be compatible with `cv2.warpAffine`.

  Variables

    - min – the minimum pixel shift that can be applied stochastically.

    - max – the maximum pixel shift that can be applied stochastically.

    - probability – the probability that the transformation will be applied when called.

    - flags – extra warp flags forwarded to `cv2.warpAffine`.

    - border_mode – border extrapolation mode forwarded to `cv2.warpAffine`.

    - border_val – border constant extrapolation value forwarded to `cv2.warpAffine`.

  `__call__`(sample)

    Translates a given image using a predetermined min/max range.

    Parameters

      sample – the image to translate; should be a 2d or 3d numpy array.

    Returns

      The translated image.

  `__init__`(min, max, probability=1.0, flags=None, border_mode=None, border_val=None)

    Validates and initializes shift parameters.

    Parameters

      - min – the minimum pixel shift that can be applied stochastically.

      - max – the maximum pixel shift that can be applied stochastically.

      - probability – the probability that the transformation will be applied when called.

      - flags – extra warp flags forwarded to `cv2.warpAffine`.

      - border_mode – border extrapolation mode forwarded to `cv2.warpAffine`.

      - border_val – border constant extrapolation value forwarded to `cv2.warpAffine`.

  `invert`(sample)

    Specifies that this operation cannot be inverted, as it is stochastic, and data loss occurs during transformation.

  `set_seed`(seed)

    Sets the internal seed to use for stochastic ops.

class `thelper.transforms.operations.` `Resize`(dsize, fx=0, fy=0, interp=1, buffer=False)

  Bases: `object`

  Resizes a given image using OpenCV and numpy.

  This operation is deterministic. The code relies on OpenCV, meaning the interpolation arguments must be compatible with `cv2.resize`.

  Variables

    - interp – interpolation type to use (forwarded to `cv2.resize`)

    - buffer – specifies whether a destination buffer should be used to avoid allocations

    - dsize – target image size (tuple of width, height).

    - dst – buffer used to avoid reallocations if `self.buffer == True`

    - fx – argument forwarded to `cv2.resize`.

    - fy – argument forwarded to `cv2.resize`.

  `__call__`(sample)

    Returns a resized copy of the provided image.

    Parameters

      sample – the image to resize; should be a 2d or 3d numpy array.

    Returns

      The resized image. May be allocated on the spot, or be a pointer to a local buffer.

  `__init__`(dsize, fx=0, fy=0, interp=1, buffer=False)

    Validates and initializes resize parameters.

    Parameters

      - dsize – size of the target image, forwarded to `cv2.resize`.

      - fx – x-scaling factor, forwarded to `cv2.resize`.

      - fy – y-scaling factor, forwarded to `cv2.resize`.

      - interp – resize interpolation type, forwarded to `cv2.resize`.

      - buffer – specifies whether a destination buffer should be used to avoid allocations

  `invert`(sample)

    Specifies that this operation cannot be inverted, as data loss is incurred during image transformation.

class `thelper.transforms.operations.` `Tile`(tile_size, tile_overlap=0.0, min_mask_iou=1.0, offset_overlap=False, bordertype=0, borderval=0)

  Bases: `object`

  Returns a list of tiles cut out from a given image.

  This operation can perform tiling given an optional mask with a target intersection over union (IoU) score, and with an optional overlap between tiles. The tiling is deterministic and can thus be inverted, but only if a mask is not used, as some image regions may be lost otherwise.

  If a mask is used, the first tile position is tested exhaustively by iterating over all input coordinates starting from the top-left corner of the image. Otherwise, the first tile position is set as (0,0). Then, all other tiles are found by offsetting frm these coordinates, and testing for IoU with the mask (if needed).

  Variables

    - tile_size – size of the output tiles, provided as a single element (`edge_size`) or as a two-element tuple or list (`[width, height]`). If integer values are used, the size is assumed to be absolute. If floating point values are used (i.e. in [0,1]), the output size is assumed to be relative to the original image size, and will be determined at execution time for each image.

    - tile_overlap – overlap allowed between two neighboring tiles; should be a ratio in [0,1].

    - min_mask_iou – minimum mask intersection over union (IoU) required for accepting a tile (in [0,1]).

    - offset_overlap – specifies whether the overlap tiling should be offset outside the image or not.

    - bordertype – border copy type to use when the image is too small for the required crop size. See `cv2.copyMakeBorder` for more information.

    - borderval – border value to use when the image is too small for the required crop size. See `cv2.copyMakeBorder` for more information.

  `__call__`(image, mask=None)

    Extracts and returns a list of tiles cut out from the given image.

    Parameters

      - image – the image to cut into tiles. If given as a 2-element list, it is assumed to contain both the image and the mask (passed through a composer).

      - mask – the mask to check tile intersections with (may be `None`).

    Returns

      A list of tiles (numpy-compatible images).

  `__init__`(tile_size, tile_overlap=0.0, min_mask_iou=1.0, offset_overlap=False, bordertype=0, borderval=0)

    Validates and initializes tiling parameters.

    Parameters

      - tile_size – size of the output tiles, provided as a single element (`edge_size`) or as a two-element tuple or list (`[width, height]`). If integer values are used, the size is assumed to be absolute. If floating point values are used (i.e. in [0,1]), the output size is assumed to be relative to the original image size, and will be determined at execution time for each image.

      - tile_overlap – overlap ratio between two consecutive (neighboring) tiles; should be in [0,1].

      - min_mask_iou – minimum mask intersection over union (IoU) required for producing a tile.

      - offset_overlap – specifies whether the overlap tiling should be offset outside the image or not.

      - bordertype – border copy type to use when the image is too small for the required crop size. See `cv2.copyMakeBorder` for more information.

      - borderval – border value to use when the image is too small for the required crop size. See `cv2.copyMakeBorder` for more information.

  `count_tiles`(image, mask=None)

    Returns the number of tiles that would be cut out from the given image.

    Parameters

      - image – the image to cut into tiles. If given as a 2-element list, it is assumed to contain both the image and the mask (passed through a composer).

      - mask – the mask to check tile intersections with (may be `None`).

    Returns

      The number of tiles that would be cut with `thelper.transforms.operations.Tile.__call__()`.

  `invert`(image, mask=None)

    Returns the reconstituted image from a list of tiles, or throws if a mask was used.

class `thelper.transforms.operations.` `ToColor`

  Bases: `object`

  Converts a single-channel image to color (RGB).

  This operation is deterministic and reversible. It CANNOT be applied to images with more than one channel (HxWx1). The byte ordering (BGR or RGB) does not matter.

  `__call__`(sample)

    Call self as a function.

  `__init__`()

    Does nothing, there’s no attribute to store for this operation.

  `invert`(sample)

    Inverts the operation by calling the ‘ToGray’ operation.

    Note that this operation is probably lossy due to OpenCV’s grayscale conversion code which uses “0.21 R + 0.72 G + 0.07 B” to compute the luminosity of a pixel.

class `thelper.transforms.operations.` `ToGray`

  Bases: `object`

  Converts a multi-channel image to grayscale.

  This operation is deterministic, but not reversible. It can be applied to images with more than three channels (RGB) — in that case, it will compute their per-pixel mean value. Note that in any case, the last dimension (that corresponds to the channels) will remain and be of size 1.

  `__call__`(sample)

    Call self as a function.

  `__init__`()

    Does nothing, there’s no attribute to store for this operation.

  `invert`(sample)

    Specifies that this operation cannot be inverted, as data loss occurs during transformation.

class `thelper.transforms.operations.` `ToNumpy`(reorder_bgr=False)

  Bases: `object`

  Converts and returns an image in numpy format from a `torch.Tensor` or `PIL.Image` format.

  This operation is deterministic. The returns image will always be encoded as HxWxC, where if the input has three channels, the ordering might be optionally changed.

  Variables

    reorder_bgr – specifies whether the channels should be reordered in OpenCV format.

  `__call__`(sample)

    Converts and returns an image in numpy format.

    Parameters

      sample – the image to convert; should be a tensor, numpy array, or PIL image.

    Returns

      The numpy-converted image.

  `__init__`(reorder_bgr=False)

    Initializes transformation parameters.

  `invert`(sample)

    Specifies that this operation cannot be inverted, as the original data type is unknown.

class `thelper.transforms.operations.` `Transpose`(axes)

  Bases: `object`

  Transposes an image via numpy.

  This operation is deterministic.

  Variables

    - axes – the axes on which to apply the transpose; forwarded to `numpy.transpose`.

    - axes_inv – used to invert the tranpose; also forwarded to `numpy.transpose`.

  `__call__`(sample)

    Transposes a given image.

    Parameters

      sample – the image to transpose; should be a numpy array.

    Returns

      The transposed image.

  `__init__`(axes)

    Validates and initializes tranpose parameters.

    Parameters

      axes – the axes on which to apply the transpose; forwarded to `numpy.transpose`.

  `invert`(sample)

    Invert-transposes a given image.

    Parameters

      sample – the image to invert-transpose; should be a numpy array.

    Returns

      The invert-transposed image.

class `thelper.transforms.operations.` `Unsqueeze`(axis)

  Bases: `object`

  Expands a dimension in the input array via numpy/PyTorch.

  This operation is deterministic.

  Variables

    axis – the axis on which to apply the expansion.

  `__call__`(sample)

    Expands a dimension in the input array via numpy/PyTorch.

    Parameters

      sample – the array to expand.

    Returns

      The array with an extra dimension.

  `__init__`(axis)

    Validates and initializes tranpose parameters.

    Parameters

      axis – the axis on which to apply the expansion.

  `invert`(sample)

    Squeezes a dimension in the input array via numpy/PyTorch.

    Parameters

      sample – the array to squeeze.

    Returns

      The array with one less dimension.

## thelper.transforms.utils module

Transformations utilities module.

This module contains utility functions used to instantiate transformation/augmentation ops.

`thelper.transforms.utils.` `load_augments`(config)

  Loads a data augmentation pipeline.

  An augmentation pipeline is essentially a specialized transformation pipeline that can be appended or prefixed to the base transforms defined for all samples. Augmentations are typically used to diversify the samples within the training set in order to help model generalization. They can also be applied to validation and test samples in order to get multiple responses for the same input so that they can be averaged/concatenated into a single output.

  Usage examples inside a session configuration file:

      # ...
      # the 'loaders' field can contain several augmentation pipelines
      # (see 'thelper.data.utils.create_loaders' for more information on these pipelines)
      "loaders": {
          # ...
          # the 'train_augments' operations are applied to training samples only
          "train_augments": {
              # specifies whether to apply the augmentations before or after the base transforms
              "append": false,
              "transforms": [
                  {
                      # here, we use a single stage, which is actually an augmentor sub-pipeline
                      # that is purely probabilistic (i.e. it does not increase input sample count)
                      "operation": "Augmentor.Pipeline",
                      "params": {
                          # the augmentor pipeline defines two operations: rotations and flips
                          "rotate_random_90": {"probability": 0.75},
                          "flip_random": {"probability": 0.75}
                      }
                  }
              ]
          },
          # ...
      }
      # ...

  Parameters

    config – the configuration dictionary defining the meta parameters as well as the list of transformation operations of the augmentation pipeline.

  Returns

    A tuple that consists of a pipeline compatible with the `torchvision.transforms` interfaces, and a bool specifying whether this pipeline should be appended or prefixed to the base transforms.

  See also

  `thelper.transforms.wrappers.AugmentorWrapper`
  `thelper.transforms.utils.load_transforms()`
  `thelper.data.utils.create_loaders()`

`thelper.transforms.utils.` `load_transforms`(stages, avoid_transform_wrapper=False)

  Loads a transformation pipeline from a list of stages.

  Each entry in the provided list will be considered a stage in the pipeline. The ordering of the stages is important, as some transformations might not be compatible if taken out of order. The entries must each be dictionaries that define an operation, its parameters, and some meta-parameters (detailed below).

  The `operation` field of each stage will be used to dynamically import a specific type of operation to apply. The `params` field of each stage will then be used to pass parameters to the constructor of this operation.

  If an operation is identified as `"Augmentor.Pipeline"` or `"albumentations.Compose"`, it will be specially handled. In both case, the `params` field becomes mandatory in the stage dictionary, and it must specify the Augmentor or albumentations pipeline operation names and parameters (as a dictionary). Two additional optional config fields can then be set for Augmentor pipelines: `input_tensor` (bool) which specifies whether the previous stage provides a `torch.Tensor` to the pipeline (default=False); and `output_tensor` (bool) which specifies whether the output of the pipeline should be converted into a tensor (default=False). For albumentations pipelines, two additional fields are also available, namely `bbox_params` (dict) and `keypoint_params` (dict). For more information on these, refer to the documentation of `albumentations.core.composition.Compose`. Finally, when unpacking dictionaries for albumentations pipelines, the keys associated to bounding boxes/masks/keypoints that must be forwarded to the composer can be specified via the `bboxes_key`, `mask_key`, and `keypoints_key` fields.

  All operations can also specify which sample components they should be applied to via the `target_key` field. This field can contain a single key (typically a string), or a list of keys. The operation will be applied at runtime to all values which are found in the samples with one of those keys. If no key is provided for an operation, it will be applied to all array-like components of the sample. Finally, all operations can specify a `linked_fate` field (bool) to specify whether the samples provided in lists should all have the same fate or not (default=True).

  Usage examples inside a session configuration file:

      # ...
      # the 'loaders' field may contain several transformation pipelines
      # (see 'thelper.data.utils.create_loaders' for more information on these pipelines)
      "loaders": {
          # ...
          # the 'base_transforms' operations are applied to all loaded samples
          "base_transforms": [
              {
                  "operation": "...",
                  "params": {
                      ...
                  },
                  "target_key": [ ... ],
                  "linked_fate": ...
              },
              {
                  "operation": "...",
                  "params": {
                      ...
                  },
                  "target_key": [ ... ],
                  "linked_fate": ...
              },
              ...
          ],
      # ...

  Parameters

    stages – a list defining a series of transformations to apply as a single pipeline.

  Returns

    A transformation pipeline object compatible with the `torchvision.transforms` interface.

  See also

  `thelper.transforms.wrappers.AlbumentationsWrapper`
  `thelper.transforms.wrappers.AugmentorWrapper`
  `thelper.transforms.wrappers.TransformWrapper`
  `thelper.transforms.utils.load_augments()`
  `thelper.data.utils.create_loaders()`

## thelper.transforms.wrappers module

Transformations wrappers module.

The wrapper classes herein are used to either support inline operations on odd sample types (e.g. lists of images) or for external libraries (e.g. Augmentor).

class `thelper.transforms.wrappers.` `AlbumentationsWrapper`(transforms, to_tensor=None, bbox_params=None, add_targets=None, image_key='image', bboxes_key='bboxes', mask_key='mask', keypoints_key='keypoints', probability=1.0, cvt_kpts_to_bboxes=False, linked_fate=False)

  Bases: `object`

  Albumentations pipeline wrapper that allows dictionary unpacking.

  See https://github.com/albu/albumentations for more information.

  Variables

    - pipeline – the augmentor pipeline instance to apply to images.

    - image_key – the key to fetch images from (when dictionaries are passed in).

    - bboxes_key – the key to fetch bounding boxes from (when dictionaries are passed in).

    - mask_key – the key to fetch masks from (when dictionaries are passed in).

    - keypoints_key – the key to fetch keypoints from (when dictionaries are passed in).

    - cvt_kpts_to_bboxes – specifies whether keypoints should be converted to bboxes for compatbility.

    - linked_fate – specifies whether input list samples should all have the same fate or not.

  See also

  `thelper.transforms.utils.load_transforms()`
  `__call__`(sample, force_linked_fate=False, op_seed=None)

    Transforms a (dict) sample, a single image, or a list of images using the augmentor pipeline.

    Parameters

      - sample – the sample or image(s) to transform (can also contain embedded lists/tuples of images).

      - force_linked_fate – override flag for recursive use allowing forced linking of arrays.

      - op_seed – seed to set before calling the wrapped operation.

    Returns

      The transformed image(s), with the same list/tuple formatting as the input.

  `__init__`(transforms, to_tensor=None, bbox_params=None, add_targets=None, image_key='image', bboxes_key='bboxes', mask_key='mask', keypoints_key='keypoints', probability=1.0, cvt_kpts_to_bboxes=False, linked_fate=False)

    Receives and stores an augmentor pipeline for later use.

    The pipeline itself is instantiated in `thelper.transforms.utils.load_transforms()`.

  `set_epoch`(epoch=0)

    Sets the current epoch number in order to change the behavior of some suboperations.

  `set_seed`(seed)

    Sets the internal seed to use for stochastic ops.

class `thelper.transforms.wrappers.` `AugmentorWrapper`(pipeline, target_keys=None, linked_fate=True)

  Bases: `object`

  Augmentor pipeline wrapper that allows pickling and multi-threading.

  See https://github.com/mdbloice/Augmentor for more information. This wrapper was last updated to work with version 0.2.2 — more recent versions introduced yet unfixed (as of 2018/08) issues on some platforms.

  All original transforms are supported here. This wrapper also fixes the list output bug for single-image samples when using operations individually.

  Variables

    - pipeline – the augmentor pipeline instance to apply to images.

    - target_keys – the sample keys to apply the pipeline to (when dictionaries are passed in).

    - linked_fate – specifies whether input list samples should all have the same fate or not.

  See also

  `thelper.transforms.utils.load_transforms()`
  `__call__`(sample, force_linked_fate=False, op_seed=None, in_cvts=None)

    Transforms a (dict) sample, a single image, or a list of images using the augmentor pipeline.

    Parameters

      - sample – the sample or image(s) to transform (can also contain embedded lists/tuples of images).

      - force_linked_fate – override flag for recursive use allowing forced linking of arrays.

      - op_seed – seed to set before calling the wrapped operation.

      - in_cvts – holds the input conversion flag array (for recursive usage).

    Returns

      The transformed image(s), with the same list/tuple formatting as the input.

  `__init__`(pipeline, target_keys=None, linked_fate=True)

    Receives and stores an augmentor pipeline for later use.

    The pipeline itself is instantiated in `thelper.transforms.utils.load_transforms()`.

  `set_epoch`(epoch=0)

    Sets the current epoch number in order to change the behavior of some suboperations.

  `set_seed`(seed)

    Sets the internal seed to use for stochastic ops.

class `thelper.transforms.wrappers.` `TransformWrapper`(operation, params=None, probability=1, convert_pil=False, target_keys=None, linked_fate=True)

  Bases: `object`

  Transform wrapper that allows operations on samples, lists, tuples, and single elements.

  Can be used to wrap the operations in `thelper.transforms` or in `torchvision.transforms` that only accept array-like objects as input. Will optionally force-convert content to PIL images.

  Can also be used to transform a list/tuple of images uniformly based on a shared dice roll, or to ensure that each image is transformed independently.

  Warning

  Stochastic transforms (e.g. `torchvision.transforms.RandomCrop`) will always treat each image in a list differently. If the same operations are to be applied to all images, you should consider using a series non-stochastic operations wrapped inside an instance of `torchvision.transforms.RandomApply`, or simply provide the probability of applying the transforms to this wrapper’s constructor.

  Variables

    - operation – the wrapped operation (callable object or class name string to import).

    - params – the parameters that are passed to the operation when init’d or called.

    - probability – the probability that the wrapped operation will be applied.

    - convert_pil – specifies whether images should be converted into PIL format or not.

    - target_keys – the sample keys to apply the transform to (when dictionaries are passed in).

    - linked_fate – specifies whether images given in a list/tuple should have the same fate or not.

  `__call__`(sample, force_linked_fate=False, op_seed=None, in_cvts=None)

    Transforms a (dict) sample, a single image, or a list of images using a wrapped operation.

    Parameters

      - sample – the sample or image(s) to transform (can also contain embedded lists/tuples of images).

      - force_linked_fate – override flag for recursive use allowing forced linking of arrays.

      - op_seed – seed to set before calling the wrapped operation.

      - in_cvts – holds the input conversion flag array (for recursive usage).

    Returns

      The transformed image(s), with the same list/tuple formatting as the input.

  `__init__`(operation, params=None, probability=1, convert_pil=False, target_keys=None, linked_fate=True)

    Receives and stores a torchvision transform operation for later use.

    If the operation is given as a string, it is assumed to be a class name and it will be imported. The parameters (if any) will then be given to the constructor of that class. Otherwise, the operation is assumed to be a callable object, and its parameters (if any) will be provided at call-time.

    Parameters

      - operation – the wrapped operation (callable object or class name string to import).

      - params – the parameters that are passed to the operation when init’d or called.

      - probability – the probability that the wrapped operation will be applied.

      - convert_pil – specifies whether images should be forced into PIL format or not.

      - target_keys – the sample keys to apply the pipeline to (when dictionaries are passed in).

      - linked_fate – specifies whether images given in a list/tuple should have the same fate or not.

  `set_epoch`(epoch=0)

    Sets the current epoch number in order to change the behavior of some suboperations.

  `set_seed`(seed)

    Sets the internal seed to use for stochastic ops.

### Navigation

- index
- modules |
- next |
- previous |