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:
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:
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:
Example
>>> q = Quaternion(tensor([1., .5, 0., 0.])) >>> q_pow = q**2
- __sub__(right)#
Subtract a given quaternion.
- Parameters:
right (
Quaternion) – the quaternion to subtract.- Return type:
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.
- 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:
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:
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:
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:
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[int], optional) – the batch size of the underlying data. Default:None- Return type:
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:
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>)
- 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[int], optional) – the batch size of the underlying data. Default:None- Return type:
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
- slerp(q1, t)#
Returns a unit quaternion spherically interpolated between quaternions self.q and q1.
See more: https://en.wikipedia.org/wiki/Slerp
- Parameters:
q1 (
Quaternion) – second quaternion to be interpolated between.t (
float) – interpolation ratio, range [0-1]
- Return type:
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>)