Merge pull request #1443 from luxonis/v3_dcl_readMePatch

Update README.md

Author: moratom

examples/cpp/DynamicCalibration/CMakeLists.txt

@@ -4,6 +4,6 @@ cmake_minimum_required(VERSION 3.10)
 ## function: dai_add_example(example_name example_src enable_test use_pcl)
 ## function: dai_set_example_test_labels(example_name ...)
 
-dai_add_example(calib_quality_dynamic calib_quality_dynamic.cpp ON OFF)
-dai_add_example(calibrate_dynamic calibrate_dynamic.cpp ON OFF)
-dai_add_example(calib_integration calib_integration.cpp ON OFF)
+dai_add_example(calibration_quality_dynamic calibration_quality_dynamic.cpp ON OFF)
+dai_add_example(calibration_dynamic calibration_dynamic.cpp ON OFF)
+dai_add_example(calibration_integration calibration_integration.cpp ON OFF)

examples/cpp/DynamicCalibration/README.md

@@ -1,6 +1,6 @@
 # Dynamic Calibration (C++) — DepthAI
 
-This folder contains two minimal, end-to-end **C++** examples that use **`dai::node::DynamicCalibration`** to (a) **calibrate** a stereo rig live and (b) **evaluate** calibration quality on demand — both while streaming synchronized stereo frames and disparity for visual feedback.
+This folder contains three minimal, end-to-end **C++** examples that use **`dai::node::DynamicCalibration`** to (a) **calibrate** a stereo rig live and (b) **evaluate** calibration quality on demand, (c) combination of both — while streaming synchronized stereo frames and disparity for visual feedback.
 
 > Close your preview window or stop the program to quit.
 
@@ -9,10 +9,10 @@ This folder contains two minimal, end-to-end **C++** examples that use **`dai::n
 ## What the node does
 
 `dai::node::DynamicCalibration` consumes **raw, unrectified** left/right mono frames and:
-- Streams **coverage feedback** (how well the calibration pattern is seen across the image).
+- Streams **coverage feedback**.
 - Produces either:
   - a **new calibration** (`CalibrationHandler`) you can apply on the device, or
-  - a **quality report** comparing *current* vs *achievable* calibration.
+  - a **quality report** comparing *current* vs *achieved* calibration.
 
 ### Outputs & metrics (C++ message types)
 
@@ -37,36 +37,69 @@ This folder contains two minimal, end-to-end **C++** examples that use **`dai::n
 
 ## 1) Live dynamic calibration (apply new calibration)
 
-**File idea:** `calibrate_dynamic.cpp`
+**File idea:** `calibration_dynamic.cpp`
 
 **Flow:**
 1. Create mono cameras → request **full-res NV12** (unrectified) → link to:
    - `DynamicCalibration.left/right`
    - `StereoDepth.left/right` (for live disparity view)
 2. Start the pipeline, give AE a moment to settle.
-3. **Start calibration** by sending `DynamicCalibrationControl(StartCalibrationCommand{})`.
+3. **Start calibration** by sending `DynamicCalibrationControl::Command::StartCalibration{}`.
 4. In the loop:
    - Show `left`, `right`, and `disparity`.
    - Poll `coverageOutput` for progress.
    - Poll `calibrationOutput` for a result.
 5. When a result arrives:
-   - **Apply** it by sending `ApplyCalibrationCommand(newCalibration)` on the control queue.
+   - **Apply** it by sending `DynamicCalibrationControl::Command::ApplyCalibration{newCalibration}` on the control queue.
    - Print quality deltas.
 
 ---
 
 ## 2) Calibration **quality check** (no applying)
 
-**File idea:** `quality_dynamic.cpp`
+**File idea:** `calibration_quality_dynamic.cpp`
 
 **Flow:**
 1. Same camera / StereoDepth / DynamicCalibration setup as above.
 2. In the loop:
-   - Send **coverage** request (`LoadImageCommand{}`) and read `coverageOutput`.
-   - Send **quality** request (`CalibrationQualityCommand{}`) and read `qualityOutput`.
+   - Send **coverage** request (`DynamicCalibrationControl::Command::LoadImage{}`) and read `coverageOutput`.
+   - Send **quality** request (`DynamicCalibrationControl::Command::CalibrationQuality{}`) and read `qualityOutput`.
 3. If `qualityData` is present, print rotation/Sampson/depth-error metrics.
-4. Optionally reset internal sample store (`ResetDataCommand{}`).
+4. Optionally reset internal sample store (`DynamicCalibrationControl::Command::ResetData{}`).
 
+
+---
+
+## 3) Continuous monitoring **+ auto-recalibration** (single binary)
+
+**File:** `calibration_integration.cpp`
+
+**What it does:**  
+Runs one loop that periodically checks calibration quality and, if drift is detected, starts calibration and applies the new calibration automatically — while showing `left`, `right`, and a colorized `disparity` preview.
+
+**Flow:**
+1. Create mono cameras → request **full-res NV12** (unrectified) → link to `dai::node::DynamicCalibration` and `dai::node::StereoDepth` for live disparity. Read the device’s current calibration as the baseline.
+2. On a fixed interval (e.g., ~3 seconds), send on the control queue:
+   - `DynamicCalibrationControl::Command::LoadImage{}` to compute coverage on the current frames, and
+   - `DynamicCalibrationControl::Command::CalibrationQuality{true}` to request a (forced) quality estimate.
+3. When a **quality** message arrives on `qualityOutput`:
+   - Log status; if `qualityData` is present, you may **reset** the internal data store with `DynamicCalibrationControl::Command::ResetData{}`.
+   - If quality indicates drift (for example, `abs(sampsonErrorNew - sampsonErrorCurrent) > 0.05f`), **start calibration** with `DynamicCalibrationControl::Command::StartCalibration{}`.
+4. When a **calibration** message arrives on `calibrationOutput`:
+   - **Apply** the new `CalibrationHandler` with `DynamicCalibrationControl::Command::ApplyCalibration{result.newCalibration}`, then **reset** data again (`ResetData{}`) to begin monitoring afresh.
+5. Exit on `q` keypress or window close.
+
+**Notes & defaults:**
+- Disparity preview can be auto-scaled to the observed maximum; zero disparity can be rendered black for clarity.
+- The 0.05 px Sampson threshold is a simple heuristic — tune to your tolerance and noise profile.
+
+**Example console output:**
+```
+Dynamic calibration status: success
+Successfully evaluated Quality
+Start recalibration process
+Successfully calibrated
+```
 ---
 
 ## Pipeline diagram
@@ -101,8 +134,11 @@ find_package(depthai CONFIG REQUIRED)    # provides depthai::core
 add_executable(calibrate_dynamic calibrate_dynamic.cpp)
 target_link_libraries(calibrate_dynamic PRIVATE depthai::core)
 
-add_executable(quality_dynamic quality_dynamic.cpp)
-target_link_libraries(quality_dynamic PRIVATE depthai::core)
+add_executable(calibration_quality_dynamic calibration_quality_dynamic.cpp)
+target_link_libraries(calibration_quality_dynamic PRIVATE depthai::core)
+
+add_executable(calibration_integration calibration_integration.cpp)
+target_link_libraries(calibration_integration PRIVATE depthai::core)
 ```
 
 Build:
@@ -114,27 +150,28 @@ cmake --build . -j
 
 Run:
 ```bash
-./calibrate_dynamic      # applies new calibration when ready
-./quality_dynamic        # reports metrics; does not apply
+./calibration_dynamic      # applies new calibration when ready
+./calibration_quality_dynamic  # reports metrics; does not apply
+./calibration_integration   # monitors quality, auto-recalibrates, and applies in one loop
 ```
 
 ---
 
 ## Commands overview (C++)
 
-- `DynamicCalibrationControl::StartCalibrationCommand{}`  
-  Begins dynamic calibration collection/solve. Combine with performance modes if available.
+- `DynamicCalibrationControl::Command::StartCalibration{}`  
+  Begins dynamic calibration collection/solve.
 
-- `DynamicCalibrationControl::ApplyCalibrationCommand{CalibrationHandler}`  
+- `DynamicCalibrationControl::Command::ApplyCalibration{CalibrationHandler}`  
   Applies the provided calibration on-device (affects downstream nodes in-session).
 
-- `DynamicCalibrationControl::LoadImageCommand{}`  
+- `DynamicCalibrationControl::Command::LoadImage{}`  
   Triggers coverage computation for the latest frames.
 
-- `DynamicCalibrationControl::CalibrationQualityCommand{bool force=false}`  
+- `DynamicCalibrationControl::Command::CalibrationQuality{bool force=false}`  
   Produces a `CalibrationQuality` message with `qualityData` if estimation is possible.
 
-- `DynamicCalibrationControl::ResetDataCommand{}`  
+- `DynamicCalibrationControl::Command::ResetData{}`  
   Clears accumulated samples/coverage state.
 
 ---

examples/cpp/DynamicCalibration/calibrate_dynamic.cpp renamed to examples/cpp/DynamicCalibration/calibration_dynamic.cpp

@@ -343,12 +343,12 @@ dai_set_example_test_labels(image_filters rvc2_all rvc4 ci)
 
 # DynamicCalibration
 if(DEPTHAI_DYNAMIC_CALIBRATION_SUPPORT)
-    add_python_example(calib_integration DynamicCalibration/calib_integration.py)
-    dai_set_example_test_labels(calib_integration ondevice rvc2_all rvc4 ci)
+    add_python_example(calibration_integration DynamicCalibration/calibration_integration.py)
+    dai_set_example_test_labels(calibration_integration ondevice rvc2_all rvc4 ci)
 
-    add_python_example(calib_quality_dynamic DynamicCalibration/calib_quality_dynamic.py)
-    dai_set_example_test_labels(calib_quality_dynamic ondevice rvc2_all rvc4 ci)
+    add_python_example(calibration_quality_dynamic DynamicCalibration/calibration_quality_dynamic.py)
+    dai_set_example_test_labels(calibration_quality_dynamic ondevice rvc2_all rvc4 ci)
 
-    add_python_example(calibrate_dynamic DynamicCalibration/calibrate_dynamic.py)
-    dai_set_example_test_labels(calibrate_dynamic ondevice rvc2_all rvc4 ci)
+    add_python_example(calibration_dynamic DynamicCalibration/calibration_dynamic.py)
+    dai_set_example_test_labels(calibration_dynamic ondevice rvc2_all rvc4 ci)
 endif()

examples/cpp/DynamicCalibration/calib_integration.cpp renamed to examples/cpp/DynamicCalibration/calibration_integration.cpp

@@ -1,6 +1,6 @@
 # Dynamic Calibration (Python) — DepthAI
 
-This folder contains two minimal, end-to-end examples that use **`dai.node.DynamicCalibration`** to (a) **calibrate** a stereo rig live and (b) **evaluate** calibration quality on demand — both while streaming synchronized stereo frames and disparity for visual feedback.
+This folder contains three minimal, end-to-end examples that use **`dai.node.DynamicCalibration`** to (a) **calibrate** a stereo device real-time and (b) **evaluate** calibration quality on demand (c) combination of both — while streaming synchronized stereo frames and disparity for visual feedback.
 
 > Press **`q`** in the preview window to quit either example.
 
@@ -9,24 +9,24 @@ This folder contains two minimal, end-to-end examples that use **`dai.node.Dynam
 ## What the node does
 
 `dai.node.DynamicCalibration` consumes **raw, unrectified** left/right mono frames and:
-- Streams **coverage feedback** (how well the calibration pattern is seen across the image).
+- Streams **coverage feedback**
 - Produces either:
-  - a **new calibration** (intrinsics/extrinsics) you can apply on the device, or
-  - a **quality report** comparing *current* vs *achievable* calibration.
+  - a **new calibration** (extrinsics) you can apply on the device, or
+  - a **quality report** comparing *current* vs *achieved* calibration.
 
 ### Outputs & metrics
 
 - **CoverageData** (`coverageOutput`)
-  - `meanCoverage` — overall spatial coverage [0–1].
-  - `dataAcquired` — amount of calibration-relevant data gathered [0–1].
-  - `coveragePerCellA/B` - matrix of spatial coverage of imager A or B
+  - `meanCoverage: float` — overall spatial coverage [0–1].
+  - `dataAcquired: float` — amount of calibration-relevant data gathered [0–1].
+  - `coveragePerCellA/B: list[list[float]]` - matrix of spatial coverage of imager A or B [0-1].
 
 - **DynamicCalibrationResult** (`calibrationOutput`)
-  - `newCalibration` — `CalibrationHandler` with updated parameters.
+  - `newCalibration: dai.CalibrationHanlder` — `CalibrationHandler` with updated parameters.
   - `calibrationDifference` — quality deltas between current and new:
-    - `rotationChange[3]` — extrinsic angle deltas (deg).
-    - `sampsonErrorCurrent`, `sampsonErrorNew` — reprojection proxy (px).
-    - `depthErrorDifference[4]` — theoretical depth error change at 1/2/5/10 m (%).
+    - `rotationChange[3]: list[float]` — extrinsic angle deltas (deg).
+    - `sampsonErrorCurrent: float`, `sampsonErrorNew: float` — reprojection proxy (px).
+    - `depthErrorDifference[4]: list[float]` — theoretical depth error change at 1/2/5/10 m (%).
   - `info` — human-readable status (e.g., "success").
 
 - **CalibrationQuality** (`qualityOutput`)
@@ -35,9 +35,9 @@ This folder contains two minimal, end-to-end examples that use **`dai.node.Dynam
 
 ---
 
-## 1) Live dynamic calibration (apply new calibration)
+## 1) Real-time dynamic calibration (apply new calibration)
 
-**Script idea:** `calibrate_dynamic.py` (based on your first snippet)
+**Script:** `calibration_dynamic.py`
 
 **Flow:**
 1. Create mono cameras → request **full-res NV12** (unrectified) → link to:
@@ -47,7 +47,7 @@ This folder contains two minimal, end-to-end examples that use **`dai.node.Dynam
 3. **Start calibration** with:
    ```python
    dynCalibInputControl.send(
-       dai.StartCalibrationCommand()
+       dai.DynamicCalibrationControl(dai.DynamicCalibrationControl.Commands.StartCalibration())
    )
    ```
 4. In the loop:
@@ -57,7 +57,7 @@ This folder contains two minimal, end-to-end examples that use **`dai.node.Dynam
 5. When a result arrives:
    - **Apply** it:
      ```python
-     dynCalibInputControl.send(dai.ApplyCalibrationCommand(calibrationData.newCalibration))
+     dynCalibInputControl.send(dai.DynamicCalibrationControl(dai.DynamicCalibrationControl.Commands.ApplyCalibration(calibrationData.newCalibration)))
      ```
    - Print quality deltas: rotation magnitude, Sampson errors, depth-error deltas.
 
@@ -77,28 +77,28 @@ Theoretical Depth Error Difference @1m:-4.20%, 2m:-3.10%, 5m:-1.60%, 10m:-0.90%
 
 ---
 
-## 2) Calibration **quality check** (no applying)
+## 2) Calibration **quality check**
 
-**Script idea:** `quality_dynamic.py` (based on your second snippet)
+**Script:** `calibration_quality_dynamic.py`
 
 **Flow:**
 1. Same camera / StereoDepth / DynamicCalibration setup as above.
 2. In the loop:
    - Show `left`, `right`, and `disparity`.
    - Ask for **coverage** on demand:
      ```python
-     dynCalibInputControl.send(dai.LoadImageCommand())
+     dynCalibInputControl.send(dai.DynamicCalibrationControl(dai.DynamicCalibrationControl.Commands.LoadImage()))
      coverage = dynCalibCoverageQueue.get()
      ```
    - Ask for **quality** on demand:
      ```python
-     dynCalibInputControl.send(dai.CalibrationQualityCommand())
+     dynCalibInputControl.send(dai.DynamicCalibrationControl(dai.DynamicCalibrationControl.Commands.dai.CalibrationQuality()))
      dynQualityResult = dynCalibQualityQueue.get()
      ```
 3. If `qualityData` is present, print rotation/Sampson/depth-error metrics.
 4. Optionally reset the internal sample store:
    ```python
-   dynCalibInputControl.send(dai.ResetDataCommand())
+   dynCalibInputControl.send(dai.DynamicCalibrationControl(dai.DynamicCalibrationControl.Commands.ResetData()))
    ```
 
 **Use this when:**
@@ -107,6 +107,39 @@ Theoretical Depth Error Difference @1m:-4.20%, 2m:-3.10%, 5m:-1.60%, 10m:-0.90%
 
 ---
 
+## 3) Continuous monitoring **+ auto-recalibration** (single script)
+
+**Script:** `calibration_integration.py`
+
+**What it does:**  
+Runs one loop that periodically checks calibration quality and, if drift is detected, starts calibration and applies the new calibration automatically — while showing `left`, `right`, and colorized `disparity` previews.
+
+**Flow:**
+1. Create mono cameras → request **full-res NV12** → link to `DynamicCalibration` and `StereoDepth` for live disparity. Read the device’s current calibration as baseline.
+2. On a fixed interval (for example, every ~3 seconds), send:
+   - `LoadImage()` to compute coverage on the current frames, and
+   - `CalibrationQuality(True)` (or equivalent) to request a quality estimate.
+3. When a quality result arrives:
+   - Log status; if quality data is present, **reset** the internal data store.
+   - If the quality indicates drift (e.g., a Sampson error delta above a small threshold like 0.05 px), **start calibration** (`StartCalibration()`).
+4. When a calibration result arrives:
+   - **Apply** the new `CalibrationHandler` to the device and **reset** data again.
+5. Press **`q`** to exit.
+
+**Notes & defaults:**
+- Disparity preview is auto-scaled to the observed maximum; **zero disparity appears black** for clarity.
+- The 0.05 px Sampson threshold is a simple heuristic — adjust per your tolerance.
+
+**Example console output:**
+```
+Dynamic calibration status: success
+Successfully evaluated Quality
+Start recalibration process
+Successfully calibrated
+```
+
+---
+
 ## Pipeline diagram
 
 ```
@@ -137,10 +170,13 @@ pip install depthai opencv-python numpy
 
 ```bash
 # Live calibration (applies new calibration when ready)
-python calibrate_dynamic.py
+python calibration_dynamic.py
+
+# Quality evaluation (reports metrics of when recalibration is required)
+python calibration_quality_dynamic.py
 
-# Quality evaluation (reports metrics; does not apply)
-python quality_dynamic.py
+# Integration example (starts new calibration when the quality reports major changes)
+python calibration_integration.py
 ```
 
 > Tip: Ensure your calibration target is well-lit, sharp, and observed across the **entire** FOV. Aim for high `meanCoverage` and steadily increasing `dataAcquired`.
@@ -149,19 +185,19 @@ python quality_dynamic.py
 
 ## Commands overview
 
-- `StartCalibrationCommand()`  
-  Begins dynamic calibration collection/solve. Use `OPTIMIZE_SPEED` for speed or `OPTIMIZE_PERFORMANCE` for more robust estimation.
+- `StartCalibration()`  
+  Begins dynamic calibration collection/solve.
 
-- `ApplyCalibrationCommand(calibration)`  
+- `ApplyCalibration(calibration)`  
   Applies the provided `CalibrationHandler` to the device (affects downstream nodes in this session).
 
-- `LoadImageCommand()`  
+- `LoadImage()`  
   Triggers coverage computation for the current frame(s).
 
-- `CalibrationQualityCommand()`  
+- `CalibrationQuality()`  
   Produces a `CalibrationQuality` message with `qualityData` if estimation is possible.
 
-- `ResetDataCommand()`  
+- `ResetData()`  
   Clears accumulated samples/coverage state to start fresh.
 
 ---
@@ -187,9 +223,9 @@ python quality_dynamic.py
   Ensure the pattern is visible, not motion-blurred, and covers diverse regions of the image. Increase lighting, adjust exposure, or hold the rig steady.
 
 - **Disparity looks worse after apply**  
-  Re-run to collect more diverse views (tilt/translate the target), or try `OPTIMIZE_PERFORMANCE`. Check for lens smudges and ensure focus is appropriate.
+  Re-run to collect more diverse views (tilt/translate the target).
 
 - **Typos in prints**  
   The examples should print “Successfully calibrated” and “Rotation difference” (avoid “Succesfully”/“dofference” if copying code).
 
----
+---