kaolin.mathutils¶

rad2deg(tensor)[source]¶

Converts a tensor of angles from radians to degrees

Parameters: tensor (torch.Tensor) – Input tensor (no shape restrictions).
Returns: Tensor of same shape as input.
Return type: torch.Tensor

Example

>>> deg = kaolin.pi * kaolin.rad2deg(torch.rand(1, 2, 3))

deg2rad(tensor)[source]¶

Converts angles from degrees to radians

Parameters: tensor (torch.Tensor) – Input tensor (no shape restrictions).
Returns: Tensor of same shape as input.
Return type: torch.Tensor

Example

>>> rad = kaolin.deg2rad(360. * torch.rand(1, 3, 3))

homogenize_points(pts: torch.Tensor)[source]¶

Converts a set of points to homogeneous coordinates.

Parameters: pts (torch.Tensor) – Tensor containing points to be homogenized.
Returns: Homogeneous coordinates for pts.
Return type: (torch.Tensor)

Shape:: pts: \(\cdots \times 2\) or \(\cdots \times 3\)

Example

>>> pts = torch.randn(2, 5, 3)
tensor([[[ 0.0897, -0.1876,  0.1637],
         [-0.1026, -0.4994,  0.8622],
         [-1.2909,  0.2678, -1.8021],
         [-0.2500,  0.3505,  0.9121],
         [ 0.0580,  1.4497, -0.7224]],

[[ 0.8102, -0.2467, 0.1951],
[ 0.4059, -1.9658, 0.1850], [ 1.5487, -0.8154, -0.5592], [ 0.2269, -0.4137, 0.7187], [-1.1810, -2.3412, -0.4925]]])

>>> homo_pts = homogenize_points(pts)
tensor([[[ 0.0897, -0.1876,  0.1637,  1.0000],
         [-0.1026, -0.4994,  0.8622,  1.0000],
         [-1.2909,  0.2678, -1.8021,  1.0000],
         [-0.2500,  0.3505,  0.9121,  1.0000],
         [ 0.0580,  1.4497, -0.7224,  1.0000]],

[[ 0.8102, -0.2467, 0.1951, 1.0000],
[ 0.4059, -1.9658, 0.1850, 1.0000], [ 1.5487, -0.8154, -0.5592, 1.0000], [ 0.2269, -0.4137, 0.7187, 1.0000], [-1.1810, -2.3412, -0.4925, 1.0000]]])

>>> homo_pts.shape
torch.Size([2, 5, 4])

unhomogenize_points(pts: torch.Tensor)[source]¶

Convert a set of points from homogeneous coordinates (i.e., projective space) to Euclidean space.

Usually, for each point \((x, y, z, w)\) for the 3D case, unhomogenize_points returns \(\left(\frac{x}{w}, \frac{y}{w}, \frac{z}{w} \right)\). For the special case where \(w\) is zero, unhomogenize_points returns \((x, y, z)\), following OpenCV’s convention.

Parameters: pts (torch.Tensor) – Tensor containing points to be unhomogenized.

Shape:: pts: \(\cdots \times 3\) or \(\cdots \times 4\) (usually).

Returns: Unhomogenized coordinates for pts.
Return type: (torch.Tensor)

Examples

>>> homo_pts = torch.randn(2, 5, 4)
tensor([[[ 0.0897, -0.1876,  0.1637,  1.0000],
         [-0.1026, -0.4994,  0.8622,  1.0000],
         [-1.2909,  0.2678, -1.8021,  1.0000],
         [-0.2500,  0.3505,  0.9121,  1.0000],
         [ 0.0580,  1.4497, -0.7224,  1.0000]],

[[ 0.8102, -0.2467, 0.1951, 1.0000],
[ 0.4059, -1.9658, 0.1850, 1.0000], [ 1.5487, -0.8154, -0.5592, 1.0000], [ 0.2269, -0.4137, 0.7187, 1.0000], [-1.1810, -2.3412, -0.4925, 1.0000]]])

>>> unhomo_pts = kal.math.unhomogenize_points(homo_pts)
tensor([[[ 0.0897, -0.1876,  0.1637],
         [-0.1026, -0.4994,  0.8622],
         [-1.2909,  0.2678, -1.8021],
         [-0.2500,  0.3505,  0.9121],
         [ 0.0580,  1.4497, -0.7224]],

[[ 0.8102, -0.2467, 0.1951],
[ 0.4059, -1.9658, 0.1850], [ 1.5487, -0.8154, -0.5592], [ 0.2269, -0.4137, 0.7187], [-1.1810, -2.3412, -0.4925]]])

>>> unhomo_pts = kal.math.unhomogenize_points(unhomo_pts)
tensor([[[  0.5482,  -1.1463],
         [ -0.1190,  -0.5792],
         [  0.7163,  -0.1486],
         [ -0.2741,   0.3843],
         [ -0.0803,  -2.0066]],

[[ 4.1518, -1.2645],
[ 2.1938, -10.6255], [ -2.7696, 1.4582], [ 0.3157, -0.5756], [ 2.3977, 4.7533]]])

transform3d(pts: torch.Tensor, tform: torch.Tensor) → torch.Tensor[source]¶

Transform a set of points pts using a general 3D transform tform.

Parameters

pts (torch.Tensor) – Points to be transformed (shape: \(\cdots \times 4\))
tform (torch.Tensor) – A 3D projective transformation matrix. (shape: \(4 \times 4\))

Returns: (torch.Tensor): Transformed points.

invert_rigid_transform_3d(tform: torch.Tensor)[source]¶

Invert a 3D rigid body (SE(3)) transform.

Parameters

tform (torch.Tensor) – SE(3) transformation matrix (shape: \(\cdots \times 4 \times 4\))

Returns

Inverse transformation matrix (shape:: \(\cdots \times 4 \times 4\))

Return type

inv_tform (torch.Tensor)

compose_transforms_3d(tforms)[source]¶

Compose (concatenate) a series of 3D transformation matrices.

Parameters

tforms (tuple, list) – Iterable containing the transforms to be composed (Each transform must be of type torch.Tensor) (shape: \(\cdots \times 4 \times 4\)).

Returns

Concatenated transform. (shape:: \(\cdots \times 4 \times 4\))

Return type

cat (torch.Tensor)

rotx(theta, enc='rad')[source]¶

Returns a 3D rotation matrix about the X-axis

Returns the 3 x 3 rotation matrix \(R\) that rotates a 3D point by an angle theta about the X-axis of the canonical Cartesian axes \(\left[ e_1 e_2 e_3 \right]\).

Note:

\[\begin{split}e_1 = \begin{bmatrix} 1 \\ 0 \\ 0 \end{bmatrix}, e_2 = \begin{bmatrix} 0 \\ 1 \\ 0 \end{bmatrix}, e_3 = \begin{bmatrix} 0 \\ 0 \\ 1 \end{bmatrix}\end{split}\]

Generated matrix:

\[\begin{split}R = \begin{bmatrix} 1 & 0 & 0 \\ 0 & cos(\theta) & -sin(\theta) \\ 0 & sin(\theta) & cos(\theta) \end{bmatrix}\end{split}\]

Parameters

theta (Tensor or np.array) – degree of rotation (assumes radians by default)
enc (str, choices=['rad', 'deg']) – whether the angle is specified in degrees (‘deg’) or radians (‘rad’). Default: ‘rad’.

Returns

one 3 x 3 rotation matrix, for each input entry in theta

Return type

Tensor

Shape:

Input: \((B)\) (or) \((B, 1)\) (\(B\) is the batchsize)
Output: \((B, 3, 3)\)

Examples

>>> # Create a random batch of angles of rotation
>>> theta = torch.randn(10, 1)
>>> # Get a 10 x 3 x 3 rotation matrix, one 3 x 3 matrix for each element
>>> rx = kaolin.mathutils.rotx(theta)
>>> # Alternatively, use rotations specified in degrees
>>> theta = 180 * torch.randn(10, 1)
>>> rx = kaolin.mathutils.rotx(theta, enc='deg')

roty(theta, enc='rad')[source]¶

Returns a 3D rotation matrix about the Y-axis

Returns the 3 x 3 rotation matrix that rotates a 3D point by an angle theta about the Y-axis of the canonical Cartesian axes [e1 e2 e3].

Note:

\[\begin{split}e_1 = \begin{bmatrix} 1 \\ 0 \\ 0 \end{bmatrix}, e_2 = \begin{bmatrix} 0 \\ 1 \\ 0 \end{bmatrix}, e_3 = \begin{bmatrix} 0 \\ 0 \\ 1 \end{bmatrix}\end{split}\]

Generated matrix:

\[\begin{split}R = \begin{bmatrix} cos(\theta) & 0 & sin(\theta) \\ 0 & 1 & 0 \\ -sin(\theta) & 0 & cos(\theta) \end{bmatrix}\end{split}\]

Parameters

theta (Tensor or np.array) – degree of rotation (assumes radians by default)
enc (str, choices=['rad', 'deg']) – whether the angle is specified in degrees (‘deg’) or radians (‘rad’). Default: ‘rad’.

Returns

one 3 x 3 rotation matrix, for each input entry in theta

Return type

Tensor

Shape:

Input: \((B)\) (or) \((B, 1)\) (\(B\) is the batchsize)
Output: \((B, 3, 3)\)

Examples

>>> # Create a random batch of angles of rotation
>>> theta = torch.randn(10, 1)
>>> # Get a 10 x 3 x 3 rotation matrix, one 3 x 3 matrix for each element
>>> ry = kaolin.mathutils.roty(theta)
>>> # Alternatively, use rotations specified in degrees
>>> theta = 180 * torch.randn(10, 1)
>>> ry = kaolin.mathutils.roty(theta, enc='deg')

rotz(theta, enc='rad')[source]¶

Returns a 3D rotation matrix about the Z-axis

Returns the 3 x 3 rotation matrix that rotates a 3D point by an angle theta about the Z-axis of the canonical Cartesian axes [e1 e2 e3].

Note:

\[\begin{split}e_1 = \begin{bmatrix} 1 \\ 0 \\ 0 \end{bmatrix}, e_2 = \begin{bmatrix} 0 \\ 1 \\ 0 \end{bmatrix}, e_3 = \begin{bmatrix} 0 \\ 0 \\ 1 \end{bmatrix}\end{split}\]

Generated matrix:

\[\begin{split}R = \begin{bmatrix} cos(\theta) & -sin(\theta) & 0 \\ sin(\theta) & cos(\theta) & 0 \\ 0 & 0 & 1 \end{bmatrix}\end{split}\]

Parameters

theta (Tensor or np.array) – degree of rotation (assumes radians by default)
enc (str, choices=['rad', 'deg']) – whether the angle is specified in degrees (‘deg’) or radians (‘rad’). Default: ‘rad’.

Returns

one 3 x 3 rotation matrix, for each input entry in theta

Return type

Tensor

Shape:

Input: \((B)\) (or) \((B, 1)\) (\(B\) is the batchsize)
Output: \((B, 3, 3)\)

Examples

>>> # Create a random batch of angles of rotation
>>> theta = torch.randn(10, 1)
>>> # Get a 10 x 3 x 3 rotation matrix, one 3 x 3 matrix for each element
>>> rz = kaolin.mathutils.rotz(theta)
>>> # Alternatively, use rotations specified in degrees
>>> theta = 180 * torch.randn(10, 1)
>>> rz = kaolin.mathutils.rotz(theta, enc='deg')

class SO3Exp(eps=1e-08)[source]¶

Exponential map for SO(3), i.e., for 3 x 3 rotation matrices.

Map a batch of so(3) vectors (axis-angle) to 3D rotation matrices.

Parameters

x (torch.Tensor) – Input so(3) exponential coordinates
eps (float, optional) – Threshold to determine which angles are deemed ‘small’

Returns

Output SO(3) rotation matrices

Return type

x (torch.Tensor)

Shape:: input: \((B, 3)\) where \(B\) is the batchsize. output: \((B, 3, 3)\) where \(B\) is the batchsize.

Example

>>> omega = torch.Tensor([[1, 2, 3], [4, 5, 6]])
>>> so3exp = SO3Exp()
>>> print(R)
>>> print(torch.bmm(R, R.transpose(1,2))) # Should be nearly identity matrices