README.md

metadata

title: Movement Tracker
emoji: 👋
colorFrom: red
colorTo: blue
sdk: static
pinned: false
short_description: Looks at whatever is moving
tags:
  - reachy_mini
  - reachy_mini_python_app

Movement Tracker

A Reachy Mini app that looks at whatever is moving. It uses OpenCV's MOG2 background subtractor to find pixels that differ from the learned background, groups them into blobs, and turns its head toward the largest one. After each move the background is relearned, since the robot's own motion changes the whole view.

If nothing moves for a while, it scans: the head sweeps smoothly left and right while watching for motion. MOG2 needs a still camera, so scanning uses a second detector that cancels out the head's own motion: it tracks background features between frames, fits the homography that explains how they moved (a turning head is close to a pure rotation, which a homography models exactly), warps the older frame to line up with the newer one, and looks for what still differs. When it sees motion, the robot turns toward it and goes back to tracking.

Motion Map

The settings page at http://<robot>:8042 shows a live motion map for checking 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 detector output (the background-subtraction mask while still, the aligned frame difference while scanning), 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

The settings page has sliders for the change thresholds (still and scanning) 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 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.
DIFF_THRESHOLD	Change, after cancelling head motion, that counts while scanning.
FRAME_GAP	Frames apart when comparing while scanning; higher sees slower.

Behavior constants live at the top of movement_tracker/main.py:

Constant	Meaning
DEADBAND	How far from the image center motion must be to turn.
IDLE_TIMEOUT	Seconds without motion before scanning starts.
SCAN_RANGE	How far the head sweeps each way, relative to body.
SCAN_SPEED	Sweep speed; faster blurs frames and breaks alignment.
SCAN_CONFIRM	Consecutive detections needed to stop a sweep.

Deployment

The app is published as the private Hugging Face Space blambert/movement-tracker. To install it, log in to Hugging Face from the robot's dashboard and add the app from there.

The Space is a git remote. Set it up once (this requires an SSH key added to your Hugging Face account):

git remote add space git@hf.co:spaces/blambert/movement-tracker

Then publish main to the Space:

git push space main

Development

Run the tests (they cover only the detector, so the full reachy-mini install isn't needed):

uv run --no-project --with pytest --with numpy --with opencv-python-headless pytest

Check formatting:

uvx black --check .
uvx isort --check .