kornia.geometry.pose#

NamedPose holds an Se2 or Se3 pose together with the names of its source and destination frames. A pose b_from_a maps points in frame a to frame b, and c_from_b * b_from_a is c_from_a: a composition whose frames do not chain raises instead of returning a wrong pose.

class kornia.geometry.pose.NamedPose(dst_from_src, frame_src=None, frame_dst=None)[source]#

Hold an SE(2) or SE(3) pose with the names of its two frames, which composition checks.

b_from_a = NamedPose(pose, frame_src="a", frame_dst="b") wraps an Se3 or Se2 pose that maps frame a to frame b; b_from_a.transform_points(points) maps points from a to b, and c_from_b * b_from_a composes two poses into c_from_a after checking that the frames chain. An unbatched Se3 maps (3,) or (N, 3), and a batch of B maps (B, 3), one point per pose (a batch of one also maps (N, 3)); an unbatched Se2 maps (2,) or (N, 2), and a batch of B maps (B, 2). Other layouts, such as a batch of poses with a point set (B, N, 3), raise ValueError. Build one from a rotation and a translation with from_rt(), or from a 3 x 3 or 4 x 4 matrix with from_matrix(). For a pose without frame names, use the Lie group classes directly; for 4 x 4 matrices, compose_transformations().

Convention:
  • NamedPose(pose, frame_src="1", frame_dst="0") is trans_01 in the notation of relative_transformation(), for an Se2 and an Se3 pose alike.

  • The matrix of c_from_b * b_from_a is c_from_b.pose.matrix() @ b_from_a.pose.matrix(). The left operand’s frame_src must equal the right operand’s frame_dst, otherwise * raises ValueError; inverse() inverts the pose and swaps the frame names.

  • The pose must be an Se2 or an Se3: an So3, So2, Quaternion or tensor is rejected at construction (use from_rt() or from_matrix() to build a pose from one), and * raises TypeError for a right operand that is not a NamedPose or holds the other group.

See also

  • Se3: the 3D rigid pose it wraps, without frame names.

  • Se2: the 2D rigid pose it wraps, without frame names.

  • relative_transformation(): the relative pose of two 4 x 4 matrices.

Example

>>> b_from_a = NamedPose(Se3.identity(), frame_src="frame_a", frame_dst="frame_b")
>>> b_from_a
NamedPose(dst_from_src=rotation: tensor([1., 0., 0., 0.])
translation: Parameter containing:
tensor([0., 0., 0.], requires_grad=True),
frame_src: frame_a -> frame_dst: frame_b)
__init__(dst_from_src, frame_src=None, frame_dst=None)[source]#

Construct NamedPose.

Parameters:
  • dst_from_src (Se2 | Se3) – Pose from source frame to destination frame.

  • frame_src (str | None, optional) – Name of the source frame; a random unique name when omitted or empty. Default: None

  • frame_dst (str | None, optional) – Name of the destination frame; a random unique name when omitted or empty. Default: None

Raises:

TypeCheckError – if dst_from_src is not an Se2 or an Se3.

__mul__(other)[source]#

Compose two NamedPoses.

Parameters:

other (NamedPose) – NamedPose to compose with.

Return type:

NamedPose

Returns:

Composed NamedPose.

Raises:
  • TypeError – if other is not a NamedPose or its pose is not of the same group as self.pose.

  • ValueError – if self.frame_src is not other.frame_dst.

Example

>>> b_from_a = NamedPose(Se3.identity(), frame_src="frame_a", frame_dst="frame_b")
>>> c_from_b = NamedPose(Se3.identity(), frame_src="frame_b", frame_dst="frame_c")
>>> c_from_b * b_from_a
NamedPose(dst_from_src=rotation: tensor([1., 0., 0., 0.])
translation: tensor([0., 0., 0.], grad_fn=<AddBackward0>),
frame_src: frame_a -> frame_dst: frame_c)
property frame_dst: str#

Name of the destination frame.

property frame_src: str#

Name of the source frame.

classmethod from_matrix(matrix, frame_src=None, frame_dst=None)[source]#

Construct NamedPose from a matrix.

Parameters:
  • matrix (Tensor) – Matrix representation of the pose.

  • frame_src (str | None, optional) – Name of the source frame; a random unique name when omitted or empty. Default: None

  • frame_dst (str | None, optional) – Name of the destination frame; a random unique name when omitted or empty. Default: None

Return type:

NamedPose | None

Returns:

NamedPose constructed from a matrix.

Example

>>> b_from_a_matrix = torch.eye(4)
>>> b_from_a = NamedPose.from_matrix(b_from_a_matrix, frame_src="frame_a", frame_dst="frame_b")
>>> b_from_a
NamedPose(dst_from_src=rotation: tensor([1., 0., 0., 0.])
translation: Parameter containing:
tensor([0., 0., 0.], requires_grad=True),
frame_src: frame_a -> frame_dst: frame_b)
classmethod from_rt(rotation, translation, frame_src=None, frame_dst=None)[source]#

Construct NamedPose from rotation and translation.

Parameters:
  • rotation (So3 | So2 | Tensor | Quaternion) – Rotation part of the pose.

  • translation (Tensor) – Translation part of the pose.

  • frame_src (str | None, optional) – Name of the source frame; a random unique name when omitted or empty. Default: None

  • frame_dst (str | None, optional) – Name of the destination frame; a random unique name when omitted or empty. Default: None

Return type:

NamedPose | None

Returns:

NamedPose constructed from rotation and translation.

Example

>>> b_from_a_rot = So3.identity()
>>> b_from_a_trans = torch.tensor([1., 2., 3.])
>>> b_from_a = NamedPose.from_rt(b_from_a_rot, b_from_a_trans, frame_src="frame_a", frame_dst="frame_b")
>>> b_from_a
NamedPose(dst_from_src=rotation: tensor([1., 0., 0., 0.])
translation: Parameter containing:
tensor([1., 2., 3.], requires_grad=True),
frame_src: frame_a -> frame_dst: frame_b)
inverse()[source]#

Inverse of the NamedPose.

Return type:

NamedPose

Returns:

Inverse of the NamedPose.

Example

>>> b_from_a = NamedPose(Se3.identity(), frame_src="frame_a", frame_dst="frame_b")
>>> b_from_a.inverse()
NamedPose(dst_from_src=rotation: tensor([1., -0., -0., -0.])
translation: tensor([0., 0., 0.], grad_fn=<SliceBackward0>),
frame_src: frame_b -> frame_dst: frame_a)
property pose: Se2 | Se3#

Pose from source frame to destination frame .

property rotation: So3 | So2#

Rotation part of the pose.

transform_points(points_in_src)[source]#

Transform points from source frame to destination frame.

Parameters:

points_in_src (Tensor) – Points in source frame.

Return type:

Tensor

Returns:

Points in destination frame.

Example

>>> b_from_a = NamedPose(Se3.identity(), frame_src="frame_a", frame_dst="frame_b")
>>> b_from_a.transform_points(torch.tensor([1., 2., 3.]))
tensor([1., 2., 3.], grad_fn=<AddBackward0>)
property translation: Tensor#

Translation part of the pose.