imgaug.augmentables.polys

Classes dealing with polygons.

class imgaug.augmentables.polys.MultiPolygon(geoms)[source]

Bases: object

Class that represents several polygons.

Parameters:geoms (list of imgaug.augmentables.polys.Polygon) – List of the polygons.

Methods

from_shapely(geometry[, label]) Create a MultiPolygon from a shapely object.
static from_shapely(geometry, label=None)[source]

Create a MultiPolygon from a shapely object.

This also creates all necessary Polygon s contained in this MultiPolygon.

Parameters:
  • geometry (shapely.geometry.MultiPolygon or shapely.geometry.Polygon or shapely.geometry.collection.GeometryCollection) – The object to convert to a MultiPolygon.
  • label (None or str, optional) – A label assigned to all Polygons within the MultiPolygon.
Returns:

The derived MultiPolygon.

Return type:

imgaug.augmentables.polys.MultiPolygon

class imgaug.augmentables.polys.Polygon(exterior, label=None)[source]

Bases: object

Class representing polygons.

Each polygon is parameterized by its corner points, given as absolute x- and y-coordinates with sub-pixel accuracy.

Parameters:
  • exterior (list of imgaug.augmentables.kps.Keypoint or list of tuple of float or (N,2) ndarray) – List of points defining the polygon. May be either a list of Keypoint objects or a list of tuple s in xy-form or a numpy array of shape (N,2) for N points in xy-form. All coordinates are expected to be the absolute subpixel-coordinates on the image, given as float s, e.g. x=10.7 and y=3.4 for a point at coordinates (10.7, 3.4). Their order is expected to be clock-wise. They are expected to not be closed (i.e. first and last coordinate differ).
  • label (None or str, optional) – Label of the polygon, e.g. a string representing the class.
Attributes:
area

Compute the area of the polygon.

coords

Alias for attribute exterior.

height

Compute the height of a bounding box encapsulating the polygon.

is_valid

Estimate whether the polygon has a valid geometry.

width

Compute the width of a bounding box encapsulating the polygon.

xx

Get the x-coordinates of all points on the exterior.

xx_int

Get the discretized x-coordinates of all points on the exterior.

yy

Get the y-coordinates of all points on the exterior.

yy_int

Get the discretized y-coordinates of all points on the exterior.

Methods

almost_equals(self, other[, max_distance, …]) Estimate if this polygon’s and another’s geometry/labels are similar.
change_first_point_by_coords(self, x, y[, …]) Reorder exterior points so that the point closest to given x/y is first.
change_first_point_by_index(self, point_idx) Reorder exterior points so that the point with given index is first.
clip_out_of_image(self, image) Cut off all parts of the polygon that are outside of an image.
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 polygon area outside of the image plane.
coords_almost_equals(self, other[, …]) Alias for Polygon.exterior_almost_equals().
copy(self[, exterior, label]) Create a shallow copy of this object.
cut_out_of_image(self, image) Deprecated.
deepcopy(self[, exterior, label]) Create a deep copy of this object.
draw_on_image(self, image[, color, …]) Draw the polygon on an image.
exterior_almost_equals(self, other[, …]) Estimate if this and another polygon’s exterior are almost identical.
extract_from_image(self, image) Extract all image pixels within the polygon area.
find_closest_point_index(self, x, y[, …]) Find the index of the exterior point closest to given coordinates.
from_shapely(polygon_shapely[, label]) Create a polygon from a Shapely Polygon.
is_fully_within_image(self, image) Estimate whether the polygon is fully inside an image plane.
is_out_of_image(self, image[, fully, partly]) Estimate whether the polygon is partially/fully outside of an image.
is_partly_within_image(self, image) Estimate whether the polygon is at least partially inside an image.
project(self, from_shape, to_shape) Project the polygon onto an image with different shape.
project_(self, from_shape, to_shape) Project the polygon onto an image with different shape in-place.
shift(self[, x, y, top, right, bottom, left]) Move this polygon along the x/y-axis.
shift_(self[, x, y]) Move this polygon along the x/y-axis in-place.
subdivide(self, points_per_edge) Derive a new polygon with N interpolated points per edge.
subdivide_(self, points_per_edge) Derive a new poly with N interpolated points per edge in-place.
to_bounding_box(self) Convert this polygon to a bounding box containing the polygon.
to_keypoints(self) Convert this polygon’s exterior to Keypoint instances.
to_line_string(self[, closed]) Convert this polygon’s exterior to a LineString instance.
to_shapely_line_string(self[, closed, …]) Convert this polygon to a Shapely LineString object.
to_shapely_polygon(self) Convert this polygon to a Shapely Polygon.
almost_equals(self, other, max_distance=0.0001, points_per_edge=8)[source]

Estimate if this polygon’s and another’s geometry/labels are similar.

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

Parameters:
  • other (imgaug.augmentables.polys.Polygon) – The other object to compare against. Expected to be a Polygon.
  • max_distance (float, optional) – See exterior_almost_equals().
  • points_per_edge (int, optional) – See exterior_almost_equals().
Returns:

True if the coordinates are almost equal and additionally the labels are equal. Otherwise False.

Return type:

bool

area

Compute the area of the polygon.

Returns:Area of the polygon.
Return type:number
change_first_point_by_coords(self, x, y, max_distance=0.0001, raise_if_too_far_away=True)[source]

Reorder exterior points so that the point closest to given x/y is first.

This method takes a given (x,y) coordinate, finds the closest corner point on the exterior and reorders all exterior corner points so that the found point becomes the first one in the array.

If no matching points are found, an exception is raised.

Parameters:
  • x (number) – X-coordinate of the point.
  • y (number) – Y-coordinate of the point.
  • max_distance (None or number, optional) – Maximum distance past which possible matches are ignored. If None the distance limit is deactivated.
  • raise_if_too_far_away (bool, optional) – Whether to raise an exception if the closest found point is too far away (True) or simply return an unchanged copy if this object (False).
Returns:

Copy of this polygon with the new point order.

Return type:

imgaug.augmentables.polys.Polygon

change_first_point_by_index(self, point_idx)[source]

Reorder exterior points so that the point with given index is first.

This method takes a given index and reorders all exterior corner points so that the point with that index becomes the first one in the array.

An AssertionError will be raised if the index does not match any exterior point’s index or the exterior does not contain any points.

Parameters:point_idx (int) – Index of the desired starting point.
Returns:Copy of this polygon with the new point order.
Return type:imgaug.augmentables.polys.Polygon
clip_out_of_image(self, image)[source]

Cut off all parts of the polygon that are outside of an image.

This operation may lead to new points being created. As a single polygon may be split into multiple new polygons, the result is always a list, which may contain more than one output polygon.

This operation will return an empty list if the polygon is completely outside of the image plane.

Parameters:image ((H,W,…) ndarray or tuple of int) – Image dimensions to use for the clipping of the polygon. 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 int s.
Returns:Polygon, clipped to fall within the image dimensions. Returned as a list, because the clipping can split the polygon into multiple parts. The list may also be empty, if the polygon was fully outside of the image plane.
Return type:list of imgaug.augmentables.polys.Polygon
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 polygon area outside of the image plane.

This estimates f = A_ooi / A, where A_ooi is the area of the polygon 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 polygon area that is outside of the image plane. Returns 0.0 if the polygon is fully inside of the image plane or has zero points. If the polygon has an area of zero, the polygon is treated similarly to a LineString, i.e. the fraction of the line that is outside the image plane is returned.
Return type:float
coords

Alias for attribute exterior.

Added in 0.4.0.

Returns:An (N, 2) float32 ndarray containing the coordinates of this polygon. This identical to the attribute exterior.
Return type:ndarray
coords_almost_equals(self, other, max_distance=0.0001, points_per_edge=8)[source]

Alias for Polygon.exterior_almost_equals().

Parameters:
Returns:

Whether the two polygon’s exteriors can be viewed as equal (approximate test).

Return type:

bool

copy(self, exterior=None, label=None)[source]

Create a shallow copy of this object.

Parameters:
  • exterior (list of imgaug.augmentables.kps.Keypoint or list of tuple or (N,2) ndarray, optional) – List of points defining the polygon. See __init__() for details.
  • label (None or str, optional) – If not None, the label of the copied object will be set to this value.
Returns:

Shallow copy.

Return type:

imgaug.augmentables.polys.Polygon

cut_out_of_image(self, image)[source]

Deprecated. Use Polygon.clip_out_of_image() instead. clip_out_of_image() has the exactly same interface.

Cut off all parts of the polygon that are outside of an image.

deepcopy(self, exterior=None, label=None)[source]

Create a deep copy of this object.

Parameters:
  • exterior (list of Keypoint or list of tuple or (N,2) ndarray, optional) – List of points defining the polygon. See imgaug.augmentables.polys.Polygon.__init__ for details.
  • label (None or str) – If not None, the label of the copied object will be set to this value.
Returns:

Deep copy.

Return type:

imgaug.augmentables.polys.Polygon

draw_on_image(self, image, color=(0, 255, 0), color_face=None, color_lines=None, color_points=None, alpha=1.0, alpha_face=None, alpha_lines=None, alpha_points=None, size=1, size_lines=None, size_points=None, raise_if_out_of_image=False)[source]

Draw the polygon on an image.

Parameters:
  • image ((H,W,C) ndarray) – The image onto which to draw the polygon. Usually expected to be of dtype uint8, though other dtypes are also handled.
  • color (iterable of int, optional) – The color to use for the whole polygon. Must correspond to the channel layout of the image. Usually RGB. The values for color_face, color_lines and color_points will be derived from this color if they are set to None. This argument has no effect if color_face, color_lines and color_points are all set anything other than None.
  • color_face (None or iterable of int, optional) – The color to use for the inner polygon area (excluding perimeter). Must correspond to the channel layout of the image. Usually RGB. If this is None, it will be derived from color * 1.0.
  • color_lines (None or iterable of int, optional) – The color to use for the line (aka perimeter/border) of the polygon. Must correspond to the channel layout of the image. Usually RGB. If this is None, it will be derived from color * 0.5.
  • color_points (None or iterable of int, optional) – The color to use for the corner points of the polygon. Must correspond to the channel layout of the image. Usually RGB. If this is None, it will be derived from color * 0.5.
  • alpha (float, optional) – The opacity of the whole polygon, where 1.0 denotes a completely visible polygon and 0.0 an invisible one. The values for alpha_face, alpha_lines and alpha_points will be derived from this alpha value if they are set to None. This argument has no effect if alpha_face, alpha_lines and alpha_points are all set anything other than None.
  • alpha_face (None or number, optional) – The opacity of the polygon’s inner area (excluding the perimeter), where 1.0 denotes a completely visible inner area and 0.0 an invisible one. If this is None, it will be derived from alpha * 0.5.
  • alpha_lines (None or number, optional) – The opacity of the polygon’s line (aka perimeter/border), where 1.0 denotes a completely visible line and 0.0 an invisible one. If this is None, it will be derived from alpha * 1.0.
  • alpha_points (None or number, optional) – The opacity of the polygon’s corner points, where 1.0 denotes completely visible corners and 0.0 invisible ones. If this is None, it will be derived from alpha * 1.0.
  • size (int, optional) – Size of the polygon. The sizes of the line and points are derived from this value, unless they are set.
  • size_lines (None or int, optional) – Thickness of the polygon’s line (aka perimeter/border). If None, this value is derived from size.
  • size_points (int, optional) – Size of the points in pixels. If None, this value is derived from 3 * size.
  • raise_if_out_of_image (bool, optional) – Whether to raise an error if the polygon 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 the polygon drawn on it. Result dtype is the same as the input dtype.

Return type:

(H,W,C) ndarray

exterior_almost_equals(self, other, max_distance=0.0001, points_per_edge=8)[source]

Estimate if this and another polygon’s exterior are almost identical.

The two exteriors can have different numbers of points, but any point randomly sampled on the exterior of one polygon should be close to the closest point on the exterior of the other polygon.

Note

This method works in an approximative way. One can come up with polygons with fairly different shapes that will still be estimated as equal by this method. In practice however this should be unlikely to be the case. The probability for something like that goes down as the interpolation parameter is increased.

Parameters:
  • other (imgaug.augmentables.polys.Polygon or (N,2) ndarray or list of tuple) – The other polygon with which to compare the exterior. If this is an ndarray, it is assumed to represent an exterior. It must then have dtype float32 and shape (N,2) with the second dimension denoting xy-coordinates. If this is a list of tuple s, it is assumed to represent an exterior. Each tuple then must contain exactly two number s, denoting xy-coordinates.
  • max_distance (number, optional) – The maximum euclidean distance between a point on one polygon and the closest point on the other polygon. If the distance is exceeded for any such pair, the two exteriors are not viewed as equal. The points are either the points contained in the polygon’s exterior ndarray or interpolated points between these.
  • points_per_edge (int, optional) – How many points to interpolate on each edge.
Returns:

Whether the two polygon’s exteriors can be viewed as equal (approximate test).

Return type:

bool

extract_from_image(self, image)[source]

Extract all image pixels within the polygon area.

This method returns a rectangular image array. All pixels within that rectangle that do not belong to the polygon area will be filled with zeros (i.e. they will be black). The method will also zero-pad the image if the polygon 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 polygon.
Returns:Pixels within the polygon. Zero-padded if the polygon is partially/fully outside of the image.
Return type:(H’,W’) ndarray or (H’,W’,C) ndarray
find_closest_point_index(self, x, y, return_distance=False)[source]

Find the index of the exterior point closest to given coordinates.

“Closeness” is here defined based on euclidean distance. This method will raise an AssertionError if the exterior contains no points.

Parameters:
  • x (number) – X-coordinate around which to search for close points.
  • y (number) – Y-coordinate around which to search for close points.
  • return_distance (bool, optional) – Whether to also return the distance of the closest point.
Returns:

  • int – Index of the closest point.
  • number – Euclidean distance to the closest point. This value is only returned if return_distance was set to True.

static from_shapely(polygon_shapely, label=None)[source]

Create a polygon from a Shapely Polygon.

Note

This will remove any holes in the shapely polygon.

Parameters:
  • polygon_shapely (shapely.geometry.Polygon) – The shapely polygon.
  • label (None or str, optional) – The label of the new polygon.
Returns:

A polygon with the same exterior as the Shapely Polygon.

Return type:

imgaug.augmentables.polys.Polygon

height

Compute the height of a bounding box encapsulating the polygon.

The height is computed based on the two exterior coordinates with lowest and largest x-coordinates.

Returns:Height of the polygon.
Return type:number
is_fully_within_image(self, image)[source]

Estimate whether the polygon is fully inside an image plane.

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 int s.
Returns:True if the polygon 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 polygon is partially/fully outside of an image.

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 int s.
  • fully (bool, optional) – Whether to return True if the polygon is fully outside of the image area.
  • partly (bool, optional) – Whether to return True if the polygon is at least partially outside fo the image area.
Returns:

True if the polygon 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 polygon is at least partially inside an image.

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 int s.
Returns:True if the polygon is at least partially inside the image area. False otherwise.
Return type:bool
is_valid

Estimate whether the polygon has a valid geometry.

To to be considered valid, the polygon must be made up of at least 3 points and have a concave shape, i.e. line segments may not intersect or overlap. Multiple consecutive points are allowed to have the same coordinates.

Returns:True if polygon has at least 3 points and is concave, otherwise False.
Return type:bool
project(self, from_shape, to_shape)[source]

Project the polygon onto an image with different shape.

The relative coordinates of all points remain the same. E.g. a point at (x=20, y=20) on an image (width=100, height=200) will be projected on a new image (width=200, height=100) to (x=40, y=10).

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) – Shape of the original image. (Before resize.)
  • to_shape (tuple of int) – Shape of the new image. (After resize.)
Returns:

Polygon object with new coordinates.

Return type:

imgaug.augmentables.polys.Polygon

project_(self, from_shape, to_shape)[source]

Project the polygon onto an image with different shape in-place.

The relative coordinates of all points remain the same. E.g. a point at (x=20, y=20) on an image (width=100, height=200) will be projected on a new image (width=200, height=100) to (x=40, y=10).

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) – Shape of the original image. (Before resize.)
  • to_shape (tuple of int) – Shape of the new image. (After resize.)
Returns:

Polygon object with new coordinates. The object may have been modified in-place.

Return type:

imgaug.augmentables.polys.Polygon

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

Move this polygon 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 polygon.

Return type:

imgaug.augmentables.polys.Polygon

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

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

Return type:

imgaug.augmentables.polys.Polygon

subdivide(self, points_per_edge)[source]

Derive a new polygon with N interpolated points per edge.

See subdivide() for details.

Added in 0.4.0.

Parameters:points_per_edge (int) – Number of points to interpolate on each edge.
Returns:Polygon with subdivided edges.
Return type:imgaug.augmentables.polys.Polygon
subdivide_(self, points_per_edge)[source]

Derive a new poly with N interpolated points per edge in-place.

See subdivide() for details.

Added in 0.4.0.

Parameters:points_per_edge (int) – Number of points to interpolate on each edge.
Returns:Polygon with subdivided edges. The object may have been modified in-place.
Return type:imgaug.augmentables.polys.Polygon
to_bounding_box(self)[source]

Convert this polygon to a bounding box containing the polygon.

Returns:Bounding box that tightly encapsulates the polygon.
Return type:imgaug.augmentables.bbs.BoundingBox
to_keypoints(self)[source]

Convert this polygon’s exterior to Keypoint instances.

Returns:Exterior vertices as Keypoint instances.
Return type:list of imgaug.augmentables.kps.Keypoint
to_line_string(self, closed=True)[source]

Convert this polygon’s exterior to a LineString instance.

Parameters:closed (bool, optional) – Whether to close the line string, i.e. to add the first point of the exterior also as the last point at the end of the line string. This has no effect if the polygon has a single point or zero points.
Returns:Exterior of the polygon as a line string.
Return type:imgaug.augmentables.lines.LineString
to_shapely_line_string(self, closed=False, interpolate=0)[source]

Convert this polygon to a Shapely LineString object.

Parameters:
  • closed (bool, optional) – Whether to return the line string with the last point being identical to the first point.
  • interpolate (int, optional) – Number of points to interpolate between any pair of two consecutive points. These points are added to the final line string.
Returns:

The Shapely LineString matching the polygon’s exterior.

Return type:

shapely.geometry.LineString

to_shapely_polygon(self)[source]

Convert this polygon to a Shapely Polygon.

Returns:The Shapely Polygon matching this polygon’s exterior.
Return type:shapely.geometry.Polygon
width

Compute the width of a bounding box encapsulating the polygon.

The width is computed based on the two exterior coordinates with lowest and largest x-coordinates.

Returns:Width of the polygon.
Return type:number
xx

Get the x-coordinates of all points on the exterior.

Returns:float32 x-coordinates array of all points on the exterior.
Return type:(N,2) ndarray
xx_int

Get the discretized x-coordinates of all points on the exterior.

The conversion from float32 coordinates to int32 is done by first rounding the coordinates to the closest integer and then removing everything after the decimal point.

Returns:int32 x-coordinates of all points on the exterior.
Return type:(N,2) ndarray
yy

Get the y-coordinates of all points on the exterior.

Returns:float32 y-coordinates array of all points on the exterior.
Return type:(N,2) ndarray
yy_int

Get the discretized y-coordinates of all points on the exterior.

The conversion from float32 coordinates to int32 is done by first rounding the coordinates to the closest integer and then removing everything after the decimal point.

Returns:int32 y-coordinates of all points on the exterior.
Return type:(N,2) ndarray
class imgaug.augmentables.polys.PolygonsOnImage(polygons, shape)[source]

Bases: imgaug.augmentables.base.IAugmentable

Container for all polygons on a single image.

Parameters:
  • polygons (list of imgaug.augmentables.polys.Polygon) – List of polygons 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.polys import Polygon, PolygonsOnImage
>>> image = np.zeros((100, 100))
>>> polys = [
>>>     Polygon([(0.5, 0.5), (100.5, 0.5), (100.5, 100.5), (0.5, 100.5)]),
>>>     Polygon([(50.5, 0.5), (100.5, 50.5), (50.5, 100.5), (0.5, 50.5)])
>>> ]
>>> polys_oi = PolygonsOnImage(polys, shape=image.shape)
Attributes:
empty

Estimate whether this object contains zero polygons.

items

Get the polygons in this container.

Methods

clip_out_of_image(self) Clip off all parts from all polygons that are outside of an image.
clip_out_of_image_(self) Clip off all parts from all polygons that are OOI in-place.
copy(self[, polygons, shape]) Create a shallow copy of this object.
deepcopy(self[, polygons, shape]) Create a deep copy of this object.
draw_on_image(self, image[, color, …]) Draw all polygons onto a given image.
fill_from_xy_array_(self, xy) Modify the corner coordinates of all polygons in-place.
invert_to_keypoints_on_image_(self, kpsoi) Invert the output of to_keypoints_on_image() in-place.
on(self, image) Project all polygons from one image shape to a new one.
on_(self, image) Project all polygons from one image shape to a new one in-place.
remove_out_of_image(self[, fully, partly]) Remove all polygons that are fully/partially outside of an image.
remove_out_of_image_(self[, fully, partly]) Remove all polygons that are fully/partially OOI in-place.
remove_out_of_image_fraction(self, fraction) Remove all Polys with an out of image fraction of >=fraction.
remove_out_of_image_fraction_(self, fraction) Remove all Polys with an OOI fraction of >=fraction in-place.
shift(self[, x, y, top, right, bottom, left]) Move the polygons along the x/y-axis.
shift_(self[, x, y]) Move the polygons along the x/y-axis in-place.
subdivide(self, points_per_edge) Interpolate N points on each polygon.
subdivide_(self, points_per_edge) Interpolate N points on each polygon.
to_keypoints_on_image(self) Convert the polygons to one KeypointsOnImage instance.
to_xy_array(self) Convert all polygon coordinates to one array of shape (N,2).
clip_out_of_image(self)[source]

Clip off all parts from all polygons that are outside of an image.

Note

The result can contain fewer polygons than the input did. That happens when a polygon is fully outside of the image plane.

Note

The result can also contain more polygons than the input did. That happens when distinct parts of a polygon are only connected by areas that are outside of the image plane and hence will be clipped off, resulting in two or more unconnected polygon parts that are left in the image plane.

Returns:Polygons, clipped to fall within the image dimensions. The count of output polygons may differ from the input count.
Return type:imgaug.augmentables.polys.PolygonsOnImage
clip_out_of_image_(self)[source]

Clip off all parts from all polygons that are OOI in-place.

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

Note

The result can contain fewer polygons than the input did. That happens when a polygon is fully outside of the image plane.

Note

The result can also contain more polygons than the input did. That happens when distinct parts of a polygon are only connected by areas that are outside of the image plane and hence will be clipped off, resulting in two or more unconnected polygon parts that are left in the image plane.

Added in 0.4.0.

Returns:Polygons, clipped to fall within the image dimensions. The count of output polygons may differ from the input count. The object and its items may have been modified in-place.
Return type:imgaug.augmentables.polys.PolygonsOnImage
copy(self, polygons=None, shape=None)[source]

Create a shallow copy of this object.

Parameters:
  • polygons (None or list of imgaug.augmentables.polys.Polygons, optional) – List of polygons on the image. If not None, then the polygons attribute of the copied object will be set to this value.
  • shape (None or tuple of int or ndarray, optional) – 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. If not None, then the shape attribute of the copied object will be set to this value.
Returns:

Shallow copy.

Return type:

imgaug.augmentables.polys.PolygonsOnImage

deepcopy(self, polygons=None, shape=None)[source]

Create a deep copy of this object.

Parameters:
  • polygons (None or list of imgaug.augmentables.polys.Polygons, optional) – List of polygons on the image. If not None, then the polygons attribute of the copied object will be set to this value.
  • shape (None or tuple of int or ndarray, optional) – 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. If not None, then the shape attribute of the copied object will be set to this value.
Returns:

Deep copy.

Return type:

imgaug.augmentables.polys.PolygonsOnImage

draw_on_image(self, image, color=(0, 255, 0), color_face=None, color_lines=None, color_points=None, alpha=1.0, alpha_face=None, alpha_lines=None, alpha_points=None, size=1, size_lines=None, size_points=None, raise_if_out_of_image=False)[source]

Draw all polygons onto a given image.

Parameters:
  • image ((H,W,C) ndarray) – The image onto which to draw the bounding boxes. This image should usually have the same shape as set in PolygonsOnImage.shape.
  • color (iterable of int, optional) – The color to use for the whole polygons. Must correspond to the channel layout of the image. Usually RGB. The values for color_face, color_lines and color_points will be derived from this color if they are set to None. This argument has no effect if color_face, color_lines and color_points are all set anything other than None.
  • color_face (None or iterable of int, optional) – The color to use for the inner polygon areas (excluding perimeters). Must correspond to the channel layout of the image. Usually RGB. If this is None, it will be derived from color * 1.0.
  • color_lines (None or iterable of int, optional) – The color to use for the lines (aka perimeters/borders) of the polygons. Must correspond to the channel layout of the image. Usually RGB. If this is None, it will be derived from color * 0.5.
  • color_points (None or iterable of int, optional) – The color to use for the corner points of the polygons. Must correspond to the channel layout of the image. Usually RGB. If this is None, it will be derived from color * 0.5.
  • alpha (float, optional) – The opacity of the whole polygons, where 1.0 denotes completely visible polygons and 0.0 invisible ones. The values for alpha_face, alpha_lines and alpha_points will be derived from this alpha value if they are set to None. This argument has no effect if alpha_face, alpha_lines and alpha_points are all set anything other than None.
  • alpha_face (None or number, optional) – The opacity of the polygon’s inner areas (excluding the perimeters), where 1.0 denotes completely visible inner areas and 0.0 invisible ones. If this is None, it will be derived from alpha * 0.5.
  • alpha_lines (None or number, optional) – The opacity of the polygon’s lines (aka perimeters/borders), where 1.0 denotes completely visible perimeters and 0.0 invisible ones. If this is None, it will be derived from alpha * 1.0.
  • alpha_points (None or number, optional) – The opacity of the polygon’s corner points, where 1.0 denotes completely visible corners and 0.0 invisible ones. Currently this is an on/off choice, i.e. only 0.0 or 1.0 are allowed. If this is None, it will be derived from alpha * 1.0.
  • size (int, optional) – Size of the polygons. The sizes of the line and points are derived from this value, unless they are set.
  • size_lines (None or int, optional) – Thickness of the polygon lines (aka perimeter/border). If None, this value is derived from size.
  • size_points (int, optional) – The size of all corner points. If set to C, each corner point will be drawn as a square of size C x C.
  • raise_if_out_of_image (bool, optional) – Whether to raise an error if any polygon 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 drawn polygons.

Return type:

(H,W,C) ndarray

empty

Estimate whether this object contains zero polygons.

Returns:True if this object contains zero polygons.
Return type:bool
fill_from_xy_array_(self, xy)[source]

Modify the corner coordinates of all polygons in-place.

Note

This currently expects that xy contains exactly as many coordinates as the polygons within this instance have corner points. Otherwise, an AssertionError will be raised.

Warning

This does not validate the new coordinates or repair the resulting polygons. If bad coordinates are provided, the result will be invalid polygons (e.g. self-intersections).

Added in 0.4.0.

Parameters:xy ((N, 2) ndarray or iterable of iterable of number) – XY-Coordinates of N corner points. N must match the number of corner points in all polygons within this instance.
Returns:This instance itself, with updated coordinates. Note that the instance was modified in-place.
Return type:PolygonsOnImage
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 PolygonsOnImage instance.

Added in 0.4.0.

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

Get the polygons in this container.

Added in 0.4.0.

Returns:Polygons within this container.
Return type:list of Polygon
on(self, image)[source]

Project all polygons from one image shape to a new one.

Parameters:image (ndarray or tuple of int) – New image onto which the polygons are to be projected. May also simply be that new image’s shape tuple.
Returns:Object containing all projected polygons.
Return type:imgaug.augmentables.polys.PolygonsOnImage
on_(self, image)[source]

Project all polygons from one image shape to a new one in-place.

Added in 0.4.0.

Parameters:image (ndarray or tuple of int) – New image onto which the polygons are to be projected. May also simply be that new image’s shape tuple.
Returns:Object containing all projected polygons. The object and its items may have been modified in-place.
Return type:imgaug.augmentables.polys.PolygonsOnImage
remove_out_of_image(self, fully=True, partly=False)[source]

Remove all polygons that are fully/partially outside of an image.

Parameters:
  • fully (bool, optional) – Whether to remove polygons that are fully outside of the image.
  • partly (bool, optional) – Whether to remove polygons that are partially outside of the image.
Returns:

Reduced set of polygons. Those that are fully/partially outside of the given image plane are removed.

Return type:

imgaug.augmentables.polys.PolygonsOnImage

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

Remove all polygons that are fully/partially OOI in-place.

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

Added in 0.4.0.

Parameters:
  • fully (bool, optional) – Whether to remove polygons that are fully outside of the image.
  • partly (bool, optional) – Whether to remove polygons that are partially outside of the image.
Returns:

Reduced set of polygons. Those that are fully/partially outside of the given image plane are removed. The object and its items may have been modified in-place.

Return type:

imgaug.augmentables.polys.PolygonsOnImage

remove_out_of_image_fraction(self, fraction)[source]

Remove all Polys with an out of image fraction of >=fraction.

Added in 0.4.0.

Parameters:fraction (number) – Minimum out of image fraction that a polygon has to have in order to be removed. A fraction of 1.0 removes only polygons that are 100% outside of the image. A fraction of 0.0 removes all polygons.
Returns:Reduced set of polygons, with those that had an out of image fraction greater or equal the given one removed.
Return type:imgaug.augmentables.polys.PolygonsOnImage
remove_out_of_image_fraction_(self, fraction)[source]

Remove all Polys with an OOI fraction of >=fraction in-place.

Added in 0.4.0.

Parameters:fraction (number) – Minimum out of image fraction that a polygon has to have in order to be removed. A fraction of 1.0 removes only polygons that are 100% outside of the image. A fraction of 0.0 removes all polygons.
Returns:Reduced set of polygons, 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.polys.PolygonsOnImage
shift(self, x=0, y=0, top=None, right=None, bottom=None, left=None)[source]

Move the polygons 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 polygons.

Return type:

imgaug.augmentables.polys.PolygonsOnImage

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

Move the polygons 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 polygons.

Return type:

imgaug.augmentables.polys.PolygonsOnImage

subdivide(self, points_per_edge)[source]

Interpolate N points on each polygon.

Added in 0.4.0.

Parameters:points_per_edge (int) – Number of points to interpolate on each edge.
Returns:Subdivided polygons.
Return type:imgaug.augmentables.polys.PolygonsOnImage
subdivide_(self, points_per_edge)[source]

Interpolate N points on each polygon.

Added in 0.4.0.

Parameters:points_per_edge (int) – Number of points to interpolate on each edge.
Returns:Subdivided polygons.
Return type:imgaug.augmentables.polys.PolygonsOnImage
to_keypoints_on_image(self)[source]

Convert the polygons to one KeypointsOnImage instance.

Added in 0.4.0.

Returns:A keypoints instance containing N coordinates for a total of N points in all exteriors of the polygons within this container. Order matches the order in polygons.
Return type:imgaug.augmentables.kps.KeypointsOnImage
to_xy_array(self)[source]

Convert all polygon coordinates to one array of shape (N,2).

Added in 0.4.0.

Returns:Array containing all xy-coordinates of all polygons within this instance.
Return type:(N, 2) ndarray
imgaug.augmentables.polys.recover_psois_(psois, psois_orig, recoverer, random_state)[source]

Apply a polygon recoverer to input polygons in-place.

Parameters:
  • psois (list of imgaug.augmentables.polys.PolygonsOnImage or imgaug.augmentables.polys.PolygonsOnImage) – The possibly broken polygons, e.g. after augmentation. The recoverer is applied to them.
  • psois_orig (list of imgaug.augmentables.polys.PolygonsOnImage or imgaug.augmentables.polys.PolygonsOnImage) – Original polygons that were later changed to psois. They are an extra input to recoverer.
  • recoverer (imgaug.augmentables.polys._ConcavePolygonRecoverer) – The polygon recoverer used to repair broken input polygons.
  • random_state (None or int or RNG or numpy.random.Generator or numpy.random.BitGenerator or numpy.random.SeedSequence or numpy.random.RandomState) – An RNG to use during the polygon recovery.
Returns:

List of repaired polygons. Note that this is psois, which was changed in-place.

Return type:

list of imgaug.augmentables.polys.PolygonsOnImage or imgaug.augmentables.polys.PolygonsOnImage