imgaug.augmentables.bbs¶

class imgaug.augmentables.bbs.BoundingBox(x1, y1, x2, y2, label=None)[source]¶

Bases: object

Class representing bounding boxes.

Each bounding box is parameterized by its top left and bottom right corners. Both are given as x and y-coordinates. The corners are intended to lie inside the bounding box area. As a result, a bounding box that lies completely inside the image but has maximum extensions would have coordinates (0.0, 0.0) and (W - epsilon, H - epsilon). Note that coordinates are saved internally as floats.

Parameters:

x1 (number) – X-coordinate of the top left of the bounding box.
y1 (number) – Y-coordinate of the top left of the bounding box.
x2 (number) – X-coordinate of the bottom right of the bounding box.
y2 (number) – Y-coordinate of the bottom right of the bounding box.
label (None or str, optional) – Label of the bounding box, e.g. a string representing the class.

Attributes:

area: Estimate the area of the bounding box.
center_x: Estimate the x-coordinate of the center point of the bounding box.
center_y: Estimate the y-coordinate of the center point of the bounding box.
height: Estimate the height of the bounding box.
width: Estimate the width of the bounding box.
x1_int: Get the x-coordinate of the top left corner as an integer.
x2_int: Get the x-coordinate of the bottom left corner as an integer.
y1_int: Get the y-coordinate of the top left corner as an integer.
y2_int: Get the y-coordinate of the bottom left corner as an integer.

Methods

`clip_out_of_image`(self, image)	Clip off all parts of the BB box that are outside of the image.
`contains`(self, other)	Estimate whether the bounding box contains a given point.
`copy`(self[, x1, y1, x2, y2, label])	Create a shallow copy of this BoundingBox instance.
`cut_out_of_image`(self, \args, \\*kwargs)	Deprecated.
`deepcopy`(self[, x1, y1, x2, y2, label])	Create a deep copy of the BoundingBox object.
`draw_on_image`(self, image[, color, alpha, …])	Draw the bounding box on an image.
`extend`(self[, all_sides, top, right, …])	Extend the size of the bounding box along its sides.
`extract_from_image`(self, image[, pad, …])	Extract the image pixels within the bounding box.
`intersection`(self, other[, default])	Compute the intersection BB between this BB and another BB.
`iou`(self, other)	Compute the IoU between this bounding box and another one.
`is_fully_within_image`(self, image)	Estimate whether the bounding box is fully inside the image area.
`is_out_of_image`(self, image[, fully, partly])	Estimate whether the BB is partially/fully outside of the image area.
`is_partly_within_image`(self, image)	Estimate whether the BB is at least partially inside the image area.
`project`(self, from_shape, to_shape)	Project the bounding box onto a differently shaped image.
`shift`(self[, top, right, bottom, left])	Move this bounding box along the x/y-axis.
`to_keypoints`(self)	Convert the BB’s corners to keypoints (clockwise, from top left).
`union`(self, other)	Compute the union BB between this BB and another BB.

area¶

Estimate the area of the bounding box.

Returns:	Area of the bounding box, i.e. `height * width`.
Return type:	number

center_x¶

Estimate the x-coordinate of the center point of the bounding box.

Returns:	X-coordinate of the center point of the bounding box.
Return type:	number

center_y¶

Estimate the y-coordinate of the center point of the bounding box.

Returns:	Y-coordinate of the center point of the bounding box.
Return type:	number

clip_out_of_image(self, image)[source]¶

Clip off all parts of the BB box that are outside of the image.

Parameters:	image ((H,W,…) ndarray or tuple of int) – Image dimensions to use for the clipping of the bounding box. If an `ndarray`, its shape will be used. If a `tuple`, it is assumed to represent the image shape and must contain at least two integers.
Returns:	Bounding box, clipped to fall within the image dimensions.
Return type:	imgaug.augmentables.bbs.BoundingBox

contains(self, other)[source]¶

Estimate whether the bounding box contains a given point.

Parameters:	other (tuple of number or imgaug.augmentables.kps.Keypoint) – Point to check for.
Returns:	`True` if the point is contained in the bounding box, `False` otherwise.
Return type:	bool

copy(self, x1=None, y1=None, x2=None, y2=None, label=None)[source]¶

Create a shallow copy of this BoundingBox instance.

Parameters:	x1 (None or number) – If not `None`, then the `x1` coordinate of the copied object will be set to this value. y1 (None or number) – If not `None`, then the `y1` coordinate of the copied object will be set to this value. x2 (None or number) – If not `None`, then the `x2` coordinate of the copied object will be set to this value. y2 (None or number) – If not `None`, then the `y2` coordinate of the copied object will be set to this value. label (None or string) – If not `None`, then the `label` of the copied object will be set to this value.
Returns:	Shallow copy.
Return type:	imgaug.augmentables.bbs.BoundingBox

cut_out_of_image(self, *args, **kwargs)[source]¶: Deprecated. Use BoundingBox.clip_out_of_image() instead. clip_out_of_image() has the exactly same interface.

deepcopy(self, x1=None, y1=None, x2=None, y2=None, label=None)[source]¶

Create a deep copy of the BoundingBox object.

Parameters:	x1 (None or number) – If not `None`, then the `x1` coordinate of the copied object will be set to this value. y1 (None or number) – If not `None`, then the `y1` coordinate of the copied object will be set to this value. x2 (None or number) – If not `None`, then the `x2` coordinate of the copied object will be set to this value. y2 (None or number) – If not `None`, then the `y2` coordinate of the copied object will be set to this value. label (None or string) – If not `None`, then the `label` of the copied object will be set to this value.
Returns:	Deep copy.
Return type:	imgaug.augmentables.bbs.BoundingBox

draw_on_image(self, image, color=(0, 255, 0), alpha=1.0, size=1, copy=True, raise_if_out_of_image=False, thickness=None)[source]¶

Draw the bounding box on an image.

Parameters:	image ((H,W,C) ndarray) – The image onto which to draw the bounding box. Currently expected to be `uint8`. color (iterable of int, optional) – The color to use, corresponding to the channel layout of the image. Usually RGB. alpha (float, optional) – The transparency of the drawn bounding box, where `1.0` denotes no transparency and `0.0` is invisible. size (int, optional) – The thickness of the bounding box in pixels. If the value is larger than `1`, then additional pixels will be added around the bounding box (i.e. extension towards the outside). copy (bool, optional) – Whether to copy the input image or change it in-place. raise_if_out_of_image (bool, optional) – Whether to raise an error if the bounding box is fully outside of the image. If set to `False`, no error will be raised and only the parts inside the image will be drawn. thickness (None or int, optional) – Deprecated.
Returns:	Image with bounding box drawn on it.
Return type:	(H,W,C) ndarray(uint8)

extend(self, all_sides=0, top=0, right=0, bottom=0, left=0)[source]¶

Extend the size of the bounding box along its sides.

Parameters:	all_sides (number, optional) – Value by which to extend the bounding box size along all sides. top (number, optional) – Value by which to extend the bounding box size along its top side. right (number, optional) – Value by which to extend the bounding box size along its right side. bottom (number, optional) – Value by which to extend the bounding box size along its bottom side. left (number, optional) – Value by which to extend the bounding box size along its left side.
Returns:	Extended bounding box.
Return type:	imgaug.BoundingBox

extract_from_image(self, image, pad=True, pad_max=None, prevent_zero_size=True)[source]¶

Extract the image pixels within the bounding box.

This function will zero-pad the image if the bounding box is partially/fully outside of the image.

Parameters:	image ((H,W) ndarray or (H,W,C) ndarray) – The image from which to extract the pixels within the bounding box. pad (bool, optional) – Whether to zero-pad the image if the object is partially/fully outside of it. pad_max (None or int, optional) – The maximum number of pixels that may be zero-paded on any side, i.e. if this has value `N` the total maximum of added pixels is `4N`. This option exists to prevent extremely large images as a result of single points being moved very far away during augmentation. prevent_zero_size* (bool, optional) – Whether to prevent the height or width of the extracted image from becoming zero. If this is set to `True` and the height or width of the bounding box is below `1`, the height/width will be increased to `1`. This can be useful to prevent problems, e.g. with image saving or plotting. If it is set to `False`, images will be returned as `(H', W')` or `(H', W', 3)` with `H` or `W` potentially being 0.
Returns:	Pixels within the bounding box. Zero-padded if the bounding box is partially/fully outside of the image. If prevent_zero_size is activated, it is guarantueed that `H'>0` and `W'>0`, otherwise only `H'>=0` and `W'>=0`.
Return type:	(H’,W’) ndarray or (H’,W’,C) ndarray

height¶

Estimate the height of the bounding box.

Returns:	Height of the bounding box.
Return type:	number

intersection(self, other, default=None)[source]¶

Compute the intersection BB between this BB and another BB.

Note that in extreme cases, the intersection can be a single point. In that case the intersection bounding box exists and it will be returned, but it will have a height and width of zero.

Parameters:	other (imgaug.augmentables.bbs.BoundingBox) – Other bounding box with which to generate the intersection. default (any, optional) – Default value to return if there is no intersection.
Returns:	Intersection bounding box of the two bounding boxes if there is an intersection. If there is no intersection, the default value will be returned, which can by anything.
Return type:	imgaug.augmentables.bbs.BoundingBox or any

iou(self, other)[source]¶

Compute the IoU between this bounding box and another one.

IoU is the intersection over union, defined as:

``area(intersection(A, B)) / area(union(A, B))``
``= area(intersection(A, B))
    / (area(A) + area(B) - area(intersection(A, B)))``

Parameters:	other (imgaug.augmentables.bbs.BoundingBox) – Other bounding box with which to compare.
Returns:	IoU between the two bounding boxes.
Return type:	float

is_fully_within_image(self, image)[source]¶

Estimate whether the bounding box is fully inside the image area.

Parameters:	image ((H,W,…) ndarray or tuple of int) – Image dimensions to use. If an `ndarray`, its shape will be used. If a `tuple`, it is assumed to represent the image shape and must contain at least two integers.
Returns:	`True` if the bounding box is fully inside the image area. `False` otherwise.
Return type:	bool

is_out_of_image(self, image, fully=True, partly=False)[source]¶

Estimate whether the BB is partially/fully outside of the image area.

Parameters:	image ((H,W,…) ndarray or tuple of int) – Image dimensions to use. If an `ndarray`, its shape will be used. If a `tuple`, it is assumed to represent the image shape and must contain at least two integers. fully (bool, optional) – Whether to return `True` if the bounding box is fully outside of the image area. partly (bool, optional) – Whether to return `True` if the bounding box is at least partially outside fo the image area.
Returns:	`True` if the bounding box is partially/fully outside of the image area, depending on defined parameters. `False` otherwise.
Return type:	bool

is_partly_within_image(self, image)[source]¶

Estimate whether the BB is at least partially inside the image area.

Parameters:	image ((H,W,…) ndarray or tuple of int) – Image dimensions to use. If an `ndarray`, its shape will be used. If a `tuple`, it is assumed to represent the image shape and must contain at least two integers.
Returns:	`True` if the bounding box is at least partially inside the image area. `False` otherwise.
Return type:	bool

project(self, from_shape, to_shape)[source]¶

Project the bounding box onto a differently shaped image.

E.g. if the bounding box is on its original image at x1=(10 of 100 pixels) and y1=(20 of 100 pixels) and is projected onto a new image with size (width=200, height=200), its new position will be (x1=20, y1=40). (Analogous for x2/y2.)

This is intended for cases where the original image is resized. It cannot be used for more complex changes (e.g. padding, cropping).

Parameters:	from_shape (tuple of int or ndarray) – Shape of the original image. (Before resize.) to_shape (tuple of int or ndarray) – Shape of the new image. (After resize.)
Returns:	`BoundingBox` instance with new coordinates.
Return type:	imgaug.augmentables.bbs.BoundingBox

shift(self, top=None, right=None, bottom=None, left=None)[source]¶

Move this bounding box along the x/y-axis.

Parameters:	top (None or int, optional) – Amount of pixels by which to shift this object from the top (towards the bottom). right (None or int, optional) – Amount of pixels by which to shift this object from the right (towards the left). bottom (None or int, optional) – Amount of pixels by which to shift this object from the bottom (towards the top). left (None or int, optional) – Amount of pixels by which to shift this object from the left (towards the right).
Returns:	Shifted bounding box.
Return type:	imgaug.augmentables.bbs.BoundingBox

to_keypoints(self)[source]¶

Convert the BB’s corners to keypoints (clockwise, from top left).

Returns:	Corners of the bounding box as keypoints.
Return type:	list of imgaug.augmentables.kps.Keypoint

union(self, other)[source]¶

Compute the union BB between this BB and another BB.

This is equivalent to drawing a bounding box around all corner points of both bounding boxes.

Parameters:	other (imgaug.augmentables.bbs.BoundingBox) – Other bounding box with which to generate the union.
Returns:	Union bounding box of the two bounding boxes.
Return type:	imgaug.augmentables.bbs.BoundingBox

width¶

Estimate the width of the bounding box.

Returns:	Width of the bounding box.
Return type:	number

x1_int¶

Get the x-coordinate of the top left corner as an integer.

Returns:	X-coordinate of the top left corner, rounded to the closest integer.
Return type:	int

x2_int¶

Get the x-coordinate of the bottom left corner as an integer.

Returns:	X-coordinate of the bottom left corner, rounded to the closest integer.
Return type:	int

y1_int¶

Get the y-coordinate of the top left corner as an integer.

Returns:	Y-coordinate of the top left corner, rounded to the closest integer.
Return type:	int

y2_int¶

Get the y-coordinate of the bottom left corner as an integer.

Returns:	Y-coordinate of the bottom left corner, rounded to the closest integer.
Return type:	int

class imgaug.augmentables.bbs.BoundingBoxesOnImage(bounding_boxes, shape)[source]¶

Bases: object

Container for the list of all bounding boxes on a single image.

Parameters:	bounding_boxes (list of imgaug.augmentables.bbs.BoundingBox) – List of bounding boxes on the image. shape (tuple of int) – The shape of the image on which the bounding boxes are placed.

Examples

>>> import numpy as np
>>> from imgaug.augmentables.bbs import BoundingBox, BoundingBoxesOnImage
>>>
>>> image = np.zeros((100, 100))
>>> bbs = [
>>>     BoundingBox(x1=10, y1=20, x2=20, y2=30),
>>>     BoundingBox(x1=25, y1=50, x2=30, y2=70)
>>> ]
>>> bbs_oi = BoundingBoxesOnImage(bbs, shape=image.shape)

Attributes:	`empty` Determine whether this instance contains zero bounding boxes. `height` Get the height of the image on which the bounding boxes fall. `width` Get the width of the image on which the bounding boxes fall.

Methods

`clip_out_of_image`(self)	Clip off all parts from all BBs that are outside of the image.
`copy`(self)	Create a shallow copy of the `BoundingBoxesOnImage` instance.
`cut_out_of_image`(self)	Deprecated.
`deepcopy`(self)	Create a deep copy of the `BoundingBoxesOnImage` object.
`draw_on_image`(self, image[, color, alpha, …])	Draw all bounding boxes onto a given image.
`from_xyxy_array`(xyxy, shape)	Convert an `(N,4) ndarray` to a `BoundingBoxesOnImage` instance.
`on`(self, image)	Project bounding boxes from one image (shape) to a another one.
`remove_out_of_image`(self[, fully, partly])	Remove all BBs that are fully/partially outside of the image.
`shift`(self[, top, right, bottom, left])	Move all all BBs along the x/y-axis.
`to_xyxy_array`(self[, dtype])	Convert the `BoundingBoxesOnImage` object to an `(N,4) ndarray`.

clip_out_of_image(self)[source]¶

Clip off all parts from all BBs that are outside of the image.

Returns:	Bounding boxes, clipped to fall within the image dimensions.
Return type:	imgaug.augmentables.bbs.BoundingBoxesOnImage

copy(self)[source]¶

Create a shallow copy of the BoundingBoxesOnImage instance.

Returns:	Shallow copy.
Return type:	imgaug.augmentables.bbs.BoundingBoxesOnImage

cut_out_of_image(self)[source]¶: Deprecated. Use BoundingBoxesOnImage.clip_out_of_image() instead. clip_out_of_image() has the exactly same interface.

deepcopy(self)[source]¶

Create a deep copy of the BoundingBoxesOnImage object.

Returns:	Deep copy.
Return type:	imgaug.augmentables.bbs.BoundingBoxesOnImage

draw_on_image(self, image, color=(0, 255, 0), alpha=1.0, size=1, copy=True, raise_if_out_of_image=False, thickness=None)[source]¶

Draw all bounding boxes onto a given image.

Parameters:	image ((H,W,3) ndarray) – The image onto which to draw the bounding boxes. This image should usually have the same shape as set in `BoundingBoxesOnImage.shape`. color (int or list of int or tuple of int or (3,) ndarray, optional) – The RGB color of all bounding boxes. If a single `int` `C`, then that is equivalent to `(C,C,C)`. alpha (float, optional) – Alpha/transparency of the bounding box. size (int, optional) – Thickness in pixels. copy (bool, optional) – Whether to copy the image before drawing the bounding boxes. raise_if_out_of_image (bool, optional) – Whether to raise an exception if any bounding box is outside of the image. thickness (None or int, optional) – Deprecated.
Returns:	Image with drawn bounding boxes.
Return type:	(H,W,3) ndarray

empty¶

Determine whether this instance contains zero bounding boxes.

Returns:	True if this object contains zero bounding boxes.
Return type:	bool

classmethod from_xyxy_array(xyxy, shape)[source]¶

Convert an (N,4) ndarray to a BoundingBoxesOnImage instance.

This is the inverse of imgaug.BoundingBoxesOnImage.to_xyxy_array().

Parameters:	xyxy ((N,4) ndarray) – Array containing the corner coordinates (top-left, bottom-right) of `N` bounding boxes in the form `(x1, y1, x2, y2)`. Should usually be of dtype `float32`. shape (tuple of int) – Shape of the image on which the bounding boxes are placed. Should usually be `(H, W, C)` or `(H, W)`.
Returns:	Object containing a list of `BoundingBox` instances derived from the provided corner coordinates.
Return type:	imgaug.augmentables.bbs.BoundingBoxesOnImage

height¶

Get the height of the image on which the bounding boxes fall.

Returns:	Image height.
Return type:	int

on(self, image)[source]¶

Project bounding boxes from one image (shape) to a another one.

Parameters:	image (ndarray or tuple of int) – New image onto which the bounding boxes are to be projected. May also simply be that new image’s shape tuple.
Returns:	Object containing the same bounding boxes after projection to the new image shape.
Return type:	imgaug.augmentables.bbs.BoundingBoxesOnImage

remove_out_of_image(self, fully=True, partly=False)[source]¶

Remove all BBs that are fully/partially outside of the image.

Parameters:	fully (bool, optional) – Whether to remove bounding boxes that are fully outside of the image. partly (bool, optional) – Whether to remove bounding boxes that are partially outside of the image.
Returns:	Reduced set of bounding boxes, with those that were fully/partially outside of the image being removed.
Return type:	imgaug.augmentables.bbs.BoundingBoxesOnImage

shift(self, top=None, right=None, bottom=None, left=None)[source]¶

Move all all BBs along the x/y-axis.

Parameters:	top (None or int, optional) – Amount of pixels by which to shift all objects from the top (towards the bottom). right (None or int, optional) – Amount of pixels by which to shift all objects from the right (towads the left). bottom (None or int, optional) – Amount of pixels by which to shift all objects from the bottom (towards the top). left (None or int, optional) – Amount of pixels by which to shift all objects from the left (towards the right).
Returns:	Shifted bounding boxes.
Return type:	imgaug.augmentables.bbs.BoundingBoxesOnImage

to_xyxy_array(self, dtype=<class 'numpy.float32'>)[source]¶

Convert the BoundingBoxesOnImage object to an (N,4) ndarray.

This is the inverse of imgaug.BoundingBoxesOnImage.from_xyxy_array().

Parameters:	dtype (numpy.dtype, optional) – Desired output datatype of the ndarray.
Returns:	`(N,4) ndarray`, where `N` denotes the number of bounding boxes and `4` denotes the top-left and bottom-right bounding box corner coordinates in form `(x1, y1, x2, y2)`.
Return type:	ndarray

width¶

Get the width of the image on which the bounding boxes fall.

Returns:	Image width.
Return type:	int