fastdev.xform.transforms¶

Module Contents¶

fastdev.xform.transforms.transform_points(pts: jaxtyping.Float[torch.Tensor, ... n 3], tf_mat: jaxtyping.Float[torch.Tensor, ... 4 4]) → jaxtyping.Float[torch.Tensor, ... n 3][source]¶

Apply a transformation matrix on a set of 3D points.

Parameters:

pts (torch.Tensor) – 3D points, could be [… n 3]
tf_mat (torch.Tensor) – Transformation matrix, could be [… 4 4]

Returns:

Transformed pts in shape of [… n 3]

Return type:

jaxtyping.Float[torch.Tensor, … n 3]

Examples

>>> pts = torch.tensor([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
>>> tf_mat = torch.tensor([[0.0, 1.0, 0.0, 1.0], [0.0, 0.0, 1.0, 2.0], [1.0, 0.0, 0.0, 3.0], [0.0, 0.0, 0.0, 1.0]])
>>> transform_points(pts, tf_mat)
tensor([[3., 5., 4.],
        [6., 8., 7.]])

Note

The dimension number of pts and tf_mat should be the same. The batch dimensions (…) are broadcasted (and thus must be broadcastable). We don’t adopt the shapes [… 3] and [… 4 4] because there is no real broadcasted vector-matrix multiplication in pytorch. [… 3] and [… 4 4] will be converted to [… 1 3] and [… 4 4] and apply a broadcasted matrix-matrix multiplication.

fastdev.xform.transforms.rotate_points(pts: jaxtyping.Float[torch.Tensor, ... n 3], rot_mat: jaxtyping.Float[torch.Tensor, ... 3 3]) → jaxtyping.Float[torch.Tensor, ... n 3][source]¶

Rotate a set of 3D points by a rotation matrix.

Parameters:

pts (torch.Tensor) – 3D points in shape [… n 3].
rot_mat (torch.Tensor) – Rotation matrix in shape [… 3 3].

Returns:

Rotated points in shape [… n 3].

Return type:

torch.Tensor

fastdev.xform.transforms.project_points(pts: torch.Tensor, intr_mat: torch.Tensor, return_depth: Literal[False] = False) → torch.Tensor[source]¶

fastdev.xform.transforms.project_points(pts: torch.Tensor, intr_mat: torch.Tensor, return_depth: Literal[True]) → Tuple[torch.Tensor, torch.Tensor]

Project 3D points in the camera space to the image plane.

Parameters:

pts – 3D points, could be Nx3 or BxNx3.
intr_mat – Intrinsic matrix, could be 3x3 or Bx3x3.

Returns:

the order is uv other than xy. depth (if return_depth): depth in the camera space.

Return type:

pixels

fastdev.xform.transforms.unproject_points(pixels, depth, intr_mat)[source]¶

Unproject pixels in the image plane to 3D points in the camera space.

Parameters:

pixels – Pixels in the image plane, could be Nx2 or BxNx2. The order is uv rather than xy.
depth – Depth in the camera space, could be N, Nx1, BxN or BxNx1.
intr_mat – Intrinsic matrix, could be 3x3 or Bx3x3.

Returns:

3D points, Nx3 or BxNx3.

Return type:

pts

fastdev.xform.transforms.inverse_tf_mat(rot_or_tf_mat: torch.Tensor) → torch.Tensor[source]¶

Inverse a rotation matrix or a transformation matrix. Reference_

Parameters:: rot_or_tf_mat (torch.Tensor) – Rotation matrix (in shape […, 3, 3]) or transformation matrix (in shape […, 4, 4]).
Returns:: Inversed matrix.
Return type:: torch.Tensor

Examples

>>> tf_mat = torch.tensor([[0, 1, 0, 1], [0, 0, 1, 2], [1, 0, 0, 3], [0, 0, 0, 1]], dtype=torch.float32)
>>> torch.allclose(inverse_tf_mat(tf_mat) @ tf_mat, torch.eye(4))
True
>>> rot_mat = torch.tensor([[0, 1, 0], [0, 0, 1], [1, 0, 0]], dtype=torch.float32)
>>> torch.allclose(inverse_tf_mat(rot_mat) @ rot_mat, torch.eye(3))
True

fastdev.xform.transforms.swap_major(rot_or_tf_mat: torch.Tensor) → torch.Tensor[source]¶

Swap the major of a rotation matrix or a transformation matrix. Reference_

Parameters:: rot_or_tf_mat (torch.Tensor) – Rotation or transformation matrix in shape […, 3, 3] or […, 4, 4].
Returns:: Matrix with swapped major.
Return type:: torch.Tensor

fastdev.xform.transforms.to_homo(pts_3d: jaxtyping.Float[torch.Tensor, ... 3]) → jaxtyping.Float[torch.Tensor, ... 4][source]¶

Convert Cartesian 3D points to Homogeneous 4D points.

Parameters:: pts_3d (torch.Tensor) – Cartesian 3D points in shape [… 3].
Returns:: Homogeneous 4D points in shape [… 4].
Return type:: torch.Tensor

Examples

>>> pts = torch.tensor([[0, 1, 0], [0, 0, 1], [1, 0, 0]], dtype=torch.float32)
>>> to_homo(pts)
tensor([[0., 1., 0., 1.],
        [0., 0., 1., 1.],
        [1., 0., 0., 1.]])

fastdev.xform.transforms.rot_tl_to_tf_mat(rot_mat: Optional[jaxtyping.Float[torch.Tensor, ... 3 3]] = None, tl: Optional[jaxtyping.Float[torch.Tensor, ... 3]] = None) → jaxtyping.Float[torch.Tensor, ... 4 4][source]¶

Build transformation matrix with rotation matrix and translation vector.

Parameters:

rot_mat (torch.Tensor, optional) – Rotation matrix in shape [… 3 3]. Defaults to None.
tl (torch.Tensor, optional) – Translation vector in shape [… 3]. Defaults to None.

Returns:

Transformation matrix in shape [… 4 4].

Return type:

torch.Tensor

Examples

>>> rot_mat = torch.tensor([[0, 1, 0], [0, 0, 1], [1, 0, 0]], dtype=torch.float32)
>>> tl = torch.tensor([1, 2, 3], dtype=torch.float32)
>>> rot_tl_to_tf_mat(rot_mat, tl)
tensor([[0., 1., 0., 1.],
        [0., 0., 1., 2.],
        [1., 0., 0., 3.],
        [0., 0., 0., 1.]])
>>> rot_tl_to_tf_mat(tl=tl)
tensor([[1., 0., 0., 1.],
        [0., 1., 0., 2.],
        [0., 0., 1., 3.],
        [0., 0., 0., 1.]])
>>> rot_tl_to_tf_mat(rot_mat=rot_mat)
tensor([[0., 1., 0., 0.],
        [0., 0., 1., 0.],
        [1., 0., 0., 0.],
        [0., 0., 0., 1.]])

fastdev.xform.transforms.expand_tf_mat(tf_mat: jaxtyping.Float[torch.Tensor, ... 3 4]) → jaxtyping.Float[torch.Tensor, ... 4 4][source]¶

Expand transformation matrix of shape [… 3 4] to shape [… 4 4].

Parameters:: tf_mat (torch.Tensor) – Transformation matrix in shape [… 3 4] or [… 4 4].
Returns:: Expanded transformation matrix in shape [… 4 4].
Return type:: torch.Tensor

Examples

>>> tf_mat = torch.tensor([[0, 1, 0, 1], [0, 0, 1, 2], [1, 0, 0, 3]], dtype=torch.float32)
>>> expand_tf_mat(tf_mat)
tensor([[0., 1., 0., 1.],
        [0., 0., 1., 2.],
        [1., 0., 0., 3.],
        [0., 0., 0., 1.]])