fastdev.xform.utils
===================

.. py:module:: fastdev.xform.utils




Module Contents
---------------

.. py:function:: coord_conversion(src_spec: str, dst_spec: str, check_handness: bool = True, return_tensors: Literal['pt'] = 'pt') -> jaxtyping.Float[torch.Tensor, 3 3]
                 coord_conversion(src_spec: str, dst_spec: str, check_handness: bool = True, return_tensors: Literal['np'] = 'np') -> jaxtyping.Float[numpy.ndarray, 3 3]

   Construct a rotation matrix based on given source and destination coordinate specifications.

   :param src_spec: Source coordinate specification, e.g., "x: right, y: down, z: front" or "opencv".
   :param dst_spec: Destination coordinate specification, e.g., "x: right, y: up, z: back" or "opengl".
   :param check_handness: If True, checks if the rotation matrix preserves right-handedness.
   :param return_tensors: Return type of the rotation matrix, either "np" for NumPy array or "pt" for PyTorch tensor.

   :returns: A 3x3 rotation matrix converting coordinates from the source to the destination specification.

   .. rubric:: Examples

   >>> coord_conversion("opencv", "opengl")
   array([[ 1.,  0.,  0.],
          [ 0., -1.,  0.],
          [ 0.,  0., -1.]], dtype=float32)
   >>> coord_conversion("x: front, y: left, z: up", "x: left, y: up, z: front")
   array([[0., 1., 0.],
          [0., 0., 1.],
          [1., 0., 0.]], dtype=float32)
   >>> coord_conversion("x: right, y: down, z: front", "x: left, y: up, z: front")
   array([[-1.,  0.,  0.],
          [ 0., -1.,  0.],
          [ 0.,  0.,  1.]], dtype=float32)
   >>> coord_conversion("x: left, y: up, z: front", "x: front, y: left, z: up", return_tensors="pt")
   tensor([[0., 0., 1.],
           [1., 0., 0.],
           [0., 1., 0.]])


.. py:function:: compose_intr_mat(fu: float, fv: float, cu: float, cv: float, skew: float = 0.0) -> numpy.ndarray

   :param fu: horizontal focal length (width)
   :param fv: vertical focal length (height)
   :param cu: horizontal principal point (width)
   :param cv: vertical principal point (height)
   :param skew: skew coefficient, default to 0


.. py:function:: look_at_rotation(camera_position: jaxtyping.Float[torch.Tensor, *batch 3], at: jaxtyping.Float[torch.Tensor, *batch 3], up: jaxtyping.Float[torch.Tensor, *batch 3]) -> jaxtyping.Float[torch.Tensor, *batch 3 3]

   This function takes a vector `camera_position` which specifies the location of the camera in world coordinates and
   two vectors `at` and `up` which indicate the position of the object and the up directions of the world
   coordinate system respectively.

   The output is a rotation matrix representing the rotation from camera coordinates to world coordinates.

   We use the OpenGL coordinate in this function, i.e. x -> right, y -> up, z -> backward.
   Hence, z_axis: pos - at, x_axis: cross(up, z_axis), y_axis: cross(z_axis, x_axis)

   Note that our implementation differs from pytorch3d.
       1. our matrix is in the OpenGL coordinate
       2. our matrix is column-major
       3. our matrix is the camera-to-world transformation

   :param camera_position: position of the camera in world coordinates
   :param at: position of the object in world coordinates
   :param up: vector specifying the up direction in the world coordinate frame.

   :returns: rotation matrices of shape [..., 3, 3]
   :rtype: R


.. py:function:: camera_position_from_spherical_angles(distance: float, elevation: float, azimuth: float, degrees: bool = True, device: Device = 'cpu') -> torch.Tensor

   Calculate the location of the camera based on the distance away from
   the target point, the elevation and azimuth angles.

   :param distance: distance of the camera from the object.
   :param elevation: angles.
                     The inputs distance, elevation and azimuth can be one of the following
                         - Python scalar
                         - Torch scalar
                         - Torch tensor of shape (N) or (1)
   :param azimuth: angles.
                   The inputs distance, elevation and azimuth can be one of the following
                       - Python scalar
                       - Torch scalar
                       - Torch tensor of shape (N) or (1)
   :param degrees: bool, whether the angles are specified in degrees or radians.
   :param device: str or torch.device, device for new tensors to be placed on.

   The vectors are broadcast against each other so they all have shape (N, 1).

   :returns: (N, 3) xyz location of the camera.
   :rtype: camera_position