Image conversion#

kornia.image.tensor_to_image(tensor, keepdim=False, force_contiguous=False)[source]#

Convert a channels-first image tensor to a channels-last NumPy array for display.

array = tensor_to_image(tensor) takes an (H, W), (C, H, W) or (B, C, H, W) tensor and returns an (H, W, C) or (B, H, W, C) NumPy array, detached from autograd and on the CPU. A single channel is dropped, and so is a batch of one unless keepdim=True, so one 1-, 3- or 4-channel image goes straight to matplotlib’s imshow.

Convention:

The array shares memory with a CPU tensor whose dtype NumPy supports, and keeps its dtype.
A tensor on another device is copied, bfloat16 becomes a float32 copy, and a dtype NumPy cannot represent, such as float8_e4m3fn, raises TypeError.
force_contiguous=True copies a result that is not contiguous, such as the channels-last view of a contiguous tensor with more than one channel.

Parameters:

tensor (Tensor) – image of the form (H, W), (C, H, W) or (B, C, H, W).
keepdim (bool, optional) – If True, keep the batch axis of a (1, C, H, W) input. Default: False
force_contiguous (bool, optional) – If True, call contiguous on the result before converting it to NumPy. Default: False

Return type:

Any

Returns:

image of the form (H, W), (H, W, C), (B, H, W) or (B, H, W, C).

Raises:

TypeError – if tensor is not a torch.Tensor.
ValueError – if tensor is not two, three or four dimensional.

See also

image_to_tensor(): the other direction, from a channels-last array.
Image.to_numpy(): returns the data of an Image in its stored layout, without moving the channels.

Example

>>> img = torch.ones(1, 3, 3)
>>> tensor_to_image(img).shape
(3, 3)

>>> img = torch.ones(3, 4, 4)
>>> tensor_to_image(img).shape
(4, 4, 3)

kornia.image.image_to_tensor(image, keepdim=True)[source]#

Convert a channels-last NumPy image or batch to a channels-first tensor view.

tensor = image_to_tensor(array) takes an (H, W, C), (H, W) or (B, H, W, C) NumPy array and returns a (C, H, W) or (B, C, H, W) tensor that shares the array’s memory. The dtype and values are kept, so uint8 stays in \([0, 255]\).

Convention:

The last axis of a 3-D or 4-D array is always the channels. A channels-first (C, H, W) array is not detected: it is read as (H, W, C).
The tensor is a view of the array. An array with a negative stride, such as OpenCV’s img[..., ::-1], raises ValueError; pass img[..., ::-1].copy().
Files and arrays relates it to torchvision’s ToTensor.

Parameters:

image (Any) – image of the form (H, W, C), (H, W) or (B, H, W, C).
keepdim (bool, optional) – If False, a 2-D or 3-D input gets a leading batch axis, (1, C, H, W). A 4-D input is always (B, C, H, W). Default: True

Return type:

Tensor

Returns:

tensor of the form (C, H, W) for a 2-D or 3-D input with keepdim=True (a 2-D input has \(C = 1\)), and (B, C, H, W) otherwise.

Raises:

TypeError – if image is not a numpy.ndarray.
ValueError – if image is not two, three or four dimensional.

See also

ImageToTensor: the module form, with keepdim=False by default.
image_list_to_tensor(): stacks a list of (H, W, C) images into a new (B, C, H, W) tensor.
tensor_to_image(): the other direction, back to a channels-last array.

Example

>>> img = np.ones((3, 3))
>>> image_to_tensor(img).shape
torch.Size([1, 3, 3])

>>> img = np.ones((4, 4, 1))
>>> image_to_tensor(img).shape
torch.Size([1, 4, 4])

>>> img = np.ones((4, 4, 3))
>>> image_to_tensor(img, keepdim=False).shape
torch.Size([1, 3, 4, 4])

kornia.image.image_list_to_tensor(images)[source]#

Stack a list of same-shape (H, W, C) images into a new (B, C, H, W) tensor.

batch = image_list_to_tensor(images) takes a non-empty list of (H, W, C) NumPy arrays or tensors, all of one shape, and returns them stacked into a new (B, C, H, W) tensor that keeps their values. Unlike image_to_tensor(), it copies, so arrays with negative strides, such as img[..., ::-1], are accepted.

Convention:

The dtype is the promotion of the images’ dtypes, so uint8 and float32 images give float32.
All images must be on one device, arrays counting as CPU; the result keeps it.

Parameters:

images (List[Any]) – list of images, each of the form (H, W, C), all of the same shape.

Return type:

Tensor

Returns:

tensor of the form (B, C, H, W).

Raises:

ValueError – if the list is empty, an image is not three dimensional, or the shapes differ.
RuntimeError – if the images are on different devices.

See also

image_to_tensor(): converts one array, or an already stacked (B, H, W, C) array, as a view.

Example

>>> imgs = [np.ones((4, 4, 1)), np.zeros((4, 4, 1))]
>>> image_list_to_tensor(imgs).shape
torch.Size([2, 1, 4, 4])

class kornia.image.ImageToTensor(keepdim=False)[source]#

Convert a NumPy image to a channels-first tensor (module form, batched by default).

to_tensor = ImageToTensor(keepdim) stores keepdim, and tensor = to_tensor(array) is image_to_tensor() with it. Unlike the function, keepdim defaults to False, so an (H, W, C) array becomes (1, C, H, W).

Parameters:: keepdim (bool, optional) – If False, a 2-D or 3-D input gets a leading batch axis, (1, C, H, W). A 4-D input is always (B, C, H, W). Default: False

See also

image_to_tensor(): the function form.

Example

>>> ImageToTensor()(np.ones((4, 5, 3))).shape
torch.Size([1, 3, 4, 5])