artist.geometry.rotations
=========================

.. py:module:: artist.geometry.rotations


Functions
---------

.. autoapisummary::

   artist.geometry.rotations.decompose_rotations
   artist.geometry.rotations.rotation_angle_and_axis


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

.. py:function:: decompose_rotations(initial_vector: torch.Tensor, target_vector: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]

   Compute ENU components of the axis-angle rotation vector that rotates initial vectors toward a target vector.

   This function does **not** perform an Euler-angle decomposition. Instead, it computes:
   1) the rotation axis via cross product, and
   2) the rotation magnitude via arccos of the dot product,
   then returns the Cartesian components of the rotation vector
   (`theta * axis`) in east, north, and up coordinates.

   Parameters
   ----------
   initial_vector : torch.Tensor
       Initial vectors in homogeneous coordinates.
       Shape is ``[number_of_heliostats, 4]``.
       Only the first three components (ENU) are used.
   target_vector : torch.Tensor
       Target vector in homogeneous coordinates.
       Shape is ``[4]``.
       Only the first three components (ENU) are used.

   Returns
   -------
   torch.Tensor
       East component of the axis-angle rotation vector.
       Shape is ``[number_of_heliostats]``.
   torch.Tensor
       North component of the axis-angle rotation vector.
       Shape is ``[number_of_heliostats]``.
   torch.Tensor
       Up component of the axis-angle rotation vector.
       Shape is ``[number_of_heliostats]``.


.. py:function:: rotation_angle_and_axis(from_orientation: torch.Tensor, to_orientation: torch.Tensor, device: torch.device | None = None) -> tuple[torch.Tensor, torch.Tensor]

   Compute the rotation axis and angle between two orientations.

   Parameters
   ----------
   from_orientation : torch.Tensor
       The original orientation.
       Shape is ``[4]``.
   to_orientation : torch.Tensor
       The rotated orientation.
       Shape is ``[4]``.
   device : torch.device | None
       The device on which to perform computations or load tensors and models (default is None).
       If None, ``ARTIST`` will automatically select the most appropriate
       device (CUDA or CPU) based on availability and OS.

   Returns
   -------
   torch.Tensor
       The rotation axis.
       Shape is ``[3]``.
   torch.Tensor
       The angle of the rotation as a scalar tensor.