imgaug.augmentables.kps¶

class imgaug.augmentables.kps.Keypoint(x, y)[source]¶

Bases: object

A single keypoint (aka landmark) on an image.

Parameters:	x (number) – Coordinate of the keypoint on the x axis. y (number) – Coordinate of the keypoint on the y axis.
Attributes:	`x_int` Get the keypoint’s x-coordinate, rounded to the closest integer. `y_int` Get the keypoint’s y-coordinate, rounded to the closest integer.

Methods

`copy`(self[, x, y])	Create a shallow copy of the keypoint instance.
`deepcopy`(self[, x, y])	Create a deep copy of the keypoint instance.
`draw_on_image`(self, image[, color, alpha, …])	Draw the keypoint onto a given image.
`generate_similar_points_manhattan`(self, …)	Generate nearby points based on manhattan distance.
`project`(self, from_shape, to_shape)	Project the keypoint onto a new position on a new image.
`shift`(self[, x, y])	Move the keypoint around on an image.

copy(self, x=None, y=None)[source]¶

Create a shallow copy of the keypoint instance.

Parameters:	x (None or number, optional) – Coordinate of the keypoint on the x axis. If `None`, the instance’s value will be copied. y (None or number, optional) – Coordinate of the keypoint on the y axis. If `None`, the instance’s value will be copied.
Returns:	Shallow copy.
Return type:	imgaug.augmentables.kps.Keypoint

deepcopy(self, x=None, y=None)[source]¶

Create a deep copy of the keypoint instance.

Parameters:	x (None or number, optional) – Coordinate of the keypoint on the x axis. If `None`, the instance’s value will be copied. y (None or number, optional) – Coordinate of the keypoint on the y axis. If `None`, the instance’s value will be copied.
Returns:	Deep copy.
Return type:	imgaug.augmentables.kps.Keypoint

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

Draw the keypoint onto a given image.

The keypoint is drawn as a square.

Parameters:	image ((H,W,3) ndarray) – The image onto which to draw the keypoint. color (int or list of int or tuple of int or (3,) ndarray, optional) – The RGB color of the keypoint. If a single `int` `C`, then that is equivalent to `(C,C,C)`. alpha (float, optional) – The opacity of the drawn keypoint, where `1.0` denotes a fully visible keypoint and `0.0` an invisible one. size (int, optional) – The size of the keypoint. If set to `S`, each square will have size `S x S`. copy (bool, optional) – Whether to copy the image before drawing the keypoint. raise_if_out_of_image (bool, optional) – Whether to raise an exception if the keypoint is outside of the image.
Returns:	image – Image with drawn keypoint.
Return type:	(H,W,3) ndarray

generate_similar_points_manhattan(self, nb_steps, step_size, return_array=False)[source]¶

Generate nearby points based on manhattan distance.

To generate the first neighbouring points, a distance of S (step size) is moved from the center point (this keypoint) to the top, right, bottom and left, resulting in four new points. From these new points, the pattern is repeated. Overlapping points are ignored.

The resulting points have a shape similar to a square rotated by 45 degrees.

Parameters:	nb_steps (int) – The number of steps to move from the center point. `nb_steps=1` results in a total of `5` output points (one center point + four neighbours). step_size (number) – The step size to move from every point to its neighbours. return_array (bool, optional) – Whether to return the generated points as a list of `Keypoint` or an array of shape `(N,2)`, where `N` is the number of generated points and the second axis contains the x-/y-coordinates.
Returns:	If return_array was `False`, then a list of `Keypoint`. Otherwise a numpy array of shape `(N,2)`, where `N` is the number of generated points and the second axis contains the x-/y-coordinates. The center keypoint (the one on which this function was called) is always included.
Return type:	list of imgaug.augmentables.kps.Keypoint or (N,2) ndarray

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

Project the keypoint onto a new position on a new image.

E.g. if the keypoint is on its original image at x=(10 of 100 pixels) and y=(20 of 100 pixels) and is projected onto a new image with size (width=200, height=200), its new position will be (20, 40).

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:	Keypoint object with new coordinates.
Return type:	imgaug.augmentables.kps.Keypoint

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

Move the keypoint around on an image.

Parameters:	x (number, optional) – Move by this value on the x axis. y (number, optional) – Move by this value on the y axis.
Returns:	Keypoint object with new coordinates.
Return type:	imgaug.augmentables.kps.Keypoint

x_int¶

Get the keypoint’s x-coordinate, rounded to the closest integer.

Returns:	result – Keypoint’s x-coordinate, rounded to the closest integer.
Return type:	int

y_int¶

Get the keypoint’s y-coordinate, rounded to the closest integer.

Returns:	result – Keypoint’s y-coordinate, rounded to the closest integer.
Return type:	int

class imgaug.augmentables.kps.KeypointsOnImage(keypoints, shape)[source]¶

Bases: object

Container for all keypoints on a single image.

Parameters:	keypoints (list of imgaug.augmentables.kps.Keypoint) – List of keypoints on the image. shape (tuple of int) – The shape of the image on which the keypoints are placed.

Examples

>>> import numpy as np
>>> from imgaug.augmentables.kps import Keypoint, KeypointsOnImage
>>>
>>> image = np.zeros((70, 70))
>>> kps = [Keypoint(x=10, y=20), Keypoint(x=34, y=60)]
>>> kps_oi = KeypointsOnImage(kps, shape=image.shape)

Attributes:	`empty` Determine whether this object contains zero keypoints. height width

Methods

`copy`(self[, keypoints, shape])	Create a shallow copy of the `KeypointsOnImage` object.
`deepcopy`(self[, keypoints, shape])	Create a deep copy of the `KeypointsOnImage` object.
`draw_on_image`(self, image[, color, alpha, …])	Draw all keypoints onto a given image.
`from_coords_array`(coords, shape)	Deprecated.
`from_distance_maps`(distance_maps[, …])	Convert outputs of `to_distance_maps()` to `KeypointsOnImage`.
`from_keypoint_image`(image[, …])	Convert `to_keypoint_image()` outputs to `KeypointsOnImage`.
`from_xy_array`(xy, shape)	Convert an `(N,2)` array to a `KeypointsOnImage` object.
`get_coords_array`(self)	Deprecated.
`on`(self, image)	Project all keypoints from one image shape to a new one.
`shift`(self[, x, y])	Move the keypoints on the x/y-axis.
`to_distance_maps`(self[, inverted])	Generate a `(H,W,N)` array of distance maps for `N` keypoints.
`to_keypoint_image`(self[, size])	Create an `(H,W,N)` image with keypoint coordinates set to `255`.
`to_xy_array`(self)	Convert all keypoint coordinates to an array of shape `(N,2)`.

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

Create a shallow copy of the KeypointsOnImage object.

Parameters:	keypoints (None or list of imgaug.Keypoint, optional) – List of keypoints on the image. If `None`, the instance’s keypoints will be copied. shape (tuple of int, optional) – The shape of the image on which the keypoints are placed. If `None`, the instance’s shape will be copied.
Returns:	Shallow copy.
Return type:	imgaug.augmentables.kps.KeypointsOnImage

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

Create a deep copy of the KeypointsOnImage object.

Parameters:	keypoints (None or list of imgaug.Keypoint, optional) – List of keypoints on the image. If `None`, the instance’s keypoints will be copied. shape (tuple of int, optional) – The shape of the image on which the keypoints are placed. If `None`, the instance’s shape will be copied.
Returns:	Deep copy.
Return type:	imgaug.augmentables.kps.KeypointsOnImage

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

Draw all keypoints onto a given image.

Each keypoint is drawn as a square of provided color and size.

Parameters:	image ((H,W,3) ndarray) – The image onto which to draw the keypoints. This image should usually have the same shape as set in `KeypointsOnImage.shape`. color (int or list of int or tuple of int or (3,) ndarray, optional) – The RGB color of all keypoints. If a single `int` `C`, then that is equivalent to `(C,C,C)`. alpha (float, optional) – The opacity of the drawn keypoint, where `1.0` denotes a fully visible keypoint and `0.0` an invisible one. size (int, optional) – The size of each point. If set to `C`, each square will have size `C x C`. copy (bool, optional) – Whether to copy the image before drawing the points. raise_if_out_of_image (bool, optional) – Whether to raise an exception if any keypoint is outside of the image.
Returns:	Image with drawn keypoints.
Return type:	(H,W,3) ndarray

empty¶

Determine whether this object contains zero keypoints.

Returns:	`True` if this object contains zero keypoints.
Return type:	bool

static from_coords_array(coords, shape)[source]¶

Deprecated. Use KeypointsOnImage.from_xy_array() instead.

Convert an (N,2) array to a KeypointsOnImage object.

Parameters:	coords : (N, 2) ndarray Coordinates of `N` keypoints on an image, given as a `(N,2)` array of xy-coordinates. shape : tuple The shape of the image on which the keypoints are placed.
Returns:	imgaug.augmentables.kps.KeypointsOnImage `KeypointsOnImage` object containing the array’s keypoints.

static from_distance_maps(distance_maps, inverted=False, if_not_found_coords={'x': -1, 'y': -1}, threshold=None, nb_channels=None)[source]¶

Convert outputs of to_distance_maps() to KeypointsOnImage.

This is the inverse of KeypointsOnImage.to_distance_maps().

Parameters:	distance_maps ((H,W,N) ndarray) – The distance maps. `N` is the number of keypoints. inverted (bool, optional) – Whether the given distance maps were generated in inverted mode (i.e. `KeypointsOnImage.to_distance_maps()` was called with `inverted=True`) or in non-inverted mode. if_not_found_coords (tuple or list or dict or None, optional) – Coordinates to use for keypoints that cannot be found in distance_maps. If this is a `list`/`tuple`, it must contain two `int` values. If it is a `dict`, it must contain the keys `x` and `y` with each containing one `int` value. If this is `None`, then the keypoint will not be added to the final `KeypointsOnImage` object. threshold (float, optional) – The search for keypoints works by searching for the argmin (non-inverted) or argmax (inverted) in each channel. This parameters contains the maximum (non-inverted) or minimum (inverted) value to accept in order to view a hit as a keypoint. Use `None` to use no min/max. nb_channels (None or int, optional) – Number of channels of the image on which the keypoints are placed. Some keypoint augmenters require that information. If set to `None`, the keypoint’s shape will be set to `(height, width)`, otherwise `(height, width, nb_channels)`.
Returns:	The extracted keypoints.
Return type:	imgaug.augmentables.kps.KeypointsOnImage

static from_keypoint_image(image, if_not_found_coords={'x': -1, 'y': -1}, threshold=1, nb_channels=None)[source]¶

Convert to_keypoint_image() outputs to KeypointsOnImage.

This is the inverse of KeypointsOnImage.to_keypoint_image().

Parameters:	image ((H,W,N) ndarray) – The keypoints image. N is the number of keypoints. if_not_found_coords (tuple or list or dict or None, optional) – Coordinates to use for keypoints that cannot be found in image. If this is a `list`/`tuple`, it must contain two `int` values. If it is a `dict`, it must contain the keys `x` and `y` with each containing one `int` value. If this is `None`, then the keypoint will not be added to the final `KeypointsOnImage` object. threshold (int, optional) – The search for keypoints works by searching for the argmax in each channel. This parameters contains the minimum value that the max must have in order to be viewed as a keypoint. nb_channels (None or int, optional) – Number of channels of the image on which the keypoints are placed. Some keypoint augmenters require that information. If set to `None`, the keypoint’s shape will be set to `(height, width)`, otherwise `(height, width, nb_channels)`.
Returns:	The extracted keypoints.
Return type:	imgaug.augmentables.kps.KeypointsOnImage

classmethod from_xy_array(xy, shape)[source]¶

Convert an (N,2) array to a KeypointsOnImage object.

Parameters:	xy ((N, 2) ndarray) – Coordinates of `N` keypoints on an image, given as a `(N,2)` array of xy-coordinates. shape (tuple of int or ndarray) – The shape of the image on which the keypoints are placed.
Returns:	`KeypointsOnImage` object containing the array’s keypoints.
Return type:	imgaug.augmentables.kps.KeypointsOnImage

get_coords_array(self)[source]¶

Deprecated. Use KeypointsOnImage.to_xy_array() instead.

Convert all keypoint coordinates to an array of shape (N,2).

Returns:	(N, 2) ndarray Array containing the coordinates of all keypoints. `N` denotes the number of keypoints. The second axis denotes the x/y-coordinates.

height¶

on(self, image)[source]¶

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

Parameters:	image (ndarray or tuple of int) – New image onto which the keypoints are to be projected. May also simply be that new image’s shape tuple.
Returns:	Object containing all projected keypoints.
Return type:	imgaug.augmentables.kps.KeypointsOnImage

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

Move the keypoints on the x/y-axis.

Parameters:	x (number, optional) – Move each keypoint by this value on the x axis. y (number, optional) – Move each keypoint by this value on the y axis.
Returns:	Keypoints after moving them.
Return type:	imgaug.augmentables.kps.KeypointsOnImage

to_distance_maps(self, inverted=False)[source]¶

Generate a (H,W,N) array of distance maps for N keypoints.

The n-th distance map contains at every location (y, x) the euclidean distance to the n-th keypoint.

This function can be used as a helper when augmenting keypoints with a method that only supports the augmentation of images.

Parameters:	inverted (bool, optional) – If `True`, inverted distance maps are returned where each distance value d is replaced by `d/(d+1)`, i.e. the distance maps have values in the range `(0.0, 1.0]` with `1.0` denoting exactly the position of the respective keypoint.
Returns:	A `float32` array containing `N` distance maps for `N` keypoints. Each location `(y, x, n)` in the array denotes the euclidean distance at `(y, x)` to the `n`-th keypoint. If inverted is `True`, the distance `d` is replaced by `d/(d+1)`. The height and width of the array match the height and width in `KeypointsOnImage.shape`.
Return type:	(H,W,N) ndarray

to_keypoint_image(self, size=1)[source]¶

Create an (H,W,N) image with keypoint coordinates set to 255.

This method generates a new uint8 array of shape (H,W,N), where H is the .shape height, W the .shape width and N is the number of keypoints. The array is filled with zeros. The coordinate of the n-th keypoint is set to 255 in the n-th channel.

This function can be used as a helper when augmenting keypoints with a method that only supports the augmentation of images.

Parameters:	size (int) – Size of each (squared) point.
Returns:	Image in which the keypoints are marked. `H` is the height, defined in `KeypointsOnImage.shape[0]` (analogous `W`). `N` is the number of keypoints.
Return type:	(H,W,N) ndarray

to_xy_array(self)[source]¶

Convert all keypoint coordinates to an array of shape (N,2).

Returns:	Array containing the coordinates of all keypoints. `N` denotes the number of keypoints. The second axis denotes the x/y-coordinates.
Return type:	(N, 2) ndarray

width¶

imgaug.augmentables.kps.compute_geometric_median(points=None, eps=1e-05, X=None)[source]¶

Estimate the geometric median of points in 2D.

Code from https://stackoverflow.com/a/30305181

Parameters:	points ((N,2) ndarray) – Points in 2D. Second axis must be given in xy-form. eps (float, optional) – Distance threshold when to return the median. X (None or (N,2) ndarray, optional) – Deprecated.
Returns:	Geometric median as xy-coordinate.
Return type:	(2,) ndarray