The engine was searching an empty room fifteen times a second

Measured rather than guessed, and the first guess was wrong. Wall clock
said H.265 decode cost 58 ms a frame; cap.read() blocks until the next
frame arrives, so that was the frame interval, not work. As CPU time:
decode 3.7 ms, detection 31.0 ms - and detection ran on every frame
whether or not anything was in front of the camera, 6,649 of 8,634
frames with faces_seen 0 and active_tracks 0 throughout.

detect_threads: OpenCV spreads a small repeated job over eight threads,
costing 31.0 ms of CPU for 8.9 ms of wall. One thread costs 15.3 ms for
15.3 ms, against a 66 ms budget at 15 fps. Half the CPU for latency
nothing can notice.

motion_gate: a 160x90 greyscale absdiff, 0.1 ms against detection's 15.
Consulted only while no track is open; forced to look every
motion_max_skip frames; compared against the last frame SEARCHED so a
slow drift cannot creep under the threshold; and a threshold above this
camera's measured noise and far below a person, so anything ambiguous
detects. tests/test_motion_gate.py pins each of those rather than the
saving, including asserting the longest run of skips rather than the
total - counting the total would pass a gate that slept forty frames
and then looked forty times.

Together 80% -> 16% of a core, detection skipped on 92% of frames.
faces_seen is still 0 and the gate is not why: run directly over the
same frames the detector finds nothing at threshold 0.50 either. The
placement is the limit, as recorded; the CPU was being spent to
rediscover that fifteen times a second.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KGcjxF1cNLcuwc3DAPcnfj

behavision/engine.py

@@ -170,6 +170,11 @@ class CameraWorker(threading.Thread):
         self._last_frame_ts = 0.0
         self._was_connected = False
         self.frames_processed = 0
+        # Motion gate state: a 160x90 greyscale thumbnail of the last frame we
+        # actually searched, and how many frames we have skipped since.
+        self._motion_prev = None
+        self._motion_skipped = 0
+        self.frames_skipped = 0
         self.faces_seen = 0
         self.pipeline = PipelineStats()
         # One outbox per worker, all writing into the same directory. Files are
@@ -236,6 +241,7 @@ class CameraWorker(threading.Thread):
         return {
             **self.source.stats(),
             "frames_processed": self.frames_processed,
+            "frames_skipped": self.frames_skipped,
             "faces_seen": self.faces_seen,
             "active_tracks": len(self.tracker.tracks),
             "pipeline": self.pipeline.snapshot(self.rcfg.min_enroll_quality),
@@ -244,6 +250,43 @@ class CameraWorker(threading.Thread):
                       "enroll_threshold": self.rcfg.enroll_threshold},
         }
 
+    def _nothing_moved(self, frame) -> bool:
+        """True when this frame is close enough to the last searched one that
+        searching it again would find the same nothing.
+
+        It cannot lose a face, and that property is what makes it acceptable
+        rather than merely cheap. Three guards, in order:
+
+          * the caller only asks while NO track is open, so a person already
+            being followed is never affected by it;
+          * `motion_max_skip` forces a real detection about once a second
+            whatever the thumbnail says, which covers a change too small or too
+            gradual for it - someone easing into frame at the far edge;
+          * the threshold sits well above measured sensor noise and well below
+            a person, and anything ambiguous falls through to detection. When
+            in doubt it looks.
+
+        Cost is 0.1 ms against detection's 15 ms, so an empty shop stops paying
+        for a search of an empty room ~90 times a second.
+        """
+        import cv2 as _cv2
+        small = _cv2.resize(_cv2.cvtColor(frame, _cv2.COLOR_BGR2GRAY), (160, 90),
+                            interpolation=_cv2.INTER_AREA)
+        prev, self._motion_prev = self._motion_prev, small
+        if prev is None:
+            return False
+        if self._motion_skipped >= self.cfg.app.motion_max_skip:
+            self._motion_skipped = 0
+            return False
+        if float(_cv2.absdiff(small, prev).mean()) >= self.cfg.app.motion_threshold:
+            self._motion_skipped = 0
+            # Keep the thumbnail we just searched against, not this one, so a
+            # slow drift cannot creep past the threshold one frame at a time.
+            return False
+        self._motion_prev = prev
+        self._motion_skipped += 1
+        return True
+
     # -- thread ---------------------------------------------------------
     def run(self) -> None:
         tcfg = self.cfg.tracking
@@ -256,6 +299,15 @@ class CameraWorker(threading.Thread):
                     continue
                 self._last_frame_ts = ts
 
+                # An empty room costs exactly as much to search as a busy one,
+                # and a shop is empty most of the day. Only ever while nothing
+                # is being tracked - see _nothing_moved.
+                if (self.cfg.app.motion_gate and not self.tracker.tracks
+                        and self._nothing_moved(frame)):
+                    self.frames_skipped += 1
+                    self._remember_tracks([])
+                    continue
+
                 detections = self.detector.detect(frame)
                 for det in detections:
                     det.quality = face_quality(frame, det.box, det.kps)