kornia.geometry.quaternion#

class kornia.geometry.quaternion.Quaternion(data)[source]#

Base class to represent a Quaternion.

A quaternion is a four dimensional vector representation of a rotation transformation in 3d. See more: https://en.wikipedia.org/wiki/Quaternion

The general definition of a quaternion is given by:

\[Q = a + b \cdot \mathbf{i} + c \cdot \mathbf{j} + d \cdot \mathbf{k}\]

Thus, we represent a rotation quaternion as a contiguous tensor structure to perform rigid bodies transformations:

\[Q = \begin{bmatrix} q_w & q_x & q_y & q_z \end{bmatrix}\]

Example

>>> q = Quaternion.identity(batch_size=4)
>>> q.data
Parameter containing:
tensor([[1., 0., 0., 0.],
        [1., 0., 0., 0.],
        [1., 0., 0., 0.],
        [1., 0., 0., 0.]], requires_grad=True)
>>> q.real
tensor([[1.],
        [1.],
        [1.],
        [1.]], grad_fn=<SliceBackward0>)
>>> q.vec
tensor([[0., 0., 0.],
        [0., 0., 0.],
        [0., 0., 0.],
        [0., 0., 0.]], grad_fn=<SliceBackward0>)
__add__(right)[source]#

Add a given quaternion.

Parameters

right (Quaternion) – the quaternion to add.

Example

>>> q1 = Quaternion.identity(batch_size=1)
>>> q2 = Quaternion(Tensor([[2., 0., 1., 1.]]))
>>> q3 = q1 + q2
>>> q3.data
Parameter containing:
tensor([[3., 0., 1., 1.]], requires_grad=True)
Return type

Quaternion

__init__(data)[source]#

Constructor for the base class.

Parameters

data (Tensor) – tensor containing the quaternion data with the sape of \((B, 4)\).

Example

>>> data = torch.rand(2, 4)
>>> q = Quaternion(data)
>>> q.shape
(2, 4)
__neg__()[source]#

Inverts the sign of the quaternion data.

Example

>>> q = Quaternion.identity(batch_size=1)
>>> -q.data
tensor([[-1., -0., -0., -0.]], grad_fn=<NegBackward0>)
Return type

Quaternion

__repr__()[source]#

Return repr(self).

Return type

str

__sub__(right)[source]#

Subtract a given quaternion.

Parameters

right (Quaternion) – the quaternion to subtract.

Example

>>> q1 = Quaternion(Tensor([[2., 0., 1., 1.]]))
>>> q2 = Quaternion.identity(batch_size=1)
>>> q3 = q1 - q2
>>> q3.data
Parameter containing:
tensor([[1., 0., 1., 1.]], requires_grad=True)
Return type

Quaternion

property coeffs: Tensor#

Return the underlying data with shape \((B,4)\).

Alias for data()

Return type

Tensor

property data: Tensor#

Return the underlying data with shape \((B,4).\)

Return type

Tensor

classmethod from_coeffs(w, x, y, z)[source]#

Create a quaternion from the data coefficients.

Parameters
  • w (float) – a float representing the \(q_w\) component.

  • x (float) – a float representing the \(q_x\) component.

  • y (float) – a float representing the \(q_y\) component.

  • z (float) – a float representing the \(q_z\) component.

Example

>>> q = Quaternion.from_coeffs(1., 0., 0., 0.)
>>> q.data
Parameter containing:
tensor([[1., 0., 0., 0.]], requires_grad=True)
Return type

Quaternion

classmethod from_matrix(matrix)[source]#

Create a quaternion from a rotation matrix.

Parameters

matrix (Tensor) – the rotation matrix to convert of shape \((B,3,3)\).

Example

>>> m = torch.eye(3)[None]
>>> q = Quaternion.from_matrix(m)
>>> q.data
Parameter containing:
tensor([[1., 0., 0., 0.]], requires_grad=True)
Return type

Quaternion

classmethod identity(batch_size)[source]#

Create a quaternion representing an identity rotation.

Parameters

batch_size (int) – the batch size of the underlying data.

Example

>>> q = Quaternion.identity(batch_size=2)
>>> q.data
Parameter containing:
tensor([[1., 0., 0., 0.],
        [1., 0., 0., 0.]], requires_grad=True)
Return type

Quaternion

matrix()[source]#

Convert the quaternion to a rotation matrix of shape \((B,3,3)\).

Example

>>> q = Quaternion.identity(batch_size=1)
>>> m = q.matrix()
>>> m
tensor([[[1., 0., 0.],
         [0., 1., 0.],
         [0., 0., 1.]]], grad_fn=<ViewBackward0>)
Return type

Tensor

property polar_angle: Tensor#

Return the polar angle with shape \((B,1)\).

Example

>>> q = Quaternion.identity(batch_size=1)
>>> q.polar_angle
tensor([[0.]], grad_fn=<AcosBackward0>)
Return type

Tensor

property q: Tensor#

Return the underlying data with shape \((B,4)\).

Alias for data()

Return type

Tensor

classmethod random(batch_size)[source]#

Create a random unit quaternion of shape \((B,4)\).

Uniformly distributed across the rotation space as per: http://planning.cs.uiuc.edu/node198.html

Parameters

batch_size (int) – the batch size of the underlying data.

Example

>>> q = Quaternion.random(batch_size=2)
>>> q.norm()
tensor([1.0000, 1.0000], grad_fn=<NormBackward1>)
Return type

Quaternion

property real: Tensor#

Return the real part with shape \((B,1)\).

Alias for w()

Return type

Tensor

property scalar: Tensor#

Return a scalar with the real with shape \((B,1)\).

Alias for w()

Return type

Tensor

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

Return the shape of the underlying data with shape \((B,4)\).

Return type

Tuple[int, ...]

property vec: Tensor#

Return the vector with the imaginary part with shape \((B,3)\).

Return type

Tensor

property w: Tensor#

Return the \(q_w\) with shape \((B,1)\).

Return type

Tensor

property x: Tensor#

Return the \(q_x\) with shape \((B,1)\).

Return type

Tensor

property y: Tensor#

Return the \(q_y\) with shape \((B,1)\).

Return type

Tensor

property z: Tensor#

Return the \(q_z\) with shape \((B,1)\).

Return type

Tensor