step.motion.drive_angle
=======================

.. py:module:: step.motion.drive_angle


Classes
-------

.. autoapisummary::

   step.motion.drive_angle.DriveAngle
   step.motion.drive_angle.DriveAngleLeft
   step.motion.drive_angle.DriveAngleRight


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

.. py:class:: DriveAngle(angle_deg: float, cm: float = None, speed: float = 1.0, until: step.condition.StopCondition = None)

   Bases: :py:obj:`step.motion.motion_step.MotionStep`


   Drive at an arbitrary angle with distance or condition-based termination.

   Decomposes the desired heading into forward and lateral velocity
   components, then runs a profiled PID controller in a rotated
   coordinate frame with heading maintenance and cross-track correction.

   Requires a mecanum or omni-wheel drivetrain.

   Angle convention (robot-centric): ``0`` = forward, ``90`` = right,
   ``-90`` = left, ``180`` = backward.

   :param angle_deg: Travel angle in degrees.
   :param cm: Distance to travel in centimeters. Omit to use condition-only mode.
   :param speed: Fraction of max speed, 0.0 to 1.0.
   :param until: Stop condition for early termination.

   Example::

       from raccoon.step.motion import drive_angle

       # Drive diagonally forward-right at 45 degrees
       drive_angle(45, cm=30)

       # Drive pure right (same as strafe_right)
       drive_angle(90, cm=20)


   .. py:method:: to_simulation_step() -> step.SimulationStep


   .. py:method:: on_start(robot: raccoon.robot.api.GenericRobot) -> None


   .. py:method:: on_update(robot: raccoon.robot.api.GenericRobot, dt: float) -> bool


.. py:class:: DriveAngleLeft(angle_deg: float, cm: float = None, speed: float = 1.0, until: step.condition.StopCondition = None)

   Bases: :py:obj:`DriveAngle`


   Drive at an angle to the left with distance or condition-based termination.

   Convenience wrapper around ``DriveAngle`` that negates the angle so
   that the ``angle_deg`` parameter is always positive (pointing left).

   The angle is measured as degrees to the left of forward:
   ``0`` = forward, ``45`` = forward-left diagonal, ``90`` = pure left.

   :param angle_deg: Degrees to the left of forward (0 = forward, 90 = pure left).
   :param cm: Distance to travel in centimeters. Omit to use condition-only
              mode.
   :param speed: Fraction of max speed, 0.0 to 1.0.
   :param until: Stop condition for early termination.

   Example::

       from raccoon.step.motion import drive_angle_left

       # Drive diagonally forward-left at 45 degrees
       drive_angle_left(45, cm=30)

       # Drive pure left until sensor
       drive_angle_left(90, speed=0.6).until(on_black(s))


.. py:class:: DriveAngleRight(angle_deg: float, cm: float = None, speed: float = 1.0, until: step.condition.StopCondition = None)

   Bases: :py:obj:`DriveAngle`


   Drive at an angle to the right with distance or condition-based termination.

   Convenience wrapper around ``DriveAngle`` that passes the angle
   directly (positive = right in the robot frame).

   The angle is measured as degrees to the right of forward:
   ``0`` = forward, ``45`` = forward-right diagonal, ``90`` = pure right.

   :param angle_deg: Degrees to the right of forward (0 = forward, 90 = pure right).
   :param cm: Distance to travel in centimeters. Omit to use condition-only
              mode.
   :param speed: Fraction of max speed, 0.0 to 1.0.
   :param until: Stop condition for early termination.

   Example::

       from raccoon.step.motion import drive_angle_right

       # Drive diagonally forward-right at 45 degrees
       drive_angle_right(45, cm=30)

       # Drive pure right until sensor
       drive_angle_right(90, speed=0.6).until(on_black(s))