---
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 .