Camera & Grid Calibration

Calibration is the biggest factor in tracking quality. This chapter walks through the seven-step Setup Wizard.

The wizard lives at Camera & Grid → Open Setup Wizard. You can also reach it directly at /wizard.

To plan grid dimensions and camera placement before you are on site, work through the interactive Positioning the Camera sketch – it mirrors the wizard's grid and camera + field-of-view views.

Before you start

Make sure you’ve completed:

• Installation – the service is running and the web UI is reachable.
• Video Inputs – at minimum, a video source produces a recognisable picture in the wizard.
• Core Concepts – you understand the Reference Point and the Grid.

And bring with you:

• Tape or gaffer marks for the Reference Point and the four grid corners – they have to be visible in the camera image.
• A tape measure.
• The camera’s datasheet – at minimum the horizontal field of view, or the sensor width and lens focal length if you’d rather have OpenFollow compute FOV for you.

The math, briefly

OpenFollow solves a Direct Linear Transform (DLT) from four known stage points (the grid corners) to their pixel positions in the camera image. The result is a camera matrix that maps any image pixel to a stage coordinate and back.

Step 1 – Preparation

This step is informational. It shows a top-down view of the stage with the Reference Point, the grid rectangle, and the camera’s field-of-view cone, and explains the two physical things you must mark before continuing:

1. Mark the Reference Point. One spot on stage that becomes (0, 0, 0). Default: the centre of the downstage edge. Match whatever the rest of the show is using.
2. Mark four grid corners. A right-angled rectangle, flat on the main performance level, with all four corners visible to the camera.

Press Next when both are physically marked.

Step 2 – Grid Setup

Enter the dimensions of the rectangle you marked. The diagram updates live.

The wizard reports the expected diagonal. Measure both diagonals on stage – they must match.

Step 3 – Video Source

If you ran Video Inputs already, this step just confirms the source. Otherwise, pick the input type and fill in the connection fields. The pipeline restarts within a second of saving and the live image starts feeding the next steps.

For bench testing without a real camera, choose Media Gallery and pick the bundled Stage scene.

Step 4 – Camera Position

The diagram shades the camera's full ground footprint – its view frustum meeting the stage floor – so you can see the covered area on both axes as you set the fields.

Enter the camera’s physical position and orientation, in metres and degrees, relative to the Reference Point.

For tracking, aim for a pitch of roughly −25° to −55° from a near-centre position: too flat and operators can’t judge depth; too steep and they can’t judge height. See Core Concepts → Recommended angle.

Lens / FOV

Two equivalent ways to describe the lens – pick one:

• Horizontal Field of View directly, in degrees. Pull this from the camera datasheet.
• Sensor Size (1/3", 1/2.3", 1", APS-C, etc., or custom width in mm) + Focal Length in mm. The wizard computes HFOV from the geometry.

If you edit HFOV directly after using the sensor/focal helper, the helper dims to indicate it’s no longer authoritative – your manual HFOV wins.

You set the horizontal field of view; the wizard derives the vertical from the frame and shows both as FOV NN°H · NN°V.

Approximate values are fine here – the next two steps refine position, orientation, and FOV automatically.

Behind Show experimental features, two lens-distortion sliders (k1 / k2, both default 0) on the Camera form bow the on-screen overlay grid to match a wide-angle or fisheye lens. The video itself is not re-warped, and marker and detection placement stay aligned. A rectilinear lens is still the better choice where you have one – see Core Concepts → The Video Feed.

Step 5 – Reference Mapping

This is the first interactive step. The camera image appears with a crosshair overlay. Drag the crosshair onto your physical Reference Point mark in the picture. All four corners and the grid overlay shift together with it – the goal is to anchor the grid to a known point on stage before fine-tuning each corner.

Tips

• Zoom your browser (Ctrl/Cmd + scroll) for finer dragging.
• Click the crosshair to focus it, then nudge with ← → ↑ ↓. Hold Shift for larger steps.
• If the live image hasn’t loaded yet, press Refresh Image.

Reset snaps the crosshair back to the centre of the image.

Step 6 – Corner Pinning

Drag each of the four labelled corners onto its physical stage mark:

• DSL – Downstage Left
• DSR – Downstage Right
• USR – Upstage Right
• USL – Upstage Left

Order matters for ergonomics: start with the two downstage corners (closest, easiest to read), then move to the upstage pair. As you drag, OpenFollow re-solves the camera in real time and shows the resulting Pos X/Y/Z, pitch, yaw, roll, and FOV underneath. Watch them drift toward sensible values as you align the corners more accurately.

Fine adjust (4× zoom)

Once a snapshot is loaded, the Fine adjust button switches to a 2×2 grid of 4×-zoomed views, one per corner, geographically arranged (USL top-left, USR top-right, DSL bottom-left, DSR bottom-right). This is how you place each corner with pixel precision after coarse alignment in the full image. Toggle back with Show full image.

Keyboard nudge

Click a corner (or use Tab) to focus it and nudge with the arrow keys; Shift + arrow for a bigger step. This works in both full-image and fine-adjust modes.

If a corner turns red

The wizard rejects positions that produce a non-convex quadrilateral or a quad with too small an area. Three likely causes:

1. Camera Position (step 4) is far enough off that the wizard can’t solve. Go back and check Pos Z and Pitch in particular.
2. Your marked rectangle is the wrong size. Re-measure on stage; the rectangle must match the dimensions you typed in step 2.
3. Your corners aren’t at 90°. Check both diagonals are equal.

Press Reset Corners to start the corner pinning over.

Step 7 – Review & Apply

The final step shows the camera snapshot with the solved grid overlaid in green, plus a summary of every value you’ve set:

• Camera: Pos X/Y/Z, pitch, yaw, roll, FOV.
• Grid: width, depth, spacing, X/Y/Z offsets.

Verify the green grid matches the floor markings in the picture. If anything looks wrong, click Back to fix it. If everything checks out, click Apply & Finish – the values land in the live config and OpenFollow starts using them immediately. PSN/OSC output continues without a restart.

Discard & Leave exits the wizard without saving.

Sharing & templates

Beyond a single station, Camera and Grid can be shared and reused from their direct-edit forms on the Camera & Grid tab:

• Apply to all stations – broadcast the current Camera and Grid to every OpenFollow station on the network. Use it when several operators share one physical camera.
• Save as template… / Load template… – store Camera and Grid together as a reusable template and recall a full venue setup later. The Load chooser also Exports a template as a single .oftemplate file and Imports one from another station.

The direct Camera and Grid forms apply live as you type but revert on reload unless you press Save; only the wizard's Apply & Finish and the form Save make values durable.

Verifying calibration on stage

After applying, walk a marker around the stage with a tape measure. The reported PSN position (visible in Overview → Live Statistics, on a connected console, or on a dedicated PSN listener) should match real-world distances within your acceptable tolerance – typically a few centimetres at the corners, possibly more at the far edges of the field of view.

If the marker is consistently offset in one direction, your Reference Point is mismarked. If it scales (the further from the centre, the worse), your grid dimensions are wrong. If it’s right at the corners but wrong in the middle, you may have the FOV off – try the Camera form (outside the wizard) and adjust HFOV by ±2° at a time.

When to recalibrate

• The camera moved or got bumped.
• The lens zoom or focus changed.
• You switched cameras.
• You changed any of the physical reference marks on stage.

You can re-run the wizard at any time. The current config is preserved until you press Apply & Finish.