Drawing#

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

Draw one-pixel segments between pairs of (x, y) points into one image, in place.

image = draw_line(image, p1, p2, color) draws the segment from p1 to p2, two \((x, y)\) points of shape (2,), or one segment per row of (B, 2) endpoints, into one (C, H, W) image and returns the same tensor. For a box outline thicker than one pixel, use draw_rectangle() with line_width.

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.
Nothing is clipped: an endpoint must lie in the image after rounding.
The color 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.

See also

draw_point2d(): colors the given points only, also in an (H, W) image.
draw_convex_polygon(): fills a polygon instead of drawing its edges.

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 or fill axis-aligned rectangles on a batch of images, in place.

image = draw_rectangle(image, rectangle, color) draws N rectangles per image, (B, N, 4) as [x1, y1, x2, y2], on (B, C, H, W) images and returns the same tensor: outlines line_width pixels thick, or filled boxes with fill=True. A rectangle that leaves the image is clipped instead of raising.

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.
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 color 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 color, (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.
BaseError – if color has neither 1 nor C values per rectangle.

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

See also

draw_convex_polygon(): fills any convex shape, one per image, with unrounded vertices.
draw_line(): draws one-pixel segments, whose endpoints must lie in the image.

Note

The rectangle coordinates are read back to the host once, and torch.compile breaks the graph there: a default torch.compile compiles the code on either side of that read and matches eager. It is outside the torch.compile promise.

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]#

Fill one convex polygon per image on a batch of images, in place.

images = draw_convex_polygon(images, polygons, colors) fills polygon b on image b of a (B, C, H, W) batch and returns the same tensor. The \((x, y)\) vertices are a (B, N, 2) tensor or a list of B tensors of shape (N_b, 2).

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 colors must already be on the images’ device; the other draw functions move theirs.
The color 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 colors, (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 colors has neither 1 nor C values per polygon.
BaseError – if the vertices are not (x, y) points.
BaseError – if the images, polygons and colors differ in batch size or device.

See also

draw_rectangle(): draws outlines as well as fills, and several rectangles per image.
draw_line(): draws the edges of a polygon as one-pixel segments.

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]#

Color the pixels at a set of (x, y) points of one image, in place.

image = draw_point2d(image, points, color) writes color into the pixel nearest to each \((x, y)\) point of points, (N, 2) or (2,), in one (C, H, W) or (H, W) image, and returns the same tensor.

Convention:: See the Convention block of draw_line() for the coordinates, the rounding, the color and the in-place drawing.

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 (an (H, W) image has one channel), or points is not (2,) or (N, 2).

See also

draw_line(): draws the pixels between two points, and states the rules both functions follow.

Example

>>> image = torch.zeros(1, 3, 4)
>>> draw_point2d(image, torch.tensor([[0, 1], [3, 2]]), torch.tensor([1.0]))
tensor([[[0., 0., 0., 0.],
         [1., 0., 0., 0.],
         [0., 0., 0., 1.]]])