kornia.geometry.liegroup#

class kornia.geometry.liegroup.So3(q)[source]#

Base class to represent the So3 group.

The SO(3) is the group of all rotations about the origin of three-dimensional Euclidean space \(R^3\) under the operation of composition. See more: https://en.wikipedia.org/wiki/3D_rotation_group

We internally represent the rotation by a unit quaternion.

Example

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

__init__(q)[source]#

Constructor for the base class.

Internally represented by a unit quaternion q.

Parameters:: data – Quaternion with the shape of \((B, 4)\).

Example

>>> data = torch.ones((2, 4))
>>> q = Quaternion(data)
>>> So3(q)
Parameter containing:
tensor([[1., 1., 1., 1.],
        [1., 1., 1., 1.]], requires_grad=True)

__mul__(right)[source]#

Compose two So3 transformations.

Parameters:: right – the other So3 transformation.
Returns:: The resulting So3 transformation.

__repr__()[source]#

Return repr(self).

Return type:: str

adjoint()[source]#

Returns the adjoint matrix of shape \((B, 3, 3)\).

Return type:: Tensor

Example

>>> s = So3.identity()
>>> s.adjoint()
tensor([[1., 0., 0.],
        [0., 1., 0.],
        [0., 0., 1.]], grad_fn=<StackBackward0>)

static exp(v)[source]#

Converts elements of lie algebra to elements of lie group.

See more: https://vision.in.tum.de/_media/members/demmeln/nurlanov2021so3log.pdf

Parameters:: v – vector of shape \((B,3)\).
Return type:: So3

Example

>>> v = torch.zeros((2, 3))
>>> s = So3.identity().exp(v)
>>> s
Parameter containing:
tensor([[1., 0., 0., 0.],
        [1., 0., 0., 0.]], requires_grad=True)

classmethod from_matrix(matrix)[source]#

Create So3 from a rotation matrix.

Parameters:: matrix (Tensor) – the rotation matrix to convert of shape \((B,3,3)\).
Return type:: So3

Example

>>> m = torch.eye(3)
>>> s = So3.from_matrix(m)
>>> s
Parameter containing:
tensor([1., 0., 0., 0.], requires_grad=True)

static hat(v)[source]#

Converts elements from vector space to lie algebra. Returns matrix of shape \((B,3,3)\).

Parameters:: v – vector of shape \((B,3)\).
Return type:: Tensor

Example

>>> v = torch.ones((1,3))
>>> m = So3.hat(v)
>>> m
tensor([[[ 0., -1.,  1.],
         [ 1.,  0., -1.],
         [-1.,  1.,  0.]]])

classmethod identity(batch_size=None, device=None, dtype=None)[source]#

Create a So3 group representing an identity rotation.

Parameters:: batch_size (Optional[int], optional) – the batch size of the underlying data. Default: None
Return type:: So3

Example

>>> s = So3.identity()
>>> s
Parameter containing:
tensor([1., 0., 0., 0.], requires_grad=True)

>>> s = So3.identity(batch_size=2)
>>> s
Parameter containing:
tensor([[1., 0., 0., 0.],
        [1., 0., 0., 0.]], requires_grad=True)

inverse()[source]#

Returns the inverse transformation.

Return type:: So3

Example

>>> s = So3.identity()
>>> s.inverse()
Parameter containing:
tensor([1., -0., -0., -0.], requires_grad=True)

log()[source]#

Converts elements of lie group to elements of lie algebra.

Return type:: Tensor

Example

>>> data = torch.ones((2, 4))
>>> q = Quaternion(data)
>>> So3(q).log()
tensor([[0., 0., 0.],
        [0., 0., 0.]], grad_fn=<WhereBackward0>)

matrix()[source]#

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

The matrix is of the form: :rtype: Tensor

\[\begin{split}\begin{bmatrix} 1-2y^2-2z^2 & 2xy-2zw & 2xy+2yw \\ 2xy+2zw & 1-2x^2-2z^2 & 2yz-2xw \\ 2xz-2yw & 2yz+2xw & 1-2x^2-2y^2\end{bmatrix}\end{split}\]

Example

>>> s = So3.identity()
>>> m = s.matrix()
>>> m
tensor([[1., 0., 0.],
        [0., 1., 0.],
        [0., 0., 1.]], grad_fn=<StackBackward0>)

property q: Quaternion #: Return the underlying data with shape \((B,4)\).

classmethod random(batch_size=None, device=None, dtype=None)[source]#

Create a So3 group representing a random rotation.

Parameters:: batch_size (Optional[int], optional) – the batch size of the underlying data. Default: None
Return type:: So3

Example

>>> s = So3.random()
>>> s = So3.random(batch_size=3)

classmethod rot_x(x)[source]#

Construct a x-axis rotation.

Parameters:: x (Tensor) – the x-axis rotation angle.
Return type:: So3

classmethod rot_y(y)[source]#

Construct a z-axis rotation.

Parameters:: y (Tensor) – the y-axis rotation angle.
Return type:: So3

classmethod rot_z(z)[source]#

Construct a z-axis rotation.

Parameters:: z (Tensor) – the z-axis rotation angle.
Return type:: So3

static vee(omega)[source]#

Converts elements from lie algebra to vector space. Returns vector of shape \((B,3)\).

\[\begin{split}omega = \begin{bmatrix} 0 & -c & b \\ c & 0 & -a \\ -b & a & 0\end{bmatrix}\end{split}\]

Parameters:: omega – 3x3-matrix representing lie algebra.
Return type:: Tensor

Example

>>> v = torch.ones((1,3))
>>> omega = So3.hat(v)
>>> So3.vee(omega)
tensor([[1., 1., 1.]])

class kornia.geometry.liegroup.Se3(rotation, translation)[source]#

Base class to represent the Se3 group.

The SE(3) is the group of rigid body transformations about the origin of three-dimensional Euclidean space \(R^3\) under the operation of composition. See more: https://ingmec.ual.es/~jlblanco/papers/jlblanco2010geometry3D_techrep.pdf

Example

>>> from kornia.geometry.quaternion import Quaternion
>>> q = Quaternion.identity()
>>> s = Se3(So3(q), torch.ones(3))
>>> s.r
Parameter containing:
tensor([1., 0., 0., 0.], requires_grad=True)
>>> s.t
Parameter containing:
tensor([1., 1., 1.], requires_grad=True)

__init__(rotation, translation)[source]#

Constructor for the base class.

Internally represented by a unit quaternion q and a translation 3-vector.

Parameters:

rotation (So3) – So3 group encompassing a rotation.
translation (Tensor) – translation vector with the shape of \((B, 3)\).

Example

>>> from kornia.geometry.quaternion import Quaternion
>>> q = Quaternion.identity(batch_size=1)
>>> s = Se3(So3(q), torch.ones((1, 3)))
>>> s.r
Parameter containing:
tensor([[1., 0., 0., 0.]], requires_grad=True)
>>> s.t
Parameter containing:
tensor([[1., 1., 1.]], requires_grad=True)

__mul__(right)[source]#

Compose two Se3 transformations.

Parameters:: right (Se3) – the other Se3 transformation.
Return type:: Se3
Returns:: The resulting Se3 transformation.

__repr__()[source]#

Return repr(self).

Return type:: str

adjoint()[source]#

Returns the adjoint matrix of shape \((B, 6, 6)\).

Return type:: Tensor

Example

>>> s = Se3.identity()
>>> s.adjoint()
tensor([[1., 0., 0., 0., 0., 0.],
        [0., 1., 0., 0., 0., 0.],
        [0., 0., 1., 0., 0., 0.],
        [0., 0., 0., 1., 0., 0.],
        [0., 0., 0., 0., 1., 0.],
        [0., 0., 0., 0., 0., 1.]], grad_fn=<CatBackward0>)

static exp(v)[source]#

Converts elements of lie algebra to elements of lie group.

Parameters:: v – vector of shape \((B, 6)\).
Return type:: Se3

Example

>>> v = torch.zeros((1, 6))
>>> s = Se3.exp(v)
>>> s.r
Parameter containing:
tensor([[1., 0., 0., 0.]], requires_grad=True)
>>> s.t
Parameter containing:
tensor([[0., 0., 0.]], requires_grad=True)

static hat(v)[source]#

Converts elements from vector space to lie algebra.

Parameters:: v – vector of shape \((B, 6)\).
Return type:: Tensor
Returns:: matrix of shape \((B, 4, 4)\).

Example

>>> v = torch.ones((1, 6))
>>> m = Se3.hat(v)
>>> m
tensor([[[ 0., -1.,  1.,  1.],
         [ 1.,  0., -1.,  1.],
         [-1.,  1.,  0.,  1.],
         [ 0.,  0.,  0.,  0.]]])

classmethod identity(batch_size=None, device=None, dtype=None)[source]#

Create a Se3 group representing an identity rotation and zero translation.

Parameters:: batch_size (Optional[int], optional) – the batch size of the underlying data. Default: None
Return type:: Se3

Example

>>> s = Se3.identity()
>>> s.r
Parameter containing:
tensor([1., 0., 0., 0.], requires_grad=True)
>>> s.t
Parameter containing:
tensor([0., 0., 0.], requires_grad=True)

inverse()[source]#

Returns the inverse transformation.

Return type:: Se3

Example

>>> s = Se3(So3.identity(), torch.ones(3))
>>> s_inv = s.inverse()
>>> s_inv.r
Parameter containing:
tensor([1., -0., -0., -0.], requires_grad=True)
>>> s_inv.t
Parameter containing:
tensor([-1., -1., -1.], requires_grad=True)

log()[source]#

Converts elements of lie group to elements of lie algebra.

Return type:: Tensor

Example

>>> from kornia.geometry.quaternion import Quaternion
>>> q = Quaternion.identity()
>>> Se3(So3(q), torch.zeros(3)).log()
tensor([0., 0., 0., 0., 0., 0.], grad_fn=<CatBackward0>)

matrix()[source]#

Returns the matrix representation of shape \((B, 4, 4)\).

Return type:: Tensor

Example

>>> s = Se3(So3.identity(), torch.ones(3))
>>> s.matrix()
tensor([[1., 0., 0., 1.],
        [0., 1., 0., 1.],
        [0., 0., 1., 1.],
        [0., 0., 0., 1.]], grad_fn=<CopySlices>)

property r: So3 #: Return the underlying rotation(So3).

classmethod random(batch_size=None, device=None, dtype=None)[source]#

Create a Se3 group representing a random transformation.

Parameters:: batch_size (Optional[int], optional) – the batch size of the underlying data. Default: None
Return type:: Se3

Example

>>> s = Se3.random()
>>> s = Se3.random(batch_size=3)

classmethod rot_x(x)[source]#

Construct a x-axis rotation.

Parameters:: x (Tensor) – the x-axis rotation angle.
Return type:: Se3

classmethod rot_y(y)[source]#

Construct a y-axis rotation.

Parameters:: y (Tensor) – the y-axis rotation angle.
Return type:: Se3

classmethod rot_z(z)[source]#

Construct a z-axis rotation.

Parameters:: z (Tensor) – the z-axis rotation angle.
Return type:: Se3

property rotation: So3 #: Return the underlying rotation(So3).

property so3: So3 #: Return the underlying rotation(So3).

property t: Tensor #: Return the underlying translation vector of shape \((B,3)\).

classmethod trans(x, y, z)[source]#

Construct a translation only Se3 instance.

Parameters:

x (Tensor) – the x-axis translation.
y (Tensor) – the y-axis translation.
z (Tensor) – the z-axis translation.

Return type:

Se3

classmethod trans_x(x)[source]#

Construct a x-axis translation.

Parameters:: x (Tensor) – the x-axis translation.
Return type:: Se3

classmethod trans_y(y)[source]#

Construct a y-axis translation.

Parameters:: y (Tensor) – the y-axis translation.
Return type:: Se3

classmethod trans_z(z)[source]#

Construct a z-axis translation.

Parameters:: z (Tensor) – the z-axis translation.
Return type:: Se3

property translation: Tensor #: Return the underlying translation vector of shape \((B,3)\).

static vee(omega)[source]#

Converts elements from lie algebra to vector space.

Parameters:: omega – 4x4-matrix representing lie algebra of shape \((B,4,4)\).
Return type:: Tensor
Returns:: vector of shape \((B,6)\).

Example

>>> v = torch.ones((1, 6))
>>> omega_hat = Se3.hat(v)
>>> Se3.vee(omega_hat)
tensor([[1., 1., 1., 1., 1., 1.]])

class kornia.geometry.liegroup.So2(z)[source]#

Base class to represent the So2 group.

The SO(2) is the group of all rotations about the origin of two-dimensional Euclidean space \(R^2\) under the operation of composition. See more: https://en.wikipedia.org/wiki/Orthogonal_group#Special_orthogonal_group

We internally represent the rotation by a complex number.

Example

>>> real = torch.tensor([1.0])
>>> imag = torch.tensor([2.0])
>>> So2(torch.complex(real, imag))
Parameter containing:
tensor([1.+2.j], requires_grad=True)

__init__(z)[source]#

Constructor for the base class.

Internally represented by complex number z.

Parameters:: z (Tensor) – Complex number with the shape of \((B, 1)\) or \((B)\).

Example

>>> real = torch.tensor(1.0)
>>> imag = torch.tensor(2.0)
>>> So2(torch.complex(real, imag)).z
Parameter containing:
tensor(1.+2.j, requires_grad=True)

__mul__(right)[source]#

Performs a left-multiplication either rotation concatenation or point-transform.

Parameters:: right – the other So2 transformation.
Returns:: The resulting So2 transformation.

__repr__()[source]#

Return repr(self).

Return type:: str

adjoint()[source]#

Returns the adjoint matrix of shape \((B, 2, 2)\).

Return type:: Tensor

Example

>>> s = So2.identity()
>>> s.adjoint()
tensor([[1., -0.],
        [0., 1.]], grad_fn=<StackBackward0>)

static exp(theta)[source]#

Converts elements of lie algebra to elements of lie group.

Parameters:: theta (Tensor) – angle in radians of shape \((B, 1)\) or \((B)\).
Return type:: So2

Example

>>> v = torch.tensor([3.1415/2])
>>> s = So2.exp(v)
>>> s
Parameter containing:
tensor([4.6329e-05+1.j], requires_grad=True)

classmethod from_matrix(matrix)[source]#

Create So2 from a rotation matrix.

Parameters:: matrix (Tensor) – the rotation matrix to convert of shape \((B, 2, 2)\).
Return type:: So2

Example

>>> m = torch.eye(2)
>>> s = So2.from_matrix(m)
>>> s.z
Parameter containing:
tensor(1.+0.j, requires_grad=True)

static hat(theta)[source]#

Converts elements from vector space to lie algebra. Returns matrix of shape \((B, 2, 2)\).

Parameters:: theta (Tensor) – angle in radians of shape \((B)\).
Return type:: Tensor

Example

>>> theta = torch.tensor(3.1415/2)
>>> So2.hat(theta)
tensor([[0.0000, 1.5707],
        [1.5707, 0.0000]])

classmethod identity(batch_size=None, device=None, dtype=None)[source]#

Create a So2 group representing an identity rotation.

Parameters:: batch_size (Optional[int], optional) – the batch size of the underlying data. Default: None
Return type:: So2

Example

>>> s = So2.identity(batch_size=2)
>>> s
Parameter containing:
tensor([1.+0.j, 1.+0.j], requires_grad=True)

inverse()[source]#

Returns the inverse transformation.

Return type:: So2

Example

>>> s = So2.identity()
>>> s.inverse().z
Parameter containing:
tensor(1.+0.j, requires_grad=True)

log()[source]#

Converts elements of lie group to elements of lie algebra.

Return type:: Tensor

Example

>>> real = torch.tensor([1.0])
>>> imag = torch.tensor([3.0])
>>> So2(torch.complex(real, imag)).log()
tensor([1.2490], grad_fn=<Atan2Backward0>)

matrix()[source]#

Convert the complex number to a rotation matrix of shape \((B, 2, 2)\).

Return type:: Tensor

Example

>>> s = So2.identity()
>>> m = s.matrix()
>>> m
tensor([[1., -0.],
        [0., 1.]], grad_fn=<StackBackward0>)

classmethod random(batch_size=None, device=None, dtype=None)[source]#

Create a So2 group representing a random rotation.

Parameters:: batch_size (Optional[int], optional) – the batch size of the underlying data. Default: None
Return type:: So2

Example

>>> s = So2.random()
>>> s = So2.random(batch_size=3)

static vee(omega)[source]#

Converts elements from lie algebra to vector space. Returns vector of shape \((B,)\).

Parameters:: omega (Tensor) – 2x2-matrix representing lie algebra.
Return type:: Tensor

Example

>>> v = torch.ones(3)
>>> omega = So2.hat(v)
>>> So2.vee(omega)
tensor([1., 1., 1.])

property z: Tensor #: Return the underlying data with shape \((B, 1)\).

class kornia.geometry.liegroup.Se2(rotation, translation)[source]#

Base class to represent the Se2 group.

The SE(2) is the group of rigid body transformations about the origin of two-dimensional Euclidean space \(R^2\) under the operation of composition. See more:

Example

>>> so2 = So2.identity(1)
>>> t = torch.ones((1, 2))
>>> se2 = Se2(so2, t)
>>> se2
rotation: Parameter containing:
tensor([1.+0.j], requires_grad=True)
translation: Parameter containing:
tensor([[1., 1.]], requires_grad=True)

__init__(rotation, translation)[source]#

Constructor for the base class.

Internally represented by a complex number z and a translation 2-vector.

Parameters:

rotation (So2) – So2 group encompassing a rotation.
translation (Tensor) – translation vector with the shape of \((B, 2)\).

Example

>>> so2 = So2.identity(1)
>>> t = torch.ones((1, 2))
>>> se2 = Se2(so2, t)
>>> se2
rotation: Parameter containing:
tensor([1.+0.j], requires_grad=True)
translation: Parameter containing:
tensor([[1., 1.]], requires_grad=True)

__mul__(right)[source]#

Compose two Se2 transformations.

Parameters:: right – the other Se2 transformation.
Returns:: The resulting Se2 transformation.

__repr__()[source]#

Return repr(self).

Return type:: str

adjoint()[source]#

Returns the adjoint matrix of shape \((B, 3, 3)\).

Return type:: Tensor

Example

>>> s = Se2.identity()
>>> s.adjoint()
tensor([[1., -0., 0.],
        [0., 1., -0.],
        [0., 0., 1.]], grad_fn=<CopySlices>)

static exp(v)[source]#

Converts elements of lie algebra to elements of lie group.

Parameters:: v – vector of shape \((B, 3)\).
Return type:: Se2

Example

>>> v = torch.ones((1, 3))
>>> s = Se2.exp(v)
>>> s.r
Parameter containing:
tensor([0.5403+0.8415j], requires_grad=True)
>>> s.t
Parameter containing:
tensor([[0.3818, 1.3012]], requires_grad=True)

static hat(v)[source]#

Converts elements from vector space to lie algebra. Returns matrix of shape \((B, 3, 3)\).

Parameters:: v – vector of shape:math:(B, 3).

Example

>>> theta = torch.tensor(3.1415/2)
>>> So2.hat(theta)
tensor([[0.0000, 1.5707],
        [1.5707, 0.0000]])

classmethod identity(batch_size=None, device=None, dtype=None)[source]#

Create a Se2 group representing an identity rotation and zero translation.

Parameters:: batch_size (Optional[int], optional) – the batch size of the underlying data. Default: None
Return type:: Se2

Example

>>> s = Se2.identity(1)
>>> s.r
Parameter containing:
tensor([1.+0.j], requires_grad=True)
>>> s.t
Parameter containing:
tensor([[0., 0.]], requires_grad=True)

inverse()[source]#

Returns the inverse transformation.

Return type:: Se2

Example

>>> s = Se2(So2.identity(1), torch.ones(1,2))
>>> s_inv = s.inverse()
>>> s_inv.r
Parameter containing:
tensor([1.+0.j], requires_grad=True)
>>> s_inv.t
Parameter containing:
tensor([[-1., -1.]], requires_grad=True)

log()[source]#

Converts elements of lie group to elements of lie algebra.

Return type:: Tensor

Example

>>> v = torch.ones((1, 3))
>>> s = Se2.exp(v).log()
>>> s
tensor([[1.0000, 1.0000, 1.0000]], grad_fn=<StackBackward0>)

matrix()[source]#

Returns the matrix representation of shape \((B, 3, 3)\).

Return type:: Tensor

Example

>>> s = Se2(So2.identity(1), torch.ones(1, 2))
>>> s.matrix()
tensor([[[1., -0., 1.],
         [0., 1., 1.],
         [0., 0., 1.]]], grad_fn=<CopySlices>)

property r: So2 #: Return the underlying rotation(So2).

classmethod random(batch_size=None, device=None, dtype=None)[source]#

Create a Se2 group representing a random transformation.

Parameters:: batch_size (Optional[int], optional) – the batch size of the underlying data. Default: None
Return type:: Se2

Example

>>> s = Se2.random()
>>> s = Se2.random(batch_size=3)

property rotation: So2 #: Return the underlying rotation(So2).

property so2: So2 #: Return the underlying rotation(So2).

property t: Tensor #: Return the underlying translation vector of shape \((B,2)\).

classmethod trans(x, y)[source]#

Construct a translation only Se2 instance.

Parameters:

x (Tensor) – the x-axis translation.
y (Tensor) – the y-axis translation.

Return type:

Se2

classmethod trans_x(x)[source]#

Construct a x-axis translation.

Parameters:: x (Tensor) – the x-axis translation.
Return type:: Se2

classmethod trans_y(y)[source]#

Construct a y-axis translation.

Parameters:: y (Tensor) – the y-axis translation.
Return type:: Se2

property translation: Tensor #: Return the underlying translation vector of shape \((B,2)\).

static vee(omega)[source]#

Converts elements from lie algebra to vector space.

Parameters:: omega – 3x3-matrix representing lie algebra of shape \((B, 3, 3)\).
Return type:: Tensor
Returns:: vector of shape \((B, 3)\).

Example

>>> v = torch.ones(3)
>>> omega_hat = Se2.hat(v)
>>> Se2.vee(omega_hat)
tensor([1., 1., 1.])