fastdev.xform.rotation ====================== .. py:module:: fastdev.xform.rotation Module Contents --------------- .. py:function:: random_rotation_matrix(num: Optional[int] = None, random_state: Optional[Union[int, numpy.random.Generator, numpy.random.RandomState]] = None, return_tensors: Literal['np', 'pt'] = 'np') .. py:function:: split_axis_angle_vector(axis_angle) .. py:function:: compose_axis_angle_vector(axis, angle) .. py:function:: axis_angle_vector_to_quaternion(axis_angle) Convert rotations given as axis/angle to quaternions. :param axis_angle: Rotations given as a vector in axis angle form, as a tensor of shape (..., 3), where the magnitude is the angle turned anticlockwise in radians around the vector's direction. :returns: quaternions with real part first, as tensor of shape (..., 4). Reference: https://en.wikipedia.org/wiki/Axis%E2%80%93angle_representation#Unit_quaternions .. py:function:: quaternion_to_axis_angle_vector(quaternions) Convert rotations given as quaternions to axis/angle. :param quaternions: quaternions with real part first, as tensor of shape (..., 4). :returns: Rotations given as a vector in axis angle form, as a tensor of shape (..., 3), where the magnitude is the angle turned anticlockwise in radians around the vector's direction. Reference: https://en.wikipedia.org/wiki/Axis%E2%80%93angle_representation#Unit_quaternions .. py:function:: standardize_quaternion(quaternions: torch.Tensor) -> torch.Tensor Convert a unit quaternion to a standard form: one in which the real part is non negative. :param quaternions: Quaternions with real part first, as tensor of shape (..., 4). :returns: Standardized quaternions as tensor of shape (..., 4). .. py:function:: quaternion_real_to_last(quaternions) .. py:function:: quaternion_real_to_first(quaternions) .. py:function:: quaternion_to_matrix(quaternions: torch.Tensor) -> torch.Tensor Convert rotations given as quaternions to rotation matrices. :param quaternions: quaternions with real part first with shape (..., 4). :type quaternions: Tensor :returns: Rotation matrices as tensor of shape (..., 3, 3). :rtype: Tensor Reference: https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation .. py:function:: matrix_to_quaternion(matrix: jaxtyping.Float[torch.Tensor, ... 3 3]) -> jaxtyping.Float[torch.Tensor, ... 4] Convert rotation matrices to quaternions using Shepperds's method. :param matrix: (np.ndarray, torch.Tensor): rotation matrices, the shape could be ...3x3. :returns: quaternions with real part first in shape of (..., 4). .. rubric:: Example >>> rot_mat = torch.tensor([[-0.2533, -0.6075, 0.7529], ... [ 0.8445, -0.5185, -0.1343], ... [ 0.4720, 0.6017, 0.6443]]) >>> matrix_to_quaternion(rot_mat) tensor([0.4671, 0.3940, 0.1503, 0.7772]) Ref: http://www.iri.upc.edu/files/scidoc/2068-Accurate-Computation-of-Quaternions-from-Rotation-Matrices.pdf Note that the way to determine the best solution is slightly different from the PDF. .. py:function:: axis_angle_to_matrix(axis: jaxtyping.Float[torch.Tensor, ... 3], angle: jaxtyping.Float[torch.Tensor, ...]) -> jaxtyping.Float[torch.Tensor, ... 3 3] Converts axis angles to rotation matrices using Rodrigues formula. :param axis: axis, the shape could be [..., 3]. :type axis: torch.Tensor :param angle: angle, the shape could be [...]. :type angle: torch.Tensor :returns: Rotation matrices [..., 3, 3]. :rtype: torch.Tensor .. rubric:: Example >>> axis = torch.tensor([1.0, 0.0, 0.0]) >>> angle = torch.tensor(0.5) >>> axis_angle_to_matrix(axis, angle) tensor([[ 1.0000, 0.0000, 0.0000], [ 0.0000, 0.8776, -0.4794], [ 0.0000, 0.4794, 0.8776]]) .. py:function:: matrix_to_euler_angles(matrix: torch.Tensor, convention: str = 'xyz') -> torch.Tensor Convert rotations given as rotation matrices to Euler angles in radians. :param matrix: Rotation matrices with shape (..., 3, 3). :param convention: Convention string of 3/4 letters, e.g. "xyz", "sxyz", "rxyz", "exyz". If the length is 3, the extrinsic rotation is assumed. If the length is 4, the first character is "r/i" (rotating/intrinsic), or "s/e" (static / extrinsic). The remaining characters are the axis "x, y, z" in the order. :returns: Euler angles in radians with shape (..., 3). .. py:function:: euler_angles_to_matrix(euler_angles: jaxtyping.Float[torch.Tensor, ... 3], axes: _AXES = 'sxyz') -> jaxtyping.Float[torch.Tensor, ... 3 3] Converts Euler angles to rotation matrices. :param euler_angles: Euler angles, the shape could be [..., 3]. :type euler_angles: torch.Tensor :param axes: Axis specification; one of 24 axis string sequences - e.g. `sxyz (the default). It's recommended to use the full name of the axes, e.g. "sxyz" instead of "xyz", but if 3 characters are provided, it will be prefixed with "s". :type axes: str :returns: Rotation matrices [..., 3, 3]. :rtype: torch.Tensor .. rubric:: Example >>> euler_angles = torch.tensor([1.0, 0.5, 2.0]) >>> euler_angles_to_matrix(euler_angles, axes="sxyz") tensor([[-0.3652, -0.6592, 0.6574], [ 0.7980, 0.1420, 0.5857], [-0.4794, 0.7385, 0.4742]]) >>> euler_angles_to_matrix(euler_angles, axes="rxyz") tensor([[-0.3652, -0.7980, 0.4794], [ 0.3234, -0.5917, -0.7385], [ 0.8729, -0.1146, 0.4742]]) .. py:function:: rotation_6d_to_matrix(d6: torch.Tensor) -> torch.Tensor Converts 6D rotation representation by Zhou et al. [1] to rotation matrix using Gram--Schmidt orthogonalization per Section B of [1]. :param d6: 6D rotation representation of shape [..., 6] :type d6: Tensor :returns: Rotation matrices of shape [..., 3, 3] :rtype: Tensor [1] Zhou, Y., Barnes, C., Lu, J., Yang, J., & Li, H. On the Continuity of Rotation Representations in Neural Networks. CVPR 2019. arxiv_ `pytorch3d implementation`_ .. _arxiv: https://arxiv.org/pdf/1812.07035 .. _`pytorch3d implementation`: https://github.com/facebookresearch/pytorch3d/blob/bd52f4a408b29dc6b4357b70c93fd7a9749ca820/pytorch3d/transforms/rotation_conversions.py#L558 .. py:function:: matrix_to_rotation_6d(matrix: torch.Tensor) -> torch.Tensor Converts rotation matrices to 6D rotation representation by Zhou et al. [1] by dropping the last row. Note that 6D representation is not unique. :param matrix: batch of rotation matrices of size [..., 3, 3] :returns: 6D rotation representation, of shape [..., 6] [1] Zhou, Y., Barnes, C., Lu, J., Yang, J., & Li, H. On the Continuity of Rotation Representations in Neural Networks. CVPR 2019. arxiv_ .. _arxiv: https://arxiv.org/pdf/1812.07035