API

benzina.torch.dataloader

class benzina.torch.dataloader.DataLoader(dataset, shape, path=None, batch_size=1, shuffle=False, sampler=None, batch_sampler=None, collate_fn=<sphinx.ext.autodoc.importer._MockObject object>, drop_last=False, timeout=0, device=None, multibuffering=3, seed=None, bias_transform=None, norm_transform=None, warp_transform=None)

Loads images from a benzina.torch.dataset.Dataset. Encapsulates a sampler and data processing transformations.

Parameters:

• dataset (benzina.torch.dataset.Dataset) – dataset from which to load the data.
• shape (int or tuple of ints) – set the shape of the samples. Note that this does not imply a resize of the image but merely set the shape of the tensor in which the data will be copied.
• path (str, optional) – path to the archive from which samples will be decoded. If not specified, the dataloader will attempt to get it from dataset.
• batch_size (int, optional) – how many samples per batch to load. (default: 1)
• shuffle (bool, optional) – set to True to have the data reshuffled at every epoch. (default: False)
• sampler (torch.utils.data.Sampler, optional) – defines the strategy to draw samples from the dataset. If specified, shuffle must be False.
• batch_sampler (torch.utils.data.Sampler, optional) – like sampler, but returns a batch of indices at a time. Mutually exclusive with batch_size, shuffle, sampler, and drop_last.
• collate_fn (callable, optional) – merges a list of samples to form a mini-batch.
• drop_last (bool, optional) – set to True to drop the last incomplete batch, if the dataset size is not divisible by the batch size. If False and the size of dataset is not divisible by the batch size, then the last batch will be smaller. (default: False)
• timeout (numeric, optional) – if positive, the timeout value for collecting a batch. Should always be non-negative. (default: 0)
• device (torch.device, optional) – set the device to use. Note that only CUDA devices are supported for the moment.
• multibuffering (int, optional) – set the size of the multibuffering buffer. (default: 3)
• seed (int, optional) – set the seed for the random transformations.
• bias_transform (benzina.torch.operations.BiasTransform or float, optional) – set the bias transformation. Values to substract a pixel’s channels with. Note that this transformation is applied before norm_transform.
• norm_transform (benzina.torch.operations.NormTransform or float or iterable of float, optional) – set the normalization transformation. Values to multiply a pixel’s channels with. Note that this transformation is applied after bias_transform.
• warp_transform (benzina.torch.operations.WarpTransform or iterable of float, optional) – set the warp transformation or use as the arguments to initialize a WarpTransform.

benzina.torch.dataset

class benzina.torch.dataset.Dataset(archive: Union[str, benzina.utils.file.Track] = None, track: Union[str, benzina.utils.file.Track] = 'bzna_input')

Parameters:

• archive (str or Track) – path to the archive or a Track. If a Track, track will be ignored.
• track (str or Track, optional) – track label or a Track. If a Track, archive must not be specified. (default: "bzna_input")

class benzina.torch.dataset.ClassificationDataset(archive: Union[str, Tuple[Union[str, benzina.utils.file.Track], Union[str, benzina.utils.file.Track]]] = None, tracks: Tuple[Union[str, benzina.utils.file.Track], Union[str, benzina.utils.file.Track]] = ('bzna_input', 'bzna_target'), input_label: str = 'bzna_thumb')

Parameters:

• archive (str or pair of Track) – path to the archive or a pair of Track. If a pair of Track, tracks will be ignored.
• tracks (pair of str or Track, optional) – pair of input and target tracks labels or a pair of input and target Track. If a pair of Track, archive must not be specified. (default: ("bzna_input", "bzna_target"))
• input_label (str, optional) – label of the inputs to use in the input track. (default: "bzna_thumb")

class benzina.torch.dataset.ImageNet(root: Union[str, Tuple[Union[str, benzina.utils.file.Track], Union[str, benzina.utils.file.Track]]] = None, split: str = None, tracks: Tuple[Union[str, benzina.utils.file.Track], Union[str, benzina.utils.file.Track]] = ('bzna_input', 'bzna_target'), input_label: str = 'bzna_thumb')

Parameters:

• root (str or pair of Track) – root of the ImageNet dataset or path to the archive or a pair of Track. If a pair of Track, tracks will be ignored.
• split (None or str, optional) – The dataset split, supports test, train, val. If not specified, samples will be drawn from all splits.
• tracks (pair of str or Track, optional) – pair of input and target tracks labels or a pair of input and target Track. If a pair of Track, root must not be specified. (default: ("bzna_input", "bzna_target"))
• input_label (str, optional) – label of the inputs to use in the input track. (default: "bzna_thumb")

benzina.torch.operations

class benzina.torch.operations.WarpTransform

Interface class that represents a warp transformation as a combined rotation, scale, skew and translation 3 x 3 matrix. The transformation is called for each sample of a batch.

class benzina.torch.operations.NormTransform

Interface class that represents a normalization transformation. The transformation is called for each sample of a batch.

class benzina.torch.operations.BiasTransform

Interface class that represents a bias transformation. The transformation is called for each sample of a batch.

class benzina.torch.operations.ConstantWarpTransform(warp=(1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0))

Represents a constant warp transformation to be applied on each sample of a batch independently of its index.

Parameters:warp (iterable of numerics, optional) – a flatten, row-major 3 x 3 warp matrix (default: flatten identity matrix).

class benzina.torch.operations.ConstantNormTransform(norm=(1.0, 1.0, 1.0))

Represents a constant norm transformation to be applied on each sample of a batch independently of its index.

Parameters:norm (numeric or iterable of numerics, optional) – an iterable in RGB order containing the normalization constant of a sample’s RGB channels. Components will be multiplied to the respective channels of a sample (default: (1.0, 1.0, 1.0)).

class benzina.torch.operations.ConstantBiasTransform(bias=(0.0, 0.0, 0.0))

Represents a constant bias transformation to be applied on each sample of a batch independently of its index.

Parameters:bias (numeric or iterable of numerics, optional) – an iterable in RGB order containing the bias of a sample’s RGB channels. Components will be substracted to the respective channels of a sample (default: (0.0, 0.0, 0.0)).

class benzina.torch.operations.SimilarityTransform(scale=(1.0, 1.0), ratio=None, degrees=(-0.0, 0.0), translate=(0.0, 0.0), flip_h=0.0, flip_v=0.0, resize=False, keep_ratio=False, random_crop=False)

Similarity warp transformation of the image keeping center invariant.

A crop of random size, aspect ratio and location is made. This crop can then be flipped and/or rotated to finally be resized to output size.

Parameters:

• scale (Sequence or float or int, optional) – crop area scaling factor interval, e.g (a, b), then scale is randomly sampled from the range a <= scale <= b. If scale is a number instead of sequence, the range of scale will be (scale^-1, scale). (default: (+1.0, +1.0))
• ratio (Sequence or float or int, optional) – range of crop aspect ratio. If ratio is a number instead of sequence like (min, max), the range of aspect ratio will be (ratio^-1, ratio). Will keep original aspect ratio by default.
• degrees (Sequence or float or int, optional) – range of degrees to select from. If degrees is a number instead of sequence like (min, max), the range of degrees will be (-degrees, +degrees). (default: (-0.0, +0.0))
• translate (Sequence or float or int, optional) – sequence of maximum absolute fraction for horizontal and vertical translations. For example translate=(a, b), then horizontal shift is randomly sampled in the range -output_width * a < dx < output_width * a and vertical shift is randomly sampled in the range -output_height * b < dy < output_height * b. If translate is a number instead of sequence, translate will be (translate, translate). These translations are applied independently from random_crop. (default: (0.0, 0.0))
• flip_h (bool, optional) – probability of the image being flipped horizontally. (default: +0.0)
• flip_v (bool, optional) – probability of the image being flipped vertically. (default: +0.0)
• resize (bool, optional) – resize the cropped image to fit the output size. It is forced to True if scale or ratio are specified. (default: False)
• keep_ratio (bool, optional) – match the smaller edge to the corresponding output edge size, keeping the aspect ratio after resize. Has no effect if resize is False. (default: False)
• random_crop (bool, optional) – randomly crop the image instead of a center crop. (default: False)

class benzina.torch.operations.RandomResizedCrop(scale=(0.08, 1.0), ratio=(0.75, 1.3333333333333333))

Crop to random size, aspect ratio and location.

A crop of random size, aspect ratio and location is made. This crop is finally resized to output size.

This is popularly used to train the Inception networks.

Parameters:

• scale (Sequence or float or int, optional) – crop area scaling factor interval, e.g (a, b), then scale is randomly sampled from the range a <= scale <= b. If scale is a number instead of sequence, the range of scale will be (scale^-1, scale). (default: (+0.08, +1.0))
• ratio (Sequence or float or int, optional) – range of crop aspect ratio. If ratio is a number instead of sequence like (min, max), the range of aspect ratio will be (ratio^-1, ratio). Will keep original aspect ratio by default. (default: (3./4., 4./3.))

class benzina.torch.operations.CenterResizedCrop(scale=1.0, keep_ratio=True)

Crops at the center and resize.

A crop at the center is made then resized to the output size.

Parameters:

• scale (float or int, optional) – edges scaling factor. (default: +1.0)
• keep_ratio (bool, optional) – match the smaller edge to the corresponding output edge size, keeping the aspect ratio after resize. Has no effect if resize is False. (default: False)

benzina.torch.operations.compute_affine_matrix(in_shape, out_shape, crop=None, degrees=0.0, translate=(0.0, 0.0), flip_h=False, flip_v=False, resize=False, keep_ratio=False)

Similarity warp transformation of the image keeping center invariant.

Parameters:

• in_shape (Sequence) – the shape of the input image
• out_shape (Sequence) – the shape of the output image
• crop (Sequence, optional) – crop center location, width and height. The center location is relative to the center of the image. If resize is not True, crop is simply a translation in the in_shape space.
• degrees (float or int, optional) – degrees to rotate the crop. (default: (0.0))
• translate (Sequence, optional) – horizontal and vertical translations. (default: (0.0, 0.0))
• flip_h (bool, optional) – flip the image horizontally. (default: False)
• flip_v (bool, optional) – flip the image vertically. (default: False)
• resize (bool, optional) – resize the cropped image to fit the output’s size. (default: False)
• keep_ratio (bool, optional) – match the smaller edge to the corresponding output edge size, keeping the aspect ratio after resize. Has no effect if resize is False. (default: False)