step.calibration.calibrate_distance_dsl
=======================================

.. py:module:: step.calibration.calibrate_distance_dsl

.. autoapi-nested-parse::

   Auto-generated step builders and DSL functions — DO NOT EDIT.

   Source: calibrate_distance.py



Classes
-------

.. autoapisummary::

   step.calibration.calibrate_distance_dsl.CalibrateDistanceBuilder


Functions
---------

.. autoapisummary::

   step.calibration.calibrate_distance_dsl.calibrate_distance


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

.. py:class:: CalibrateDistanceBuilder

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


   Builder for CalibrateDistance. Auto-generated — do not edit.


   .. py:method:: distance_cm(value: float)


   .. py:method:: speed(value: float)


   .. py:method:: calibrate_light_sensors(value: bool)


   .. py:method:: persist_to_yaml(value: bool)


   .. py:method:: ema_alpha(value: float)


   .. py:method:: calibration_sets(value: Optional[List[str]])


   .. py:method:: exclude_ir_sensors(value: Optional[List[IRSensor]])


.. py:function:: calibrate_distance(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: Optional[List[str]] = None, exclude_ir_sensors: Optional[List[IRSensor]] = None)

   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.

   :param distance_cm: Distance (in cm) the robot drives during calibration. Longer distances yield better accuracy.
   :param 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.
   :param calibrate_light_sensors: If ``True``, run IR sensor calibration after the distance calibration is confirmed.
   :param persist_to_yaml: If ``True``, write the EMA-filtered baseline to ``raccoon.project.yml`` so it persists across program runs.
   :param ema_alpha: EMA smoothing coefficient between 0.0 and 1.0. Higher values produce slower convergence but a more stable baseline.
   :param calibration_sets: List of named IR calibration surface sets (e.g. ``["default", "transparent"]``). Only used when ``calibrate_light_sensors`` is ``True``.
   :param exclude_ir_sensors: List of ``IRSensor`` instances to skip during IR calibration.

   :returns: A CalibrateDistanceBuilder (chainable via ``.distance_cm()``, ``.speed()``, ``.calibrate_light_sensors()``, ``.persist_to_yaml()``, ``.ema_alpha()``, ``.calibration_sets()``, ``.exclude_ir_sensors()``, ``.on_anomaly()``, ``.skip_timing()``).

   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"],
       )