step.motion.arc
===============

.. py:module:: step.motion.arc


Classes
-------

.. autoapisummary::

   step.motion.arc.Arc
   step.motion.arc.DriveArcLeft
   step.motion.arc.DriveArcRight
   step.motion.arc.DriveArc
   step.motion.arc.StrafeArcLeft
   step.motion.arc.StrafeArcRight
   step.motion.arc.StrafeArc


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

.. py:class:: Arc(config: raccoon.motion.ArcMotionConfig)

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


   Step wrapper around the native `ArcMotion` controller.


   .. py:attribute:: config


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

      Convert this step to a simulation-friendly summary.

      The default implementation uses timing history only when it can query
      the tracker synchronously; otherwise it returns conservative defaults.
      Override in subclasses that know their motion delta or exact duration.



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

      Called once before the loop. Override to set up motion/velocity.



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

      Called each cycle with dt in seconds. Return True when motion is complete.



.. py:class:: DriveArcLeft(radius_cm: float, degrees: float, speed: float = 1.0)

   Bases: :py:obj:`Arc`


   Drive along a circular arc curving to the left.

   The robot drives forward while simultaneously turning counter-clockwise,
   tracing a circular arc of the given radius. The motion completes when
   the robot has turned by the specified number of degrees.

   :param radius_cm: Turning radius in centimeters (center of arc to robot center).
   :param degrees: Arc angle in degrees (how much the robot turns).
   :param speed: Fraction of max speed, 0.0 to 1.0 (default 1.0).

   :returns: A DriveArcLeft step configured for a left (CCW) arc.

   Example::

       from raccoon.step.motion import drive_arc_left

       # Quarter-circle left with 30 cm radius
       drive_arc_left(radius_cm=30, degrees=90)

       # Gentle wide arc at half speed
       drive_arc_left(radius_cm=50, degrees=45, speed=0.5)


.. py:class:: DriveArcRight(radius_cm: float, degrees: float, speed: float = 1.0)

   Bases: :py:obj:`Arc`


   Drive along a circular arc curving to the right.

   The robot drives forward while simultaneously turning clockwise,
   tracing a circular arc of the given radius. The motion completes when
   the robot has turned by the specified number of degrees.

   :param radius_cm: Turning radius in centimeters (center of arc to robot center).
   :param degrees: Arc angle in degrees (how much the robot turns).
   :param speed: Fraction of max speed, 0.0 to 1.0 (default 1.0).

   :returns: A DriveArcRight step configured for a right (CW) arc.

   Example::

       from raccoon.step.motion import drive_arc_right

       # Quarter-circle right with 30 cm radius
       drive_arc_right(radius_cm=30, degrees=90)


.. py:class:: DriveArc(radius_cm: float, degrees: float, speed: float = 1.0)

   Bases: :py:obj:`Arc`


   Drive along a circular arc with explicit direction (internal use only).

   Positive degrees = counter-clockwise (left), negative = clockwise (right).


.. py:class:: StrafeArcLeft(radius_cm: float, degrees: float, speed: float = 1.0)

   Bases: :py:obj:`Arc`


   Strafe along a circular arc curving to the left.

   The robot strafes laterally (to the right) while simultaneously turning
   counter-clockwise, tracing a circular arc of the given radius. The motion
   completes when the robot has turned by the specified number of degrees.

   Internally uses a profiled PID on heading and derives the lateral velocity
   from the angular velocity command: ``vy = |omega| * radius``. This produces
   coordinated acceleration along the arc.

   Prerequisites:
       Requires a mecanum or omni-wheel drivetrain capable of lateral motion.

   :param radius_cm: Turning radius in centimeters (center of arc to robot center).
   :param degrees: Arc angle in degrees (how much the robot turns).
   :param speed: Fraction of max speed, 0.0 to 1.0 (default 1.0).

   :returns: A StrafeArcLeft step configured for a left (CCW) strafe arc.

   Example::

       from raccoon.step.motion import strafe_arc_left

       # Quarter-circle strafe arc to the left with 30 cm radius
       strafe_arc_left(radius_cm=30, degrees=90)

       # Gentle wide strafe arc at half speed
       strafe_arc_left(radius_cm=50, degrees=45, speed=0.5)


.. py:class:: StrafeArcRight(radius_cm: float, degrees: float, speed: float = 1.0)

   Bases: :py:obj:`Arc`


   Strafe along a circular arc curving to the right.

   The robot strafes laterally (to the left) while simultaneously turning
   clockwise, tracing a circular arc of the given radius. The motion
   completes when the robot has turned by the specified number of degrees.

   Internally uses a profiled PID on heading and derives the lateral velocity
   from the angular velocity command: ``vy = |omega| * radius``. This produces
   coordinated acceleration along the arc.

   Prerequisites:
       Requires a mecanum or omni-wheel drivetrain capable of lateral motion.

   :param radius_cm: Turning radius in centimeters (center of arc to robot center).
   :param degrees: Arc angle in degrees (how much the robot turns).
   :param speed: Fraction of max speed, 0.0 to 1.0 (default 1.0).

   :returns: A StrafeArcRight step configured for a right (CW) strafe arc.

   Example::

       from raccoon.step.motion import strafe_arc_right

       # Quarter-circle strafe arc to the right with 30 cm radius
       strafe_arc_right(radius_cm=30, degrees=90)


.. py:class:: StrafeArc(radius_cm: float, degrees: float, speed: float = 1.0)

   Bases: :py:obj:`Arc`


   Strafe along a circular arc with explicit direction (internal use only).

   Positive degrees = counter-clockwise (left), negative = clockwise (right).