libstp.step.motion.move_until.core
==================================

.. py:module:: libstp.step.motion.move_until.core

.. autoapi-nested-parse::

   Core MoveUntil step and configuration.

   Moves (drive, turn, strafe) until an IR sensor condition is met.



Classes
-------

.. autoapisummary::

   libstp.step.motion.move_until.core.SurfaceColor
   libstp.step.motion.move_until.core.MoveUntilConfig
   libstp.step.motion.move_until.core.MoveUntil


Functions
---------

.. autoapisummary::

   libstp.step.motion.move_until.core.move_until


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

.. py:class:: SurfaceColor(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Target surface color for sensor-based motion.


   .. py:attribute:: BLACK
      :value: 'black'



   .. py:attribute:: WHITE
      :value: 'white'



.. py:class:: MoveUntilConfig

   Configuration for MoveUntil step.


   .. py:attribute:: sensor
      :type:  Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]]


   .. py:attribute:: target
      :type:  SurfaceColor


   .. py:attribute:: forward_speed
      :type:  float
      :value: 0.0



   .. py:attribute:: angular_speed
      :type:  float
      :value: 0.0



   .. py:attribute:: strafe_speed
      :type:  float
      :value: 0.0



   .. py:attribute:: confidence_threshold
      :type:  float
      :value: 0.7



   .. py:attribute:: scale_speed_on_approach
      :type:  bool
      :value: True



.. py:class:: MoveUntil(config: MoveUntilConfig)

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


   Move until a sensor detects a specified color (black or white).

   Supports any combination of forward, angular, and strafe velocities.
   Can accept a single sensor or a list of sensors - triggers when ANY sensor detects.


   .. py:attribute:: config


   .. py:attribute:: triggered_sensor
      :type:  libstp.sensor_ir.IRSensor | None
      :value: None



   .. 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:: move_until(sensor: Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]], target: SurfaceColor, forward_speed: float = 0.0, angular_speed: float = 0.0, strafe_speed: float = 0.0, confidence_threshold: float = 0.7, scale_speed_on_approach: bool = True) -> MoveUntil

   Move with any combination of velocities until any sensor detects the target color.

   This is the most general "move until" factory. It accepts arbitrary
   forward, strafe, and angular velocity components simultaneously, allowing
   complex motions such as arcing turns or diagonal drives while waiting for
   a sensor trigger. Each control cycle the given IR sensor(s) are polled,
   and the step completes as soon as any sensor's probability for the target
   color meets or exceeds ``confidence_threshold``.

   For simpler cases, prefer the dedicated helpers (``drive_forward_until_black``,
   ``turn_left_until_white``, ``strafe_right_until_black``, etc.).

   :param sensor: A single :class:`~libstp.sensor_ir.IRSensor` or a list of
                  sensors. The step triggers when **any** sensor in the list detects
                  the target color.
   :param target: The surface color to detect --
                  :attr:`SurfaceColor.BLACK` or :attr:`SurfaceColor.WHITE`.
   :param forward_speed: Forward/backward speed in m/s. Positive = forward,
                         negative = backward. Defaults to 0.0.
   :param angular_speed: Rotational speed in rad/s. Positive = counter-clockwise,
                         negative = clockwise. Defaults to 0.0.
   :param strafe_speed: Lateral speed in m/s. Positive = left, negative = right.
                        Requires a mecanum or holonomic drivetrain. Defaults to 0.0.
   :param confidence_threshold: Minimum probability (0.0 -- 1.0) that the sensor
                                must report for the target color before the step considers the
                                condition met. Defaults to 0.7.
   :param scale_speed_on_approach: If ``True``, reduce velocity as the sensor
                                   reading approaches the threshold to allow more precise stopping.
                                   Defaults to ``True``.

   :returns: A configured motion step that can be executed by the step
             runner.
   :rtype: MoveUntil

   Example::

       from libstp.sensor_ir import IRSensor
       from libstp.step.motion.move_until.core import SurfaceColor

       front_ir = IRSensor(0)

       # Arc forward-left while looking for black
       step = move_until(
           front_ir,
           target=SurfaceColor.BLACK,
           forward_speed=0.3,
           angular_speed=0.2,
       )

       # Strafe right with high confidence threshold
       step = move_until(
           front_ir,
           target=SurfaceColor.WHITE,
           strafe_speed=-0.2,
           confidence_threshold=0.9,
       )