# kornia.geometry.quaternion¶

class kornia.geometry.quaternion.Quaternion(data)

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=<SelectBackward0>)
>>> q.vec
tensor([[0., 0., 0.],
[0., 0., 0.],
[0., 0., 0.],
[0., 0., 0.]], grad_fn=<SliceBackward0>)

__add__(right)

Add a given quaternion.

Parameters:

right (Quaternion) – the quaternion to add.

Return type:

Quaternion

Example

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

__init__(data)

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__()

Inverts the sign of the quaternion data.

Return type:

Quaternion

Example

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

__pow__(t)

Return the power of a quaternion raised to exponent t.

Parameters:

t (float) – raised exponent.

Return type:

Quaternion

Example

>>> q = Quaternion(tensor([1., .5, 0., 0.]))
>>> q_pow = q**2

__repr__()

Return repr(self).

Return type:

str

__sub__(right)

Subtract a given quaternion.

Parameters:

right (Quaternion) – the quaternion to subtract.

Return type:

Quaternion

Example

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

property coeffs: Tuple[Tensor, Tensor, Tensor, Tensor]

Return a tuple with the underlying coefficients in WXYZ order.

property data: Tensor

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

classmethod from_axis_angle(axis_angle)

Create a quaternion from axis-angle representation.

Parameters:

axis_angle (Tensor) – rotation vector of shape $$(B, 3)$$.

Return type:

Quaternion

Example

>>> axis_angle = torch.tensor([[1., 0., 0.]])
>>> q = Quaternion.from_axis_angle(axis_angle)
>>> q.data
Parameter containing:
tensor([[0.8776, 0.4794, 0.0000, 0.0000]], requires_grad=True)

classmethod from_coeffs(w, x, y, z)

Create a quaternion from the data coefficients.

Parameters:
Return type:

Quaternion

Example

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

classmethod from_euler(roll, pitch, yaw)

Create a quaternion from euler angles.

Parameters:
Return type:

Quaternion

Example

>>> roll, pitch, yaw = tensor(0), tensor(1), tensor(0)
>>> q = Quaternion.from_euler(roll, pitch, yaw)
>>> q.data
Parameter containing:
tensor([0.8776, 0.0000, 0.4794, 0.0000], requires_grad=True)

classmethod from_matrix(matrix)

Create a quaternion from a rotation matrix.

Parameters:

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

Return type:

Quaternion

Example

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

classmethod identity(batch_size=None, device=None, dtype=None)

Create a quaternion representing an identity rotation.

Parameters:

batch_size (, optional) – the batch size of the underlying data. Default: None

Return type:

Quaternion

Example

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

matrix()

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

Return type:

Tensor

Example

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

property polar_angle: Tensor

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

Example

>>> q = Quaternion.identity()
>>> q.polar_angle
tensor(0., grad_fn=<AcosBackward0>)

property q: Tensor

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

Alias for data()

classmethod random(batch_size=None, device=None, dtype=None)

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 (, optional) – the batch size of the underlying data. Default: None

Return type:

Quaternion

Example

>>> q = Quaternion.random()
>>> q = Quaternion.random(batch_size=2)

property real: Tensor

Return the real part with shape $$(B,)$$.

Alias for :func: ~kornia.geometry.quaternion.Quaternion.w

property scalar: Tensor

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

Alias for :func: ~kornia.geometry.quaternion.Quaternion.w

property shape: Tuple[int, ...]

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

slerp(q1, t)

Returns a unit quaternion spherically interpolated between quaternions self.q and q1.

See more: https://en.wikipedia.org/wiki/Slerp

Parameters:
Return type:

Quaternion

Example

>>> q0 = Quaternion.identity()
>>> q1 = Quaternion(torch.tensor([1., .5, 0., 0.]))
>>> q2 = q0.slerp(q1, .3)

to_euler()

Create a quaternion from euler angles.

Parameters:

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

Return type:

Example

>>> q = Quaternion(tensor([2., 0., 1., 1.]))
>>> roll, pitch, yaw = q.to_euler()
>>> roll
tensor(2.0344, grad_fn=<Atan2Backward0>)
>>> pitch
tensor(1.5708, grad_fn=<AsinBackward0>)
>>> yaw
tensor(2.2143, grad_fn=<Atan2Backward0>)

property vec: Tensor

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

property w: Tensor

Return the $$q_w$$ with shape $$(B,)$$.

property x: Tensor

Return the $$q_x$$ with shape $$(B,)$$.

property y: Tensor

Return the $$q_y$$ with shape $$(B,)$$.

property z: Tensor

Return the $$q_z$$ with shape $$(B,)$$.