step.motion.line_follow_builder
===============================

.. py:module:: step.motion.line_follow_builder


Classes
-------

.. autoapisummary::

   step.motion.line_follow_builder.FollowCorrection
   step.motion.line_follow_builder.ConfigurableLineFollowBuilder


Functions
---------

.. autoapisummary::

   step.motion.line_follow_builder.line_follow


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

.. py:class:: FollowCorrection

   Bases: :py:obj:`enum.StrEnum`


   Enum where members are also (and must be) strings


   .. py:attribute:: ANGULAR
      :value: 'angular'



   .. py:attribute:: LATERAL
      :value: 'lateral'



   .. py:attribute:: FORWARD
      :value: 'forward'



.. py:class:: ConfigurableLineFollowBuilder

   Bases: :py:obj:`raccoon.step.step_builder.StepBuilder`


   Base class for generated step builders.

   Subclasses must implement ``_build()`` to construct the real Step
   from the collected parameters.

   Since StepBuilder extends Step, it satisfies StepProtocol and can be
   used anywhere a Step is expected (seq, parallel, mission step lists).


   .. py:method:: dual(left_sensor: raccoon.sensor_ir.IRSensor, right_sensor: raccoon.sensor_ir.IRSensor) -> ConfigurableLineFollowBuilder


   .. py:method:: single(sensor: raccoon.sensor_ir.IRSensor, side: step.motion.line_follow.LineSide = LineSide.LEFT) -> ConfigurableLineFollowBuilder


   .. py:method:: move(forward: float = 0.0, strafe: float = 0.0) -> ConfigurableLineFollowBuilder


   .. py:method:: forward_speed(value: float) -> ConfigurableLineFollowBuilder


   .. py:method:: strafe_speed(value: float) -> ConfigurableLineFollowBuilder


   .. py:method:: correct_angular() -> ConfigurableLineFollowBuilder


   .. py:method:: correct_lateral(hold_heading: bool = True) -> ConfigurableLineFollowBuilder


   .. py:method:: correct_forward(hold_heading: bool = True) -> ConfigurableLineFollowBuilder


   .. py:method:: correction_sign(value: float) -> ConfigurableLineFollowBuilder


   .. py:method:: hold_heading(degrees: float | None) -> ConfigurableLineFollowBuilder

      Hold an absolute heading while correcting laterally/forward.

      ``degrees`` is measured from the :func:`mark_heading_reference` origin
      (CCW-positive, same convention as ``turn_to_heading_left`` and
      ``drive_forward(heading=…)``). Pass ``None`` (the default) to hold
      whatever heading the robot has when the step starts. Only takes effect
      together with :meth:`correct_lateral` / :meth:`correct_forward` (the
      heading-hold correction modes); it is a no-op under angular correction.
      Requires :func:`mark_heading_reference` earlier in the mission.



   .. py:method:: distance_cm(value: float | None) -> ConfigurableLineFollowBuilder


   .. py:method:: pid(kp: float, ki: float = 0.0, kd: float = 0.1, integral_max: float = 1.0, integral_min: float | None = None) -> ConfigurableLineFollowBuilder

      Set the correction PID gains and its integral anti-windup band.

      ``integral_max``/``integral_min`` clamp the PID's accumulated integral
      (in the normalised correction space the PID emits, roughly [-1, 1]).
      Leave ``integral_min`` as ``None`` to mirror ``-integral_max`` (the
      classic symmetric clamp); set both explicitly for an asymmetric band
      (e.g. ``integral_min=0.0`` for a one-sided integrator). Only matters
      when ``ki`` is non-zero.



   .. py:method:: until(value: raccoon.step.condition.StopCondition | None) -> ConfigurableLineFollowBuilder


.. py:function:: line_follow() -> ConfigurableLineFollowBuilder