vis4d.op.geometry.rotation¶

Rotation utilities.

Functions

`acute_angle`(theta_1, theta_2)	Update theta_1 to mkae the agnle between two thetas is acute.
`alpha2yaw`(alpha, center)	Get vertical rotation by alpha + theta.
`euler_angles_to_matrix`(euler_angles[, ...])	Convert rotations given as Euler angles in radians to rotation matrices.
`generate_rotation_output`(pred[, num_bins])	Convert output to bin confidence and cos / sin of residual.
`matrix_to_euler_angles`(matrix[, convention])	Convert rotations given as rotation matrices to Euler angles in radians.
`matrix_to_quaternion`(matrix)	Convert rotations given as rotation matrices to quaternions.
`normalize_angle`(input_angles)	Normalize content of input_angles to range [-pi, pi].
`quaternion_apply`(quaternion, points)	Apply the rotation given by a quaternion to a 3D point.
`quaternion_invert`(quaternion)	Return quaternion that represents inverse rotation.
`quaternion_multiply`(quat1, quat2)	Multiply two quaternions representing rotations.
`quaternion_raw_multiply`(quat1, quat2)	Multiply two quaternions.
`quaternion_to_matrix`(quaternions)	Convert rotations given as quaternions to rotation matrices.
`rotate_orientation`(orientation, extrinsics)	Rotate the orientation of the object in different coordinate.
`rotate_velocities`(velocities, extrinsics)	Rotate the velocities of the object in different coordinate.
`rotation_matrix_yaw`(rotation_matrix, axis_mode)	Get yaw of 3D boxes in euler angle under given axis mode.
`rotation_output_to_alpha`(output[, num_bins])	Get alpha from bin-based regression output.
`standardize_quaternion`(quaternions)	Convert a unit quaternion to a standard form.
`yaw2alpha`(rot_y, center)	Get alpha by vertical rotation - theta.

acute_angle(theta_1, theta_2)[source]¶

Update theta_1 to mkae the agnle between two thetas is acute.

Return type:: Tensor

alpha2yaw(alpha, center)[source]¶

Get vertical rotation by alpha + theta.

Parameters:

alpha (Tensor) – Observation angle of object, ranging [-pi..pi]
center (Tensor) – 3D object center in camera coordinates

Returns:

Vertical rotation in camera coordinates [-pi..pi]

Return type:

rot_y

euler_angles_to_matrix(euler_angles, convention='XYZ')[source]¶

Convert rotations given as Euler angles in radians to rotation matrices.

Parameters:

euler_angles (Tensor) – Euler angles in radians as tensor of shape (…, 3).
convention (str) – Convention string of three uppercase letters from
"X"
"Y"
"Z". (and)

Return type:

Tensor

Returns:

Rotation matrices as tensor of shape (…, 3, 3).

Raises:

ValueError – if convention string is not a combination of XYZ

generate_rotation_output(pred, num_bins=2)[source]¶

Convert output to bin confidence and cos / sin of residual.

The viewpoint (alpha) prediction (N, num_bins + 2 * num_bins) consists of: bin confidences (N, num_bins): softmax logits for bin probability. 1st entry is probability for orientation being in bin 1, 2nd entry is probability for orientation being in bin 2, and so on. bin residual (N, num_bins * 2): angle residual w.r.t. bin N orientation, represented as sin and cos values.

See: 3D Bounding Box Estimation Using Deep Learning and Geometry, Mousavian et al., CVPR’17

Return type:: Tensor

matrix_to_euler_angles(matrix, convention='XYZ')[source]¶

Convert rotations given as rotation matrices to Euler angles in radians.

Parameters:

matrix (Tensor) – Rotation matrices as tensor of shape (…, 3, 3).
convention (str) – Convention string of three uppercase letters.

Return type:

Tensor

Returns:

Euler angles in radians as tensor of shape (…, 3).

Raises:

ValueError – if convention string is not a combination of XYZ

matrix_to_quaternion(matrix)[source]¶

Convert rotations given as rotation matrices to quaternions.

Parameters:: matrix (Tensor) – Rotation matrices as tensor of shape (…, 3, 3).
Return type:: Tensor
Returns:: quaternions with real part first, as tensor of shape (…, 4).
Raises:: ValueError – If shape of input matrix is not correct.

normalize_angle(input_angles)[source]¶

Normalize content of input_angles to range [-pi, pi].

Parameters:: input_angles (Tensor) – (Tensor) tensor of any shape containing unnormalized angles.
Return type:: Tensor
Returns:: Tensor with angles normalized to +/- pi

quaternion_apply(quaternion, points)[source]¶

Apply the rotation given by a quaternion to a 3D point.

Usual torch rules for broadcasting apply.

Parameters:

quaternion (Tensor) – Tensor of quaternions, real part first, of shape (…, 4).
points (Tensor) – Tensor of 3D points of shape (…, 3).

Return type:

Tensor

Returns:

Tensor of rotated points of shape (…, 3).

Raises:

ValueError – If points is not a valid 3D point set.

quaternion_invert(quaternion)[source]¶

Return quaternion that represents inverse rotation.

Parameters:: quaternion (Tensor) – Quaternions as tensor of shape (…, 4), with real part first, which must be versors (unit quaternions).
Return type:: Tensor
Returns:: The inverse, a tensor of quaternions of shape (…, 4).

quaternion_multiply(quat1, quat2)[source]¶

Multiply two quaternions representing rotations.

Returns the quaternion representing their composition, i.e. the version with nonnegative real part. Usual torch rules for broadcasting apply.

Parameters:

quat1 (Tensor) – Quaternions as tensor of shape (…, 4), real part first.
quat2 (Tensor) – Quaternions as tensor of shape (…, 4), real part first.

Return type:

Tensor

Returns:

The product of quat1 and quat2, tensor of quaternions shape (…, 4).

quaternion_raw_multiply(quat1, quat2)[source]¶

Multiply two quaternions.

Usual torch rules for broadcasting apply.

Parameters:

quat1 (Tensor) – Quaternions as tensor of shape (…, 4), real part first.
quat2 (Tensor) – Quaternions as tensor of shape (…, 4), real part first.

Return type:

Tensor

Returns:

The product of quat1 and quat2, tensor of quaternions shape (…, 4).

quaternion_to_matrix(quaternions)[source]¶

Convert rotations given as quaternions to rotation matrices.

Parameters:: quaternions (Tensor) – quaternions with real part first, as tensor of shape (…, 4).
Return type:: Tensor
Returns:: Rotation matrices as tensor of shape (…, 3, 3).

rotate_orientation(orientation, extrinsics, axis_mode=AxisMode.ROS)[source]¶

Rotate the orientation of the object in different coordinate.

Parameters:

orientation (Tensor) – [N, 3] Orientation of the object in euler angles.
extrinsics (Tensor) – [4, 4] Extrinsic matrix of the object.
axis_mode (AxisMode) – Coordinate system convention. Default: AxisMode.ROS

Return type:

Tensor

rotate_velocities(velocities, extrinsics)[source]¶

Rotate the velocities of the object in different coordinate.

Return type:: Tensor

rotation_matrix_yaw(rotation_matrix, axis_mode)[source]¶

Get yaw of 3D boxes in euler angle under given axis mode.

Parameters:

rotation_matrix (Tensor) – [N, 3, 3] Rotation matrix of the object.
axis_mode (AxisMode) – Coordinate system convention.

Returns:

[N, 3] Yaw in euler angle.

Return type:

orientation (Tensor)

rotation_output_to_alpha(output, num_bins=2)[source]¶

Get alpha from bin-based regression output.

Uses method described in (with two bins): See: 3D Bounding Box Estimation Using Deep Learning and Geometry, Mousavian et al., CVPR’17

Parameters:

output (Tensor) – (Tensor) bin based regressed output.
num_bins (int) – (int) number of bins to use

Return type:

Tensor

Returns:

Tensor containing the angle from the bin-based regression output

standardize_quaternion(quaternions)[source]¶

Convert a unit quaternion to a standard form.

Standard form: One in which the real part is non negative.

Parameters:: quaternions (Tensor) – Quaternions with real part first, as tensor of shape (…, 4).
Return type:: Tensor
Returns:: Standardized quaternions as tensor of shape (…, 4).

yaw2alpha(rot_y, center)[source]¶

Get alpha by vertical rotation - theta.

Parameters:

rot_y (Tensor) – Rotation around Y-axis in camera coordinates [-pi..pi]
center (Tensor) – 3D object center in camera coordinates

Returns:

Observation angle of object, ranging [-pi..pi]

Return type:

alpha