kornia.geometry.conversions¶

rad2deg(tensor: torch.Tensor) → torch.Tensor[source]¶

Function that converts angles from radians to degrees.

Parameters: tensor (torch.Tensor) – Tensor of arbitrary shape.
Returns: Tensor with same shape as input.
Return type: torch.Tensor

Example

>>> input = torch.tensor(3.1415926535) * torch.rand(1, 3, 3)
>>> output = rad2deg(input)

deg2rad(tensor: torch.Tensor) → torch.Tensor[source]¶

Function that converts angles from degrees to radians.

Parameters: tensor (torch.Tensor) – Tensor of arbitrary shape.
Returns: tensor with same shape as input.
Return type: torch.Tensor

Examples:

>>> input = 360. * torch.rand(1, 3, 3)
>>> output = deg2rad(input)

pol2cart(rho: torch.Tensor, phi: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor][source]¶

Function that converts polar coordinates to cartesian coordinates.

Parameters

rho (torch.Tensor) – Tensor of arbitrary shape.
phi (torch.Tensor) – Tensor of same arbitrary shape.

Returns

Tensor with same shape as input.

Return type

torch.Tensor, torch.Tensor

Example

>>> rho = torch.rand(1, 3, 3)
>>> phi = torch.rand(1, 3, 3)
>>> x, y = pol2cart(rho, phi)

cart2pol(x: torch.Tensor, y: torch.Tensor, eps: float = 1e-08) → Tuple[torch.Tensor, torch.Tensor][source]¶

Function that converts cartesian coordinates to polar coordinates.

Parameters

rho (torch.Tensor) – Tensor of arbitrary shape.
phi (torch.Tensor) – Tensor of same arbitrary shape.
eps (float) – To avoid division by zero. Default is 1e-8

Returns

Tensor with same shape as input.

Return type

torch.Tensor, torch.Tensor

Example

>>> x = torch.rand(1, 3, 3)
>>> y = torch.rand(1, 3, 3)
>>> rho, phi = cart2pol(x, y)

convert_points_from_homogeneous(points: torch.Tensor, eps: float = 1e-08) → torch.Tensor[source]¶

Function that converts points from homogeneous to Euclidean space.

Examples:

>>> input = torch.rand(2, 4, 3)  # BxNx3
>>> output = convert_points_from_homogeneous(input)  # BxNx2

convert_points_to_homogeneous(points: torch.Tensor) → torch.Tensor[source]¶

Function that converts points from Euclidean to homogeneous space.

Examples:

>>> input = torch.rand(2, 4, 3)  # BxNx3
>>> output = convert_points_to_homogeneous(input)  # BxNx4

convert_affinematrix_to_homography(A: torch.Tensor) → torch.Tensor[source]¶

Function that converts batch of affine matrices from [Bx2x3] to [Bx3x3].

Examples:

>>> input = torch.rand(2, 2, 3)  # Bx2x3
>>> output = convert_affinematrix_to_homography(input)  # Bx3x3

rotation_matrix_to_angle_axis(rotation_matrix: torch.Tensor) → torch.Tensor[source]¶

Convert 3x3 rotation matrix to Rodrigues vector.

Parameters: rotation_matrix (torch.Tensor) – rotation matrix.
Returns: Rodrigues vector transformation.
Return type: torch.Tensor

Shape:

Input: \((N, 3, 3)\)
Output: \((N, 3)\)

Example

>>> input = torch.rand(2, 3, 3)  # Nx3x3
>>> output = rotation_matrix_to_angle_axis(input)  # Nx3

rotation_matrix_to_quaternion(rotation_matrix: torch.Tensor, eps: float = 1e-08, order: kornia.geometry.conversions.QuaternionCoeffOrder = <QuaternionCoeffOrder.XYZW: 'xyzw'>) → torch.Tensor[source]¶

Convert 3x3 rotation matrix to 4d quaternion vector.

The quaternion vector has components in (w, x, y, z) or (x, y, z, w) format.

Note

The (x, y, z, w) order is going to be deprecated in favor of efficiency.

Parameters

rotation_matrix (torch.Tensor) – the rotation matrix to convert.
eps (float) – small value to avoid zero division. Default: 1e-8.
order (QuaternionCoeffOrder) – quaternion coefficient order. Default: ‘xyzw’. Note: ‘xyzw’ will be deprecated in favor of ‘wxyz’.

Returns

the rotation in quaternion.

Return type

torch.Tensor

Shape:

Input: \((*, 3, 3)\)
Output: \((*, 4)\)

Example

>>> input = torch.rand(4, 3, 3)  # Nx3x3
>>> output = rotation_matrix_to_quaternion(input, eps=torch.finfo(input.dtype).eps,
...                                        order=QuaternionCoeffOrder.WXYZ)  # Nx4

quaternion_to_angle_axis(quaternion: torch.Tensor, order: kornia.geometry.conversions.QuaternionCoeffOrder = <QuaternionCoeffOrder.XYZW: 'xyzw'>) → torch.Tensor[source]¶

Convert quaternion vector to angle axis of rotation.

The quaternion should be in (x, y, z, w) or (w, x, y, z) format.

Adapted from ceres C++ library: ceres-solver/include/ceres/rotation.h

Parameters

quaternion (torch.Tensor) – tensor with quaternions.
order (QuaternionCoeffOrder) – quaternion coefficient order. Default: ‘xyzw’. Note: ‘xyzw’ will be deprecated in favor of ‘wxyz’.

Returns

tensor with angle axis of rotation.

Return type

torch.Tensor

Shape:

Input: \((*, 4)\) where * means, any number of dimensions
Output: \((*, 3)\)

Example

>>> quaternion = torch.rand(2, 4)  # Nx4
>>> angle_axis = quaternion_to_angle_axis(quaternion)  # Nx3

quaternion_to_rotation_matrix(quaternion: torch.Tensor, order: kornia.geometry.conversions.QuaternionCoeffOrder = <QuaternionCoeffOrder.XYZW: 'xyzw'>) → torch.Tensor[source]¶

Converts a quaternion to a rotation matrix.

The quaternion should be in (x, y, z, w) or (w, x, y, z) format.

Parameters

quaternion (torch.Tensor) – a tensor containing a quaternion to be converted. The tensor can be of shape \((*, 4)\).
order (QuaternionCoeffOrder) – quaternion coefficient order. Default: ‘xyzw’. Note: ‘xyzw’ will be deprecated in favor of ‘wxyz’.

Returns

the rotation matrix of shape \((*, 3, 3)\).

Return type

torch.Tensor

Example

>>> quaternion = torch.tensor((0., 0., 0., 1.))
>>> quaternion_to_rotation_matrix(quaternion, order=QuaternionCoeffOrder.WXYZ)
tensor([[-1.,  0.,  0.],
        [ 0., -1.,  0.],
        [ 0.,  0.,  1.]])

quaternion_log_to_exp(quaternion: torch.Tensor, eps: float = 1e-08, order: kornia.geometry.conversions.QuaternionCoeffOrder = <QuaternionCoeffOrder.XYZW: 'xyzw'>) → torch.Tensor[source]¶

Applies exponential map to log quaternion.

The quaternion should be in (x, y, z, w) or (w, x, y, z) format.

Parameters

quaternion (torch.Tensor) – a tensor containing a quaternion to be converted. The tensor can be of shape \((*, 3)\).
order (QuaternionCoeffOrder) – quaternion coefficient order. Default: ‘xyzw’. Note: ‘xyzw’ will be deprecated in favor of ‘wxyz’.

Returns

the quaternion exponential map of shape \((*, 4)\).

Return type

torch.Tensor

Example

>>> quaternion = torch.tensor((0., 0., 0.))
>>> quaternion_log_to_exp(quaternion, eps=torch.finfo(quaternion.dtype).eps,
...                       order=QuaternionCoeffOrder.WXYZ)
tensor([1., 0., 0., 0.])

quaternion_exp_to_log(quaternion: torch.Tensor, eps: float = 1e-08, order: kornia.geometry.conversions.QuaternionCoeffOrder = <QuaternionCoeffOrder.XYZW: 'xyzw'>) → torch.Tensor[source]¶

Applies the log map to a quaternion.

The quaternion should be in (x, y, z, w) format.

Parameters

quaternion (torch.Tensor) – a tensor containing a quaternion to be converted. The tensor can be of shape \((*, 4)\).
eps (float) – A small number for clamping.
order (QuaternionCoeffOrder) – quaternion coefficient order. Default: ‘xyzw’. Note: ‘xyzw’ will be deprecated in favor of ‘wxyz’.

Returns

the quaternion log map of shape \((*, 3)\).

Return type

torch.Tensor

Example

>>> quaternion = torch.tensor((1., 0., 0., 0.))
>>> quaternion_exp_to_log(quaternion, eps=torch.finfo(quaternion.dtype).eps,
...                       order=QuaternionCoeffOrder.WXYZ)
tensor([0., 0., 0.])

angle_axis_to_quaternion(angle_axis: torch.Tensor, order: kornia.geometry.conversions.QuaternionCoeffOrder = <QuaternionCoeffOrder.XYZW: 'xyzw'>) → torch.Tensor[source]¶

Convert an angle axis to a quaternion.

The quaternion vector has components in (x, y, z, w) or (w, x, y, z) format.

Adapted from ceres C++ library: ceres-solver/include/ceres/rotation.h

Parameters

angle_axis (torch.Tensor) – tensor with angle axis.
order (QuaternionCoeffOrder) – quaternion coefficient order. Default: ‘xyzw’. Note: ‘xyzw’ will be deprecated in favor of ‘wxyz’.

Returns

tensor with quaternion.

Return type

torch.Tensor

Shape:

Input: \((*, 3)\) where * means, any number of dimensions
Output: \((*, 4)\)

Example

>>> angle_axis = torch.rand(2, 3)  # Nx3
>>> quaternion = angle_axis_to_quaternion(angle_axis, order=QuaternionCoeffOrder.WXYZ)  # Nx4

angle_axis_to_rotation_matrix(angle_axis: torch.Tensor) → torch.Tensor[source]¶

Convert 3d vector of axis-angle rotation to 3x3 rotation matrix

Parameters: angle_axis (torch.Tensor) – tensor of 3d vector of axis-angle rotations.
Returns: tensor of 3x3 rotation matrices.
Return type: torch.Tensor

Shape:

Input: \((N, 3)\)
Output: \((N, 3, 3)\)

Example

>>> input = torch.rand(1, 3)  # Nx3
>>> output = angle_axis_to_rotation_matrix(input)  # Nx3x3

denormalize_pixel_coordinates(pixel_coordinates: torch.Tensor, height: int, width: int, eps: float = 1e-08) → torch.Tensor[source]¶

Denormalize pixel coordinates.

The input is assumed to be -1 if on extreme left, 1 if on extreme right (x = w-1).

Parameters

pixel_coordinates (torch.Tensor) – the normalized grid coordinates. Shape can be \((*, 2)\).
width (int) – the maximum width in the x-axis.
height (int) – the maximum height in the y-axis.
eps (float) – safe division by zero. (default 1e-8).

Returns

the denormalized pixel coordinates.

Return type

torch.Tensor

normalize_pixel_coordinates(pixel_coordinates: torch.Tensor, height: int, width: int, eps: float = 1e-08) → torch.Tensor[source]¶

Normalize pixel coordinates between -1 and 1.

Normalized, -1 if on extreme left, 1 if on extreme right (x = w-1).

Parameters

pixel_coordinates (torch.Tensor) – the grid with pixel coordinates. Shape can be \((*, 2)\).
width (int) – the maximum width in the x-axis.
height (int) – the maximum height in the y-axis.
eps (float) – safe division by zero. (default 1e-8).

Returns

the normalized pixel coordinates.

Return type

torch.Tensor

denormalize_pixel_coordinates3d(pixel_coordinates: torch.Tensor, depth: int, height: int, width: int, eps: float = 1e-08) → torch.Tensor[source]¶

Denormalize pixel coordinates.

The input is assumed to be -1 if on extreme left, 1 if on extreme right (x = w-1).

Parameters

pixel_coordinates (torch.Tensor) – the normalized grid coordinates. Shape can be \((*, 3)\).
depth (int) – the maximum depth in the x-axis.
height (int) – the maximum height in the y-axis.
width (int) – the maximum width in the x-axis.
eps (float) – safe division by zero. (default 1e-8).

Returns

the denormalized pixel coordinates.

Return type

torch.Tensor

normalize_pixel_coordinates3d(pixel_coordinates: torch.Tensor, depth: int, height: int, width: int, eps: float = 1e-08) → torch.Tensor[source]¶

Normalize pixel coordinates between -1 and 1.

Normalized, -1 if on extreme left, 1 if on extreme right (x = w-1).

Parameters

pixel_coordinates (torch.Tensor) – the grid with pixel coordinates. Shape can be \((*, 3)\).
depth (int) – the maximum depth in the z-axis.
height (int) – the maximum height in the y-axis.
width (int) – the maximum width in the x-axis.
eps (float) – safe division by zero. (default 1e-8).

Returns

the normalized pixel coordinates.

Return type

torch.Tensor

normalize_quaternion(quaternion: torch.Tensor, eps: float = 1e-12) → torch.Tensor[source]¶

Normalizes a quaternion.

The quaternion should be in (x, y, z, w) format.

Parameters

quaternion (torch.Tensor) – a tensor containing a quaternion to be normalized. The tensor can be of shape \((*, 4)\).
eps (Optional[bool]) – small value to avoid division by zero. Default: 1e-12.

Returns

the normalized quaternion of shape \((*, 4)\).

Return type

torch.Tensor

Example

>>> quaternion = torch.tensor((1., 0., 1., 0.))
>>> normalize_quaternion(quaternion)
tensor([0.7071, 0.0000, 0.7071, 0.0000])