imgaug.augmentables.bbs¶

Classes representing bounding boxes.

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.
coords: Get the top-left and bottom-right coordinates as one array.
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

`almost_equals`(self, other[, max_distance])	Compare this and another BB’s label and coordinates.
`clip_out_of_image`(self, image)	Clip off all parts of the BB box that are outside of the image.
`clip_out_of_image_`(self, image)	Clip off parts of the BB box that are outside of the image in-place.
`compute_out_of_image_area`(self, image)	Compute the area of the BB that is outside of the image plane.
`compute_out_of_image_fraction`(self, image)	Compute fraction of BB area outside of the image plane.
`contains`(self, other)	Estimate whether the bounding box contains a given point.
`coords_almost_equals`(self, other[, max_distance])	Estimate if this and another BB have almost identical coordinates.
`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_box_on_image`(self, image[, color, …])	Draw the rectangle of the bounding box on an image.
`draw_label_on_image`(self, image[, color, …])	Draw a box showing the BB’s label.
`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.
`extend_`(self[, all_sides, top, right, …])	Extend the size of the bounding box along its sides in-place.
`extract_from_image`(self, image[, pad, …])	Extract the image pixels within the bounding box.
`from_point_soup`(xy)	Convert a `(2P,) or (P,2) ndarray` to a BB instance.
`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.
`project_`(self, from_shape, to_shape)	Project the bounding box onto a differently shaped image in-place.
`shift`(self[, x, y, top, right, bottom, left])	Move this bounding box along the x/y-axis.
`shift_`(self[, x, y])	Move this bounding box along the x/y-axis in-place.
`to_keypoints`(self)	Convert the BB’s corners to keypoints (clockwise, from top left).
`to_polygon`(self)	Convert this bounding box to a polygon covering the same area.
`union`(self, other)	Compute the union BB between this BB and another BB.

almost_equals(self, other, max_distance=0.0001)[source]¶

Compare this and another BB’s label and coordinates.

This is the same as coords_almost_equals() but additionally compares the labels.

Added in 0.4.0.

Parameters:	other (imgaug.augmentables.bbs.BoundingBox or iterable) – The other object to compare against. Expected to be a `BoundingBox`. max_distance (number, optional) – See `coords_almost_equals()`.
Returns:	`True` if the coordinates are almost equal and additionally the labels are equal. Otherwise `False`.
Return type:	bool

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

clip_out_of_image_(self, image)[source]¶

Clip off parts of the BB box that are outside of the image in-place.

Added in 0.4.0.

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. The object may have been modified in-place.
Return type:	imgaug.augmentables.bbs.BoundingBox

compute_out_of_image_area(self, image)[source]¶

Compute the area of the BB that is outside of the image plane.

Added in 0.4.0.

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:	Total area of the bounding box that is outside of the image plane. Can be `0.0`.
Return type:	float

compute_out_of_image_fraction(self, image)[source]¶

Compute fraction of BB area outside of the image plane.

This estimates f = A_ooi / A, where A_ooi is the area of the bounding box that is outside of the image plane, while A is the total area of the bounding box.

Added in 0.4.0.

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:	Fraction of the bounding box area that is outside of the image plane. Returns `0.0` if the bounding box is fully inside of the image plane. If the bounding box has an area of zero, the result is `1.0` if its coordinates are outside of the image plane, otherwise `0.0`.
Return type:	float

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

coords¶

Get the top-left and bottom-right coordinates as one array.

Added in 0.4.0.

Returns:	A `(N, 2)` numpy array with `N=2` containing the top-left and bottom-right coordinates.
Return type:	ndarray

coords_almost_equals(self, other, max_distance=0.0001)[source]¶

Estimate if this and another BB have almost identical coordinates.

Added in 0.4.0.

Parameters:	other (imgaug.augmentables.bbs.BoundingBox or iterable) – The other bounding box with which to compare this one. If this is an `iterable`, it is assumed to represent the top-left and bottom-right coordinates of that bounding box, given as e.g. an `(2,2)` ndarray or an `(4,)` ndarray or as a similar list. max_distance (number, optional) – The maximum euclidean distance between a corner on one bounding box and the closest corner on the other bounding box. If the distance is exceeded for any such pair, the two BBs are not viewed as equal.
Returns:	Whether the two bounding boxes have almost identical corner coordinates.
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.

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

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_box_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 rectangle of the bounding box on an image.

This method does not draw the label.

Added in 0.4.0.

Parameters:	image ((H,W,C) ndarray) – The image onto which to draw the bounding box rectangle. 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)

draw_label_on_image(self, image, color=(0, 255, 0), color_text=None, color_bg=None, alpha=1.0, size=1, size_text=20, height=30, copy=True, raise_if_out_of_image=False)[source]¶

Draw a box showing the BB’s label.

The box is placed right above the BB’s rectangle.

Added in 0.4.0.

Parameters:	image ((H,W,C) ndarray) – The image onto which to draw the label. Currently expected to be `uint8`. color (None or iterable of int, optional) – The color to use, corresponding to the channel layout of the image. Usually RGB. Text and background colors will be derived from this. color_text (None or iterable of int, optional) – The text color to use. If `None`, derived from color_bg. color_bg (None or iterable of int, optional) – The background color of the label box. If `None`, derived from color. 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). size_text (int, optional) – Font size to use. height (int, optional) – Height of the label box in pixels. 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.
Returns:	Image with bounding box drawn on it.
Return type:	(H,W,C) ndarray(uint8)

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.

This will automatically also draw the label, unless it is None. To only draw the box rectangle use draw_box_on_image(). To draw the label even if it is None or to configure e.g. its color, use draw_label_on_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

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

Extend the size of the bounding box along its sides in-place.

Added in 0.4.0.

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. The object may have been modified in-place.
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

classmethod from_point_soup(xy)[source]¶

Convert a (2P,) or (P,2) ndarray to a BB instance.

This is the inverse of to_xyxy_array().

Added in 0.4.0.

Parameters:	xy ((2P,) ndarray or (P, 2) array or iterable of number or iterable of iterable of number) – Array containing `P` points in xy-form denoting a soup of points around which to place a bounding box. The array should usually be of dtype `float32`.
Returns:	Bounding box around the points.
Return type:	imgaug.augmentables.bbs.BoundingBox

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

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

Project the bounding box onto a differently shaped image in-place.

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).

Added in 0.4.0.

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. The object may have been modified in-place.
Return type:	imgaug.augmentables.bbs.BoundingBox

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

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

The origin (0, 0) is at the top left of the image.

Parameters:	x (number, optional) – Value to be added to all x-coordinates. Positive values shift towards the right images. y (number, optional) – Value to be added to all y-coordinates. Positive values shift towards the bottom images. top (None or int, optional) – Deprecated since 0.4.0. Amount of pixels by which to shift this object from the top (towards the bottom). right (None or int, optional) – Deprecated since 0.4.0. Amount of pixels by which to shift this object from the right (towards the left). bottom (None or int, optional) – Deprecated since 0.4.0. Amount of pixels by which to shift this object from the bottom (towards the top). left (None or int, optional) – Deprecated since 0.4.0. 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

shift_(self, x=0, y=0)[source]¶

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

The origin (0, 0) is at the top left of the image.

Added in 0.4.0.

Parameters:	x (number, optional) – Value to be added to all x-coordinates. Positive values shift towards the right images. y (number, optional) – Value to be added to all y-coordinates. Positive values shift towards the bottom images.
Returns:	Shifted bounding box. The object may have been modified in-place.
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

to_polygon(self)[source]¶

Convert this bounding box to a polygon covering the same area.

Added in 0.4.0.

Returns:	The bounding box converted to a polygon.
Return type:	imgaug.augmentables.polys.Polygon

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: imgaug.augmentables.base.IAugmentable

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 or ndarray) – The shape of the image on which the objects are placed. Either an image with shape `(H,W,[C])` or a `tuple` denoting such an image shape.

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. `items` Get the bounding boxes in this container. `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.
`clip_out_of_image_`(self)	Clip off in-place all parts from all BBs that are outside of the image.
`copy`(self[, bounding_boxes, shape])	Create a shallow copy of the `BoundingBoxesOnImage` instance.
`cut_out_of_image`(self)	Deprecated.
`deepcopy`(self[, bounding_boxes, shape])	Create a deep copy of the `BoundingBoxesOnImage` object.
`draw_on_image`(self, image[, color, alpha, …])	Draw all bounding boxes onto a given image.
`fill_from_xy_array_`(self, xy)	Modify the BB coordinates of this instance in-place.
`fill_from_xyxy_array_`(self, xyxy)	Modify the BB coordinates of this instance in-place.
`from_point_soups`(xy, shape)	Convert an `(N, 2P) or (N, P, 2) ndarray` to a BBsOI instance.
`from_xyxy_array`(xyxy, shape)	Convert an `(N, 4) or (N, 2, 2) ndarray` to a BBsOI instance.
`invert_to_keypoints_on_image_`(self, kpsoi)	Invert the output of `to_keypoints_on_image()` in-place.
`on`(self, image)	Project bounding boxes from one image (shape) to a another one.
`on_`(self, image)	Project BBs from one image (shape) to a another one in-place.
`remove_out_of_image`(self[, fully, partly])	Remove all BBs that are fully/partially outside of the image.
`remove_out_of_image_`(self[, fully, partly])	Remove in-place all BBs that are fully/partially outside of the image.
`remove_out_of_image_fraction`(self, fraction)	Remove all BBs with an out of image fraction of at least fraction.
`remove_out_of_image_fraction_`(self, fraction)	Remove in-place all BBs with an OOI fraction of at least fraction.
`shift`(self[, x, y, top, right, bottom, left])	Move all BBs along the x/y-axis.
`shift_`(self[, x, y])	Move all BBs along the x/y-axis in-place.
`to_keypoints_on_image`(self)	Convert the bounding boxes to one `KeypointsOnImage` instance.
`to_polygons_on_image`(self)	Convert the bounding boxes to one `PolygonsOnImage` instance.
`to_xy_array`(self)	Convert the `BoundingBoxesOnImage` object to an `(N,2) ndarray`.
`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

clip_out_of_image_(self)[source]¶

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

Added in 0.4.0.

Returns:	Bounding boxes, clipped to fall within the image dimensions. The object and its items may have been modified in-place.
Return type:	imgaug.augmentables.bbs.BoundingBoxesOnImage

copy(self, bounding_boxes=None, shape=None)[source]¶

Create a shallow copy of the BoundingBoxesOnImage instance.

Parameters:	bounding_boxes (None or list of imgaug.augmntables.bbs.BoundingBox, optional) – List of bounding boxes on the image. If `None`, the instance’s bounding boxes will be copied. shape (tuple of int, optional) – The shape of the image on which the bounding boxes are placed. If `None`, the instance’s shape will be copied.
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.

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

deepcopy(self, bounding_boxes=None, shape=None)[source]¶

Create a deep copy of the BoundingBoxesOnImage object.

Parameters:	bounding_boxes (None or list of imgaug.augmntables.bbs.BoundingBox, optional) – List of bounding boxes on the image. If `None`, the instance’s bounding boxes will be copied. shape (tuple of int, optional) – The shape of the image on which the bounding boxes are placed. If `None`, the instance’s shape will be copied.
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

fill_from_xy_array_(self, xy)[source]¶

Modify the BB coordinates of this instance in-place.

See fill_from_xyxy_array_().

Added in 0.4.0.

Parameters:	xy ((2B, 2) ndarray or iterable of iterable of number) – Coordinates of `B` bounding boxes on an image, given as a `(2B,2)` array of two corner xy-coordinates per bounding box. `B` must match the number of bounding boxes in this instance.
Returns:	This instance itself, with updated bounding box coordinates. Note that the instance was modified in-place.
Return type:	BoundingBoxesOnImage

fill_from_xyxy_array_(self, xyxy)[source]¶

Modify the BB coordinates of this instance in-place.

Note

This currently expects exactly one entry in xyxy per bounding in this instance. (I.e. two corner coordinates per instance.) Otherwise, an AssertionError will be raised.

Note

This method will automatically flip x-coordinates if x1>x2 for a bounding box. (Analogous for y-coordinates.)

Added in 0.4.0.

Parameters:	xyxy ((N, 4) ndarray or iterable of iterable of number) – Coordinates of `N` bounding boxes on an image, given as a `(N,4)` array of two corner xy-coordinates per bounding box. `N` must match the number of bounding boxes in this instance.
Returns:	This instance itself, with updated bounding box coordinates. Note that the instance was modified in-place.
Return type:	BoundingBoxesOnImage

classmethod from_point_soups(xy, shape)[source]¶

Convert an (N, 2P) or (N, P, 2) ndarray to a BBsOI instance.

Added in 0.4.0.

Parameters:	xy ((N, 2P) ndarray or (N, P, 2) array or iterable of iterable of number or iterable of iterable of iterable of number) – Array containing the corner coordinates of `N` bounding boxes. Each bounding box is represented by a soup of `P` points. If `(N, P)` then the second axis is expected to be in xy-form (e.g. `x1`, `y1`, `x2`, `y2`, …). The final bounding box coordinates will be derived using `min` and `max` operations on the xy-values. The array 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 point soups.
Return type:	imgaug.augmentables.bbs.BoundingBoxesOnImage

classmethod from_xyxy_array(xyxy, shape)[source]¶

Convert an (N, 4) or (N, 2, 2) ndarray to a BBsOI instance.

This is the inverse of to_xyxy_array().

Parameters:	xyxy ((N, 4) ndarray or (N, 2, 2) array) – Array containing the corner coordinates of `N` bounding boxes. Each bounding box is represented by its top-left and bottom-right coordinates. The array 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

invert_to_keypoints_on_image_(self, kpsoi)[source]¶

Invert the output of to_keypoints_on_image() in-place.

This function writes in-place into this BoundingBoxesOnImage instance.

Added in 0.4.0.

Parameters:	kpsoi (imgaug.augmentables.kps.KeypointsOnImages) – Keypoints to convert back to bounding boxes, i.e. the outputs of `to_keypoints_on_image()`.
Returns:	Bounding boxes container with updated coordinates. Note that the instance is also updated in-place.
Return type:	BoundingBoxesOnImage

items¶

Get the bounding boxes in this container.

Added in 0.4.0.

Returns:	Bounding boxes within this container.
Return type:	list of BoundingBox

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

on_(self, image)[source]¶

Project BBs from one image (shape) to a another one in-place.

Added in 0.4.0.

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. The object and its items may have been modified in-place.
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

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

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

Added in 0.4.0.

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. The object and its items may have been modified in-place.
Return type:	imgaug.augmentables.bbs.BoundingBoxesOnImage

remove_out_of_image_fraction(self, fraction)[source]¶

Remove all BBs with an out of image fraction of at least fraction.

Added in 0.4.0.

Parameters:	fraction (number) – Minimum out of image fraction that a bounding box has to have in order to be removed. A fraction of `1.0` removes only bounding boxes that are `100%` outside of the image. A fraction of `0.0` removes all bounding boxes.
Returns:	Reduced set of bounding boxes, with those that had an out of image fraction greater or equal the given one removed.
Return type:	imgaug.augmentables.bbs.BoundingBoxesOnImage

remove_out_of_image_fraction_(self, fraction)[source]¶

Remove in-place all BBs with an OOI fraction of at least fraction.

‘OOI’ is the abbreviation for ‘out of image’.

Added in 0.4.0.

Parameters:	fraction (number) – Minimum out of image fraction that a bounding box has to have in order to be removed. A fraction of `1.0` removes only bounding boxes that are `100%` outside of the image. A fraction of `0.0` removes all bounding boxes.
Returns:	Reduced set of bounding boxes, with those that had an out of image fraction greater or equal the given one removed. The object and its items may have been modified in-place.
Return type:	imgaug.augmentables.bbs.BoundingBoxesOnImage

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

Move all BBs along the x/y-axis.

The origin (0, 0) is at the top left of the image.

Parameters:	x (number, optional) – Value to be added to all x-coordinates. Positive values shift towards the right images. y (number, optional) – Value to be added to all y-coordinates. Positive values shift towards the bottom images. top (None or int, optional) – Deprecated since 0.4.0. Amount of pixels by which to shift all objects from the top (towards the bottom). right (None or int, optional) – Deprecated since 0.4.0. Amount of pixels by which to shift all objects from the right (towads the left). bottom (None or int, optional) – Deprecated since 0.4.0. Amount of pixels by which to shift all objects from the bottom (towards the top). left (None or int, optional) – Deprecated since 0.4.0. 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

shift_(self, x=0, y=0)[source]¶

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

The origin (0, 0) is at the top left of the image.

Added in 0.4.0.

Parameters:	x (number, optional) – Value to be added to all x-coordinates. Positive values shift towards the right images. y (number, optional) – Value to be added to all y-coordinates. Positive values shift towards the bottom images.
Returns:	Shifted bounding boxes. The object and its items may have been modified in-place.
Return type:	imgaug.augmentables.bbs.BoundingBoxesOnImage

to_keypoints_on_image(self)[source]¶

Convert the bounding boxes to one KeypointsOnImage instance.

Added in 0.4.0.

Returns:	A keypoints instance containing `N*4` coordinates for `N` bounding boxes. Order matches the order in `bounding_boxes`.
Return type:	imgaug.augmentables.kps.KeypointsOnImage

to_polygons_on_image(self)[source]¶

Convert the bounding boxes to one PolygonsOnImage instance.

Added in 0.4.0.

Returns:	A `PolygonsOnImage` containing polygons. Each polygon covers the same area as the corresponding bounding box.
Return type:	imgaug.augmentables.polys.PolygonsOnImage

to_xy_array(self)[source]¶

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

Added in 0.4.0.

Returns:	`(2*B,2) ndarray` of xy-coordinates, where `B` denotes the number of bounding boxes.
Return type:	ndarray

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

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

This is the inverse of 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