Manual / Setup
Installing Person Detection Experimental
On the pre-built OpenFollow image and .deb package, Person Detection ships ready to run: the inference engine and the quality-tier models are bundled, so detection works offline with nothing to install. You only need this page to add detection to a source or base-only build that ships without the engine, or to add the model-export tools on a workstation so Download Model can fetch models beyond the bundled tiers.
Experimental – not for show use. Person Detection is an experimental feature. Accuracy, model defaults, and settings can change between releases, and the install procedure is not yet stable. Do not put it on a show-critical path. Use it for evaluation and rehearsal only.
Hardware-heavy. The installer refuses to start with less than 512 MB free for the engine, or 4 GB free with --with-export (torch + ultralytics are several gigabytes). Downloaded models need more still: it warns when the model location has under 24 GB free. Models are stored on the NVMe drive when one is mounted, otherwise in the application's working directory, so an NVMe drive is recommended when you keep many. Detection is also far more compute-heavy than marker-driven tracking and is really a workstation feature. Budget hardware accordingly – see Hardware.
Step by step
You run a single bundled installer on the device over SSH. You'll need a second computer – a Mac, or a PC running Linux or Windows – on the same network as the OpenFollow station, and the same VLAN if your network uses them. The device itself is headless, so all commands run on it from that computer.
Internet needed during install. The installer downloads packages, and Download Model fetches models, so the OpenFollow station needs internet access for those steps. Detection with an installed model runs offline.
<device-ip> in the commands below fills in automatically.
SSH refused with a host-key warning? If you see REMOTE HOST IDENTIFICATION HAS CHANGED, the device's SSH identity changed since you last connected at this IP (typically a reflash). Clear the stale key and try again: ssh-keygen -R <device-ip> (same command on macOS, Linux, and Windows).
You'll use Terminal – a standard app for sending text-based commands to another computer without a graphical user interface. Type or paste each line exactly and press Enter. Where a command shows <device-ip>, replace it with your station's IP address (shown on the device screen) – or enter it in the box above to fill every command at once.
-
Open Terminal.
On a Mac: press Cmd+Space, type
Terminal, press Enter. On Linux: press Ctrl+Alt+T, or open "Terminal" from your applications. -
Connect to your station.
ssh openfollow@<device-ip>When it asks for a password, type your device's password and press Enter. The characters won't appear as you type – that's normal. On stations set up from the prepared OpenFollow image, the default password is
openfollow. From here on, what you type runs on the device. -
Run the installer.
/usr/share/openfollow/install-detection.shIt checks free space, then installs the engine (onnxruntime and OpenCV) and restarts the OpenFollow service. If it stops with a space warning, free up storage (or fit an NVMe) and run it again. On an image or
.debthat already includes the engine it reports that and exits. -
Done.
When it prints
Done., the engine is installed. Open the web interface, tick Person detection under General → Station Settings → Advanced Settings → Features and save, then open the Person Detection tab. Pick a model under Detection Model; models beyond the bundled tiers are fetched with Download Model (needs the export tools, see below).
You'll use PowerShell (Windows 10) or Terminal (Windows 11) – a standard app for sending text-based commands to another computer without a graphical user interface. Both include the ssh command. Type or paste each line exactly and press Enter. Where a command shows <device-ip>, replace it with your station's IP address (shown on the device screen) – or enter it in the box above to fill every command at once.
-
Open PowerShell or Terminal.
Click Start, type
PowerShell(Windows 10) orTerminal(Windows 11), and press Enter. A text window opens. -
Connect to your station.
ssh openfollow@<device-ip>The first time you connect it may ask "Are you sure you want to continue connecting?" – type
yesand press Enter. When it asks for a password, type your device's password (it won't appear as you type – that's normal). On stations set up from the prepared OpenFollow image, the default password isopenfollow. From here on, what you type runs on the device. -
Run the installer.
/usr/share/openfollow/install-detection.shIt checks free space, then installs the engine (onnxruntime and OpenCV) and restarts the OpenFollow service. If it stops with a space warning, free up storage (or fit an NVMe) and run it again. On an image or
.debthat already includes the engine it reports that and exits. -
Done.
When it prints
Done., the engine is installed. Open the web interface, tick Person detection under General → Station Settings → Advanced Settings → Features and save, then open the Person Detection tab. Pick a model under Detection Model; models beyond the bundled tiers are fetched with Download Model (needs the export tools, see below).
ssh "not recognized"? On older Windows, add the client under Settings → Apps → Optional features → Add a feature → OpenSSH Client, then close and reopen the window.
The packages the install script installs – for advanced users, or when the script isn't available. They go into the application's Python environment. The interpreter is /opt/openfollow/venv/bin/python. Step 1 gives you detection with ONNX models; steps 2 and 3 add the model-export tools behind Download Model and are optional.
Check free space first. The engine needs at least 512 MB free; the export tools need at least ~4 GB. On a unit with an NVMe, keep the download cache and temp files off the small onboard storage (the bundled installer does this for you).
1. Connect to the device
ssh openfollow@<device-ip>
2. Install the inference engine
sudo /opt/openfollow/venv/bin/python -m pip install \
"onnxruntime>=1.17" "opencv-python>=4.8"
3. Optional: install the model-export tools
Install a CPU-only build of the tensor runtime first, from the CPU package index, so the install doesn't pull the large unused GPU libraries:
sudo /opt/openfollow/venv/bin/python -m pip install \
--index-url https://download.pytorch.org/whl/cpu torch torchvision
sudo /opt/openfollow/venv/bin/python -m pip install ultralytics onnx onnxslim
4. Verify
/opt/openfollow/venv/bin/python -c "import onnxruntime, cv2"
/opt/openfollow/venv/bin/python -c "import ultralytics, onnx"
Each should print nothing and exit cleanly (the second only if you installed the export tools). An ImportError means a package above didn't install – re-run the step that installs it and watch for errors in its output.
5. Restart the service
sudo systemctl restart openfollow
Detection is now available in the web UI. Tick Person detection under General → Station Settings → Advanced Settings → Features, open the Person Detection tab and pick a model under Detection Model.
Download Model. Models beyond the bundled tiers are fetched under Detection Model → Advanced models → Download Model: choose a Model, set the Export image size (a multiple of 32; match the inference size you run) and click Download model. It needs an internet connection and the export tools, which you add on a workstation by running the installer with --with-export: /usr/share/openfollow/install-detection.sh --with-export. They pull in torch and ultralytics (large, and AGPL-licensed) and aren't needed on a show Pi. Without them the section asks you to install them.