# Transforms¶

## Image¶

### center_crop¶

chainercv.transforms.center_crop(img, size, return_param=False, copy=False)[source]

Center crop an image by size.

An image is cropped to size. The center of the output image and the center of the input image are same.

Parameters: img (ndarray) – An image array to be cropped. This is in CHW format. size (tuple) – The size of output image after cropping. This value is $$(height, width)$$. return_param (bool) – If True, this function returns information of slices. copy (bool) – If False, a view of img is returned. If return_param = False, returns an array out_img that is cropped from the input array. If return_param = True, returns a tuple whose elements are out_img, param. param is a dictionary of intermediate parameters whose contents are listed below with key, value-type and the description of the value. y_slice (slice): A slice used to crop the input image. The relation below holds together with x_slice. x_slice (slice): Similar to y_slice. out_img = img[:, y_slice, x_slice]  ndarray or (ndarray, dict)

### flip¶

chainercv.transforms.flip(img, y_flip=False, x_flip=False, copy=False)[source]

Flip an image in vertical or horizontal direction as specified.

Parameters: img (ndarray) – An array that gets flipped. This is in CHW format. y_flip (bool) – Flip in vertical direction. x_flip (bool) – Flip in horizontal direction. copy (bool) – If False, a view of img will be returned. Transformed img in CHW format.

### pca_lighting¶

chainercv.transforms.pca_lighting(img, sigma, eigen_value=None, eigen_vector=None)[source]

AlexNet style color augmentation

This method adds a noise vector drawn from a Gaussian. The direction of the Gaussian is same as that of the principal components of the dataset.

This method is used in training of AlexNet [1].

 [1] Alex Krizhevsky, Ilya Sutskever, Geoffrey E. Hinton. ImageNet Classification with Deep Convolutional Neural Networks. NIPS 2012.
Parameters: img (ndarray) – An image array to be augmented. This is in CHW and RGB format. sigma (float) – Standard deviation of the Gaussian. In the original paper, this value is 10% of the range of intensity (25.5 if the range is $$[0, 255]$$). eigen_value (ndarray) – An array of eigen values. The shape has to be $$(3,)$$. If it is not specified, the values computed from ImageNet are used. eigen_vector (ndarray) – An array of eigen vectors. The shape has to be $$(3, 3)$$. If it is not specified, the vectors computed from ImageNet are used. An image in CHW format.

### random_crop¶

chainercv.transforms.random_crop(img, size, return_param=False, copy=False)[source]

Crop array randomly into size.

The input image is cropped by a randomly selected region whose shape is size.

Parameters: img (ndarray) – An image array to be cropped. This is in CHW format. size (tuple) – The size of output image after cropping. This value is $$(height, width)$$. return_param (bool) – If True, this function returns information of slices. copy (bool) – If False, a view of img is returned. If return_param = False, returns an array out_img that is cropped from the input array. If return_param = True, returns a tuple whose elements are out_img, param. param is a dictionary of intermediate parameters whose contents are listed below with key, value-type and the description of the value. y_slice (slice): A slice used to crop the input image. The relation below holds together with x_slice. x_slice (slice): Similar to x_slice. out_img = img[:, y_slice, x_slice]  ndarray or (ndarray, dict)

### random_expand¶

chainercv.transforms.random_expand(img, max_ratio=4, fill=0, return_param=False)[source]

Expand an image randomly.

This method randomly place the input image on a larger canvas. The size of the canvas is $$(rH, rW)$$, where $$(H, W)$$ is the size of the input image and $$r$$ is a random ratio drawn from $$[1, max\_ratio]$$. The canvas is filled by a value fill except for the region where the original image is placed.

This data augmentation trick is used to create “zoom out” effect [2].

 [2] Wei Liu, Dragomir Anguelov, Dumitru Erhan, Christian Szegedy, Scott Reed, Cheng-Yang Fu, Alexander C. Berg. SSD: Single Shot MultiBox Detector. ECCV 2016.
Parameters: img (ndarray) – An image array to be augmented. This is in CHW format. max_ratio (float) – The maximum ratio of expansion. In the original paper, this value is 4. fill (float, tuple or ndarray) – The value of padded pixels. In the original paper, this value is the mean of ImageNet. If it is numpy.ndarray, its shape should be $$(C, 1, 1)$$, where $$C$$ is the number of channels of img. return_param (bool) – Returns random parameters. If return_param = False, returns an array out_img that is the result of expansion. If return_param = True, returns a tuple whose elements are out_img, param. param is a dictionary of intermediate parameters whose contents are listed below with key, value-type and the description of the value. ratio (float): The sampled value used to make the canvas. y_offset (int): The y coodinate of the top left corner of the image after placing on the canvas. x_offset (int): The x coordinate of the top left corner of the image after placing on the canvas. ndarray or (ndarray, dict)

### random_flip¶

chainercv.transforms.random_flip(img, y_random=False, x_random=False, return_param=False, copy=False)[source]

Randomly flip an image in vertical or horizontal direction.

Parameters: img (ndarray) – An array that gets flipped. This is in CHW format. y_random (bool) – Randomly flip in vertical direction. x_random (bool) – Randomly flip in horizontal direction. return_param (bool) – Returns information of flip. copy (bool) – If False, a view of img will be returned. If return_param = False, returns an array out_img that is the result of flipping. If return_param = True, returns a tuple whose elements are out_img, param. param is a dictionary of intermediate parameters whose contents are listed below with key, value-type and the description of the value. y_flip (bool): Whether the image was flipped in the vertical direction or not. x_flip (bool): Whether the image was flipped in the horizontal direction or not. ndarray or (ndarray, dict)

### random_rotate¶

chainercv.transforms.random_rotate(img, return_param=False)[source]

Randomly rotate images by 90, 180, 270 or 360 degrees.

Parameters: img (ndarray) – An arrays that get flipped. This is in CHW format. return_param (bool) – Returns information of rotation. If return_param = False, returns an array out_img that is the result of rotation. If return_param = True, returns a tuple whose elements are out_img, param. param is a dictionary of intermediate parameters whose contents are listed below with key, value-type and the description of the value. k (int): The integer that represents the number of times the image is rotated by 90 degrees. ndarray or (ndarray, dict)

### random_sized_crop¶

chainercv.transforms.random_sized_crop(img, scale_ratio_range=(0.08, 1), aspect_ratio_range=(0.75, 1.3333333333333333), return_param=False, copy=False)[source]

Crop an image to random size and aspect ratio.

The size $$(H_{crop}, W_{crop})$$ and the left top coordinate $$(y_{start}, x_{start})$$ of the crop are calculated as follows:

• $$H_{crop} = \lfloor{\sqrt{s \times H \times W \times a}}\rfloor$$
• $$W_{crop} = \lfloor{\sqrt{s \times H \times W \div a}}\rfloor$$
• $$y_{start} \sim Uniform\{0, H - H_{crop}\}$$
• $$x_{start} \sim Uniform\{0, W - W_{crop}\}$$
• $$s \sim Uniform(s_1, s_2)$$
• $$b \sim Uniform(a_1, a_2)$$ and $$a = b$$ or $$a = \frac{1}{b}$$ in 50/50 probability.

Here, $$s_1, s_2$$ are the two floats in scale_ratio_range and $$a_1, a_2$$ are the two floats in aspect_ratio_range. Also, $$H$$ and $$W$$ are the height and the width of the image. Note that $$s \approx \frac{H_{crop} \times W_{crop}}{H \times W}$$ and $$a \approx \frac{H_{crop}}{W_{crop}}$$. The approximations come from flooring floats to integers.

Note

When it fails to sample a valid scale and aspect ratio for ten times, it picks values in a non-uniform way. If this happens, the selected scale ratio can be smaller than scale_ratio_range[0].

Parameters: img (ndarray) – An image array. This is in CHW format. scale_ratio_range (tuple of two floats) – Determines the distribution from which a scale ratio is sampled. The default values are selected so that the area of the crop is 8~100% of the original image. This is the default setting used to train ResNets in Torch style. aspect_ratio_range (tuple of two floats) – Determines the distribution from which an aspect ratio is sampled. The default values are $$\frac{3}{4}$$ and $$\frac{4}{3}$$, which are also the default setting to train ResNets in Torch style. return_param (bool) – Returns parameters if True. If return_param = False, returns only the cropped image. If return_param = True, returns a tuple of cropped image and param. param is a dictionary of intermediate parameters whose contents are listed below with key, value-type and the description of the value. y_slice (slice): A slice used to crop the input image. The relation below holds together with x_slice. x_slice (slice): Similar to y_slice. out_img = img[:, y_slice, x_slice]  scale_ratio (float): $$s$$ in the description (see above). aspect_ratio (float): $$a$$ in the description. ndarray or (ndarray, dict)

### resize¶

chainercv.transforms.resize(img, size, interpolation=2)[source]

Resize image to match the given shape.

This method uses cv2 or PIL for the backend. If cv2 is installed, this function uses the implementation in cv2. This implementation is faster than the implementation in PIL. Under Anaconda environment, cv2 can be installed by the following command.

\$ conda install -c menpo opencv3=3.2.0

Parameters: img (ndarray) – An array to be transformed. This is in CHW format and the type should be numpy.float32. size (tuple) – This is a tuple of length 2. Its elements are ordered as (height, width). interpolation (int) – Determines sampling strategy. This is one of PIL.Image.NEAREST, PIL.Image.BILINEAR, PIL.Image.BICUBIC, PIL.Image.LANCZOS. Bilinear interpolation is the default strategy. A resize array in CHW format. ndarray

### resize_contain¶

chainercv.transforms.resize_contain(img, size, fill=0, interpolation=2, return_param=False)[source]

Resize the image to fit in the given area while keeping aspect ratio.

If both the height and the width in size are larger than the height and the width of the img, the img is placed on the center with an appropriate padding to match size.

Otherwise, the input image is scaled to fit in a canvas whose size is size while preserving aspect ratio.

Parameters: img (ndarray) – An array to be transformed. This is in CHW format. size (tuple of two ints) – A tuple of two elements: height, width. The size of the image after resizing. fill (float, tuple or ndarray) – The value of padded pixels. If it is numpy.ndarray, its shape should be $$(C, 1, 1)$$, where $$C$$ is the number of channels of img. interpolation (int) – Determines sampling strategy. This is one of PIL.Image.NEAREST, PIL.Image.BILINEAR, PIL.Image.BICUBIC, PIL.Image.LANCZOS. Bilinear interpolation is the default strategy. return_param (bool) – Returns information of resizing and offsetting. If return_param = False, returns an array out_img that is the result of resizing. If return_param = True, returns a tuple whose elements are out_img, param. param is a dictionary of intermediate parameters whose contents are listed below with key, value-type and the description of the value. y_offset (int): The y coodinate of the top left corner of the image after placing on the canvas. x_offset (int): The x coordinate of the top left corner of the image after placing on the canvas. scaled_size (tuple): The size to which the image is scaled to before placing it on a canvas. This is a tuple of two elements: height, width. ndarray or (ndarray, dict)

### rotate¶

chainercv.transforms.rotate(img, angle, expand=True)[source]

Rotate images by degrees.

Parameters: img (ndarray) – An arrays that get rotated. This is in CHW format. angle (float) – Counter clock-wise rotation angle (degree). expand (bool) – The output shaped is adapted or not. If True, the input image is contained complete in the output. returns an array out_img that is the result of rotation. ndarray

### scale¶

chainercv.transforms.scale(img, size, fit_short=True, interpolation=2)[source]

Rescales the input image to the given “size”.

When fit_short == True, the input image will be resized so that the shorter edge will be scaled to length size after resizing. For example, if the height of the image is larger than its width, image will be resized to (size * height / width, size).

Otherwise, the input image will be resized so that the longer edge will be scaled to length size after resizing.

Parameters: img (ndarray) – An image array to be scaled. This is in CHW format. size (int) – The length of the smaller edge. fit_short (bool) – Determines whether to match the length of the shorter edge or the longer edge to size. interpolation (int) – Determines sampling strategy. This is one of PIL.Image.NEAREST, PIL.Image.BILINEAR, PIL.Image.BICUBIC, PIL.Image.LANCZOS. Bilinear interpolation is the default strategy. A scaled image in CHW format. ndarray

### ten_crop¶

chainercv.transforms.ten_crop(img, size)[source]

Crop 10 regions from an array.

This method crops 10 regions. All regions will be in shape size. These regions consist of 1 center crop and 4 corner crops and horizontal flips of them.

The crops are ordered in this order.

• center crop
• top-left crop
• bottom-left crop
• top-right crop
• bottom-right crop
• center crop (flipped horizontally)
• top-left crop (flipped horizontally)
• bottom-left crop (flipped horizontally)
• top-right crop (flipped horizontally)
• bottom-right crop (flipped horizontally)
Parameters: img (ndarray) – An image array to be cropped. This is in CHW format. size (tuple) – The size of output images after cropping. This value is $$(height, width)$$. The cropped arrays. The shape of tensor is $$(10, C, H, W)$$.

## Bounding Box¶

### crop_bbox¶

chainercv.transforms.crop_bbox(bbox, y_slice=None, x_slice=None, allow_outside_center=True, return_param=False)[source]

Translate bounding boxes to fit within the cropped area of an image.

This method is mainly used together with image cropping. This method translates the coordinates of bounding boxes like translate_bbox(). In addition, this function truncates the bounding boxes to fit within the cropped area. If a bounding box does not overlap with the cropped area, this bounding box will be removed.

The bounding boxes are expected to be packed into a two dimensional tensor of shape $$(R, 4)$$, where $$R$$ is the number of bounding boxes in the image. The second axis represents attributes of the bounding box. They are $$(y_{min}, x_{min}, y_{max}, x_{max})$$, where the four attributes are coordinates of the top left and the bottom right vertices.

Parameters: bbox (ndarray) – Bounding boxes to be transformed. The shape is $$(R, 4)$$. $$R$$ is the number of bounding boxes. y_slice (slice) – The slice of y axis. x_slice (slice) – The slice of x axis. allow_outside_center (bool) – If this argument is False, bounding boxes whose centers are outside of the cropped area are removed. The default value is True. return_param (bool) – If True, this function returns indices of kept bounding boxes. If return_param = False, returns an array bbox. If return_param = True, returns a tuple whose elements are bbox, param. param is a dictionary of intermediate parameters whose contents are listed below with key, value-type and the description of the value. index (numpy.ndarray): An array holding indices of used bounding boxes. ndarray or (ndarray, dict)

### flip_bbox¶

chainercv.transforms.flip_bbox(bbox, size, y_flip=False, x_flip=False)[source]

Flip bounding boxes accordingly.

The bounding boxes are expected to be packed into a two dimensional tensor of shape $$(R, 4)$$, where $$R$$ is the number of bounding boxes in the image. The second axis represents attributes of the bounding box. They are $$(y_{min}, x_{min}, y_{max}, x_{max})$$, where the four attributes are coordinates of the top left and the bottom right vertices.

Parameters: bbox (ndarray) – An array whose shape is $$(R, 4)$$. $$R$$ is the number of bounding boxes. size (tuple) – A tuple of length 2. The height and the width of the image before resized. y_flip (bool) – Flip bounding box according to a vertical flip of an image. x_flip (bool) – Flip bounding box according to a horizontal flip of an image. Bounding boxes flipped according to the given flips. ndarray

### resize_bbox¶

chainercv.transforms.resize_bbox(bbox, in_size, out_size)[source]

Resize bounding boxes according to image resize.

The bounding boxes are expected to be packed into a two dimensional tensor of shape $$(R, 4)$$, where $$R$$ is the number of bounding boxes in the image. The second axis represents attributes of the bounding box. They are $$(y_{min}, x_{min}, y_{max}, x_{max})$$, where the four attributes are coordinates of the top left and the bottom right vertices.

Parameters: bbox (ndarray) – An array whose shape is $$(R, 4)$$. $$R$$ is the number of bounding boxes. in_size (tuple) – A tuple of length 2. The height and the width of the image before resized. out_size (tuple) – A tuple of length 2. The height and the width of the image after resized. Bounding boxes rescaled according to the given image shapes. ndarray

### rotate_bbox¶

chainercv.transforms.rotate_bbox(bbox, angle, size)[source]

Rotate bounding boxes by degrees.

Parameters: bbox (ndarray) – An array whose shape is $$(R, 4)$$. $$R$$ is the number of bounding boxes. angle (float) – Counter clock-wise rotation angle (degree). image is rotated by 90 degrees. size (tuple) – A tuple of length 2. The height and the width of the image. Bounding boxes rescaled according to the given k. ndarray

### translate_bbox¶

chainercv.transforms.translate_bbox(bbox, y_offset=0, x_offset=0)[source]

Translate bounding boxes.

This method is mainly used together with image transforms, such as padding and cropping, which translates the left top point of the image from coordinate $$(0, 0)$$ to coordinate $$(y, x) = (y_{offset}, x_{offset})$$.

The bounding boxes are expected to be packed into a two dimensional tensor of shape $$(R, 4)$$, where $$R$$ is the number of bounding boxes in the image. The second axis represents attributes of the bounding box. They are $$(y_{min}, x_{min}, y_{max}, x_{max})$$, where the four attributes are coordinates of the top left and the bottom right vertices.

Parameters: bbox (ndarray) – Bounding boxes to be transformed. The shape is $$(R, 4)$$. $$R$$ is the number of bounding boxes. y_offset (int or float) – The offset along y axis. x_offset (int or float) – The offset along x axis. Bounding boxes translated according to the given offsets. ndarray

## Point¶

### flip_point¶

chainercv.transforms.flip_point(point, size, y_flip=False, x_flip=False)[source]

Modify points according to image flips.

Parameters: point (ndarray) – Points in the image. The shape of this array is $$(P, 2)$$. $$P$$ is the number of points in the image. The last dimension is composed of $$y$$ and $$x$$ coordinates of the points. size (tuple) – A tuple of length 2. The height and the width of the image, which is associated with the points. y_flip (bool) – Modify points according to a vertical flip of an image. x_flip (bool) – Modify keypoipoints according to a horizontal flip of an image. Points modified according to image flips. ndarray

### resize_point¶

chainercv.transforms.resize_point(point, in_size, out_size)[source]

Adapt point coordinates to the rescaled image space.

Parameters: point (ndarray) – Points in the image. The shape of this array is $$(P, 2)$$. $$P$$ is the number of points in the image. The last dimension is composed of $$y$$ and $$x$$ coordinates of the points. in_size (tuple) – A tuple of length 2. The height and the width of the image before resized. out_size (tuple) – A tuple of length 2. The height and the width of the image after resized. Points rescaled according to the given image shapes. ndarray

### translate_point¶

chainercv.transforms.translate_point(point, y_offset=0, x_offset=0)[source]

Translate points.

This method is mainly used together with image transforms, such as padding and cropping, which translates the top left point of the image to the coordinate $$(y, x) = (y_{offset}, x_{offset})$$.

Parameters: point (ndarray) – Points in the image. The shape of this array is $$(P, 2)$$. $$P$$ is the number of points in the image. The last dimension is composed of $$y$$ and $$x$$ coordinates of the points. y_offset (int or float) – The offset along y axis. x_offset (int or float) – The offset along x axis. Points modified translation of an image. ndarray