kornia.geometry.conversions

kornia.geometry.conversions.rad2deg(tensor)[source]

Function that converts angles from radians to degrees.

Parameters

tensor (Tensor) – Tensor of arbitrary shape.

Return type

Tensor

Returns

Tensor with same shape as input.

Example

>>> input = torch.tensor(3.1415926535) * torch.rand(1, 3, 3)
>>> output = rad2deg(input)
kornia.geometry.conversions.deg2rad(tensor)[source]

Function that converts angles from degrees to radians.

Parameters

tensor (Tensor) – Tensor of arbitrary shape.

Return type

Tensor

Returns

tensor with same shape as input.

Examples

>>> input = 360. * torch.rand(1, 3, 3)
>>> output = deg2rad(input)
kornia.geometry.conversions.pol2cart(rho, phi)[source]

Function that converts polar coordinates to cartesian coordinates.

Parameters
  • rho (Tensor) – Tensor of arbitrary shape.

  • phi (Tensor) – Tensor of same arbitrary shape.

Return type

Tuple[Tensor, Tensor]

Returns

Tensor with same shape as input.

Example

>>> rho = torch.rand(1, 3, 3)
>>> phi = torch.rand(1, 3, 3)
>>> x, y = pol2cart(rho, phi)
kornia.geometry.conversions.cart2pol(x, y, eps=1e-08)[source]

Function that converts cartesian coordinates to polar coordinates.

Parameters
  • rho – Tensor of arbitrary shape.

  • phi – Tensor of same arbitrary shape.

  • eps (float, optional) – To avoid division by zero. Default: 1e-08

Return type

Tuple[Tensor, Tensor]

Returns

Tensor with same shape as input.

Example

>>> x = torch.rand(1, 3, 3)
>>> y = torch.rand(1, 3, 3)
>>> rho, phi = cart2pol(x, y)
kornia.geometry.conversions.convert_points_from_homogeneous(points, eps=1e-08)[source]

Function that converts points from homogeneous to Euclidean space.

Parameters
  • points (Tensor) – the points to be transformed.

  • eps (float, optional) – to avoid division by zero. Default: 1e-08

Return type

Tensor

Returns

the points in Euclidean space.

Examples

>>> input = torch.rand(2, 4, 3)  # BxNx3
>>> output = convert_points_from_homogeneous(input)  # BxNx2
kornia.geometry.conversions.convert_points_to_homogeneous(points)[source]

Function that converts points from Euclidean to homogeneous space.

Parameters

points (Tensor) – the points to be transformed.

Return type

Tensor

Returns

the points in homogeneous coordinates.

Examples

>>> input = torch.rand(2, 4, 3)  # BxNx3
>>> output = convert_points_to_homogeneous(input)  # BxNx4
kornia.geometry.conversions.convert_affinematrix_to_homography(A)[source]

Function that converts batch of affine matrices.

Parameters

A (Tensor) – the affine matrix with shape \((B,2,3)\).

Return type

Tensor

Returns

the homography matrix with shape of \((B,3,3)\).

Examples

>>> input = torch.rand(2, 2, 3)  # Bx2x3
>>> output = convert_affinematrix_to_homography(input)  # Bx3x3
kornia.geometry.conversions.rotation_matrix_to_angle_axis(rotation_matrix)[source]

Convert 3x3 rotation matrix to Rodrigues vector in radians.

Parameters

rotation_matrix (Tensor) – rotation matrix.

Return type

Tensor

Returns

Rodrigues vector transformation.

Shape:
  • Input: \((N, 3, 3)\)

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

Example

>>> input = torch.rand(2, 3, 3)  # Nx3x3
>>> output = rotation_matrix_to_angle_axis(input)  # Nx3
kornia.geometry.conversions.rotation_matrix_to_quaternion(rotation_matrix, eps=1e-08, order=QuaternionCoeffOrder.XYZW)[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 (Tensor) – the rotation matrix to convert.

  • eps (float, optional) – small value to avoid zero division. Default: 1e-08

  • order (QuaternionCoeffOrder, optional) – quaternion coefficient order. Note: ‘xyzw’ will be deprecated in favor of ‘wxyz’. Default: QuaternionCoeffOrder.XYZW

Return type

Tensor

Returns

the rotation in quaternion.

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
kornia.geometry.conversions.quaternion_to_angle_axis(quaternion, order=QuaternionCoeffOrder.XYZW)[source]

Convert quaternion vector to angle axis of rotation in radians.

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 (Tensor) – tensor with quaternions.

  • order (QuaternionCoeffOrder, optional) – quaternion coefficient order. Note: ‘xyzw’ will be deprecated in favor of ‘wxyz’. Default: QuaternionCoeffOrder.XYZW

Return type

Tensor

Returns

tensor with angle axis of rotation.

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
kornia.geometry.conversions.quaternion_to_rotation_matrix(quaternion, order=QuaternionCoeffOrder.XYZW)[source]

Convert a quaternion to a rotation matrix.

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

Parameters
  • quaternion (Tensor) – a tensor containing a quaternion to be converted. The tensor can be of shape \((*, 4)\).

  • order (QuaternionCoeffOrder, optional) – quaternion coefficient order. Note: ‘xyzw’ will be deprecated in favor of ‘wxyz’. Default: QuaternionCoeffOrder.XYZW

Return type

Tensor

Returns

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

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.]])
kornia.geometry.conversions.quaternion_log_to_exp(quaternion, eps=1e-08, order=QuaternionCoeffOrder.XYZW)[source]

Apply exponential map to log quaternion.

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

Parameters
  • quaternion (Tensor) – a tensor containing a quaternion to be converted. The tensor can be of shape \((*, 3)\).

  • order (QuaternionCoeffOrder, optional) – quaternion coefficient order. Note: ‘xyzw’ will be deprecated in favor of ‘wxyz’. Default: QuaternionCoeffOrder.XYZW

Return type

Tensor

Returns

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

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.])
kornia.geometry.conversions.quaternion_exp_to_log(quaternion, eps=1e-08, order=QuaternionCoeffOrder.XYZW)[source]

Apply the log map to a quaternion.

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

Parameters
  • quaternion (Tensor) – a tensor containing a quaternion to be converted. The tensor can be of shape \((*, 4)\).

  • eps (float, optional) – A small number for clamping. Default: 1e-08

  • order (QuaternionCoeffOrder, optional) – quaternion coefficient order. Note: ‘xyzw’ will be deprecated in favor of ‘wxyz’. Default: QuaternionCoeffOrder.XYZW

Return type

Tensor

Returns

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

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.])
kornia.geometry.conversions.angle_axis_to_quaternion(angle_axis, order=QuaternionCoeffOrder.XYZW)[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 (Tensor) – tensor with angle axis in radians.

  • order (QuaternionCoeffOrder, optional) – quaternion coefficient order. Note: ‘xyzw’ will be deprecated in favor of ‘wxyz’. Default: QuaternionCoeffOrder.XYZW

Return type

Tensor

Returns

tensor with quaternion.

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
kornia.geometry.conversions.angle_axis_to_rotation_matrix(angle_axis)[source]

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

Parameters

angle_axis (Tensor) – tensor of 3d vector of axis-angle rotations in radians.

Return type

Tensor

Returns

tensor of 3x3 rotation matrices.

Shape:
  • Input: \((N, 3)\)

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

Example

>>> input = torch.rand(1, 3)  # Nx3
>>> output = angle_axis_to_rotation_matrix(input)  # Nx3x3
kornia.geometry.conversions.denormalize_pixel_coordinates(pixel_coordinates, height, width, eps=1e-08)[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 (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, optional) – safe division by zero. Default: 1e-08

Return type

Tensor

Returns

the denormalized pixel coordinates.

kornia.geometry.conversions.normalize_pixel_coordinates(pixel_coordinates, height, width, eps=1e-08)[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 (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, optional) – safe division by zero. Default: 1e-08

Return type

Tensor

Returns

the normalized pixel coordinates.

kornia.geometry.conversions.denormalize_pixel_coordinates3d(pixel_coordinates, depth, height, width, eps=1e-08)[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 (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, optional) – safe division by zero. Default: 1e-08

Return type

Tensor

Returns

the denormalized pixel coordinates.

kornia.geometry.conversions.normalize_pixel_coordinates3d(pixel_coordinates, depth, height, width, eps=1e-08)[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 (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, optional) – safe division by zero. Default: 1e-08

Return type

Tensor

Returns

the normalized pixel coordinates.

kornia.geometry.conversions.normalize_quaternion(quaternion, eps=1e-12)[source]

Normalize a quaternion.

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

Parameters
  • quaternion (Tensor) – a tensor containing a quaternion to be normalized. The tensor can be of shape \((*, 4)\).

  • eps (float, optional) – small value to avoid division by zero. Default: 1e-12

Return type

Tensor

Returns

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

Example

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