Drawing#

kornia.image.draw_line(image, p1, p2, color)[source]#

Draw a line, or one line per row of (B, 2) endpoints, into an image.

Convention:

Points are \((x, y)\), x the column and y the row, with pixel centres at integer coordinates, as in Coordinates and sizes. A fractional endpoint goes to the pixel whose centre is nearest, a coordinate exactly halfway rounding up.
A line has one pixel per step along its longer axis: the pixel whose centre is nearest to the segment between the two endpoint pixels, a tie going to the larger coordinate. The line is therefore the same from p1 to p2 as from p2 to p1, and both endpoints are drawn.
The image is one \((C, H, W)\) tensor, and (B, 2) endpoints draw B lines into it. An endpoint outside the image raises ValueError; nothing is clipped.
The colour is cast to the image’s dtype without rescaling or a range check, and a single value is written to every channel.
The image is drawn in place and returned.
Drawing compares these rules with OpenCV, Pillow and torchvision.

Parameters:

image (Tensor) – the input image to where to draw the lines with shape \((C,H,W)\).
p1 (Tensor) – the start point [x y] of the line with shape (2, ) or (B, 2).
p2 (Tensor) – the end point [x y] of the line, with the same shape as p1.
color (Tensor) – the color of the line with shape \((C)\) where \(C\) is the number of channels of the image, or a single value with shape \((1)\) or 0-d.

Return type:

Tensor

Returns:

The image containing the line.

Raises:

ValueError – if p1 and p2 differ in shape, or their last dimension is not 2.
ValueError – if an endpoint lies outside the image after rounding, or the image is not (C, H, W).
ValueError – if color has neither 1 nor C values.

Examples

>>> image = torch.zeros(1, 8, 8)
>>> draw_line(image, torch.tensor([6, 4]), torch.tensor([1, 4]), torch.tensor([255]))
tensor([[[  0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.],
         [  0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.],
         [  0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.],
         [  0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.],
         [  0., 255., 255., 255., 255., 255., 255.,   0.],
         [  0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.],
         [  0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.],
         [  0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.]]])

kornia.image.draw_rectangle(image, rectangle, color=None, fill=None, line_width=1)[source]#

Draw N rectangles on a batch of image tensors.

Convention:

A rectangle is [x1, y1, x2, y2], its two corners in either order and both included, with the coordinates rounded as in draw_line(). Each side of the outline is line_width pixels thick and grows inward, so the outline stays inside the rectangle; a side thicker than the rectangle covers it. The outline and a fill are clipped to the image: the part of a side that lies outside the image is not drawn, and neither raises.
The corners are rounded and the vertices of draw_convex_polygon() are not, so a filled rectangle and the same polygon always agree for integer corners; for fractional ones each side can be one row or column apart, so a polygon thinner than a pixel can fill nothing.
The colour and the in-place drawing follow draw_line().

Parameters:

image (Tensor) – the images, \((B, C, H, W)\).
rectangle (Tensor) – the rectangles, \((B, N, 4)\): N per image, each [x1, y1, x2, y2].
color (Optional[Tensor], optional) – the colour, \((C)\) or \((B, N, C)\), or a single value (0-d, \((1)\) or \((B, N, 1)\)). Black by default. Default: None
fill (Optional[bool], optional) – whether to fill the rectangles instead of drawing their outlines. Default: None
line_width (int, optional) – the thickness of each side of the outline in pixels, a positive integer. Ignored when fill=True. Default: 1

Raises:

ShapeError – if the image is not (B, C, H, W). It is also a ValueError.
ValueError – if rectangle is not (B, N, 4), or its batch size differs from the image’s.
ValueError – if line_width is not a positive int.

Return type:

Tensor

Returns:

This operation modifies image inplace but also returns the drawn tensor for convenience, with the shape of the input \((B, C, H, W)\).

Example

>>> img = torch.rand(2, 3, 10, 12)
>>> rect = torch.tensor([[[0, 0, 4, 4]], [[4, 4, 11, 9]]])
>>> out = draw_rectangle(img, rect)
>>> thick_out = draw_rectangle(img.clone(), rect, line_width=2)

kornia.image.draw_convex_polygon(images, polygons, colors)[source]#

Draws convex polygons on a batch of image tensors.

Convention:

Vertices are \((x, y)\) in the pixel frame of draw_line(), used as given, without rounding. A pixel is filled when its centre lies inside the polygon or on its boundary, as skimage.draw.polygon fills; cv2.fillConvexPoly fills more. The part outside the image is clipped.
The polygon is taken to be convex: each row is filled from its leftmost to its rightmost edge crossing, so in a concave polygon a gap between two edges within a row is filled too.
The polygons and the colours must already be on the images’ device; the other draw functions move theirs.
The colour and the in-place drawing follow draw_line().

Parameters:

images (Tensor) – is tensor of BxCxHxW.
polygons (Union[Tensor, List[Tensor]]) – represents polygons as points, either BxNx2 or List of variable length polygons. N is the number of points. 2 is (x, y).
colors (Tensor) – the fill colours, \((B, C)\) or \((C)\), or a single value (0-d, \((1)\) or \((B, 1)\)).

Return type:

Tensor

Returns:

This operation modifies image inplace but also returns the drawn tensor for convenience, with the shape of the input \((B, C, H, W)\).

Raises:

ShapeError – if the images are not (B, C, H, W). It is also a ValueError.
ValueError – if polygons is a tensor that is not three dimensional.
BaseError – if the vertices are not (x, y) points.
BaseError – if the images, polygons and colors differ in batch size or device.

Example

>>> img = torch.rand(1, 3, 12, 16)
>>> poly = torch.tensor([[[4, 4], [12, 4], [12, 8], [4, 8]]])
>>> color = torch.tensor([[0.5, 0.5, 0.5]])
>>> out = draw_convex_polygon(img, poly, color)

kornia.image.draw_point2d(image, points, color)[source]#

Set one or more coordinates in a Tensor to a color.

Convention:: See the Convention block of draw_line() for the coordinates, the rounding, the colour and the in-place drawing. The image is \((C, H, W)\) or \((H, W)\).

Parameters:

image (Tensor) – the input image on which to draw the points with shape \((C,H,W)\) or \((H,W)\).
points (Tensor) – the [x, y] points to be drawn on the image with shape \((N, 2)\), a single point with shape \((2,)\), or an empty tensor with shape \((0, 2)\).
color (Tensor) – the color of the pixel with \((C)\) where \(C\) is the number of channels of the image, or a single value with shape \((1)\) or 0-d.

Return type:

Tensor

Returns:

The image with points set to the color. This operation modifies image inplace but also returns the drawn tensor for convenience. An empty point set leaves the image unchanged.

Raises:

ValueError – if the image is not (C, H, W) or (H, W), or a point lies outside the image after rounding.
BaseError – if color has neither 1 nor C values, or points is not (2,) or (N, 2).