step.calibration.calibrate
==========================

.. py:module:: step.calibration.calibrate

.. autoapi-nested-parse::

   Unified calibration step (distance + IR sensors).



Classes
-------

.. autoapisummary::

   step.calibration.calibrate.Calibrate


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

.. py:class:: Calibrate(distance_cm: float = 30.0, speed: float = 1.0, persist_to_yaml: bool = True, ema_alpha: float = 0.7, calibration_sets: Optional[List[str]] = None, exclude_ir_sensors: Optional[List[raccoon.sensor_ir.IRSensor]] = None)

   Bases: :py:obj:`step.calibration.calibrate_distance.CalibrateDistance`


   Run a unified distance and IR sensor calibration.

   This is the recommended all-in-one calibration entry point. It drives
   the robot a known distance, prompts the user to measure the actual
   distance traveled, then adjusts the per-wheel ``ticks_to_rad`` values
   to correct odometry. After distance calibration, it automatically
   calibrates IR sensors by sampling them during a drive over the
   calibration surface(s).

   Calibration values are persisted to ``raccoon.project.yml`` using an
   exponential moving average (EMA), so the baseline converges toward the
   true value over multiple calibration runs.

   Prerequisites:
       The robot must have drive motors with encoder feedback and
       a configured kinematics model. For IR calibration, IR sensors
       must be registered in ``robot.defs.analog_sensors``.

   :param distance_cm: Distance (in cm) the robot drives during calibration.
                       Longer distances yield more accurate results.
   :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 persist_to_yaml: If ``True``, write the EMA-filtered baseline
                           back to ``raccoon.project.yml`` so it persists across 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 to
                            run (e.g. ``["default", "transparent"]``). Each set beyond
                            the first triggers an additional drive-and-sample cycle.
   :param exclude_ir_sensors: List of ``IRSensor`` instances to skip during
                              IR calibration.

   Example::

       from raccoon.step.calibration import calibrate

       # Basic calibration with defaults
       calibrate()

       # Custom: longer drive, two IR surface sets
       calibrate(
           distance_cm=50.0,
           calibration_sets=["default", "transparent"],
       )