kornia.geometry.keypoints#

Object-oriented API for keypoints: Keypoints wraps a tensor of 2D (x, y) points and transforms and pads it; Keypoints3D validates and stores 3D (x, y, z) points.

class kornia.geometry.keypoints.Keypoints(keypoints, raise_if_not_floating_point=True)[source]#

2D keypoints, stored as an \((N, 2)\) or \((B, N, 2)\) tensor of (x, y) points.

Parameters:

keypoints (Union[Tensor, List[Tensor]]) – tensor of \((N, 2)\) or \((B, N, 2)\) coordinates. A list of tensors is not implemented (see Known defects).
raise_if_not_floating_point (bool, optional) – True raises ValueError for a non-floating-point tensor, False casts it to float32. Default: True

Convention:

A point is (x, y) in pixel coordinates (Coordinates and sizes), the frame of the Boxes vertices.
transform_keypoints() maps a point to \(M [x, y, 1]^\top\) and converts it back with convert_points_from_homogeneous(). inplace=False returns a new Keypoints; inplace=True and transform_keypoints_() rebind self to the transformed tensor and return self. Neither writes into the tensor that self wrapped.
The constructor and from_tensor() wrap a floating-point tensor without copying it. pad(), unpad(), item assignment and index_put(inplace=True) write into the stored tensor, so they change the caller’s tensor; call clone() first to keep it.
Known defects: list input and to_tensor(as_padded_sequence=True) raise NotImplementedError (#5023).

clone()[source]#

Create an independent copy of the 2D keypoints.

Return type:: Keypoints

property data: Tensor#

Return the raw 2D keypoint coordinate tensor.

Returns:: Tensor storing keypoint coordinates in (..., 2) format, where the last dimension contains x and y.

property device: device#: Returns keypoints device.

property dtype: dtype#: Returns keypoints dtype.

classmethod from_tensor(keypoints)[source]#

Validate and wrap a tensor of 2D keypoint coordinates.

Parameters:: keypoints (Tensor) – Floating-point tensor in \((N, 2)\) or \((B, N, 2)\) format; an integer tensor raises ValueError. The last dimension stores (x, y) coordinates.
Return type:: Keypoints
Returns:: New Keypoints instance containing the input coordinates.

index_put(indices, values, inplace=False)[source]#

Write keypoint coordinates at selected tensor indices.

See the Convention block on Keypoints.

Parameters:

indices (Union[Tuple[Tensor, ...], List[Tensor]]) – Index tuple or list accepted by Tensor.index_put_ for the stored coordinate tensor.
values (Union[Tensor, Keypoints]) – Replacement coordinates, either as a raw tensor or another Keypoints object.
inplace (bool, optional) – If True, update this object in place. Otherwise, clone the coordinates first and return a new wrapper. Default: False

Return type:

Keypoints

Returns:

Keypoints object containing the updated coordinates.

pad(padding_size)[source]#

Pad the keypoints in place.

See the Convention block on Keypoints.

padding_size is ordered as (left, right, top, bottom). Only left and top shift the coordinate origin. Both the batched \((B, N, 2)\) and the unbatched \((N, 2)\) container are supported; the unbatched form carries a single image, so padding_size must have exactly one row.

Parameters:: padding_size (Tensor) – per-image padding in pixels, shaped \((B, 4)\). A single row broadcasts across the batch.
Return type:: Keypoints

property shape: Tuple[int, ...] | Size#

Return the tensor shape used to store 2D keypoints.

Returns:: Shape of data. The common layouts are \((N, 2)\) for unbatched keypoints and \((B, N, 2)\) for batched keypoints, where \(B\) is the batch size, \(N\) is the number of keypoints, and the final dimension stores (x, y) coordinates.

to_tensor(as_padded_sequence=False)[source]#

Cast Keypoints to a tensor.

Parameters:

as_padded_sequence (bool, optional) –

not implemented; True raises NotImplementedError (#5023). Default: False

Return type:

Union[Tensor, List[Tensor]]

Returns:

The stored tensor itself, \((N, 2)\) or \((B, N, 2)\).

transform_keypoints(M, inplace=False)[source]#

Apply a transformation matrix to the 2D keypoints.

See the Convention block on Keypoints.

Parameters:

M (Tensor) – The transformation matrix to be applied, shape of \((3, 3)\) or \((B, 3, 3)\).
inplace (bool, optional) – True rebinds this object to the transformed tensor and returns it; False returns a new Keypoints. Default: False

Return type:

Keypoints

Returns:

The transformed keypoints.

transform_keypoints_(M)[source]#

Inplace version of Keypoints.transform_keypoints().

Return type:: Keypoints

type(dtype)[source]#

Cast stored keypoint coordinates to a target dtype.

Parameters:: dtype (dtype) – Destination dtype for the coordinate tensor.
Return type:: Keypoints
Returns:: self, rebound to the converted tensor; the tensor it wrapped before is not modified.

unpad(padding_size)[source]#

Undo pad() in place.

See the Convention block on Keypoints.

Accepts the same batched and unbatched containers and padding_size layout as pad().

Parameters:: padding_size (Tensor) – per-image padding in pixels, shaped \((B, 4)\). A single row broadcasts across the batch.
Return type:: Keypoints

class kornia.geometry.keypoints.Keypoints3D(keypoints, raise_if_not_floating_point=True)[source]#

3D keypoints, stored as an \((N, 3)\) or \((B, N, 3)\) tensor of (x, y, z) points.

The constructor validates the tensor as Keypoints does and wraps a floating-point one without copying it.

Parameters:

keypoints (Union[Tensor, List[Tensor]]) – tensor of \((N, 3)\) or \((B, N, 3)\) coordinates. A list of tensors is not implemented (see Known defects).
raise_if_not_floating_point (bool, optional) – True raises ValueError for a non-floating-point tensor, False casts it to float32. Default: True

Convention:

Known defects: list input, pad(), unpad(), transform_keypoints(), transform_keypoints_() and to_tensor(as_padded_sequence=True) raise NotImplementedError (#5023).

clone()[source]#

Create an independent copy of the 3D keypoints.

Return type:: Keypoints3D

property data: Tensor#

Return the raw 3D keypoint coordinate tensor.

Returns:: Tensor storing coordinates in (..., 3) format, with the final dimension ordered as (x, y, z).

classmethod from_tensor(keypoints)[source]#

Validate and wrap a tensor of 3D keypoint coordinates.

Parameters:: keypoints (Tensor) – Tensor in \((N, 3)\) or \((B, N, 3)\) format, where the last dimension stores (x, y, z).
Return type:: Keypoints3D
Returns:: New Keypoints3D instance containing the input coordinates.

pad(padding_size)[source]#

Not implemented: raises NotImplementedError (#5023).

Return type:: Keypoints3D

property shape: Size#

Return the tensor shape used to store 3D keypoints.

Returns:: Shape of data. The common layouts are \((N, 3)\) and \((B, N, 3)\), where the final dimension stores (x, y, z) coordinates.

to_tensor(as_padded_sequence=False)[source]#

Cast Keypoints3D to a tensor.

Parameters:

as_padded_sequence (bool, optional) –

not implemented; True raises NotImplementedError (#5023). Default: False

Return type:

Union[Tensor, List[Tensor]]

Returns:

The stored tensor itself, \((N, 3)\) or \((B, N, 3)\).

transform_keypoints(M, inplace=False)[source]#

Not implemented: raises NotImplementedError (#5023).

Use transform_points() on data instead.

Return type:: Keypoints3D

transform_keypoints_(M)[source]#

Not implemented: raises NotImplementedError (#5023).

Return type:: Keypoints3D

unpad(padding_size)[source]#

Not implemented: raises NotImplementedError (#5023).

Return type:: Keypoints3D