3D Markers

A marker is a tracked point in 3D space, identified by a numeric ID and a human-readable name. Markers are the unit of tracking that OpenFollow broadcasts on PSN, OTP, OSC, and RTTrPM. This chapter covers how to set them up, drive them, and reason about their IDs across multi-instance setups.

Marker IDs

Marker IDs are integers ≥ 1 – what the receiving show-control system sees. ID 0 is reserved as "ignored" on the PSN wire and is rejected on every write boundary (selection lists, OSC input, catalog edits).

Shared catalog

Marker ID, name, and colour live in a shared catalog synced across every OpenFollow station on the LAN. The most recent edit to an entry wins; deletes propagate too. Catalog edits sync to every other OpenFollow on the LAN within a few seconds.

Edit the catalog in Markers & Zones → Marker Control & Visibility. Add a row, type a name (e.g. "House Left"), pick a colour, save – every other station picks up the entry within a heartbeat.

Per-station selection

Each station picks which catalog markers it drives and which it renders:

• Controlled markers – markers driven by an input on this station (gamepad / keyboard / OSC). PSN broadcasts every one.
• Viewer markers – markers shown in the on-screen overlay. Usually the same as the controlled markers.

Selection is saved per station and is edited in the same Marker Control & Visibility section as the catalog. Each beacon also carries the station's selection, so the UI flags conflicts when two stations claim the same marker.

Both fields take a comma-separated list:

1, 2, 3

The two lists differ when one OpenFollow station should see markers driven by another – for example, two cameras on the same stage, each tracking its own marker but rendering the other's ball as well to give the operator situational awareness.

Choosing a numbering scheme

• One performer per ID. Marker 1 is the lead vocalist, marker 2 is the support, etc. Easiest for static shows.
• One operator per ID. Marker 1 is whatever operator A is currently following; the cue list reroutes consoles to different markers as the show progresses. More flexible for festivals and one-offs.

Coordinate system

Marker positions are in PSN stage coordinates, in metres:

• X – stage left (+) / stage right (−).
• Y – upstage (+) / downstage (−).
• Z – up (+) / down (−).

Receivers with different conventions (Eos x/z/y, ADM-OSC fractional, etc.) are handled by the matching OSC output template – markers stay in PSN space internally.

Driving a marker

Each marker can be driven by any combination of:

• A gamepad bound to it.
• The keyboard.
• The mouse.
• External OSC input.

Multiple inputs are additive within a frame – a gamepad-driven marker still accepts an OSC position jump, for example. Last write wins per axis.

Switch which marker the operator is actively driving with the next/prev marker keys (default Tab for next, prev unbound; configurable in Input → Keyboard) or the assigned gamepad buttons (defaults: D-Pad Right / D-Pad Left).

Marker visuals

How the marker appears on the on-screen overlay is controlled in Markers & Zones → Marker Visuals:

• Ball – a sphere at the marker position. Configurable size (m) and transparency.
• Crosshair – a 2D cross pinned to the marker. Configurable size, thickness, colour.
• Z Line – the line between the ground position and the ball, drawing the Z value that is set.
• Ground circle – a circle on the stage plane at the marker’s ground position.
• Z display – show Z relative to the stage level rather than the absolute world Z.

Per-marker colour is set in the catalog row (see Shared catalog); the add-row picker auto-suggests the first unused colour from a 20-entry palette. Visuals affect only the on-screen overlay; they have no effect on PSN/OSC output.

Marker movement

Speed bounds and default position are in Markers & Zones → Marker Movement:

Each marker keeps its own live speed, so two operators on two gamepads adjust their own speed independently. Left Bumper / Right Bumper on a pad writes to the marker that pad is routed to; keyboard R/T writes to the active marker. Streak detection (consecutive presses raise the step size) stays global. Gamepad stick input scales with deflection; keyboard movement is fixed-rate.

Resetting a marker

Press the configured Reset key/button (default X on keyboard, X button on the gamepad) to snap the active marker to its Default X/Y/Z position. Useful when a marker drifts off-screen or you need a clean starting position before a cue.

Position jumps via OSC

An OSC sender on the LAN can move a marker by sending one of:

/marker/<id>     x  y  z       # full triple, all three axes
/marker/<id>/x   v             # set X only
/marker/<id>/y   v             # set Y only
/marker/<id>/z   v             # set Z only

Coordinates are absolute, in metres, in the same PSN frame the rest of OpenFollow uses. See Controls → OSC input for the full settings and sender examples.

The OSC input port (default 8765) and the IP allowlist live in Input → OSC Input Without an allowlist, any device on the LAN can hijack marker positions – see Networking & Security.

Use cases

• Cue presets. Hard-code a marker to a stage position from your cue list – "marker 1 to (3, 5, 1.6) before scene 4".
• Chained instances. An upstream OpenFollow instance broadcasts a marker; a downstream instance picks it up and re-sends in a different output protocol.
• Console-driven tracking. A console with computed encoder positions drives an OpenFollow marker that other systems then react to.

Marker output

What gets broadcast for each marker is configured in the Output tab. By default:

• PSN sends every controlled marker at the data fps (default 60 Hz).
• OTP / RTTrPM are off by default; enable per the relevant section.
• OSC outputs are configured per-transmitter – each transmitter picks its source markers (the transmitter’s Default markers) and a named destination, plus its own message template and trigger. A single marker can drive any number of OSC transmitters.

See Output Protocols and OSC Transmitters.