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
- __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
- __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
- property coeffs: Tensor#
Return the underlying data with shape \((B,4)\).
Alias for
data()- Return type
- classmethod from_coeffs(w, x, y, z)[source]#
Create a quaternion from the data coefficients.
- Parameters
Example
>>> q = Quaternion.from_coeffs(1., 0., 0., 0.) >>> q.data Parameter containing: tensor([[1., 0., 0., 0.]], requires_grad=True)
- Return type
- 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
- 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
- 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
- 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
- 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
- property scalar: Tensor#
Return a scalar with the real with shape \((B,1)\).
Alias for
w()- Return type