Core Concepts

Read this once. The terms here recur throughout the manual and the web UI.

What OpenFollow is (and isn’t)

OpenFollow turns a video feed plus a control input into a stream of 3D positions and broadcasts them on open show-control protocols. It’s a position generator, not a fixture controller – no DMX, no Art-Net, no sACN. Your console or media server consumes the position data and decides what to do with it.

One instance handles one camera. Multiple instances on the same network can track different angles of the same stage.

The Reference Point

Every position OpenFollow reports is measured against a single physical point on stage called the Reference Point. It is the (0, 0, 0) of your show. Everything – camera position, grid offsets, marker coordinates, OSC output – is relative to it.

If your venue already has a defined origin, use it. If not, the centre of the downstage edge is a sensible default. Match whatever the rest of the show is using.

Coordinate system

OpenFollow uses the PSN theatrical convention everywhere – in the wizard, in the web UI, and on the wire:

Units are metres. Consoles with different axis conventions (e.g. ETC Eos Augment3D in X/Z/Y order) are handled by the matching OSC output template – see OSC Transmitters.

The Grid

The Grid is a flat, right-angled rectangle on the main performance level. It serves three purposes:

1. Calibration target. The wizard uses the four grid corners to solve the camera’s position and orientation. All four corners must be visible on camera.
2. Visual reference. The grid is drawn as an overlay on the live video so you can see where stage coordinates land in the image.
3. Normalisation. The frac transform on a position placeholder ([x.frac], [y.frac], [z.frac]) reports a marker’s position as a fraction of the grid – useful for spatial-audio engines that expect −1..1.

The grid is configured by its width (X), depth (Y), and three offsets (X, Y, Z) that describe where its centre sits relative to the Reference Point. By default the Reference Point is at the centre of the front edge of the grid.

The grid is a calibration aid, not a fence – anything in the camera’s field of view can be tracked.

The interactive Positioning the Camera sketch shows how the grid, camera position, and field of view fit together.

The Video Feed

Everything OpenFollow produces starts with the camera – it can only track what it can see. The feed is the single biggest factor in how well tracking works: the better it is, the better the results. Five things matter most:

• Position. Mount the camera front of house, looking at the stage. Frame it to cover the whole performance area, and don’t overshoot far beyond it – field of view spent on dead space is resolution lost on the performers.
• Angle. Steep enough to read depth, shallow enough to read height – see the recommended range below.
• Image quality. A sharp, well-exposed image at adequate resolution. A soft, dark, or noisy picture makes the performer hard to place; lighting that hides people (low light, haze, backlight, blackouts) is the most common cause. A more light-sensitive camera, or one with IR / night-vision, helps in dark scenes.
• Lens. Use a rectilinear lens. OpenFollow does not re-warp the video to remove distortion, so fisheye and other high-distortion lenses bend straight stage lines and degrade both calibration and tracking – avoid them. Where a wide-angle or fisheye lens is unavoidable, an experimental overlay-distortion option (k1 / k2) can bow the on-screen overlay grid to line up with the image.
• Latency. Operators follow what they see; lag between the live action and the image makes accurate following hard. Prefer low-latency sources and keep the video path short.

Recommended angle

Aim for a vertical angle of roughly 25° to 55° below horizontal, with the camera near the stage centreline:

• Too flat (under about 25°): depth reads poorly, so operators struggle to judge how far up- or downstage the performer is.
• Too steep (over about 55°): the performer’s height is hard to judge; if you can’t lower the angle, measure and program heights in advance.
• Well off to one side (more than about 15°): harder to operate and less predictable; a more centred position is better.

Plan placement with the interactive Positioning the Camera tool – it flags angles outside these ranges as you set them.

Markers

A marker is a tracked point in 3D space identified by an integer ID ≥ 1 and a human-readable name from the shared catalog. Markers are what gets broadcast on PSN, OTP, OSC, and RTTrPM. A typical setup uses one marker per performer, but you can attach a marker to any object you want to track – a prop, a flying piece, a moving truss element.

Markers are split into two roles:

• Controlled markers – markers driven by an input on this OpenFollow instance (gamepad, keyboard, OSC).
• Viewer markers – markers shown in the on-screen overlay. Usually this matches controlled markers, but can include markers driven by another instance for a multi-camera setup.

Controllers and inputs

A controller is whatever drives a marker. OpenFollow supports four input types as first-class controllers:

Multiple inputs can be active simultaneously – a gamepad-driven marker still accepts OSC position jumps, and the keyboard remains live for actions like reset and zone toggle.

Output protocols

OpenFollow can broadcast the same marker positions on as many of these protocols as you need, simultaneously:

• PSN – PosiStageNet, multicast UDP. The native tracking protocol most lighting consoles understand.
• OTP – Object Transform Protocol. Multicast, ANSI E1.59. Experimental.
• OSC – Open Sound Control, unicast UDP/TCP. Highly configurable per-message templates, used for QLab, ETC Eos, ADM-OSC spatial audio, and anything else that listens on OSC.
• RTTrPM – Real-Time Tracking Protocol (Module). For some immersive audio systems. Experimental.

OSC is per-transmitter: each output has its own destination, message template, and trigger. See OSC Transmitters.

Triggers

An OSC output isn’t always a stream. Each output carries a trigger describing when to send:

• Stream – fire at a fixed rate (1 / 5 / 10 / 20 / 30 / 60 Hz). Optionally only when the marker has moved ≥ min change metres since the last send.
• Hotkey – fire on a key + modifier press or release.
• Controller button – fire on a gamepad button press or release.
• MIDI message / Fader on change – fire from MIDI surfaces, virtual faders, or marker faders. See Hardware Inputs.

Trigger Zones

A zone is a polygon on the stage plane. The zone engine evaluates marker (and optionally person-detection Experimental) positions at a configurable rate (default 10 FPS) and sends OSC messages on enter, exit, and dwell. Zones are how you do cue-style automation – “fire QLab cue 12 when anyone is downstage centre” – without continuous tracking.

Web UI tabs at a glance

With these concepts in hand, head to the Quick Start or jump to the chapter that matches your task.