Motion detect fraction small area of frame

config.env.example

@@ -138,11 +138,20 @@ CROSS_SNAPSHOT_CLEANUP_SEC=60
 
 # --- Rate / performance ---
 # Enable motion detection pre-filter: skip inference on frames with no movement
-# (true/false, default: false). When enabled, frames below MOTION_THRESHOLD are
-# skipped, saving NPU/CPU load.
+# (true/false, default: false), saving NPU/CPU load. Motion is measured by the
+# fraction of pixels that changed (localized-motion aware), NOT the whole-frame
+# average, so an object entering the edge of the frame is detected immediately.
 MOTION_DETECTION_ENABLED=false
-# Mean absolute pixel difference threshold (0–255) to consider a frame as having
-# motion. Lower = more sensitive. Default 5.0.
+# Per-pixel intensity change (0-255) for a pixel to count as "moved". Lower = more
+# sensitive to subtle movement. Default 25.
+MOTION_PIXEL_DELTA=25
+# Fraction of frame pixels (0-1) that must change to trigger inference. Lower =
+# more sensitive / detects smaller or farther objects sooner. Default 0.002 (0.2%).
+MOTION_MIN_AREA_FRAC=0.002
+# Heartbeat: always run inference at least every N frames even with no detected
+# motion, so a slow or barely-moving object is never missed for long. Default 15.
+MOTION_HEARTBEAT_FRAMES=15
+# (Deprecated) old whole-frame mean-difference threshold; no longer used.
 MOTION_THRESHOLD=5.0
 # Sliding window in seconds for computing the crossing rate (objects/minute)
 RATE_WINDOW_SEC=60