libstp.step.motion.move_until.strafe ==================================== .. py:module:: libstp.step.motion.move_until.strafe .. autoapi-nested-parse:: Factory functions for strafing laterally until an IR sensor detects a surface color. Prerequisites: Strafing requires a mecanum or holonomic drivetrain capable of lateral movement. These steps will have no lateral effect on a differential-drive robot. Functions --------- .. autoapisummary:: libstp.step.motion.move_until.strafe.strafe_until_black libstp.step.motion.move_until.strafe.strafe_until_white libstp.step.motion.move_until.strafe.strafe_left_until_black libstp.step.motion.move_until.strafe.strafe_left_until_white libstp.step.motion.move_until.strafe.strafe_right_until_black libstp.step.motion.move_until.strafe.strafe_right_until_white Module Contents --------------- .. py:function:: strafe_until_black(sensor: Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]], strafe_speed: float, confidence_threshold: float = 0.7) -> libstp.step.motion.move_until.core.MoveUntil Strafe laterally until any sensor detects a black surface. Commands a constant lateral 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 strafe speed; prefer the directional helpers ``strafe_left_until_black`` / ``strafe_right_until_black`` for most use cases. Prerequisites: Requires a mecanum or holonomic drivetrain capable of lateral movement. :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 strafe_speed: Lateral speed in m/s. Positive values strafe left, negative values strafe 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 strafes and stops when black is detected. :rtype: MoveUntil Example:: from libstp.sensor_ir import IRSensor side_ir = IRSensor(1) # Strafe left at 0.2 m/s until black is found step = strafe_until_black(side_ir, strafe_speed=0.2) .. py:function:: strafe_until_white(sensor: Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]], strafe_speed: float, confidence_threshold: float = 0.7) -> libstp.step.motion.move_until.core.MoveUntil Strafe laterally until any sensor detects a white surface. Commands a constant lateral 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 strafe speed; prefer the directional helpers ``strafe_left_until_white`` / ``strafe_right_until_white`` for most use cases. Prerequisites: Requires a mecanum or holonomic drivetrain capable of lateral movement. :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 strafe_speed: Lateral speed in m/s. Positive values strafe left, negative values strafe 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 strafes and stops when white is detected. :rtype: MoveUntil Example:: from libstp.sensor_ir import IRSensor side_ir = IRSensor(1) # Strafe right at 0.2 m/s until white is found step = strafe_until_white(side_ir, strafe_speed=-0.2) .. py:function:: strafe_left_until_black(sensor: Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]], speed: float = 0.3, confidence_threshold: float = 0.7) -> libstp.step.motion.move_until.core.MoveUntil Strafe left until any sensor detects a black surface. Commands a constant leftward lateral 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 leftward motion, so you should pass a positive value. Prerequisites: Requires a mecanum or holonomic drivetrain capable of lateral movement. :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: Lateral speed in m/s. Pass a positive value; the sign is negated internally to strafe left. Defaults to 0.3. :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 strafes left and stops when black is detected. :rtype: MoveUntil Example:: from libstp.sensor_ir import IRSensor left_ir = IRSensor(1) # Strafe left at 0.2 m/s until the left sensor finds a black line step = strafe_left_until_black(left_ir, speed=0.2) .. py:function:: strafe_left_until_white(sensor: Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]], speed: float = 0.3, confidence_threshold: float = 0.7) -> libstp.step.motion.move_until.core.MoveUntil Strafe left until any sensor detects a white surface. Commands a constant leftward lateral 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 leftward motion, so you should pass a positive value. Prerequisites: Requires a mecanum or holonomic drivetrain capable of lateral movement. :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: Lateral speed in m/s. Pass a positive value; the sign is negated internally to strafe left. Defaults to 0.3. :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 strafes left and stops when white is detected. :rtype: MoveUntil Example:: from libstp.sensor_ir import IRSensor left_ir = IRSensor(1) # Strafe left at default speed until the left sensor finds white step = strafe_left_until_white(left_ir) .. py:function:: strafe_right_until_black(sensor: Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]], speed: float = 0.3, confidence_threshold: float = 0.7) -> libstp.step.motion.move_until.core.MoveUntil Strafe right until any sensor detects a black surface. Commands a constant rightward lateral 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 (rightward) regardless of the sign passed in. Prerequisites: Requires a mecanum or holonomic drivetrain capable of lateral movement. :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: Lateral speed in m/s. The absolute value is used, so negative inputs are treated as positive. Defaults to 0.3. :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 strafes right and stops when black is detected. :rtype: MoveUntil Example:: from libstp.sensor_ir import IRSensor right_ir = IRSensor(3) # Strafe right at 0.25 m/s until the right sensor hits a black line step = strafe_right_until_black(right_ir, speed=0.25) .. py:function:: strafe_right_until_white(sensor: Union[libstp.sensor_ir.IRSensor, list[libstp.sensor_ir.IRSensor]], speed: float = 0.3, confidence_threshold: float = 0.7) -> libstp.step.motion.move_until.core.MoveUntil Strafe right until any sensor detects a white surface. Commands a constant rightward lateral 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 (rightward) regardless of the sign passed in. Prerequisites: Requires a mecanum or holonomic drivetrain capable of lateral movement. :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: Lateral speed in m/s. The absolute value is used, so negative inputs are treated as positive. Defaults to 0.3. :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 strafes right and stops when white is detected. :rtype: MoveUntil Example:: from libstp.sensor_ir import IRSensor right_ir = IRSensor(3) # Strafe right at default speed until the right sensor finds white step = strafe_right_until_white(right_ir) # Use multiple sensors with high confidence bottom_ir = IRSensor(4) step = strafe_right_until_white( [right_ir, bottom_ir], speed=0.2, confidence_threshold=0.85 )