TurboWarp-Camera-Calibration

Calibrate a camera shared through TurboWarp-Camera-Source against a ChArUco board, and publish its intrinsic calibration profile.

Every block is available as soon as the extension is loaded; there is nothing to switch on. The solver runs on a Web Worker and is created on first use, so loading the extension costs nothing until a calibration starts.

Requirements

• TurboWarp Desktop, Web, or Packager.
• @kubohiroya/turbowarp-camera-source loaded first. This extension never opens a camera itself.
• A ChArUco board, flat and unglossy: a chessboard with an ArUco marker inside each light square. The block arguments count inner corners, not printed squares: a 10×7 square board is 9 by 6. Supported boards are 9×6, 7×5, and 5×4 inner corners; draw them with the package's ./runtime helpers so the markers match.
• The extension must run without the sandbox.

Calibrating a camera

The simplest way is to let the extension take the samples:

start shared camera [default]
start camera [default] calibration [calibration-1] board [9] by [6] square [0.025] m marker [0.018] m max error [1.5] px
start automatic calibration capture for camera [default]
repeat until <not <automatic capture running for camera [default]?>>
  say (camera calibration guidance [default])
if <(camera calibration state [default]) = [solved]> then
  publish calibration profile for camera [default]

Automatic capture looks at the frame every 250 ms and keeps a view only when it would be accepted. Once it has enough views it solves in the background, and it finishes the session when the error on views held back from the fit is within the limit. At 40 views it does not stop; the view most like the others makes room for the new one.

To take the samples by hand instead:

start camera [default] calibration [calibration-1] board [9] by [6] square [0.025] m marker [0.018] m max error [1.5] px
repeat until <(camera [default] calibration sample count) = 12>
  add calibration sample for camera [default]
solve calibration for camera [default]
publish calibration profile for camera [default]

Each shared camera has its own session, profile, and diagnostics. Cancelling one camera never stops another consumer of the same shared camera.

Guiding the operator

During automatic capture a frame that cannot be used is not an error. camera calibration guidance says what to do instead:

The person holding the board is often not looking at the screen. Three reporters are meant for continuous cues such as sounds:

• camera calibration tilt direction: top-near, top-far, left-near, or right-near, whichever direction the kept views reach least.
• camera calibration novelty: 0 to 1, how much the view in front of the camera would add. It is measured on tilt, so sliding the board does not raise it.
• camera calibration progress: 0 to 16, four gates of four steps — enough views to solve, enough tilt among them, enough to hold some back, and an answer that holds on the held-back views. It never goes down.

Getting a usable result

Compare the reprojection error with the hold-out error. A low error on the calibration samples alone does not prove the result generalizes; the two agreeing is the evidence that it does.

Blocks

Error codes

The calibration profile

The profile is intrinsics only: an intrinsic matrix, a distortion model and its coefficients, the calibrated image size, its quality, and when it was measured. It also records the capture conditions the camera reported when the session started (resize mode, zoom, focus mode and distance, frame rate, facing mode) and the camera's own name, so Camera Source can later answer whether the profile fits the camera in front of it. A value the camera did not report is left out rather than guessed.

It never carries a world pose, and a pose that was not measured is never filled in with identity. Preview mirroring is a display concern; profile coordinates are always the unmirrored capture coordinates.

Profiles written by @kubohiroya/turbowarp-realtime-motion-capture are accepted on import; their world pose is dropped rather than reinterpreted.

Calibration files

A calibration leaves the PC as a ROS camera_info YAML file. Publish the profile and read Camera Source's camera profile YAML for [CAMERA_ID] to write one; ROS and OpenCV-based tools read the standard part, and the capture conditions compatibility needs travel under turbowarp_camera_source. import calibration profile reads that file back through Camera Source's own reader, so it is accepted or refused for the same reasons there and here.

Board pose

A calibration needs the board to move, so where a board sits is measured separately, after calibration, once the board has stopped. The result is the board in the camera's frame, never a world pose. Its scale comes from the declared square size, so the block asks whether that size was measured with a ruler or is nominal, and records the answer. The observed corners are kept with it so a placement tool can re-solve the measurement into a shared frame.

How the packages divide the work

Detecting a ChArUco board and solving a calibration needs OpenCV, and a TurboWarp extension ships as a single standalone bundle. Keeping the solver in its own extension lets Camera Source stay small enough for every camera consumer to load. The OpenCV inside is built for this extension to run in a Web Worker and to carry only the functions it calls; the whole extension is about 3.9 MB.

Safety

Calibration reads camera frames only to detect the board. Nothing is uploaded. A profile that carries a pairing credential is rejected rather than stored. Load unsandboxed extension code only from a source you trust.

Development

See the repository README and architecture documentation for build, test, release, and compatibility details.