# kornia.utils¶

## Image¶

tensor_to_image(tensor: torch.Tensor) → numpy.array[source]

Converts a PyTorch tensor image to a numpy image. In case the tensor is in the GPU, it will be copied back to CPU.

Parameters

tensor (torch.Tensor) – image of the form $$(H, W)$$, $$(C, H, W)$$ or $$(B, C, H, W)$$.

Returns

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

Return type

numpy.ndarray

image_to_tensor(image: numpy.ndarray, keepdim: bool = True) → torch.Tensor[source]

Converts a numpy image to a PyTorch 4d tensor image.

Parameters
• image (numpy.ndarray) – image of the form $$(H, W, C)$$, $$(H, W)$$ or $$(B, H, W, C)$$.

• keepdim (bool) – If False unsqueeze the input image to match the shape $$(B, H, W, C)$$. Default: True

Returns

tensor of the form $$(B, C, H, W)$$ if keepdim is False,

$$(C, H, W)$$ otherwise.

Return type

torch.Tensor

## Grid¶

create_meshgrid(height: int, width: int, normalized_coordinates: bool = True, device: Optional[torch.device] = device(type='cpu')) → torch.Tensor[source]

Generates a coordinate grid for an image.

When the flag normalized_coordinates is set to True, the grid is normalized to be in the range [-1,1] to be consistent with the pytorch function grid_sample. http://pytorch.org/docs/master/nn.html#torch.nn.functional.grid_sample

Parameters
• height (int) – the image height (rows).

• width (int) – the image width (cols).

• normalized_coordinates (bool) – whether to normalize coordinates in the range [-1, 1] in order to be consistent with the PyTorch function grid_sample.

Returns

returns a grid tensor with shape $$(1, H, W, 2)$$.

Return type

torch.Tensor

create_meshgrid3d(depth: int, height: int, width: int, normalized_coordinates: bool = True, device: Optional[torch.device] = device(type='cpu')) → torch.Tensor[source]

Generates a coordinate grid for an image.

When the flag normalized_coordinates is set to True, the grid is normalized to be in the range [-1,1] to be consistent with the pytorch function grid_sample. http://pytorch.org/docs/master/nn.html#torch.nn.functional.grid_sample

Parameters
• depth (int) – the image depth (channels).

• height (int) – the image height (rows).

• width (int) – the image width (cols).

• normalized_coordinates (bool) – whether to normalize coordinates in the range [-1, 1] in order to be consistent with the PyTorch function grid_sample.

Returns

returns a grid tensor with shape $$(1, D, H, W, 3)$$.

Return type

torch.Tensor

## Pointcloud¶

save_pointcloud_ply(filename: str, pointcloud: torch.Tensor) → None[source]

Utility function to save to disk a pointcloud in PLY format.

Parameters
• filename (str) – the path to save the pointcloud.

• pointcloud (torch.Tensor) – tensor containing the pointcloud to save. The tensor must be in the shape of $$(*, 3)$$ where the last component is assumed to be a 3d point coordinate $$(X, Y, Z)$$.

load_pointcloud_ply(filename: str, header_size: Optional[int] = 8) → torch.Tensor[source]

Utility function to load from disk a pointcloud in PLY format.

Parameters
• filename (str) – the path to the pointcloud.

Returns

a tensor containing the loaded point with shape

$$(*, 3)$$ where $$*$$ represents the number of points.

Return type

torch.Tensor

## Metrics¶

confusion_matrix(input: torch.Tensor, target: torch.Tensor, num_classes: int, normalized: Optional[bool] = False) → torch.Tensor[source]

Compute confusion matrix to evaluate the accuracy of a classification.

Parameters
• input (torch.Tensor) – tensor with estimated targets returned by a classifier. The shape can be $$(B, *)$$ and must contain integer values between 0 and K-1.

• target (torch.Tensor) – tensor with ground truth (correct) target values. The shape can be $$(B, *)$$ and must contain integer values between 0 and K-1, whete targets are assumed to be provided as one-hot vectors.

• num_classes (int) – total possible number of classes in target.

• normalized – (Optional[bool]): wether to return the confusion matrix normalized. Default: False.

Returns

a tensor containing the confusion matrix with shape $$(B, K, K)$$ where K is the number of classes.

Return type

torch.Tensor

mean_iou(input: torch.Tensor, target: torch.Tensor, num_classes: int, eps: Optional[float] = 1e-06) → torch.Tensor[source]

Calculate mean Intersection-Over-Union (mIOU).

The function internally computes the confusion matrix.

Parameters
• input (torch.Tensor) – tensor with estimated targets returned by a classifier. The shape can be $$(B, *)$$ and must contain integer values between 0 and K-1.

• target (torch.Tensor) – tensor with ground truth (correct) target values. The shape can be $$(B, *)$$ and must contain integer values between 0 and K-1, whete targets are assumed to be provided as one-hot vectors.

• num_classes (int) – total possible number of classes in target.

Returns

a tensor representing the mean intersection-over union with shape $$(B, K)$$ where K is the number of classes.

Return type

torch.Tensor

one_hot(labels: torch.Tensor, num_classes: int, device: Optional[torch.device] = None, dtype: Optional[torch.dtype] = None, eps: Optional[float] = 1e-06) → torch.Tensor[source]

Converts an integer label x-D tensor to a one-hot (x+1)-D tensor.

Parameters
• labels (torch.Tensor) – tensor with labels of shape $$(N, *)$$, where N is batch size. Each value is an integer representing correct classification.

• num_classes (int) – number of classes in labels.

• device (Optional[torch.device]) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type (see torch.set_default_tensor_type()). device will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types.

• dtype (Optional[torch.dpython:type]) – the desired data type of returned tensor. Default: if None, infers data type from values.

Returns

the labels in one hot tensor of shape $$(N, C, *)$$,

Return type

torch.Tensor

Examples::
>>> labels = torch.LongTensor([[[0, 1], [2, 0]]])
>>> kornia.losses.one_hot(labels, num_classes=3)
tensor([[[[1., 0.],
[0., 1.]],
[[0., 1.],
[0., 0.]],
[[0., 0.],
[1., 0.]]]]