Image container

class kornia.image.ImageSize(height, width)

Data class to represent the size of an image, without its channels.

Convention:

See the Convention block of Image. The positional order is (height, width), kornia’s order for sizes and the reverse of \((x, y)\) points.

Parameters:

• height (int | Tensor) – image height.

• width (int | Tensor) – image width.

Example

>>> size = ImageSize(3, 4)
>>> size.height
3
>>> size.width
4

height: int | Tensor

width: int | Tensor

class kornia.image.PixelFormat(color_space, bit_depth)

Data class to represent the pixel format of an image.

Convention:

See the Convention block of Image, which checks a pixel format against the data; the data class itself checks nothing.

Parameters:

• color_space (ColorSpace) – color space.

• bit_depth (int) – the storage size of one channel value in bits, 8 * element_size() of the data: 8 for uint8, 32 for float32.

Example

>>> pixel_format = PixelFormat(ColorSpace.RGB, 8)
>>> pixel_format.color_space
<ColorSpace.RGB: 2>
>>> pixel_format.bit_depth
8

bit_depth: int

color_space: ColorSpace

class kornia.image.ColorSpace(value)

Enum that represents the color space of an image.

Convention:

See the Convention block of Image, which checks the color space against the channel count. There is no color space with alpha: a 4-channel image is UNKNOWN.

BGR = 3

GRAY = 1

RGB = 2

UNKNOWN = 0

class kornia.image.ChannelsOrder(value)

Enum that represents the channels order of an image.

Convention:

See the Convention block of Image. CHANNELS_FIRST stores \((C, H, W)\) and CHANNELS_LAST stores \((H, W, C)\).

CHANNELS_FIRST = 0

CHANNELS_LAST = 1

class kornia.image.ImageLayout(image_size, channels, channels_order)

Data class to represent the layout of an image.

Convention:

See the Convention block of Image, which checks a layout against the data; the data class itself checks nothing.

Parameters:

• image_size (ImageSize) – image size.

• channels (int) – number of channels.

• channels_order (ChannelsOrder) – channels order.

Example

>>> layout = ImageLayout(ImageSize(3, 4), 3, ChannelsOrder.CHANNELS_LAST)
>>> layout.image_size
ImageSize(height=3, width=4)
>>> layout.channels
3
>>> layout.channels_order
<ChannelsOrder.CHANNELS_LAST: 1>

channels: int

channels_order: ChannelsOrder

image_size: ImageSize

class kornia.image.Image(data, pixel_format, layout)

Class that holds an Image torch.Tensor representation.

Warning

This API is experimental and might suffer changes in the future.

Convention:

• An Image holds one image, \((C, H, W)\) or \((H, W, C)\) as layout.channels_order says, never a batch: a 4-D tensor raises ShapeError. The layout and the pixel format are checked against the data: bit_depth is the storage size, 8 * data.element_size(), and the color space must fit the channel count, 1 for GRAY, 3 for RGB and BGR, any for UNKNOWN.

• from_numpy(), to_numpy(), from_dlpack() and to_dlpack() share memory with the array or capsule of a CPU image. to_numpy() returns the stored layout, so an image from from_file() gives \((C, H, W)\).

• to_gray(), to_rgb() and to_bgr() return the image itself when it is already in that color space, an image with new data when it is in another of the three, and raise ValueError for UNKNOWN. Converting RGB or BGR to gray requires uint8 or a floating dtype supported by rgb_to_grayscale(); other integer dtypes, such as uint16, are unsupported even though Image can hold them. An already-gray image is returned unchanged regardless of dtype. to(), float() and clone() return a new Image and leave this one unchanged.

Parameters:

• data (Tensor) – a torch.Tensor containing the image data.

• pixel_format (PixelFormat) – the pixel format of the image.

• layout (ImageLayout) – a dataclass containing the image layout information.

Examples

>>> # from a torch.tensor
>>> data = torch.randint(0, 255, (3, 4, 5), dtype=torch.uint8)  # CxHxW
>>> pixel_format = PixelFormat(
...     color_space=ColorSpace.RGB,
...     bit_depth=8,
... )
>>> layout = ImageLayout(
...     image_size=ImageSize(4, 5),
...     channels=3,
...     channels_order=ChannelsOrder.CHANNELS_FIRST,
... )
>>> img = Image(data, pixel_format, layout)
>>> assert img.channels == 3

>>> # from a numpy array (like opencv)
>>> data = np.ones((4, 5, 3), dtype=np.uint8)  # HxWxC
>>> img = Image.from_numpy(data, color_space=ColorSpace.RGB)
>>> assert img.channels == 3
>>> assert img.width == 5
>>> assert img.height == 4

property channels: int

Return the number channels of the image.

property channels_order: ChannelsOrder

Return the channels order.

clone()

Return a copy of the image.

Return type:

Image

property data: Tensor

Return the underlying torch.Tensor data.

property device: device

Return the image device.

property dtype: dtype

Return the image data type.

float()

Return the image as float32; the image itself is not changed.

Return type:

Image

classmethod from_dlpack(data)

Construct an Image from a DLPack capsule, sharing its memory.

Parameters:

data (Any) – a DLPack capsule from numpy, tvm or jax. The capsule must hold a (C, H, W) image; it is labelled GRAY for 1 channel, RGB for 3 and UNKNOWN otherwise.

Raises:

• ShapeError – if the capsule has more than three dimensions. It is also a ValueError.

• IndexError – if the capsule has fewer than three dimensions.

Return type:

Image

Example

>>> x = np.ones((3, 4, 5))  # (C, H, W)
>>> img = Image.from_dlpack(x.__dlpack__())
>>> img.channels, img.height, img.width
(3, 4, 5)

classmethod from_file(file_path)

Construct an Image from a file.

The file is loaded with load_image() as ImageLoadType.RGB8: the image is \((3, H, W)\) uint8, RGB and CHANNELS_FIRST, on the CPU.

Parameters:

file_path (str | Path) – the path to the file to read the image from.

Return type:

Image

classmethod from_numpy(data, color_space=None, channels_order=ChannelsOrder.CHANNELS_LAST)

Construct an Image from a numpy array, sharing its memory.

Parameters:

• data (Any) – a numpy array containing the image data.

• color_space (Optional[ColorSpace], optional) – the color space of the image. If None, a 1-channel array is GRAY, a 3-channel array is RGB and any other channel count is UNKNOWN. An explicit color space that does not match the channel count raises. Default: None

• channels_order (ChannelsOrder, optional) – what dimension the channels are in the image torch.Tensor. Default: ChannelsOrder.CHANNELS_LAST

Raises:

• ValueError – if channels_order is neither CHANNELS_LAST nor CHANNELS_FIRST.

• ValueCheckError – if an explicit color_space does not match the channel count (also a ValueError).

• ShapeError – if data has more than three dimensions. It is also a ValueError.

• IndexError – if data has fewer than two dimensions.

Return type:

Image

Example

>>> data = np.ones((4, 5, 3), dtype=np.uint8)  # HxWxC
>>> img = Image.from_numpy(data, color_space=ColorSpace.RGB)
>>> assert img.channels == 3
>>> assert img.width == 5
>>> assert img.height == 4

property height: int

Return the image height (number of rows).

property image_size: ImageSize

Return the image size.

property layout: ImageLayout

Return the image layout.

property pixel_format: PixelFormat

Return the pixel format.

print(max_width=256)

Print the image torch.Tensor to the console.

Parameters:

max_width (int, optional) – the widest image, in pixels, that is printed without resizing; see image_to_string(). Default: 256

Return type:

None

A BGR image is converted to RGB first, so the terminal shows the true colours.

img = Image.from_file("panda.png")
img.print()

property shape: tuple[int, ...]

Return the image shape.

to(device=None, dtype=None)

Return the image on device and with dtype, like torch.Tensor.to().

The image itself is not changed; assign the result (img = img.to(...)). The pixel format’s bit_depth follows the new dtype.

Parameters:

• device (Union[str, device, None], optional) – the device to move the image to. Default: None

• dtype (Optional[dtype], optional) – the data type to cast the image to. Default: None

Returns:

the image on the given device and with the given dtype.

Return type:

Image

Raises:

ValueCheckError – if the image was built with checks disabled and its color space does not fit its channels.

to_bgr()

Convert the image to BGR.

Return type:

Image

to_dlpack()

Return a DLPack capsule from the image torch.Tensor.

Return type:

Any

to_gray()

Convert the image to grayscale.

Return type:

Image

to_numpy()

Return the image data as a numpy array on the CPU, in the stored layout.

Return type:

Any

to_rgb()

Convert the image to RGB.

Return type:

Image

property width: int

Return the image width (number of columns).

write(file_path)

Write the image to a file.

The format follows the file extension; see kornia.io.write_image() for the supported formats. A BGR image is converted to RGB first, so the file holds the true colours.

Parameters:

file_path (str | Path) – the path to the file to write the image to.

Return type:

None

Example

>>> data = np.ones((4, 5, 3), dtype=np.uint8)  # HxWxC
>>> img = Image.from_numpy(data)
>>> import tempfile, os
>>> with tempfile.TemporaryDirectory() as tmp:
...     img.write(os.path.join(tmp, "test.jpg"))