OpenFollow Preview

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.

Type it here and every <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.

  1. Open Terminal.

    On a Mac: press Cmd+Space, type Terminal, press Enter. On Linux: press Ctrl+Alt+T, or open "Terminal" from your applications.

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

  3. Run the installer.
    /usr/share/openfollow/install-detection.sh

    It 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 .deb that already includes the engine it reports that and exits.

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

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.