imgaug.augmentables.lines¶

Classes representing lines.

class imgaug.augmentables.lines.LineString(coords, label=None)[source]¶

Bases: object

Class representing line strings.

A line string is a collection of connected line segments, each having a start and end point. Each point is given as its (x, y) absolute (sub-)pixel coordinates. The end point of each segment is also the start point of the next segment.

The line string is not closed, i.e. start and end point are expected to differ and will not be connected in drawings.

Parameters:

coords (iterable of tuple of number or ndarray) – The points of the line string.
label (None or str, optional) – The label of the line string.

Attributes:

height: Compute the height of a bounding box encapsulating the line.
length: Compute the total euclidean length of the line string.
width: Compute the width of a bounding box encapsulating the line.
xx: Get an array of x-coordinates of all points of the line string.
xx_int: Get an array of discrete x-coordinates of all points.
yy: Get an array of y-coordinates of all points of the line string.
yy_int: Get an array of discrete y-coordinates of all points.

Methods

`almost_equals`(self, other[, max_distance, …])	Compare this and another line string.
`clip_out_of_image`(self, image)	Clip off all parts of the line string that are outside of the image.
`compute_distance`(self, other[, default])	Compute the minimal distance between the line string and other.
`compute_neighbour_distances`(self)	Compute the euclidean distance between each two consecutive points.
`compute_out_of_image_fraction`(self, image)	Compute fraction of polygon area outside of the image plane.
`compute_pointwise_distances`(self, other[, …])	Compute min distances between points of this and another line string.
`concatenate`(self, other)	Concatenate this line string with another one.
`contains`(self, other[, max_distance])	Estimate whether a point is on this line string.
`coords_almost_equals`(self, other[, …])	Compare this and another LineString’s coordinates.
`copy`(self[, coords, label])	Create a shallow copy of this line string.
`deepcopy`(self[, coords, label])	Create a deep copy of this line string.
`draw_heatmap_array`(self, image_shape[, …])	Draw the line segments and points of the line string as a heatmap array.
`draw_lines_heatmap_array`(self, image_shape)	Draw the line segments of this line string as a heatmap array.
`draw_lines_on_image`(self, image[, color, …])	Draw the line segments of this line string on a given image.
`draw_mask`(self, image_shape[, size_lines, …])	Draw this line segment as a binary image mask.
`draw_on_image`(self, image[, color, …])	Draw this line string onto an image.
`draw_points_heatmap_array`(self, image_shape)	Draw the points of this line string as a heatmap array.
`draw_points_on_image`(self, image[, color, …])	Draw the points of this line string onto a given image.
`extract_from_image`(self, image[, size, pad, …])	Extract all image pixels covered by the line string.
`find_intersections_with`(self, other)	Find all intersection points between this line string and other.
`get_pointwise_inside_image_mask`(self, image)	Determine per point whether it is inside of a given image plane.
`is_fully_within_image`(self, image[, default])	Estimate whether the line string is fully inside an image plane.
`is_out_of_image`(self, image[, fully, …])	Estimate whether the line is partially/fully outside of the image area.
`is_partly_within_image`(self, image[, default])	Estimate whether the line string is at least partially inside the image.
`project`(self, from_shape, to_shape)	Project the line string onto a differently shaped image.
`project_`(self, from_shape, to_shape)	Project the line string onto a differently shaped image in-place.
`shift`(self[, x, y, top, right, bottom, left])	Move this line string along the x/y-axis.
`shift_`(self[, x, y])	Move this line string along the x/y-axis in-place.
`subdivide`(self, points_per_edge)	Derive a new line string with `N` interpolated points per edge.
`to_bounding_box`(self)	Generate a bounding box encapsulating the line string.
`to_heatmap`(self, image_shape[, size_lines, …])	Generate a heatmap object from the line string.
`to_keypoints`(self)	Convert the line string points to keypoints.
`to_polygon`(self)	Generate a polygon from the line string points.
`to_segmentation_map`(self, image_shape[, …])	Generate a segmentation map object from the line string.

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

Compare this and another line string.

Parameters:	other (imgaug.augmentables.lines.LineString) – The other object to compare against. Expected to be a `LineString`. max_distance (float, optional) – See `coords_almost_equals()`. points_per_edge (int, optional) – See `coords_almost_equals()`.
Returns:	`True` if the coordinates are almost equal and additionally the labels are equal. Otherwise `False`.
Return type:	bool

clip_out_of_image(self, image)[source]¶

Clip off all parts of the line string that are outside of the image.

Parameters:	image (ndarray or tuple of int) – Either an image with shape `(H,W,[C])` or a `tuple` denoting such an image shape.
Returns:	Line strings, clipped to the image shape. The result may contain any number of line strins, including zero.
Return type:	list of imgaug.augmentables.lines.LineString

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

Compute the minimal distance between the line string and other.

Parameters:	other (tuple of number or imgaug.augmentables.kps.Keypoint or imgaug.augmentables.LineString) – Other object to which to compute the distance. default (any) – Value to return if this line string or other contain no points.
Returns:	Minimal distance to other or default if no distance could be computed.
Return type:	float or any

compute_neighbour_distances(self)[source]¶

Compute the euclidean distance between each two consecutive points.

Returns:	`(N-1,)` `float32` array of euclidean distances between point pairs. Same order as in coords.
Return type:	ndarray

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. 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 inside the image plane is returned.
Return type:	float

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

Compute min distances between points of this and another line string.

Parameters:	other (tuple of number or imgaug.augmentables.kps.Keypoint or imgaug.augmentables.LineString) – Other object to which to compute the distances. default (any) – Value to return if other contains no points.
Returns:	For each coordinate of this line string, the distance to any closest location on other. default if no distance could be computed.
Return type:	list of float or any

concatenate(self, other)[source]¶

Concatenate this line string with another one.

This will add a line segment between the end point of this line string and the start point of other.

Parameters:	other (imgaug.augmentables.lines.LineString or ndarray or iterable of tuple of number) – The points to add to this line string.
Returns:	New line string with concatenated points. The label of this line string will be kept.
Return type:	imgaug.augmentables.lines.LineString

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

Estimate whether a point is on this line string.

This method uses a maximum distance to estimate whether a point is on a line string.

Parameters:	other (tuple of number or imgaug.augmentables.kps.Keypoint) – Point to check for. max_distance (float) – Maximum allowed euclidean distance between the point and the closest point on the line. If the threshold is exceeded, the point is not considered to fall on the line.
Returns:	`True` if the point is on the line string, `False` otherwise.
Return type:	bool

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

Compare this and another LineString’s coordinates.

This is an approximate method based on pointwise distances and can in rare corner cases produce wrong outputs.

Parameters:	other (imgaug.augmentables.lines.LineString or tuple of number or ndarray or list of ndarray or list of tuple of number) – The other line string or its coordinates. max_distance (float, optional) – Max distance of any point from the other line string before the two line strings are evaluated to be unequal. points_per_edge (int, optional) – How many points to interpolate on each edge.
Returns:	Whether the two LineString’s coordinates are almost identical, i.e. the max distance is below the threshold. If both have no coordinates, `True` is returned. If only one has no coordinates, `False` is returned. Beyond that, the number of points is not evaluated.
Return type:	bool

copy(self, coords=None, label=None)[source]¶

Create a shallow copy of this line string.

Parameters:	coords (None or iterable of tuple of number or ndarray) – If not `None`, then the coords of the copied object will be set to this value. label (None or str) – If not `None`, then the label of the copied object will be set to this value.
Returns:	Shallow copy.
Return type:	imgaug.augmentables.lines.LineString

deepcopy(self, coords=None, label=None)[source]¶

Create a deep copy of this line string.

Parameters:	coords (None or iterable of tuple of number or ndarray) – If not `None`, then the coords of the copied object will be set to this value. label (None or str) – If not `None`, then the label of the copied object will be set to this value.
Returns:	Deep copy.
Return type:	imgaug.augmentables.lines.LineString

draw_heatmap_array(self, image_shape, alpha_lines=1.0, alpha_points=1.0, size_lines=1, size_points=0, antialiased=True, raise_if_out_of_image=False)[source]¶

Draw the line segments and points of the line string as a heatmap array.

Parameters:	image_shape (tuple of int) – The shape of the image onto which to draw the line mask. alpha_lines (float, optional) – Opacity of the line string. Higher values denote a more visible line string. alpha_points (float, optional) – Opacity of the line string points. Higher values denote a more visible points. size_lines (int, optional) – Thickness of the line segments. size_points (int, optional) – Size of the points in pixels. antialiased (bool, optional) – Whether to draw the line with anti-aliasing activated. raise_if_out_of_image (bool, optional) – Whether to raise an error if the line string 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:	`float32` array of shape image_shape (no channel axis) with drawn line segments and points. All values are in the interval `[0.0, 1.0]`.
Return type:	ndarray

draw_lines_heatmap_array(self, image_shape, alpha=1.0, size=1, antialiased=True, raise_if_out_of_image=False)[source]¶

Draw the line segments of this line string as a heatmap array.

Parameters:	image_shape (tuple of int) – The shape of the image onto which to draw the line mask. alpha (float, optional) – Opacity of the line string. Higher values denote a more visible line string. size (int, optional) – Thickness of the line segments. antialiased (bool, optional) – Whether to draw the line with anti-aliasing activated. raise_if_out_of_image (bool, optional) – Whether to raise an error if the line string 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:	`float32` array of shape image_shape (no channel axis) with drawn line string. All values are in the interval `[0.0, 1.0]`.
Return type:	ndarray

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

Draw the line segments of this line string on a given image.

Parameters:	image (ndarray or tuple of int) – The image onto which to draw. Expected to be `uint8` and of shape `(H, W, C)` with `C` usually being `3` (other values are not tested). If a tuple, expected to be `(H, W, C)` and will lead to a new `uint8` array of zeros being created. color (int or iterable of int) – Color to use as RGB, i.e. three values. alpha (float, optional) – Opacity of the line string. Higher values denote a more visible line string. size (int, optional) – Thickness of the line segments. antialiased (bool, optional) – Whether to draw the line with anti-aliasing activated. raise_if_out_of_image (bool, optional) – Whether to raise an error if the line string 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 line drawn on it.
Return type:	ndarray

draw_mask(self, image_shape, size_lines=1, size_points=0, raise_if_out_of_image=False)[source]¶

Draw this line segment as a binary image mask.

Parameters:	image_shape (tuple of int) – The shape of the image onto which to draw the line mask. size_lines (int, optional) – Thickness of the line segments. size_points (int, optional) – Size of the points in pixels. raise_if_out_of_image (bool, optional) – Whether to raise an error if the line string 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:	Boolean line mask of shape image_shape (no channel axis).
Return type:	ndarray

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

Draw this line string onto an image.

Parameters:	image (ndarray) – The (H,W,C) uint8 image onto which to draw the line string. color (iterable of int, optional) – Color to use as RGB, i.e. three values. The color of the line and points are derived from this value, unless they are set. color_lines (None or iterable of int) – Color to use for the line segments as RGB, i.e. three values. If `None`, this value is derived from color. color_points (None or iterable of int) – Color to use for the points as RGB, i.e. three values. If `None`, this value is derived from `0.5 * color`. alpha (float, optional) – Opacity of the line string. Higher values denote more visible points. The alphas of the line and points are derived from this value, unless they are set. alpha_lines (None or float, optional) – Opacity of the line string. Higher values denote more visible line string. If `None`, this value is derived from alpha. alpha_points (None or float, optional) – Opacity of the line string points. Higher values denote more visible points. If `None`, this value is derived from alpha. size (int, optional) – Size of the line string. 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 line segments. If `None`, this value is derived from size. size_points (None or int, optional) – Size of the points in pixels. If `None`, this value is derived from `3 * size`. antialiased (bool, optional) – Whether to draw the line with anti-aliasing activated. This does currently not affect the point drawing. raise_if_out_of_image (bool, optional) – Whether to raise an error if the line string 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 line string drawn on it.
Return type:	ndarray

draw_points_heatmap_array(self, image_shape, alpha=1.0, size=1, raise_if_out_of_image=False)[source]¶

Draw the points of this line string as a heatmap array.

Parameters:	image_shape (tuple of int) – The shape of the image onto which to draw the point mask. alpha (float, optional) – Opacity of the line string points. Higher values denote a more visible points. size (int, optional) – Size of the points in pixels. raise_if_out_of_image (bool, optional) – Whether to raise an error if the line string 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:	`float32` array of shape image_shape (no channel axis) with drawn line string points. All values are in the interval `[0.0, 1.0]`.
Return type:	ndarray

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

Draw the points of this line string onto a given image.

Parameters:	image (ndarray or tuple of int) – The image onto which to draw. Expected to be `uint8` and of shape `(H, W, C)` with `C` usually being `3` (other values are not tested). If a tuple, expected to be `(H, W, C)` and will lead to a new `uint8` array of zeros being created. color (iterable of int) – Color to use as RGB, i.e. three values. alpha (float, optional) – Opacity of the line string points. Higher values denote a more visible points. size (int, optional) – Size of the points in pixels. copy (bool, optional) – Whether it is allowed to draw directly in the input array (`False`) or it has to be copied (`True`). The routine may still have to copy, even if `copy=False` was used. Always use the return value. raise_if_out_of_image (bool, optional) – Whether to raise an error if the line string 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:	`float32` array of shape image_shape (no channel axis) with drawn line string points. All values are in the interval `[0.0, 1.0]`.
Return type:	ndarray

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

Extract all image pixels covered by the line string.

This will only extract pixels overlapping with the line string. As a rectangular image array has to be returned, non-overlapping pixels will be set to zero.

This function will by default zero-pad the image if the line string is partially/fully outside of the image. This is for consistency with the same methods for bounding boxes and polygons.

Parameters:	image (ndarray) – The image of shape (H,W,[C]) from which to extract the pixels within the line string. size (int, optional) – Thickness of the line. 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. antialiased* (bool, optional) – Whether to apply anti-aliasing to the line string. prevent_zero_size (bool, optional) – Whether to prevent height or width of the extracted image from becoming zero. If this is set to `True` and height or width of the line string 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 overlapping with the line string. Zero-padded if the line string is partially/fully outside of the image and `pad=True`. 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

find_intersections_with(self, other)[source]¶

Find all intersection points between this line string and other.

Parameters:	other (tuple of number or list of tuple of number or list of LineString or LineString) – The other geometry to use during intersection tests.
Returns:	All intersection points. One list per pair of consecutive start and end point, i.e. N-1 lists of N points. Each list may be empty or may contain multiple points.
Return type:	list of list of tuple of number

get_pointwise_inside_image_mask(self, image)[source]¶

Determine per point whether it is inside of a given image plane.

Parameters:	image (ndarray or tuple of int) – Either an image with shape `(H,W,[C])` or a `tuple` denoting such an image shape.
Returns:	(N,) ``bool array with one value for each of the `N` points indicating whether it is inside of the provided image plane (`True`) or not (`False`).
Return type:	ndarray

height¶

Compute the height of a bounding box encapsulating the line.

The height is computed based on the two points with lowest and largest y-coordinates.

Returns:	The height of the line string.
Return type:	float

is_fully_within_image(self, image, default=False)[source]¶

Estimate whether the line string is fully inside an image plane.

Parameters:	image (ndarray or tuple of int) – Either an image with shape `(H,W,[C])` or a `tuple` denoting such an image shape. default (any) – Default value to return if the line string contains no points.
Returns:	`True` if the line string is fully inside the image area. `False` otherwise. Will return default if this line string contains no points.
Return type:	bool or any

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

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

Parameters:	image (ndarray or tuple of int) – Either an image with shape `(H,W,[C])` or a tuple denoting such an image shape. fully (bool, optional) – Whether to return `True` if the line string is fully outside of the image area. partly (bool, optional) – Whether to return `True` if the line string is at least partially outside fo the image area. default (any) – Default value to return if the line string contains no points.
Returns:	`True` if the line string is partially/fully outside of the image area, depending on defined parameters. `False` otherwise. Will return default if this line string contains no points.
Return type:	bool or any

is_partly_within_image(self, image, default=False)[source]¶

Estimate whether the line string is at least partially inside the image.

Parameters:	image (ndarray or tuple of int) – Either an image with shape `(H,W,[C])` or a `tuple` denoting such an image shape. default (any) – Default value to return if the line string contains no points.
Returns:	`True` if the line string is at least partially inside the image area. `False` otherwise. Will return default if this line string contains no points.
Return type:	bool or any

length¶

Compute the total euclidean length of the line string.

Returns:	The length based on euclidean distance, i.e. the sum of the lengths of each line segment.
Return type:	float

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

Project the line string onto a differently shaped image.

E.g. if a point of the line string 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 (x=20, y=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 or ndarray) – Shape of the original image. (Before resize.) to_shape (tuple of int or ndarray) – Shape of the new image. (After resize.)
Returns:	Line string with new coordinates.
Return type:	imgaug.augmentables.lines.LineString

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

Project the line string onto a differently shaped image in-place.

E.g. if a point of the line string 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 (x=20, y=40).

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:	Line string with new coordinates. The object may have been modified in-place.
Return type:	imgaug.augmentables.lines.LineString

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

Move this line string 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:	result – Shifted line string.
Return type:	imgaug.augmentables.lines.LineString

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

Move this line string 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:	result – Shifted line string. The object may have been modified in-place.
Return type:	imgaug.augmentables.lines.LineString

subdivide(self, points_per_edge)[source]¶

Derive a new line string with N interpolated points per edge.

The interpolated points have (per edge) regular distances to each other.

For each edge between points A and B this adds points at A + (i/(1+N)) * (B - A), where i is the index of the added point and N is the number of points to add per edge.

Calling this method two times will split each edge at its center and then again split each newly created edge at their center. It is equivalent to calling subdivide(3).

Parameters:	points_per_edge (int) – Number of points to interpolate on each edge.
Returns:	Line string with subdivided edges.
Return type:	imgaug.augmentables.lines.LineString

to_bounding_box(self)[source]¶

Generate a bounding box encapsulating the line string.

Returns:	Bounding box encapsulating the line string. `None` if the line string contained no points.
Return type:	None or imgaug.augmentables.bbs.BoundingBox

to_heatmap(self, image_shape, size_lines=1, size_points=0, antialiased=True, raise_if_out_of_image=False)[source]¶

Generate a heatmap object from the line string.

This is similar to draw_lines_heatmap_array(), executed with alpha=1.0. The result is wrapped in a HeatmapsOnImage object instead of just an array. No points are drawn.

Parameters:	image_shape (tuple of int) – The shape of the image onto which to draw the line mask. size_lines (int, optional) – Thickness of the line. size_points (int, optional) – Size of the points in pixels. antialiased (bool, optional) – Whether to draw the line with anti-aliasing activated. raise_if_out_of_image (bool, optional) – Whether to raise an error if the line string 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:	Heatmap object containing drawn line string.
Return type:	imgaug.augmentables.heatmaps.HeatmapsOnImage

to_keypoints(self)[source]¶

Convert the line string points to keypoints.

Returns:	Points of the line string as keypoints.
Return type:	list of imgaug.augmentables.kps.Keypoint

to_polygon(self)[source]¶

Generate a polygon from the line string points.

Returns:	Polygon with the same corner points as the line string. Note that the polygon might be invalid, e.g. contain less than `3` points or have self-intersections.
Return type:	imgaug.augmentables.polys.Polygon

to_segmentation_map(self, image_shape, size_lines=1, size_points=0, raise_if_out_of_image=False)[source]¶

Generate a segmentation map object from the line string.

This is similar to draw_mask(). The result is wrapped in a SegmentationMapsOnImage object instead of just an array.

Parameters:	image_shape (tuple of int) – The shape of the image onto which to draw the line mask. size_lines (int, optional) – Thickness of the line. size_points (int, optional) – Size of the points in pixels. raise_if_out_of_image (bool, optional) – Whether to raise an error if the line string 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:	Segmentation map object containing drawn line string.
Return type:	imgaug.augmentables.segmaps.SegmentationMapsOnImage

width¶

Compute the width of a bounding box encapsulating the line.

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

Returns:	The width of the line string.
Return type:	float

xx¶

Get an array of x-coordinates of all points of the line string.

Returns:	`float32` x-coordinates of the line string points.
Return type:	ndarray

xx_int¶

Get an array of discrete x-coordinates of all points.

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 the line string points.
Return type:	ndarray

yy¶

Get an array of y-coordinates of all points of the line string.

Returns:	`float32` y-coordinates of the line string points.
Return type:	ndarray

yy_int¶

Get an array of discrete y-coordinates of all points.

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 the line string points.
Return type:	ndarray

class imgaug.augmentables.lines.LineStringsOnImage(line_strings, shape)[source]¶

Bases: imgaug.augmentables.base.IAugmentable

Object that represents all line strings on a single image.

Parameters:	line_strings (list of imgaug.augmentables.lines.LineString) – List of line strings 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.lines import LineString, LineStringsOnImage
>>>
>>> image = np.zeros((100, 100))
>>> lss = [
>>>     LineString([(0, 0), (10, 0)]),
>>>     LineString([(10, 20), (30, 30), (50, 70)])
>>> ]
>>> lsoi = LineStringsOnImage(lss, shape=image.shape)

Attributes:	`empty` Estimate whether this object contains zero line strings. `items` Get the line strings in this container.

Methods

`clip_out_of_image`(self)	Clip off all parts of the line strings that are outside of an image.
`clip_out_of_image_`(self)	Clip off all parts of the LSs that are outside of an image in-place.
`copy`(self[, line_strings, shape])	Create a shallow copy of this object.
`deepcopy`(self[, line_strings, shape])	Create a deep copy of the object.
`draw_on_image`(self, image[, color, …])	Draw all line strings onto a given image.
`fill_from_xy_array_`(self, xy)	Modify the corner coordinates of all line strings in-place.
`from_xy_arrays`(xy, shape)	Convert an `(N,M,2)` ndarray to a `LineStringsOnImage` object.
`invert_to_keypoints_on_image_`(self, kpsoi)	Invert the output of `to_keypoints_on_image()` in-place.
`on`(self, image)	Project the line strings from one image shape to a new one.
`on_`(self, image)	Project the line strings from one image shape to a new one in-place.
`remove_out_of_image`(self[, fully, partly])	Remove all line strings that are fully/partially outside of an image.
`remove_out_of_image_`(self[, fully, partly])	Remove all LS that are fully/partially outside of an image in-place.
`remove_out_of_image_fraction`(self, fraction)	Remove all LS with an out of image fraction of at least fraction.
`remove_out_of_image_fraction_`(self, fraction)	Remove all LS with an OOI fraction of at least fraction in-place.
`shift`(self[, x, y, top, right, bottom, left])	Move the line strings along the x/y-axis.
`shift_`(self[, x, y])	Move the line strings along the x/y-axis in-place.
`to_keypoints_on_image`(self)	Convert the line strings to one `KeypointsOnImage` instance.
`to_xy_array`(self)	Convert all line string coordinates to one array of shape `(N,2)`.
`to_xy_arrays`(self[, dtype])	Convert this object to an iterable of `(M,2)` arrays of points.

clip_out_of_image(self)[source]¶

Clip off all parts of the line strings that are outside of an image.

Note

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

Note

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

Returns:	Line strings, clipped to fall within the image dimensions. The count of output line strings may differ from the input count.
Return type:	imgaug.augmentables.lines.LineStringsOnImage

clip_out_of_image_(self)[source]¶

Clip off all parts of the LSs that are outside of an image in-place.

Note

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

Note

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

Added in 0.4.0.

Returns:	Line strings, clipped to fall within the image dimensions. The count of output line strings may differ from the input count.
Return type:	imgaug.augmentables.lines.LineStringsOnImage

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

Create a shallow copy of this object.

Parameters:	line_strings (None or list of imgaug.augmentables.lines.LineString, optional) – List of line strings on the image. If not `None`, then the `line_strings` 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.lines.LineStringsOnImage

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

Create a deep copy of the object.

Parameters:	line_strings (None or list of imgaug.augmentables.lines.LineString, optional) – List of line strings on the image. If not `None`, then the `line_strings` 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.lines.LineStringsOnImage

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

Draw all line strings onto a given image.

Parameters:	image (ndarray) – The `(H,W,C)` `uint8` image onto which to draw the line strings. color (iterable of int, optional) – Color to use as RGB, i.e. three values. The color of the lines and points are derived from this value, unless they are set. color_lines (None or iterable of int) – Color to use for the line segments as RGB, i.e. three values. If `None`, this value is derived from color. color_points (None or iterable of int) – Color to use for the points as RGB, i.e. three values. If `None`, this value is derived from `0.5 * color`. alpha (float, optional) – Opacity of the line strings. Higher values denote more visible points. The alphas of the line and points are derived from this value, unless they are set. alpha_lines (None or float, optional) – Opacity of the line strings. Higher values denote more visible line string. If `None`, this value is derived from alpha. alpha_points (None or float, optional) – Opacity of the line string points. Higher values denote more visible points. If `None`, this value is derived from alpha. size (int, optional) – Size of the line strings. 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 line segments. If `None`, this value is derived from size. size_points (None or int, optional) – Size of the points in pixels. If `None`, this value is derived from `3 * size`. antialiased (bool, optional) – Whether to draw the lines with anti-aliasing activated. This does currently not affect the point drawing. raise_if_out_of_image (bool, optional) – Whether to raise an error if a line string 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 line strings drawn on it.
Return type:	ndarray

empty¶

Estimate whether this object contains zero line strings.

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

fill_from_xy_array_(self, xy)[source]¶

Modify the corner coordinates of all line strings in-place.

Note

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

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 line strings within this instance.
Returns:	This instance itself, with updated coordinates. Note that the instance was modified in-place.
Return type:	LineStringsOnImage

classmethod from_xy_arrays(xy, shape)[source]¶

Convert an (N,M,2) ndarray to a LineStringsOnImage object.

This is the inverse of to_xy_array().

Parameters:	xy ((N,M,2) ndarray or iterable of (M,2) ndarray) – Array containing the point coordinates `N` line strings with each `M` points given as `(x,y)` coordinates. `M` may differ if an iterable of arrays is used. Each array should usually be of dtype `float32`. shape (tuple of int) – `(H,W,[C])` shape of the image on which the line strings are placed.
Returns:	Object containing a list of `LineString` objects following the provided point coordinates.
Return type:	imgaug.augmentables.lines.LineStringsOnImage

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 LineStringsOnImage instance.

Added in 0.4.0.

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

items¶

Get the line strings in this container.

Added in 0.4.0.

Returns:	Line strings within this container.
Return type:	list of LineString

on(self, image)[source]¶

Project the line strings from one image shape to a new one.

Parameters:	image (ndarray or tuple of int) – The new image onto which to project. Either an image with shape `(H,W,[C])` or a tuple denoting such an image shape.
Returns:	Object containing all projected line strings.
Return type:	imgaug.augmentables.lines.LineStrings

on_(self, image)[source]¶

Project the line strings from one image shape to a new one in-place.

Added in 0.4.0.

Parameters:	image (ndarray or tuple of int) – The new image onto which to project. Either an image with shape `(H,W,[C])` or a tuple denoting such an image shape.
Returns:	Object containing all projected line strings. The object and its items may have been modified in-place.
Return type:	imgaug.augmentables.lines.LineStrings

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

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

Parameters:	fully (bool, optional) – Whether to remove line strings that are fully outside of the image. partly (bool, optional) – Whether to remove line strings that are partially outside of the image.
Returns:	Reduced set of line strings. Those that are fully/partially outside of the given image plane are removed.
Return type:	imgaug.augmentables.lines.LineStringsOnImage

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

Remove all LS that are fully/partially outside of an image in-place.

Added in 0.4.0.

Parameters:	fully (bool, optional) – Whether to remove line strings that are fully outside of the image. partly (bool, optional) – Whether to remove line strings that are partially outside of the image.
Returns:	Reduced set of line strings. 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.lines.LineStringsOnImage

remove_out_of_image_fraction(self, fraction)[source]¶

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

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

remove_out_of_image_fraction_(self, fraction)[source]¶

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

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

Added in 0.4.0.

Parameters:	fraction (number) – Minimum out of image fraction that a line string has to have in order to be removed. A fraction of `1.0` removes only line strings that are `100%` outside of the image. A fraction of `0.0` removes all line strings.
Returns:	Reduced set of line strings, 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.lines.LineStringsOnImage

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

Move the line strings 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 line strings.
Return type:	imgaug.augmentables.lines.LineStringsOnImage

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

Move the line strings 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 line strings. The object and its items may have been modified in-place.
Return type:	imgaug.augmentables.lines.LineStringsOnImage

to_keypoints_on_image(self)[source]¶

Convert the line strings to one KeypointsOnImage instance.

Added in 0.4.0.

Returns:	A keypoints instance containing `N` coordinates for a total of `N` points in the `coords` attributes of all line strings. Order matches the order in `line_strings` and `coords` attributes.
Return type:	imgaug.augmentables.kps.KeypointsOnImage

to_xy_array(self)[source]¶

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

Added in 0.4.0.

Returns:	Array containing all xy-coordinates of all line strings within this instance.
Return type:	(N, 2) ndarray

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

Convert this object to an iterable of (M,2) arrays of points.

This is the inverse of from_xy_array().

Parameters:	dtype (numpy.dtype, optional) – Desired output datatype of the ndarray.
Returns:	The arrays of point coordinates, each given as `(M,2)`.
Return type:	list of ndarray