feat: tune detection sensitivity live from the settings page

Add sliders for the MOG2 change threshold and minimum blob size, and box
the largest blob in red on the motion map when it is too small to track.

README.md

@@ -25,18 +25,22 @@ as soon as it sees something.
 ## Motion Map
 
 The settings page at `http://<robot>:8042` shows a live motion map for checking
-detection: the camera view with the tracked blob boxed in green, the raw
+detection: the camera view with the largest blob boxed (green if the robot will
+turn toward it, red if it is below the minimum blob size), the raw
 background-subtraction mask, and the cleaned mask used to pick the blob. Above
 it is what the robot is doing (learning the background, watching, tracking, or
 scanning).
 
 ## Tuning
 
-Detection constants live at the top of `movement_tracker/motion.py`:
+The settings page has sliders for the change threshold and the minimum blob
+size, so detection can be tuned live while watching the motion map. Changes last
+until the app restarts; the defaults are the constants at the top of
+`movement_tracker/motion.py`:
 
 | Constant        | Meaning                                                          |
 |-----------------|------------------------------------------------------------------|
-| `VAR_THRESHOLD` | MOG2 sensitivity; raise it to ignore noise and flicker.          |
+| `VAR_THRESHOLD` | MOG2 change threshold; raise it to ignore noise and flicker.     |
 | `MIN_BLOB_FRAC` | Smallest blob, as a fraction of the image, that triggers a turn. |
 | `WARMUP`        | Frames used to learn the background before reacting.             |
 

movement_tracker/main.py

@@ -5,7 +5,7 @@ import time
 import cv2
 import numpy as np
 from fastapi import Response
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from reachy_mini import ReachyMini, ReachyMiniApp
 from reachy_mini.utils import create_head_pose
 
@@ -26,6 +26,11 @@ class StateResp(BaseModel):
     state: str
 
 
+class Sensitivity(BaseModel):
+    var_threshold: float = Field(ge=1, le=100)
+    min_blob_frac: float = Field(ge=0, le=0.1)
+
+
 class MovementTracker(ReachyMiniApp):
     # Optional: URL to a custom configuration page for the app
     # eg. "http://localhost:8042"
@@ -47,6 +52,19 @@ class MovementTracker(ReachyMiniApp):
         def get_state() -> StateResp:
             return StateResp(state=self.state)
 
+        @self.settings_app.get("/sensitivity")
+        def get_sensitivity() -> Sensitivity:
+            d = self.detector
+            return Sensitivity(
+                var_threshold=d.var_threshold, min_blob_frac=d.min_blob_frac
+            )
+
+        @self.settings_app.post("/sensitivity")
+        def set_sensitivity(req: Sensitivity) -> Sensitivity:
+            self.detector.set_var_threshold(req.var_threshold)
+            self.detector.min_blob_frac = req.min_blob_frac
+            return req
+
         @self.settings_app.get("/motion.jpg")
         def motion_jpg() -> Response:
             img = self.detector.debug_image()

movement_tracker/motion.py

@@ -2,12 +2,14 @@ import cv2
 import numpy as np
 
 WIDTH = 320  # frames are downscaled to this width before processing
+# defaults; both can be changed live from the settings page
 VAR_THRESHOLD = 25  # MOG2 sensitivity; higher ignores subtler changes
 MIN_BLOB_FRAC = 0.005  # smallest blob, as a fraction of the image, worth reacting to
 WARMUP = 15  # frames MOG2 needs to learn the background before its mask is useful
 
 KERNEL = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
 BLOB_COLOR = (0, 255, 0)
+SMALL_BLOB_COLOR = (0, 0, 255)  # largest blob, but below MIN_BLOB_FRAC
 LABEL_COLOR = (0, 200, 255)
 DEBUG_WIDTH = 1280  # panels are upscaled so labels and boxes stay crisp
 
@@ -16,17 +18,24 @@ class MotionDetector:
     """Find the largest moving blob in a stream of frames from a still camera."""
 
     def __init__(self) -> None:
-        # latest (frame, raw mask, cleaned mask, blob box) for the debug view;
-        # replaced as a whole so readers on other threads see a consistent set
+        self.var_threshold = VAR_THRESHOLD
+        self.min_blob_frac = MIN_BLOB_FRAC
+        # latest (frame, raw mask, cleaned mask, blob box, big enough) for the debug
+        # view; replaced as a whole so readers on other threads see a consistent set
         self.snapshot: tuple | None = None
         self.reset()
 
+    def set_var_threshold(self, value: float) -> None:
+        """Change MOG2 sensitivity without forgetting the learned background."""
+        self.var_threshold = value
+        self.sub.setVarThreshold(value)
+
     def reset(self) -> None:
         """Forget the learned background, e.g. after the camera moved."""
         # shadow detection also flags anything moderately darker than the background
         # (e.g. gray clothes against a white wall), so treat every change as motion
         self.sub = cv2.createBackgroundSubtractorMOG2(
-            varThreshold=VAR_THRESHOLD, detectShadows=False
+            varThreshold=self.var_threshold, detectShadows=False
         )
         self.n = 0
 
@@ -41,7 +50,7 @@ class MotionDetector:
         raw = self.sub.apply(small)
         self.n += 1
         if self.n < WARMUP:
-            self.snapshot = (small, raw, None, None)
+            self.snapshot = (small, raw, None, None, False)
             return None
 
         # drop speckle, then join fragments of the same object
@@ -49,8 +58,9 @@ class MotionDetector:
         mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, KERNEL, iterations=2)
 
         blob = largest_blob(mask)
-        self.snapshot = (small, raw, mask, blob and blob[0])
-        if blob is None:
+        ok = blob is not None and blob[2] >= self.min_blob_frac * mask.size
+        self.snapshot = (small, raw, mask, blob and blob[0], ok)
+        if not ok:
             return None
 
         x, y = blob[1]
@@ -61,12 +71,13 @@ class MotionDetector:
         if self.snapshot is None:
             return None
 
-        small, raw, mask, box = self.snapshot
+        small, raw, mask, box, ok = self.snapshot
         frame = upscale(small, DEBUG_WIDTH, cv2.INTER_LINEAR)
         if box is not None:
             f = DEBUG_WIDTH / small.shape[1]
             x, y, w, h = (round(v * f) for v in box)
-            cv2.rectangle(frame, (x, y), (x + w, y + h), BLOB_COLOR, 3)
+            color = BLOB_COLOR if ok else SMALL_BLOB_COLOR
+            cv2.rectangle(frame, (x, y), (x + w, y + h), color, 3)
 
         # during warmup there is no cleaned mask yet
         mask = np.zeros_like(raw) if mask is None else mask
@@ -101,16 +112,13 @@ def label(img: np.ndarray, text: str) -> np.ndarray:
 
 def largest_blob(
     mask: np.ndarray,
-) -> tuple[tuple[int, ...], tuple[float, float]] | None:
-    """Return the (x, y, w, h) box and centroid of the largest blob, if big enough."""
+) -> tuple[tuple[int, ...], tuple[float, float], int] | None:
+    """Return the (x, y, w, h) box, centroid and area of the largest blob."""
     n, _, stats, centroids = cv2.connectedComponentsWithStats(mask)
     if n < 2:
         return None
 
     # label 0 is the background
     i = 1 + int(np.argmax(stats[1:, cv2.CC_STAT_AREA]))
-    if stats[i, cv2.CC_STAT_AREA] < MIN_BLOB_FRAC * mask.size:
-        return None
-
     box = tuple(int(v) for v in stats[i, :4])
-    return box, tuple(centroids[i])
+    return box, tuple(centroids[i]), int(stats[i, cv2.CC_STAT_AREA])

movement_tracker/static/index.html

@@ -11,10 +11,24 @@
 <body>
     <h1>Movement Tracker</h1>
 
+    <h2>Sensitivity</h2>
+    <p class="legend">Lower values make detection more sensitive.</p>
+    <div class="slider">
+        <label for="var_threshold">Change threshold</label>
+        <input type="range" id="var_threshold" min="4" max="64" step="1">
+        <output id="var_threshold_out"></output>
+    </div>
+    <div class="slider">
+        <label for="min_blob_frac">Minimum blob size</label>
+        <input type="range" id="min_blob_frac" min="0.0002" max="0.02" step="0.0002">
+        <output id="min_blob_frac_out"></output>
+    </div>
+
     <h2>Motion map</h2>
-    <p class="legend">The camera view boxes the largest moving blob in green. The raw
-        mask is the background subtraction output; the cleaned mask is what picks the
-        blob.</p>
+    <p class="legend">The camera view boxes the largest moving blob: green if the
+        robot will turn toward it, red if it is smaller than the minimum blob size. The
+        raw mask is the background subtraction output; the cleaned mask is what picks
+        the blob.</p>
     <div id="state"></div>
     <img id="motion" alt="Motion map">
     <script src="/static/main.js"></script>

movement_tracker/static/main.js

@@ -14,3 +14,29 @@ setInterval(async () => {
         state.textContent = "Robot: unreachable";
     }
 }, 500);
+
+// sensitivity sliders: show values while dragging, send them on release
+const sliders = {
+    var_threshold: (v) => `${v}`,
+    min_blob_frac: (v) => `${(v * 100).toFixed(2)}% of image`,
+};
+const input = (k) => document.getElementById(k);
+const show = (k) => (input(`${k}_out`).textContent = sliders[k](Number(input(k).value)));
+
+async function sensitivity(method) {
+    const body = method === "POST"
+        ? JSON.stringify(Object.fromEntries(Object.keys(sliders).map((k) => [k, Number(input(k).value)])))
+        : undefined;
+    const resp = await fetch("/sensitivity", { method, body, headers: { "Content-Type": "application/json" } });
+    const values = await resp.json();
+    for (const k in sliders) {
+        input(k).value = values[k];
+        show(k);
+    }
+}
+
+for (const k in sliders) {
+    input(k).addEventListener("input", () => show(k));
+    input(k).addEventListener("change", () => sensitivity("POST"));
+}
+sensitivity("GET");

movement_tracker/static/style.css

@@ -19,4 +19,25 @@ body {
 #state {
     margin-bottom: 8px;
     font-family: monospace;
+}
+
+.slider {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 12px;
+    margin-bottom: 8px;
+}
+
+.slider label {
+    width: 10em;
+}
+
+.slider input {
+    flex: 1;
+    max-width: 400px;
+}
+
+.slider output {
+    font-family: monospace;
 }