Remote Control: Calibrators

Last updated 7 August 2026

How to run a calibration from outside Backstage — start an alignment or a black-level pass, cancel one, restore an earlier result, and follow progress.

This page covers controlling a calibrator. Setting one up is Use Camera Calibration (CalibratorLite).

The cal domain covers both kinds of calibrator: Calibrator Lite, the camera-based calibration built into Backstage, and the external BRAINSALT Calibrator. Both are addressed the same way, by object name, so a control system does not need to know which kind it is talking to.

Before you start

  • A calibrator exists in the scene, set up and able to run when driven from the Backstage UI
  • Its name is settled — every route addresses it by name
  • For the protocol: Settings > Remote Control > Enable Show-Control Protocol is on (off by default)
  • The room lighting is right for the pass you are triggering — dark and constant for an alignment, completely dark for a black level — and stays that way for the whole run, because a remotely triggered pass has nobody in the room to notice that it did not

JSON protocol — domain cal

Send newline-delimited JSON to TCP 7400 (or UDP 7401 if enabled), with target set to the calibrator's exact name, case-sensitive.

Actions

Action

Args

Effect

list

—

Every calibrator in the project — both kinds — each as a status object

status

—

The status object for one calibrator

align

—

Start an alignment pass

black

—

Start a black-level pass

cancel

—

Abandon the pass in progress

restoreAlign

{"index": <0-based>}

Put back a stored alignment result. 0 is the newest

restoreBlack

{"index": <0-based>}

Put back a stored black-level result. 0 is the newest

 
{"domain":"cal","action":"list"}
{"domain":"cal","action":"align","target":"Dome"}
{"domain":"cal","action":"cancel","target":"Dome"}
{"domain":"cal","action":"restoreAlign","target":"Dome","args":{"index":0}}

Status

Field

Meaning

name

The calibrator's name — the sole identifier

state

Idle, Aligning, BlackLevel, Complete or Error

progress

How far the current pass has got

message

Human-readable detail — the text to surface on a control surface, especially in Error

alignSnapshots

Stored alignment results, newest first. The index into this list is what restoreAlign takes

blackSnapshots

Stored black-level results, newest first, indexed the same way

Live status

{"domain":"sys","action":"subscribe","args":{"domains":["cal"]}}

A calibration is long-running, so subscribing matters more here than elsewhere: state, progress and message together are enough to drive a progress bar and an error readout without polling.

The external Calibrator behaves slightly differently

Both kinds answer the same actions, but the external Calibrator has two quirks worth designing around:

  • black and restoreBlack do nothing if there is no black-level correction file to work with. The command is accepted; nothing happens.

  • restoreAlign and restoreBlack work by copying files back into place. Backstage's file watchdogs then reload the warp meshes and the black-level correction image on their own — so the restore completes a moment after the command returns, and the way to confirm it is the status, not the response.

Web Console — the Calibrator Lite block

Drop a Calibrator Lite block onto a Web Console page for start alignment, black level and cancel, with live status, progress and snapshot restore in a browser.

The palette calls this block Calibrator Lite, but like the protocol domain it works for a scene's external Calibrator too. Do not go looking for a second block.

This is the route to reach for when a technician on site needs to re-run an alignment from a tablet rather than at the machine.

Node editor

The external Calibrator is driven through AutoCalibrationFH nodes — the "Calibrator N" objects that run Calibrator.exe. Those nodes are where a graph participates in calibration, for instance triggering a scheduled overnight realign.

Common Mistakes

  • 404 calibrator not found — target must match the object name exactly, including case. Run cal.list, which returns both kinds.

  • black accepted but nothing happens — on an external Calibrator, there is no black-level correction file to act on. This is a no-op by design, not a failure.

  • A restore seems not to have applied — file-based restores complete asynchronously while the watchdogs reload. Watch state rather than trusting the command response.

  • Restoring the wrong snapshot — the index is 0-based and 0 is the newest, not the oldest. Read alignSnapshots before picking an index.

  • Starting a pass while one is running — check state is Idle first. Aligning or BlackLevel means a pass is already in progress; cancel it if you need to take over.

  • A scheduled overnight pass produces a bad result — the room was not dark, or the light changed while it ran. An unattended trigger cannot check the room; whatever schedules it has to guarantee the lighting.

Remote Control — the three routes, and every other controllable element

Use Camera Calibration (CalibratorLite) — setting up and running camera calibration

Enable and Configure the Show-Control Protocol — the protocol in full: transports, auth, allowlist, the reference client

Configure Projector Warping (Mesh Warp) — the warp meshes an alignment result writes