step.motion.arc_segment
=======================

.. py:module:: step.motion.arc_segment

.. autoapi-nested-parse::

   Convenience wrapper that parameterises a drive arc by heading change + arc distance.



Functions
---------

.. autoapisummary::

   step.motion.arc_segment.drive_arc_segment


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

.. py:function:: drive_arc_segment(heading_degrees: float = _UNSET, distance_cm: float = _UNSET, speed: float = 1.0) -> raccoon.step.step_builder.StepBuilder

   Drive along a circular arc specified by heading change and travel distance.

   Instead of choosing a radius and arc angle separately, specify the desired
   heading change and how far the robot should travel along the arc.  The
   radius is computed automatically:
   ``radius = distance_cm / radians(|heading_degrees|)``.

   Positive heading_degrees = left (CCW), negative = right (CW).

   :param heading_degrees: Desired heading change in degrees.
                           Positive = left/CCW, negative = right/CW.
   :param distance_cm: Distance the robot travels along the arc path in
                       centimeters (always positive).
   :param speed: Fraction of max speed, 0.0 to 1.0 (default 1.0).

   :raises ValueError: If heading_degrees is zero (arc would have infinite radius)
       or distance_cm is not positive.

   :returns: A DriveArcLeftBuilder or DriveArcRightBuilder configured with the
             computed radius and heading.

   Example::

       from raccoon.step.motion import drive_arc_segment

       # Gently curve left by 10 degrees over 25 cm of travel
       drive_arc_segment(heading_degrees=10, distance_cm=25)

       # Curve right by 30 degrees over 40 cm at half speed
       drive_arc_segment(heading_degrees=-30, distance_cm=40, speed=0.5)