Implementation:Kornia Kornia Image Class

Knowledge Sources	Kornia
Domains	Vision, Image_Representation
Last Updated	2026-02-09 15:00 GMT

Overview

The Image class provides a structured wrapper around a torch.Tensor that carries metadata about pixel format, color space, image layout, and channels order for type-safe image manipulation within the Kornia library.

Description

This module provides the Image class in the Kornia image package. It wraps a raw torch.Tensor with PixelFormat (color space and bit depth) and ImageLayout (image size, channel count, and channels order) metadata. The class enforces shape and bit-depth consistency at construction time using KORNIA_CHECK_SHAPE and KORNIA_CHECK. It provides properties for accessing image dimensions, device, dtype, and layout information. Color space conversions are supported via to_gray(), to_rgb(), and to_bgr() methods. Interoperability is provided through class methods from_numpy(), from_dlpack(), from_file() and instance methods to_numpy(), to_dlpack(), write(). The class also supports terminal visualization via print().

Usage

Import this class when you need a metadata-aware image container that enforces layout constraints, supports color space conversions, and provides seamless I/O with numpy, DLPack, and file formats.

Code Reference

Source Location

• Repository: Kornia
• File: kornia/image/image.py
• Lines: 1-402

Signature

class Image:
    def __init__(self, data: torch.Tensor, pixel_format: PixelFormat, layout: ImageLayout) -> None: ...

    def to(self, device=None, dtype=None) -> Image: ...
    def clone(self) -> Image: ...
    def float(self) -> Image: ...
    def to_gray(self) -> Image: ...
    def to_rgb(self) -> Image: ...
    def to_bgr(self) -> Image: ...

    @classmethod
    def from_numpy(cls, data, color_space=ColorSpace.RGB,
                   channels_order=ChannelsOrder.CHANNELS_LAST) -> Image: ...
    def to_numpy(self) -> np_ndarray: ...

    @classmethod
    def from_dlpack(cls, data) -> Image: ...
    def to_dlpack(self) -> DLPack: ...

    @classmethod
    def from_file(cls, file_path: str | Path) -> Image: ...
    def write(self, file_path: str | Path) -> None: ...

    def print(self, max_width: int = 256) -> None: ...

Import

from kornia.image.image import Image

I/O Contract

Constructor Inputs

Name	Type	Required	Description
data	torch.Tensor	Yes	The raw image tensor data.
pixel_format	PixelFormat	Yes	Pixel format (color_space, bit_depth).
layout	ImageLayout	Yes	Layout (image_size, channels, channels_order).

Key Properties

Property	Type	Description
data	torch.Tensor	Underlying tensor data.
shape	tuple[int, ...]	Image tensor shape.
dtype	torch.dtype	Data type of the tensor.
device	torch.device	Device where the tensor resides.
channels	int	Number of image channels.
height	int	Image height in pixels.
width	int	Image width in pixels.
channels_order	ChannelsOrder	CHANNELS_FIRST or CHANNELS_LAST.

Usage Examples

import torch
from kornia.image.image import Image
from kornia.image.base import PixelFormat, ImageLayout, ImageSize, ColorSpace, ChannelsOrder

# Create from tensor
data = torch.randint(0, 255, (3, 4, 5), dtype=torch.uint8)
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

# Create from numpy (OpenCV-style HxWxC)
import numpy as np
data = np.ones((4, 5, 3), dtype=np.uint8)
img = Image.from_numpy(data, color_space=ColorSpace.RGB)
assert img.width == 5 and img.height == 4

# Color space conversion
gray_img = img.to_gray()
assert gray_img.channels == 1

# Load from file
img = Image.from_file("photo.png")
img.print()  # terminal visualization

Related Pages

• Principle:Kornia_Kornia_Image_Data_Model