MetriCal Reports
When running a calibration with MetriCal, successful runs generate a comprehensive set of charts and diagnostics to help you understand your calibration quality. These are output to your command line interface as full report detailing every run.
This documentation explains each report section, what metrics they display, and how to interpret figures to improve your calibration workflow.
Generating Reports
Reports can be saved to an HTML file for later inspection. This is useful for sharing results with team members or for archiving results in a human-readable format.
Calibrate Mode
Use the --report-path argument when running MetriCal's
Calibrate command to save the CLI report directly to an HTML
file.
metrical calibrate --report-path "report.html" ...
Report Mode
Use Report command to generate a report from a plex or the output file of a previous calibration.
metrical report [OPTIONS] <PLEX_OR_RESULTS_PATH>
Color Coding in MetriCal Output
MetriCal uses ANSI terminal codes for colorizing output according to an internal assessment of metric quality:
- █ Cyan : Spectacular (excellent calibration quality)
- █ Green: Good (solid calibration quality)
- █ Orange: Okay, but generally poor (may need improvement)
- █ Red: Bad (likely needs attention)
Note that this quality assessment is based on experience with a variety of datasets and may not accurately reflect your specific calibration needs. Use these colors as a general guide, but always consider the context of your calibration setup and goals.
Chart Sections Overview
MetriCal organizes its report into sections, each identified by a two-letter prefix on its tables. The HTML report includes a table of contents linking to each section:
- Data Intake (
DI-*prefix) - Metadata about the run, its components, and its object spaces - Synchronization (
SY-*prefix) - Temporal offsets, detection timelines, and sync groups - Data Quality (
DQ-*prefix) - Observation filtering, camera FOV coverage, and LiDAR detection quality - Camera Modeling (
CM-*prefix) - How well the camera models fit the data - Calibrated Object Space (
CO-*prefix) - Planarity of optimized calibration targets - Extrinsics Info (
EI-*prefix) - Metrics on the spatial relationships between components - Calibration Optimization (
OP-*prefix) - Per-phase optimization timing - Calibration Summary (
CS-*prefix) - Overall performance metrics and the final verdict - Data Diagnostics (
DD-*prefix) - Warnings and advice about your calibration dataset - Calibrated Plex (
CP-*prefix) - The calibration results themselves - URDF Conversion (
UF-*prefix) - Link mapping when converting a URDF (spec workflows only)
Let's explore each section in detail.
Data Intake Charts (DI)
These charts describe the run configuration and the components and targets that participated in it.
DI-001: Calibration Metadata
This table displays the basic configuration settings used for your calibration run. Both the input arguments and the actual settings used during optimization are shown for reference.
DI-002: Calibrated Components
This table lists every component participating in the calibration. The Label column shows the abbreviated identifier (a shortened name that omits common prefix/suffixes) that the rest of the report uses to refer to each component, so you can cross-reference a component here against the other tables.
DI-003: Object Space Descriptions
This table describes the calibration targets (object spaces) used in your dataset:
- Type: The type of target object (e.g., DotMarkers, Charuco, etc.)
- UUID: The unique identifier of the object
- Detector: The detector used (e.g., "Dictionary: Aruco7x7_50") and its description
- Variance: The expected prior variances of the target descriptor
DI-004: Processed Observation Count
This critical table shows how many observations were processed from your dataset:
- Component: The abbreviated component name (see DI-002 to match abbreviated name to the full name)
- # read: Total number of observations read from the dataset
- # with detections: Number of measurements where the detector identified features
If there's a significant drop between these columns, it may indicate an issue with your dataset or settings. These instances will be flagged in the diagnostics section. The subsequent filtering of those detections is broken out per target in DQ-001.
Synchronization Charts (SY)
These charts describe the temporal relationships between your sensor components: how their clocks line up, when detections occurred, and how observations were grouped for joint calibration.
SY-001: Temporal Offset Estimation (MST)
This table reports the estimated clock offset between each component and a reference component,
following the Minimum Spanning Tree of spatial
constraints. A confidence value between 0 and 1 estimates the reliability of each offset; values
below 0.5 are low confidence, and "—" marks the reference component. The heading reads Temporal
Offset Estimation (MST) when offsets were applied, or (MST, not applied) when they were only
estimated. To apply temporal offset correction, re-run with the --time-sync flag; unsynchronized
clocks are also flagged by the Temporal Offsets Detected
diagnostic.
SY-002: Detection Timeline
This chart visualizes when detections occurred across your dataset timeline:
- X-axis represents time in seconds since the first observation
- Each row represents a different sensor component
- Points indicate timestamps when features were detected
- Components are color-coded for easy differentiation
- If no detections were found for a given component, then
(N/A)is printed instead.
This helps you visualize how synchronized your sensor data is and identify any gaps in observations, or components that lacked detections at all. If you expect all of your observations to align nicely but they aren't aligned at all, it's a sign that your timestamps are not being written or read correctly. Either way, this table is a good place to start debugging.
SY-003: Sync Group Assignment
This chart shows how observations are grouped for joint calibration. A sync group is a set of observations, close enough in time, that MetriCal treats as simultaneous. Components that never share a sync group with the rest of the system cannot be tied in temporally; such a component is flagged by the Component Shares No Sync Groups diagnostic.
Data Quality Charts (DQ)
These charts assess the quality and coverage of the detections that survived filtering.
DQ-001: Filtered Observation Count
This table reports the camera detection filtering pipeline left-to-right as a sequence of stages, with counts reported per target (one count per detected calibration target per frame). Reading across the row shows how many per-target detections survive the quality filter and the motion filter. A large drop at any stage indicates that a filter removed most of your data, which the diagnostics section will flag.
DQ-002: Camera FOV Coverage
This visual chart shows how well your calibration data covers the field of view (FOV) of each camera:
- The chart divides each camera's image into a 10x10 grid
- Each grid cell shows how many features were detected in that region
- Color coding indicates feature density:
- █ Red: No features detected
- █ Orange: 1-15 features detected
- █ Green: 16-50 features detected
- █ Cyan: >50 features detected
Ideally, you want to see a mostly green/cyan grid with minimal red cells, indicating good coverage across the entire FOV. Poor coverage can lead to inaccurate intrinsics calibration, and is flagged by the Poor Camera Feature Coverage diagnostic.
DQ-003: Lidar Circle Detection Quality
This table reports the quality of all detections per LiDAR and circle target, replacing the older LiDAR circle coverage histogram with per-target statistics:
- # Detect: Total detections
- Med. RMS: Median raw cluster planarity, in millimeters; values above 20 mm suggest noise
- % Noisy: Fraction of detections with RMS above 20 mm
- Med. Arc: Median visible arc, in degrees, per detection
- # Arc Rej.: Detections rejected for showing less than 180° of visible arc (from occlusion or the edge of the field of view)
- Med. Cull: Median % of points rejected during filtering. >20% indicates high noise
A high % Noisy or Med. RMS points to noisy edge points and is flagged by the Poor LiDAR Circle Planarity diagnostic.
Camera Modeling Charts (CM)
These charts show how well the selected camera models fit your calibration data.
CM-001: Binned Reprojection Errors
This heatmap visualizes reprojection errors across the camera's field of view:
- The chart shows a 10x10 grid representing the camera FOV
- Each cell contains the weighted RMSE (Root Mean Square Error) of reprojection errors in that region
- Color coding indicates error magnitude:
- █ Cyan: < 0.1px error
- █ Green: 0.1-0.25px error
- █ Orange: 0.25-1.0px error
- █ Red: > 1px error or no data
Ideally, most cells should be cyan or green. Areas with consistently higher errors (orange/red) may indicate issues with your camera model or lens distortion that isn't being captured correctly.
CM-002: Stereo Pair Rectification Table
For multi-camera setups, this chart shows the stereo rectification error between camera pairs. Any cameras that saw the same targets at the same time are added to a stereo pair.
- Lists each camera pair combination
- Shows various error metrics for stereo rectification
- Indicates how well the extrinsic calibration aligns the two cameras
Lower RMSE values indicate better stereo calibration. The number of mutual images is the number of images that contained overlapping stereo observations between the specified components pairs, and the number of mutual features indicates the total number of matched points between those overlapping stereo observations. The histogram is generated relative to the number of mutual features.
CM-003: Feature Depth Variation
This table reports the within-observation feature depth spread for each camera, a scale-invariant metric for assessing the risk of projective compensation (where focal length and depth trade off against one another). Higher ratios indicate better depth diversity.
- Per-Object Max Spread: The maximum Z-range (depth) across all features observed in a single frame
- Per-Object Depth Ratio: The ratio of max spread to median depth
- Consolidated Depth Ratio: The ratio computed across all objects observed
Low depth ratios mean the target was observed at a nearly constant depth, which makes focal length harder to separate from distance; capturing the target at a range of distances improves this.
CM-004: Camera Summary Statistics
This table summarizes per-camera reprojection RMSE, outlier counts, and residual percentiles. RMSE below 0.25px is excellent; above 1.0px warrants investigation. This can vary based on your camera image resolution or camera type.
If two cameras have pixels of different sizes, then it is important to first convert these RMSEs
to some metric size so as to compare them equally. This is what pixel_pitch in the
Plex API is for: cameras can be compared more equally with that
in mind, as the pixel size between two cameras is not always equal!
Calibrated Object Space Charts (CO)
CO-001: Calibrated Object-Space Planarity
This table measures how far the optimized object-space points have drifted from planarity for each target that is expected to be planar. Large planarity drift on a board that should be flat is a strong indicator of projective compensation from a poor calibration; a well-constrained calibration keeps planar targets planar.
Extrinsics Info Charts (EI)
These charts provide metrics on the spatial relationships between your calibrated components.
EI-001: Component Relative Extrinsics Errors
This is a complete summary of all component extrinsics errors (as RMSE) between each pair of components, as described by the Composed Relative Extrinsics metrics. It measures how much each pairwise extrinsic was adjusted during optimization, weighted by the prior covariance, and is one of the most useful tables when evaluating the quality of a plex's extrinsics calibration. Because the errors are weighted, outliers are taken into account. Lower values indicate more precise extrinsic calibration between components.
Rotations are printed as Euler angles, using Extrinsic XYZ convention.
- X, Y, Z (m): Translation errors in meters
- Roll, Pitch, Yaw (°): Rotation errors in degrees
EI-002: IMU Preintegration RMSEs
This table reports the weighted preintegration residuals per IMU, using the IMU Preintegration Error metric. High translation or rotation RMSE may indicate noisy IMU data or a poor IMU model fit.
EI-003: Trajectory Alignment RMSEs (Hand-Eye / LNS)
This table reports the weighted residual error from hand-eye or local navigation system (LNS) trajectory alignment. High values may indicate a poor trajectory fit, noisy pose data, or insufficient motion for the alignment to be observable.
EI-004: Camera-LiDAR Summary Statistics
This table reports per-pair camera-LiDAR misalignment metrics aggregated across all cameras, with outliers downweighted. It draws on the Root Mean Square Error (RMSE) of three residual metrics, each computed when a camera-LiDAR pair is co-visible with a LiDAR circle target:
For a component that has been appropriately modeled (i.e. there are no un-modeled systematic error sources present), this represents the mean quantity of error from observations taken by a single component.
EI-005: LiDAR-LiDAR Summary Statistics
This table reports plane-normal consistency between LiDAR pairs, with outliers downweighted, drawing on the Paired 3D Point Error metric for co-visible LiDAR. Lower values indicate better agreement.
Two LiDAR calibrated simultaneously will have the same RMSE relative to one another. This makes intuitive sense: LiDAR A will have a certain relative error to LiDAR B, but LiDAR B will have that same relative error when compared to LiDAR A. Make sure to take this into account when comparing LiDAR RMSE more generally.
Calibration Optimization Charts (OP)
OP-001: Calibration Phases
This table lists the bundle adjustment phases executed during optimization. Each phase refines the calibration with a different set of parameters or constraints; the table reports the iterations and wall-clock duration of each phase, which is useful for understanding where optimization time was spent.
Calibration Summary Charts (CS)
These charts provide overall metrics on calibration quality and the final outcome of the run.
CS-001: Optimization Summary Statistics
This table provides high-level metrics about the optimization process:
- Optimized Object RMSE: The overall reprojection error computed across all cameras
- Posterior Variance: A statistical measure of the calibration uncertainty; lower is better
Lower values indicate a more accurate calibration.
CS-002: Calibration Verdict
This table reports the final calibration outcome: the pass/fail verdict, a summary of the components calibrated, a breakdown of the diagnostics by severity, and the paths to the output files (including the commands to extract the optimized plex and object space from the results MCAP). This verdict table replaces the standalone Output Summary from earlier versions, so the output-file locations now live here.
Data Diagnostics
MetriCal performs comprehensive analysis of your calibration data and provides diagnostics to help identify potential issues. These diagnostics are categorized by severity level:
█ DD-001 High-Risk Diagnostics
Critical issues that likely need to be addressed for reliable calibration:
- No Component to Register Against: Missing required component for calibration
- Component Missing Compatible Component Type: Compatible component exists but has no detections
- Motion Filter filtered all component observations: One of our filters removed all observations, or no observations had any usable detections for a requested topic
- Object Has Large Variances: Object has excessive variance (> 1e-6)
- Projective Compensation: MetriCal has detected a common projective compensation in the results
- Poor LiDAR Feature Coverage: Poor feature coverage in LiDAR circle captures
- Poor LiDAR Circle Planarity: LiDAR circle detections have many off-plane edge points, indicating noisy detections
- IMU Specific Force in g Units: Accelerometer data is reported in units of gravity (g) rather than the expected m/s²
- IMU Intrinsics Out of Range: Calibrated IMU scale or shear values fall outside expected ranges (scale near 1.0, shear near 0.0), suggesting insufficient excitation or an over-complex intrinsics model
- Gravity Magnitude Out of Range: The gravity magnitude inferred for an object space deviates significantly from the expected ~9.81 m/s², indicating a poor IMU calibration
█ DD-002 Medium-Risk Diagnostics
Issues that should be addressed but may not prevent successful calibration:
- Poor Camera Feature Coverage: Poor feature coverage in camera FOV (< 75%)
- Two or More Spatial Subplexes: Multiple unrelated spatial groups detected
- Low Mutual Observations Count: Camera pair could benefit from more mutual observations
- Component Shares No Sync Groups: Component has no timestamp overlap with others
- Low Camera Initialization Success Rate: Camera initialization produced poses for fewer than half of available observations, which can degrade calibration quality
- IMU Motion Profile Issues: An IMU has a minor single-axis excitation deficiency; calibration proceeds but accuracy along the deficient axis may be degraded
- IMU Timing Jitter: IMU timestamps are non-periodic, which prevents spectral motion analysis for that IMU
- LNS Motion Profile Issues: A local navigation sensor's trajectory has insufficient excitation
- Temporal Offsets Detected: Sensor components appear to have unsynchronized clocks; offsets
were detected but not applied (re-run with
--time-syncto correct them)
An example of a medium-risk diagnostic as printed in the report:
█ DD-003 Low-Risk Diagnostics
Advice that might help improve calibration quality:
- Component Has Many Low Quality Detections: High proportion of detections discarded due to quality issues
Calibrated Plex Charts (CP)
These tables display the actual calibration results for your sensor system.
CP-001: Obfuscation Level
As MetriCal is a credit-based system, we want to make sure you have control over when credits are
consumed. By default, the calibrate command will not show results or consume credits unless you
explicitly pass the show-results flag. This
allows you to run dry runs of calibrations to see if everything looks good before committing to
spending credits on the final result.
Table CP-001 will show you the current results obfuscation behavior based on presence or absence of
the show-results flag along with the status of your calibration.
Forcing Output of Results
In the case of a failed calibration, or a calibration with high-risk data diagnostics, no results
will be shown regardless of the presence of the show-results flag. This is because MetriCal works
to prevent you from using bad calibrations at all! If you feel confident in your data collection
approach, though, just set
override-diagnostics to true to
force output of the calibration results.
CP-002: Calibrated Camera Models
This table shows the calibrated intrinsic parameters for each camera. Different models will have different interpretations; see the Camera Models page for more.
- Camera: The abbreviated component name for each camera. See DI-002 for full names.
- Frame Specification: Basic frame specifications for the camera (width, height, pixel pitch)
- Projection Model: Calibrated projection parameters (focal length, principal point)
- Distortion Model: Calibrated distortion parameters (varies by model type)
The standard deviations (±) indicate the uncertainty of each parameter.
CP-003: Calibrated IMU Models
This table presents the final IMU noise parameters and bias estimates for every IMU component after optimization. The most interesting column for most users is the Intrinsics: scale, shear, rotation, and g sensitivity.
CP-004: Calibrated Extrinsics
This table represents the Minimum Spanning Tree of all spatial constraints in the Plex. Note that this table doesn't print all spatial constraints in the plex; it just takes the "best" constraints possible that would still preserve the structure.
Rotations are printed as Euler angles, using Extrinsic XYZ convention.
- Translation (m): The X, Y, Z position of each component relative to the origin
- Diff from input (mm): How much the calibration changed from the initial values
- Rotation (°): The Roll, Pitch, Yaw rotation of each component in degrees
- Diff from input (°): How much the rotation changed from the initial values
The table also indicates which "subplex" each component belongs to (components that share spatial relationships), and reports the extrinsic posterior uncertainty for each constraint.
Conclusion
Interpreting MetriCal output charts is key to understanding your calibration quality and identifying areas for improvement. By systematically analyzing each section, you can iteratively improve your calibration process to achieve more accurate results.
Remember that calibration is both an art and a science—experimental design matters greatly, and the metrics provided by MetriCal help you quantify the quality of your calibration data and results.