step.calibration.calibrate_distance

Distance calibration step using the new UI library.

Supports two calibration modes: - Runtime calibration: Apply measured ticks_to_rad for this run (best accuracy now) - Persistent learning: Update YAML baseline using EMA (converges over multiple runs)

Attributes

DEFAULT_EMA_ALPHA

Exceptions

CalibrationRequiredError

Raised when an operation requires calibration but none has been performed.

Classes

DistanceCalibrationResult

Result of distance calibration.

PerWheelCalibration

Result of per-wheel distance calibration.

CalibrateDistance

Calibrate per-wheel distance estimation via encoder measurement.

Functions

is_distance_calibrated(→ bool)

Check if distance calibration has been performed.

check_distance_calibration(→ None)

Log a warning when distance calibration has not been performed yet.

reset_distance_calibration(→ None)

Reset the calibration flag (for testing).

Module Contents

step.calibration.calibrate_distance.DEFAULT_EMA_ALPHA = 0.7
exception step.calibration.calibrate_distance.CalibrationRequiredError

Bases: Exception

Raised when an operation requires calibration but none has been performed.

step.calibration.calibrate_distance.is_distance_calibrated() → bool

Check if distance calibration has been performed.

step.calibration.calibrate_distance.check_distance_calibration() → None

Log a warning when distance calibration has not been performed yet.

step.calibration.calibrate_distance.reset_distance_calibration() → None

Reset the calibration flag (for testing).

class step.calibration.calibrate_distance.DistanceCalibrationResult

Result of distance calibration.

requested_distance_cm: float
measured_distance_cm: float
scale_factor: float
class step.calibration.calibrate_distance.PerWheelCalibration

Result of per-wheel distance calibration.

motor_port: int
old_ticks_to_rad: float
new_ticks_to_rad: float
delta_ticks: int
ema_baseline: float = 0.0
motor_name: str | None = None
class step.calibration.calibrate_distance.CalibrateDistance(distance_cm: float = 30.0, speed: float = 1.0, calibrate_light_sensors: bool = False, persist_to_yaml: bool = True, ema_alpha: float = 0.7, calibration_sets: List[str] | None = None, exclude_ir_sensors: List[raccoon.sensor_ir.IRSensor] | None = None)

Bases: raccoon.ui.step.UIStep

Calibrate per-wheel distance estimation via encoder measurement.

Drives the robot a known distance, then prompts the user to enter the actual measured distance. The step computes a corrected ticks_to_rad value for each drive motor so that odometry matches real-world distances.

The calibration operates in two modes simultaneously:

  • Runtime: Applies the measured ticks_to_rad directly for best accuracy during this run.

  • Persistent: Updates the YAML baseline using an exponential moving average (EMA) so the stored value converges toward the true value over multiple calibration runs.

Parameters:

  • distance_cm – Distance (in cm) the robot drives during calibration. Longer distances yield better accuracy.

  • speed – Drive speed during the calibration runs, as a fraction of max speed in [0.0, 1.0]. Lower speeds reduce wheel slip and usually produce more accurate calibration.

  • calibrate_light_sensors – If True, run IR sensor calibration after the distance calibration is confirmed.

  • persist_to_yaml – If True, write the EMA-filtered baseline to raccoon.project.yml so it persists across program runs.

  • ema_alpha – EMA smoothing coefficient between 0.0 and 1.0. Higher values produce slower convergence but a more stable baseline.

  • calibration_sets – List of named IR calibration surface sets (e.g. ["default", "transparent"]). Only used when calibrate_light_sensors is True.

  • exclude_ir_sensors – List of IRSensor instances to skip during IR calibration.

Example:

from raccoon.step.calibration import calibrate_distance

# Distance-only calibration with defaults
calibrate_distance()

# Distance + IR sensor calibration
calibrate_distance(
    distance_cm=50.0,
    calibrate_light_sensors=True,
    calibration_sets=["default", "transparent"],
)
calibration_distance_cm = 30.0
speed = 1.0
calibrate_light_sensors = False
persist_to_yaml = True
ema_alpha = 0.7
calibration_sets = ['default']
exclude_ir_sensors: List[raccoon.sensor_ir.IRSensor] = []
result: DistanceCalibrationResult | None = None
per_wheel_results: List[PerWheelCalibration] = []