Skip to main content

​
Overview

Camera calibration finds where a fixed (external) camera sits relative to a robot’s base — the camera_wrt_base transform that skills such as pick-and-place read to turn what the camera sees into where the arm should move. It runs from the grid CLI, drives the arm hand-guided, and records the result on the robot’s camera automatically.
This calibrates fixed cameras only — a camera mounted on a tripod or rig looking at the workspace, not one riding the end-effector. The arm moves the target through the camera’s view; the camera stays put.

​
Step 1: Print the calibration target

The calibration uses a 12×9 radon checkerboard with 16.5 mm squares. Generate it with OpenCV’s gen_pattern.py:
Print it and attach it to a rigid flat board. Make sure:
  • Scale is exact — print at 100% (no “fit to page”), then measure a printed square; it must be 16.5 mm. Printer scaling silently shrinks the board and biases every result.
  • There is a white border of at least one square-width on all sides.
  • The surface is non-reflective, with no creases or unevenness.
  • The mount is rigid (a 3D-printed mount is ideal; tape works). The board and camera must never wiggle during a run.
Attach the printed board to the arm’s end-effector, and mount the camera at a fixed location looking at the workspace. During the run you hand-guide the arm to move the board through the camera’s view.

​
Step 2: Run the calibration

Calibration is offered at the end of robot add, from the grid CLI:
  1. Run robot add and complete the setup for your robot.
  2. At the final step the wizard flags any camera that has not been calibrated. Press c to calibrate now (or enter to skip and finish). If more than one camera is uncalibrated, pick the one to calibrate.
A live window opens showing the camera feed with the detected target. Its keys are in that window, not the terminal: Hand-guide the arm to a variety of poses and collect a sample at each. Hold the arm still at the instant you press space, so the pose and the frame match. Aim for a wide spread of target size, skew, and position in the frame — the coverage meters turn green as you cover the range. 15–20 well-distributed samples generally suffice; more is better. Example calibration window showing the detected target
If the target isn’t detected, confirm it is non-reflective and that the board is 12×9 squares. OpenCV sometimes counts interior corners (one fewer per side).

​
Step 3: Read the result

Press c to solve. The CLI reports a reprojection error in pixels and a verdict:
  • < 0.15 px — good.
  • 0.15–0.3 px — marginal; consider re-running.
  • > 0.3 px — too high; re-run the calibration.
The error reflects the extrinsic’s quality, not just the per-frame corner fit, so a wobbling board or a mis-reported arm pose shows up as a higher number. On a good result the CLI records the calibration on the robot’s camera and pushes it to the robot’s config. Skills that need the extrinsic then read it over Nexus — no copying by hand.
If the error stays high despite good coverage, check the arm’s end-effector pose. A wrong rotation-representation conversion in a robot driver gives the end-effector frame the wrong orientation, which the solve cannot recover from.