ROS 2 camera calibration: validate and publish camera_info

A calibration file can be mathematically valid and still produce incorrect measurements when attached to the wrong image stream. Resolution changes, rectification, optical-frame naming and driver startup behavior can all separate the published calibration from the pixels being processed.

This guide is for teams integrating machine-vision cameras with ROS 2. You will learn when existing calibration is sufficient, when new measurements are justified, and how to verify that camera_info describes the images your application actually consumes. Start with validation rather than replacing calibration simply because a calibration package is available.

Decide which calibration needs attention

There are several different calibration problems. A checkerboard procedure for an image stream does not automatically address all of them.

Factory calibration is a starting point only when the device provides it for the relevant imaging subsystem. Do not assume every camera includes calibration for the lens attached to it. A camera with an interchangeable lens may need application-specific intrinsic calibration after lens selection and focus adjustment.

For a device that supplies factory parameters, first check whether those parameters meet your measurement requirements. Recalibrate when controlled tests reveal unacceptable errors, or when an optical change invalidates the existing model.

If the error concerns alignment between cameras rather than distortion within one image, follow the shared-coordinate-frame calibration guide. Replacing intrinsics is not a substitute for measuring an extrinsic transform.

Establish the image and camera_info contract

A sensor_msgs/msg/CameraInfo message must describe a particular image geometry, not merely identify a camera.

Record these items together:

• Camera identity and active stream, such as monochrome, color, infrared or depth.
• Image topic, dimensions, encoding and processing stage.
• Matching camera_info topic and optical frame.
• Distortion model and coefficient ordering.
• Acquisition mode, crop, binning and any downstream resizing.
• Calibration source, configuration location and software version.

The main message fields have different purposes:

• K is the intrinsic matrix for the raw, distorted image geometry.
• D contains distortion coefficients interpreted according to distortion_model.
• R describes the rectification rotation.
• P describes projection into the rectified image, including a translation term where applicable.
• binning_x, binning_y and roi describe acquisition geometry that consumers must interpret correctly.

The uncalibrated-message convention includes K[0] being zero. That is a useful warning, but nonzero values do not prove that calibration is correct.

An optical frame follows the camera convention: x points right, y points down and z points forward. The image and its associated calibration should identify the same optical frame and carry matching acquisition timestamps.

For stereo inputs, the raw-stream and metadata verification guide explains why stream selection must precede recalibration.

Measure the error before changing parameters

Use an independent validation capture, not only the images used to fit the calibration. Keep focus, resolution and acquisition settings fixed throughout the test.

Capture a dimensionally verified target at several positions and tilts across the useful field. Include the corners, working distances and orientations that matter to the application. A flat, stationary target near the image center is an easy case and can hide edge distortion or poor pose diversity.

For each detected target point, compare the observed location with its predicted projection. One useful metric is the root-mean-square length of the image-plane residual:

Here, N is the number of observed points. State this definition when reporting results, because some tools normalize over individual coordinate components instead.

For example, suppose 20 validation points have a total squared residual of 10 pixels²:

That result is neither automatically acceptable nor automatically poor. Connect it to the measurement budget. For a pinhole projection with fixed depth, a small horizontal image error gives this approximate lateral contribution:

This estimate excludes depth uncertainty, target error, pose uncertainty and mechanical motion. It also does not make RMS a worst-case bound. Inspect residuals by image region and test known dimensions separately.

For depth applications, also compare measured depth against independent references across the operating range. A low reprojection residual does not establish accurate depth. Use the 3D positioning guide when planning those distance-dependent tests.

Account for cropping, resizing and rectification

Calibration belongs to an image coordinate system. Changing that coordinate system can require different published parameters even when the optics have not moved.

For a simple axis-aligned pixel-coordinate transformation:

For a crop beginning at horizontal coordinate 160, with no resizing, sx = 1 and tx = -160. An original principal point at 640 therefore becomes 640 - 160 = 480 in the cropped image.

If an image width is halved, a focal length of 900 pixels becomes 900 × 0.5 = 450 pixels. The principal-point calculation must also include the resampler's coordinate convention. Some center-aligned resamplers introduce a half-pixel-related offset rather than applying scale alone.

These equations describe a simple coordinate change. They do not justify treating every sensor mode as a software resize. Binning, sensor readout changes and device processing may require mode-specific parameters.

ROS also provides ROI and binning metadata. Do not adjust the matrices and then accidentally apply the same crop correction again through a consumer's ROI handling. Verify the convention used by both publisher and consumer.

For rectified images, the left portion of P describes the effective intrinsic projection. Passing rectified pixels through raw-image undistortion again can introduce new errors. Similarly, depth registered into a color image generally needs the projection geometry of that output image, not an unrelated depth-stream matrix.

When a depth stream unexpectedly changes dimensions, check the depth-resolution and decimation diagnostic before fitting another calibration.

Publish calibration through the supported driver path

A saved file does not change a running publisher unless something explicitly loads it. Treat loading, publishing and persistence as separate checks.

1. Discover the active topics and publisher. Start with topic types and publisher details rather than assuming launch-file names match runtime names.

   ros2 topic list -t
   ros2 topic info /camera/camera_info --verbose
   ros2 topic echo /camera/camera_info --once
   

   These are example topic names. Replace them with the topics discovered on your system. Inspect the associated image metadata as well.

2. Find the driver's documented calibration interface. Some drivers use camera_info_manager and expose a calibration URL parameter. Others publish device-provided parameters or use a different configuration mechanism. There is no universal parameter name that works for every camera driver.

3. Validate the file format and identity. A common calibration YAML contains image_width, image_height, camera_name, camera_matrix, distortion_model, distortion_coefficients, rectification_matrix and projection_matrix. Compatibility depends on the loader. A parameter file and a calibration file are not automatically interchangeable.

4. Load the file where the node runs. A local file URL must resolve inside the node's runtime environment. A path visible on the host may not exist inside a container. Check permissions, startup logs and any camera-name validation reported by the loader.

5. Use a calibration service only when supported. A driver may provide a service with type sensor_msgs/srv/SetCameraInfo. Inspect the service and its response. A successful update does not, by itself, prove that parameters were written to device memory or will survive restart.

6. Choose one authoritative publisher. Do not add a second publisher to the existing calibration topic as a quick replacement. Consumers can receive conflicting messages. If the driver cannot load application calibration, use a deliberate republishing path with distinct topics, paired image headers and a clearly defined configuration source.

7. Restart and compare. Save the intended configuration, restart the acquisition process, and verify the published values again. This checks persistence rather than only the current node state.

Verify that the consumer uses the intended model

Successful publication is only half the integration. A consumer can remain subscribed to an old topic or receive nothing because its quality-of-service settings are incompatible.

Check the complete chain:

• The intended node is the publisher identified by topic inspection.
• Image and calibration subscriptions resolve to the expected fully qualified names.
• Publisher and subscriber QoS settings are compatible.
• Image dimensions agree with the geometry represented by the calibration and its ROI or binning metadata.
• The distortion model is supported by the consumer.
• Timestamp pairing works without borrowing calibration headers from another frame.
• The optical frame exists and downstream transforms refer to it consistently.
• Raw and rectified processing stages are not confused.

Use a stationary target first. Check straight features after undistortion, independent target dimensions and residual patterns near the image edges. Then repeat with normal acquisition timing and application motion.

If results are delivered asynchronously, preserve the relationship between each image and its metadata. The timestamp-based frame-matching guide covers errors that can resemble calibration drift even when the geometric model is unchanged.

Keep an acceptance record containing the calibration file, stream configuration, validation captures and measured errors. Repeat the same checks after restart and after any optics or acquisition-mode change.

Choose hardware around the validation requirement

Choose area scan cameras when the task needs image measurements and you can establish the required lens model. Use the camera finder to narrow the acquisition options, then confirm software integration separately.

The LS-CMR-0053 is an acquisition candidate to evaluate against your application requirements. Its catalog entry does not establish ROS driver support or calibration-file loading behavior.

The LS-CMR-0166 is another acquisition candidate. Before selection, verify access to image timestamps, stream settings and the calibration interfaces your integration needs.

For depth measurement, compare the appropriate 3D sensors. Ask how the device exposes intrinsic parameters, sensor-to-sensor transforms and calibration for processed output streams. Do not assume that a general image-calibration tool can modify internal depth processing.

Before choosing a sensing method, the 3D method-selection guide helps separate depth-generation requirements from software publication requirements.

When recalibration is the wrong first action

Recalibration will not fix every geometric symptom. Investigate these alternatives before replacing a known configuration:

A device identity displayed differently under another interface is also not sufficient evidence of incorrect calibration. Confirm the physical device, active stream and supported driver behavior through documented identification methods. Do not overwrite calibration solely to make a displayed label look familiar.

Final acceptance checklist and next step

Before releasing the configuration:

• Record device identity, lens settings and active image mode so the calibration remains traceable.
• Confirm which geometry each image and CameraInfo pair represents.
• Validate on independent captures across the actual measurement region.
• Compare errors with the application budget, including depth and frame-transform contributions.
• Confirm one authoritative calibration publisher and compatible subscriptions.
• Restart the system and verify that the intended parameters return.
• Preserve the previous configuration and use only documented device recovery procedures.

Keep existing calibration when it passes these checks. Recalibrate only the layer that fails, then repeat the same acceptance tests.

To plan an acquisition setup, start with the camera configuration workflow. If you need help separating optical accuracy from driver integration, send the stream details, calibration source and validation measurements through application support.