libstp.step.motion.move_until.turn ================================== .. py:module:: libstp.step.motion.move_until.turn .. autoapi-nested-parse:: Factory functions for turning in place until an IR sensor detects a surface color. Functions --------- .. autoapisummary:: libstp.step.motion.move_until.turn.turn_until_black libstp.step.motion.move_until.turn.turn_until_white libstp.step.motion.move_until.turn.turn_left_until_black libstp.step.motion.move_until.turn.turn_left_until_white libstp.step.motion.move_until.turn.turn_right_until_black libstp.step.motion.move_until.turn.turn_right_until_white Module Contents --------------- .. py:function:: turn_until_black(sensor: Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]], angular_speed: float, confidence_threshold: float = 0.7) -> libstp.step.motion.move_until.core.MoveUntil Turn in place until any sensor detects a black surface. Commands a constant angular velocity and polls the given IR sensor(s) each control cycle. The step completes as soon as any sensor's ``probabilityOfBlack()`` meets or exceeds ``confidence_threshold``. This is the low-level variant that accepts a signed angular speed; prefer the directional helpers ``turn_left_until_black`` / ``turn_right_until_black`` for most use cases. :param sensor: A single :class:`~libstp.sensor_ir.IRSensor` or a list of sensors. The step triggers when **any** sensor in the list detects black. :param angular_speed: Rotational speed in rad/s. Positive values rotate counter-clockwise (left), negative values rotate clockwise (right). :param confidence_threshold: Minimum probability (0.0 -- 1.0) that the sensor must report for black before the step considers the condition met. Defaults to 0.7. :returns: A configured motion step that rotates in place and stops when black is detected. :rtype: MoveUntil Example:: from libstp.sensor_ir import IRSensor side_ir = IRSensor(1) # Rotate CCW at 0.5 rad/s until the sensor finds black step = turn_until_black(side_ir, angular_speed=0.5) .. py:function:: turn_until_white(sensor: Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]], angular_speed: float, confidence_threshold: float = 0.7) -> libstp.step.motion.move_until.core.MoveUntil Turn in place until any sensor detects a white surface. Commands a constant angular velocity and polls the given IR sensor(s) each control cycle. The step completes as soon as any sensor's ``probabilityOfWhite()`` meets or exceeds ``confidence_threshold``. This is the low-level variant that accepts a signed angular speed; prefer the directional helpers ``turn_left_until_white`` / ``turn_right_until_white`` for most use cases. :param sensor: A single :class:`~libstp.sensor_ir.IRSensor` or a list of sensors. The step triggers when **any** sensor in the list detects white. :param angular_speed: Rotational speed in rad/s. Positive values rotate counter-clockwise (left), negative values rotate clockwise (right). :param confidence_threshold: Minimum probability (0.0 -- 1.0) that the sensor must report for white before the step considers the condition met. Defaults to 0.7. :returns: A configured motion step that rotates in place and stops when white is detected. :rtype: MoveUntil Example:: from libstp.sensor_ir import IRSensor side_ir = IRSensor(1) # Rotate CW at 0.5 rad/s until the sensor finds white step = turn_until_white(side_ir, angular_speed=-0.5) .. py:function:: turn_left_until_black(sensor: Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]], speed: float = 1.0, confidence_threshold: float = 0.7) -> libstp.step.motion.move_until.core.MoveUntil Turn left (counter-clockwise) until any sensor detects a black surface. Commands a constant counter-clockwise angular velocity and polls the given IR sensor(s) each control cycle. The step completes as soon as any sensor's ``probabilityOfBlack()`` meets or exceeds ``confidence_threshold``. The speed is forced positive (CCW) regardless of the sign passed in. A common use case is sweeping a side-mounted IR sensor across the field to locate a black line, then stopping precisely when found. :param sensor: A single :class:`~libstp.sensor_ir.IRSensor` or a list of sensors. The step triggers when **any** sensor in the list detects black. :param speed: Angular speed in rad/s. The absolute value is used, so negative inputs are treated as positive. Defaults to 1.0. :param confidence_threshold: Minimum probability (0.0 -- 1.0) that the sensor must report for black before the step considers the condition met. Defaults to 0.7. :returns: A configured motion step that turns left and stops when black is detected. :rtype: MoveUntil Example:: from libstp.sensor_ir import IRSensor right_ir = IRSensor(3) # Sweep left at 0.8 rad/s until the right sensor crosses a black line step = turn_left_until_black(right_ir, speed=0.8) .. py:function:: turn_left_until_white(sensor: Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]], speed: float = 1.0, confidence_threshold: float = 0.7) -> libstp.step.motion.move_until.core.MoveUntil Turn left (counter-clockwise) until any sensor detects a white surface. Commands a constant counter-clockwise angular velocity and polls the given IR sensor(s) each control cycle. The step completes as soon as any sensor's ``probabilityOfWhite()`` meets or exceeds ``confidence_threshold``. The speed is forced positive (CCW) regardless of the sign passed in. :param sensor: A single :class:`~libstp.sensor_ir.IRSensor` or a list of sensors. The step triggers when **any** sensor in the list detects white. :param speed: Angular speed in rad/s. The absolute value is used, so negative inputs are treated as positive. Defaults to 1.0. :param confidence_threshold: Minimum probability (0.0 -- 1.0) that the sensor must report for white before the step considers the condition met. Defaults to 0.7. :returns: A configured motion step that turns left and stops when white is detected. :rtype: MoveUntil Example:: from libstp.sensor_ir import IRSensor right_ir = IRSensor(3) # Sweep left at 0.6 rad/s until white surface is found step = turn_left_until_white(right_ir, speed=0.6) .. py:function:: turn_right_until_black(sensor: Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]], speed: float = 1.0, confidence_threshold: float = 0.7) -> libstp.step.motion.move_until.core.MoveUntil Turn right (clockwise) until any sensor detects a black surface. Commands a constant clockwise angular velocity and polls the given IR sensor(s) each control cycle. The step completes as soon as any sensor's ``probabilityOfBlack()`` meets or exceeds ``confidence_threshold``. The speed is negated internally to produce clockwise rotation, so you should pass a positive value. A common use case is sweeping a side-mounted IR sensor across the field to locate a black line, then stopping precisely when found. :param sensor: A single :class:`~libstp.sensor_ir.IRSensor` or a list of sensors. The step triggers when **any** sensor in the list detects black. :param speed: Angular speed in rad/s. Pass a positive value; the sign is negated internally to rotate clockwise. Defaults to 1.0. :param confidence_threshold: Minimum probability (0.0 -- 1.0) that the sensor must report for black before the step considers the condition met. Defaults to 0.7. :returns: A configured motion step that turns right and stops when black is detected. :rtype: MoveUntil Example:: from libstp.sensor_ir import IRSensor left_ir = IRSensor(1) # Sweep right at 0.8 rad/s until the left sensor crosses a black line step = turn_right_until_black(left_ir, speed=0.8) .. py:function:: turn_right_until_white(sensor: Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]], speed: float = 1.0, confidence_threshold: float = 0.7) -> libstp.step.motion.move_until.core.MoveUntil Turn right (clockwise) until any sensor detects a white surface. Commands a constant clockwise angular velocity and polls the given IR sensor(s) each control cycle. The step completes as soon as any sensor's ``probabilityOfWhite()`` meets or exceeds ``confidence_threshold``. The speed is negated internally to produce clockwise rotation, so you should pass a positive value. :param sensor: A single :class:`~libstp.sensor_ir.IRSensor` or a list of sensors. The step triggers when **any** sensor in the list detects white. :param speed: Angular speed in rad/s. Pass a positive value; the sign is negated internally to rotate clockwise. Defaults to 1.0. :param confidence_threshold: Minimum probability (0.0 -- 1.0) that the sensor must report for white before the step considers the condition met. Defaults to 0.7. :returns: A configured motion step that turns right and stops when white is detected. :rtype: MoveUntil Example:: from libstp.sensor_ir import IRSensor left_ir = IRSensor(1) # Sweep right slowly until the left sensor finds white step = turn_right_until_white(left_ir, speed=0.5)