Image container

class kornia.image.ImageSize(height, width)

Hold the height and width of an image, without its channels.

size = ImageSize(height, width) stores the two sizes of one image in a frozen data class, read back as size.height and size.width. The positional order is (height, width), kornia’s order for sizes and the reverse of \((x, y)\) points.

Parameters:

• height (int | Tensor) – image height in pixels, an int, a float or a one-element tensor.

• width (int | Tensor) – image width in pixels, an int, a float or a one-element tensor.

See also

• ImageLayout: holds an ImageSize together with the channel count and order.

• Image: checks the size against the shape of its data.

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)

Hold the color space of an image and the storage size of one channel value.

pixel_format = PixelFormat(color_space, bit_depth) describes the values of an Image: their ColorSpace and the bits that store one channel value. The data class checks nothing; Image raises when either field does not fit its data.

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.

See also

• ColorSpace: the values of color_space.

• ImageLayout: describes the arrangement of the values instead: size, channel count and order.

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)

Name the color space of an image: unknown, gray, RGB or BGR.

ColorSpace.RGB and its siblings label the channels of an Image through PixelFormat. Image checks the label against the channel count: GRAY needs 1 channel, RGB and BGR need 3, and UNKNOWN takes any count. No member has alpha, so a 4-channel image is UNKNOWN.

See also

• PixelFormat: pairs the color space with the bit depth.

• Image: converts between GRAY, RGB and BGR with to_gray, to_rgb and to_bgr.

BGR = 3

GRAY = 1

RGB = 2

UNKNOWN = 0

class kornia.image.ChannelsOrder(value)

Name where an image keeps its channels: first, (C, H, W), or last, (H, W, C).

ChannelsOrder.CHANNELS_FIRST is the order of kornia tensors, (C, H, W), and CHANNELS_LAST the order of NumPy and OpenCV arrays, (H, W, C). ImageLayout carries it, and Image checks the shape of its data against it.

See also

• ImageLayout: holds the order together with the size and the channel count.

CHANNELS_FIRST = 0

CHANNELS_LAST = 1

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

Hold the size, channel count and channel order of an image.

layout = ImageLayout(ImageSize(H, W), C, ChannelsOrder.CHANNELS_FIRST) describes the shape of an Image’s data. The data class checks nothing; Image raises ShapeError when its data does not have this shape.

Parameters:

• image_size (ImageSize) – image size.

• channels (int) – number of channels.

• channels_order (ChannelsOrder) – channels order.

See also

• ImageSize: the image_size field.

• ChannelsOrder: the channels_order field.

• PixelFormat: describes the values of the pixels instead of their arrangement.

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)

Hold one image tensor with its layout and color space, checked against the data.

img = Image(data, pixel_format, layout) wraps one unbatched image tensor, (C, H, W) or (H, W, C) as layout.channels_order says, and raises when the shape, the bit depth or the color space does not fit the data. from_numpy(), from_dlpack() and from_file() build the layout and the pixel format for you. kornia’s other functions take plain channels-first tensors: pass them img.data of a CHANNELS_FIRST image, or img.data[None] where they take a batch.

Warning

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

Convention:

• A batch or an (H, W) tensor raises ShapeError.

• from_numpy(), to_numpy(), from_dlpack() and to_dlpack() share memory with the array or capsule of a CPU image, except that to_numpy() copies bfloat16 data to float32 because NumPy has no bfloat16 dtype. to_numpy() and to_dlpack() return the stored layout, so an image from from_file() gives (C, H, W). Neither the array nor the capsule carries the layout or the color space: from_numpy() reads (H, W, C) and from_dlpack() reads (C, H, W) unless channels_order says otherwise, and both label the color space by channel count unless color_space is given. Pass img.pixel_format.color_space and img.channels_order to read an exported image back.

• 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, raise TypeError even though Image can hold them. 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.

See also

• load_image(): loads a file as a plain tensor, with a choice of ImageLoadType; from_file() always loads RGB8.

• image_to_tensor(): converts a NumPy array to a channels-first tensor without the container.

• ImageLayout: the shape description the constructor checks.

• PixelFormat: the value description the constructor checks.

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 without rescaling; the image itself is not changed.

A uint8 255 becomes 255.0, outside the \([0, 1]\) range that print() reads for a float image.

Return type:

Image

classmethod from_dlpack(data, color_space=None, channels_order=ChannelsOrder.CHANNELS_FIRST)

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

A capsule carries neither the layout nor the color space, so read img.to_dlpack() back with Image.from_dlpack(capsule, img.pixel_format.color_space, img.channels_order).

Parameters:

• data (Any) – a DLPack capsule from numpy, tvm or jax, holding a (C, H, W) image, or (H, W, C) with channels_order=CHANNELS_LAST.

• color_space (Optional[ColorSpace], optional) – the color space of the image. If None, a 1-channel image is GRAY, a 3-channel image 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) – the layout of the capsule. Default: ChannelsOrder.CHANNELS_FIRST

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 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)
>>> hwc = Image.from_numpy(np.ones((4, 5, 3), dtype=np.uint8))  # (H, W, C), CHANNELS_LAST
>>> back = Image.from_dlpack(hwc.to_dlpack(), hwc.pixel_format.color_space, hwc.channels_order)
>>> back.channels, back.height, back.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 colors.

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, sharing its memory.

The capsule holds the data in the image’s own channels_order, (C, H, W) or (H, W, C), and carries no color space; read it back with Image.from_dlpack(capsule, img.pixel_format.color_space, img.channels_order).

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.

The array shares memory with CPU data whose dtype NumPy supports. Bfloat16 data is copied to float32, preserving its values, because NumPy has no bfloat16 dtype.

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

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