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

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


Classes
-------

.. autoapisummary::

   libstp.step.motion.arc.Arc


Functions
---------

.. autoapisummary::

   libstp.step.motion.arc.drive_arc_left
   libstp.step.motion.arc.drive_arc_right
   libstp.step.motion.arc.drive_arc


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

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

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


   Step wrapper around the native `ArcMotion` controller.


   .. py:attribute:: config


   .. py:method:: to_simulation_step() -> libstp.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: libstp.robot.api.GenericRobot) -> None

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



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

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



.. py:function:: drive_arc_left(radius_cm: float, degrees: float, speed: float = 1.0) -> 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: An Arc step configured for a left (CCW) arc.

   Example::

       from libstp.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:function:: drive_arc_right(radius_cm: float, degrees: float, speed: float = 1.0) -> 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: An Arc step configured for a right (CW) arc.

   Example::

       from libstp.step.motion import drive_arc_right

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


.. py:function:: drive_arc(radius_cm: float, degrees: float, speed: float = 1.0) -> Arc

   Drive along a circular arc with explicit direction.

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

   :param radius_cm: Turning radius in centimeters (always positive).
   :param degrees: Arc angle in degrees. Positive = left/CCW, negative = right/CW.
   :param speed: Fraction of max speed, 0.0 to 1.0 (default 1.0).

   :returns: An Arc step.

   Example::

       from libstp.step.motion import drive_arc

       # Left arc
       drive_arc(radius_cm=30, degrees=90)

       # Right arc
       drive_arc(radius_cm=30, degrees=-90)