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

draw_rectangle(image: torch.Tensor, rectangle: torch.Tensor, color: Optional[torch.Tensor] = None, fill: Optional[bool] = None, width: int = 1) → torch.Tensor[source]¶

Draws N rectangles on a batch of image tensors.

Parameters

image (torch.Tensor) – is tensor of BxCxHxW.
rectangle (torch.Tensor) – represents number of rectangles to draw in BxNx4 N is the number of boxes to draw per batch index[x1, y1, x2, y2] 4 is in (top_left.x, top_left.y, bot_right.x, bot_right.y).
color (torch.Tensor, optional) – a size 1, size 3, BxNx1, or BxNx3 tensor. If C is 3, and color is 1 channel it will be broadcasted Default: None (black).
fill (bool, optional) – is a flag used to fill the boxes with color if True. Default: False.
width (int) – The line width. Default: 1. (Not implemented yet).

Returns

This operation modifies image inplace but also returns the drawn tensor for convenience with same shape the of the input BxCxHxW.

Return type

torch.Tensor

Example

>>> img = torch.rand(2, 3, 10, 12)
>>> rect = torch.tensor([[[0, 0, 4, 4]], [[4, 4, 10, 10]]])
>>> out = draw_rectangle(img, rect)

Grid¶

create_meshgrid(height: int, width: int, normalized_coordinates: bool = True, device: Optional[torch.device] = device(type='cpu'), dtype: torch.dtype = torch.float32) → 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.
device (torch.device) – the device on which the grid will be generated. Default: cpu.
dtype (torch.dpython:type) – the data type of the generated gird. Default: float32.

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'), dtype: torch.dtype = torch.float32) → 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.
device (torch.device) – the device on which the grid will be generated. Default: cpu.
dtype (torch.dpython:type) – the data type of the generated gird. Default: float32.

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