robot.heading_reference
=======================

.. py:module:: robot.heading_reference


Classes
-------

.. autoapisummary::

   robot.heading_reference.HeadingReferenceService


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

.. py:class:: HeadingReferenceService(robot: robot.api.GenericRobot)

   Bases: :py:obj:`robot.service.RobotService`


   Stores an absolute IMU heading reference and computes turns relative to it.

   Use ``robot.get_service(HeadingReferenceService)`` to access.


   .. py:method:: mark(origin_offset_deg: float = 0.0, positive_direction: str = 'left') -> None

      Capture the current absolute IMU heading as the reference.

      :param origin_offset_deg: Offset in degrees added to the captured heading.
                                Use this to define a consistent origin regardless of the robot's
                                physical starting rotation.  For example, if the robot is placed
                                at 30° to the board edge but you want 0° to mean "along the
                                board edge", pass ``origin_offset_deg=-30``.
      :param positive_direction: Which physical direction corresponds to positive
                                 angles.  ``"left"`` (default) means CCW is positive, matching the
                                 standard mathematical convention.  ``"right"`` flips the sign so
                                 CW is positive.



   .. py:property:: reference_deg
      :type: float | None


      The stored reference in degrees, or None if not set.


   .. py:method:: compute_turn(target_deg: float, force_direction: str | None = None) -> float

      Compute the signed relative turn angle to reach *target_deg* from reference.

      :param target_deg: Desired heading in degrees relative to the reference.
      :param force_direction: ``"left"`` to force CCW, ``"right"`` to force CW,
                              or ``None`` (default) for shortest path.

      :returns: Signed angle in degrees (positive = CCW / left, negative = CW / right).
                Normalized to [-180, 180] for shortest path, or adjusted to the
                forced direction.

      :raises RuntimeError: If no reference has been marked yet.