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.

  • header_size (Optional[int]) – the size of the ply file header that will be skipped during loading. Default is 8 lines.

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, where 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, where 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: 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]]])
>>> one_hot(labels, num_classes=3)
tensor([[[[1.0000e+00, 1.0000e-06],
          [1.0000e-06, 1.0000e+00]],
<BLANKLINE>
         [[1.0000e-06, 1.0000e+00],
          [1.0000e-06, 1.0000e-06]],
<BLANKLINE>
         [[1.0000e-06, 1.0000e-06],
          [1.0000e+00, 1.0000e-06]]]])