Appearance
Vision: coordinates, calibration targets and robots
Last updated
License feature: Machine VisionA coordinate system turns where in the picture into where on the machine. Once a camera has one, every tool that finds something — Pattern match, Circle gauge, Circles, Blobs — also publishes its position in millimeters from a datum (worldX, worldY), and Caliper and Circle gauge measure through it, correcting for a camera that is not quite square to the part.
Align a robot as well and the same positions are published in the robot's own frame (robotX, robotY, robotAngle), ready to send as a pick point. One calibration serves both: a measuring report reads the plane, the robot reads its frame.
It is set per camera, in the Coordinates card under the picture. Calibrating, like teaching, does not take effect until you Save.
Choosing a method
| Method | Use it when | Notes |
|---|---|---|
| ChArUco board | Almost always | A chessboard with a marker in each white square. Every corner is identified, so the board may be partly out of view, and the origin is always the printed corner marked with the red L |
| Markers (ArUco / AprilTag) | Aligning to a fixture or a robot | Individual markers at positions you give. Glue them to the fixture, or jog the robot to each center. Their positions are remembered, so recalibrating after a camera knock is Find markers, then Use this calibration |
| Chessboard | You already have one | It looks the same turned half round, so its origin is the corner nearest the top left of the picture. Fine for measuring; use ChArUco if the origin must not move |
| Points by hand | No target to hand | Click points in the picture and type where each one is. Four or more, spread around the working area |
AprilTag 36h11 is the default marker family — the one robotics people usually expect. All the ArUco and AprilTag dictionaries are built into OpenCV, so nothing extra is installed.
Calibrating with a ChArUco board
- In Coordinates, press Calibrate coordinates. ChArUco board is selected.
- Press Download printable and print the SVG at 100 % / actual size — not "fit to page".
- Measure a square on the print with calipers and type that into Square, measured. Printers scale; a sheet printed at 97 % makes every position 3 % wrong.
- Lay the board flat, at the height of the top of the part, filling as much of the working area as you can.
- Press Find board. The frame it was found in replaces the preview, with every corner circled and the axes drawn from the origin.
- Check the summary: "24 points: 0.048 mm RMS, worst 0.083 mm (0.21 px RMS)." A fraction of a pixel is good; several pixels means the board is not flat, not the size typed, or is curled.
- Press Use this calibration, then Save.
Move the pointer over the picture: the corner of the image shows the plane position under it. Lay a rule in view and run the pointer along it — that is the check worth doing before trusting the numbers.
Aligning a robot
The plane comes first; the robot is fitted to it. You need three or more points spread across the working area (three is the minimum that can tell whether the robot's Y runs the other way to the camera's).
- Calibrate the plane, as above. Leave the editor open, or press Recalibrate to reopen it.
- Under Robot alignment, press Add point.
- Put something the robot can touch — a marker's center tick, a pin, the tip of a part — in view. Press the crosshair on the row and click it in the picture; the plane X and Y fill in.
- Jog the robot's tool to it and type the robot's X and Y.
- Repeat for at least two more points, as far apart as the working area allows.
- Press Fit robot. The summary gives the error, which way the robot is turned and whether it is mirrored.
- Use this calibration, then Save.
The fit is rigid — rotation and position only — because both sides are in real lengths. If the robot's points come out a different size from the plane's, the card says so: "The robot's points are 0.0394× the size of the plane's." is millimeters on one side and inches on the other.
With Markers, a quick route is to print a few, glue them where the robot can reach, Find markers, type each one's position, Solve, then touch each center with the robot for the alignment rows.
What gets published
| Tag | Tools | Meaning |
|---|---|---|
worldX, worldY | Pattern, Circle gauge, Circles, Blobs | Where it is on the plane, in the calibration's units |
worldAngle | Pattern match | How far the part is turned from as taught, in degrees, as the plane sees it |
worldPositions | Circles, Blobs | Every part found, JSON [[x, y], …], top to bottom then left to right. worldX/worldY are the first |
robotX, robotY, robotAngle, robotPositions | as above | The same in the robot's frame, when a robot is aligned |
These tags only exist while the camera has a coordinate system; they are added on Save and removed if it is cleared. The pixel tags (x, y, offsetX …) are unchanged.
Angles follow the frame they are in: counter-clockwise from +X toward +Y. A ChArUco board's Y runs down the board as printed, so a part turned counter-clockwise on the sheet reads as a negative worldAngle. The robot angle accounts for a mirrored robot.
Accuracy and its limits
- One plane. Positions are exact at the height calibrated. Something taller or shorter reads off by parallax — the further from the camera's center, the more. Calibrate at the surface you measure, or use a telecentric lens.
- Spread the points. A calibration is good inside the area its points cover and guesses outside it.
- Three points cannot correct perspective. Points that only span a triangle give an affine map, and the card says "No perspective correction." Add a fourth corner.
- Lens distortion is not corrected. Wide-angle lenses bend straight lines near the edges; keep the working area near the middle, or use a longer lens.
- Pixel precision. Pattern match finds a position to the nearest pixel; Circle gauge to a fraction of one. About 0.22 mm per pixel at the center on the card is the resolution to expect.
- A moved camera is a new calibration. Nothing can detect a knock by itself — recalibrate after any change to the camera, lens or mounting. Markers fixed to the fixture make that quick: their positions are remembered.
- A changed frame shape is refused. If the camera starts sending a different aspect ratio, positioning tools fail with "The camera now sends 1280 × 720 but was calibrated at 1280 × 960. Calibrate the coordinates again." — a robot told to stop is better than one sent somewhere confidently wrong. Same shape at a different resolution is fine.
Camera mounted on the robot
Not yet supported. Today's alignment is fixed: it assumes the camera does not move relative to the robot's base. A camera on the arm needs the arm's pose with every frame (hand-eye calibration), which is planned to replace the fixed alignment without changing the plane calibration.