Skip to main content
Version: 12.0

Releases + Changelogs

Version 12.0.0​

Release Page

MetriCal Sensor Calibration Utilities repository for v12.0.0: https://gitlab.com/tangram-vision/platform/metrical/-/releases/v12.0.0

Overview​

This release is probably one of our largest ever. There are new modes, new mathematics, and more expressivity. And as with every major version bump, we've also made some changes to the CLI arguments. Most old arguments that have changed have been deprecated, not removed, so you can still use your scripts from v11.0 (for the most part). You'll just get loud warnings about switching over before v13 comes around...

Change Your MetriCal Alias!​

First and foremost: If you're a current user, we suggest adding the --tty flag to your metrical bash alias. See an example in the setup docs. This allows MetriCal to render progress bars in the terminal, which makes it a much nicer experience when processing large datasets. Otherwise, you'll just see a blank screen for a while.

UI + UX Highlights​

Offline Licensing​

MetriCal now offers users the option to cache licenses for offline use. If you're running MetriCal "in the field" (aka away from a modem), this is the feature for you! Note that offline licenses are only valid for a week before MetriCal needs to ping a Tangram server.

Visit the licensing docs for setup and details.

Descriptive Error Messages​

We've reworked every. single. error case in MetriCal to have a descriptive error message. Instead of getting something generic, you'll now see the error, the error's cause, and a helpful suggestion on how to fix it. Many of these suggestions link directly to the documentation, so you don't have to search around for the "right answer" anymore.

Miette Is Great

For those of you developing your own Rust programs, we couldn't recommend miette enough.

Cached Detections​

Tired of re-running detections when running a new calibration? We've got you covered. MetriCal now caches its detections from the initial dataset processing. This means you can change models and test different configurations in a fraction of the processing time.

There are two ways MetriCal finds detections:

  • Passed to the CLI via the $DATA required argument. For instance, instead of passing an MCAP, one could just pass that MCAP's cached detections JSON.
  • Automatically found in the same directory as the dataset. Cached detections are written to the same directory as the dataset, named with a .detections.json extension to the dataset name. For example, /dataset/example.mcap would have a cached detections file named /dataset/example.detections.json. If MetriCal finds this file, it will use it instead of re-processing the entire dataset.
Potential Naming Conflicts

This also means that datasets with the same name will produce detection caches with the same name. We don't advise naming all of your files the same thing anyway, but... you do you.

If you have cached detections, but really want to re-process them anyway, just pass the --overwrite/-y flag to Calibrate or Evaluate mode.

Multiple Seed Plex in Init Mode​

You can now pass multiple seed plex to Init mode. This is useful in a "big rig" scenario, when it's just not feasible to collect every sensor's data in one run. For example, one might run data from 4 cameras individually, then combine them all into one system to gather extrinsics via Init mode.

When processing multiple seed plex, the newest plex is given priority, being processed for new information from newest to oldest. If there is an existing Init'd plex for the dataset, that plex is also used as a seed. This makes it even easier to compare and contrast different calibrations.

Display Mode​

Version 12.0 also introduces Display mode, which allows you to visualize the applied calibration to any dataset. This takes the place of the --render flag in Calibrate and Evaluate modes, which now just renders the detections used for calibration. Important: Display mode expects a running instance of Rerun v0.18.

Changelog​

Added​

  • CLI:
    • Change the logging level more easily with verbose flags: -v (Debug), -vv (Trace), -q (Warn), or -qq (Error).
    • Multi-progress bar to estimate observation read-in time. Make sure to add -t to a Docker alias to use this functionality!
    • Offline licensing. See the licensing docs for setup and details.
    • An OptimizationProfile argument to Calibrate mode that allows users to tune the parameters of the adjustment e.g. relative error threshold, absolute error threshold, and max iterations.
    • A binned outlier count is now reported in the camera binned reprojection table.
    • Display mode to visualize the output of a calibration.
    • A new sub-mode, metrical shape tabular which can convert a plex into a simplified, stable, tabular format that holds a set of intrinsics (and direct artefacts of the intrinsics, such as look-up tables) alongside extrinsics. The tabular format from this mode can be exported as either JSON or MsgPack binary (to compress the total filesize, as LUTs can be quite large).
    • Tables for Component Relative Extrinsics, as well as Preintegrated IMU errors. This should give you a much better idea of extrinsics quality beyond the abstract covariance values for spatial constraints.
  • Data I/O:
    • Expanded list of encodings for YUYV image types in ROS - uyvy, UYVY, yuv422, yuyv, YUYV, and yuv422_yuy2 are all supported.
      • That's gotta be all of them, right? Right? Let's all come together to make life easier for your old Tangram pals.
    • H264 message types for ROS1 (from this project) and MCAP (from Foxglove's CompressedVideo).
    • Added support to CompressedImage types for the alternate spelling for "jpg".
  • Detection and reweighting of Paired 3D Point outliers.

Changed​

  • Algorithm Changes:
    • Use new M-estimators, and remove all explicit outlier logic. No more outlier flags!
    • Paired Plane Normals between lidar-lidar pairs are no longer used
    • The motion filter has been rewritten to include both images and lidar detections. Users can manipulate the motion detector thresholds by using the --camera-motion-threshold and --lidar-motion-threshold flags, or just turn it off with --disable-motion-filter.
    • The motion filter now runs after all detections have been processed. This means that you can manipulate the motion filter over cached detections, too.
  • CLI:
    • UmbraOutput is now CalibrationOutput.
    • All error codes have been changed in favor of simpler error code and more descriptive fixes.
    • Look Up Tables generated via the metrical shape lut command are now generated using the image_luts module from the applications crate. This changes the final schema for look up tables but makes them more directly compatible with OpenCV and other software that expects both row and column remappings to be separated.
  • Init mode:
    • Init mode can now take multiple plex as seeds.
    • If a previously generated init plex is found at the same location as the plex-to-be-written, then the previous plex is used as a seed for the new plex.
    • Change of basis is respected and applied in Init mode when seeding the plex with an input plex.
  • Rendering:
    • Observations and detections are rendered in the same entity in the visualization.
    • When rendering more than one point cloud in Display mode, each component's point clouds are uniformily colored rather than colored by the point's intensity value. This allows for easier comparison between components.
    • Calibrate mode no longer renders the results of a calibration, only the observations and detections. Results are applied in Display mode.

Fixed​

  • CLI:
    • Component names with "/" no longer cause file I/O issues with the shape focus command
  • Detectors:
    • The circle detector for point clouds and the feature detector for images are now much more robust to misdetections and noise.
  • Init mode:
    • Init mode now correctly handles all (spec'd) cases in which a seed plex as the basis for a new plex.
    • Topics that are not usable by MetriCal for the purposes of calibration are now filtered out.
    • If there are no usable topics, Init mode will list the usable topics in a dataset for the user.
  • There was a (self-induced) memory pressure build-up during lidar detection that has been remedied.

Removed​

  • Init mode:
    • Preset devices have been removed from Init mode.

Version 11.0.0​

Release Page

MetriCal Sensor Calibration Utilities repository for v11.0.0: https://gitlab.com/tangram-vision/platform/metrical/-/releases/v11.0.0

Overview​

This version bump is a big one! Data processing improvements, algorithmic improvements, CLI simplification... there's a little something for everyone here. Most of the changes in 11.0.0 were made based on testing from customers in the field. Thanks, everyone!

Note that many CLI arguments have been shifted or removed. Be sure to check the changelog and updated documentation to make sure your settings remain.

Changelog​

Added​

  • Visualization improvements:
    • Render navigation states and IMU data by default.
    • Render all observations when log level is set to debug.
  • Change of Basis tooling:
    • Add --topic-to-observation-basis global argument to all modes in order to map a coordinate basis to each component's observations on plex construction (docs).
    • Add --topic-to-component-basis global argument to all modes in order to map a coordinate basis to each component on plex construction (docs).
    • Changed-basis plex is now included in MetriCal output (docs).

Changed​

  • Init mode only looks through the first 100 observations to create the initial plex; this should greatly speed up Init mode for most datasets.
  • All observations are now run through their respective detectors before image motion filtering occurs.
  • The motion filter acts on the image detections themselves, not the entire image. This should improve the quality of the motion filter in busy, "noisy" datasets (docs).
  • A user-specified root is now required to generate the URDF from a plex in Shape mode (docs).
  • Reformulate IMU calibration approach:
    • Remove unnecessary IMU initialization.
    • Implement improvements to IMU optimization mathematics.
    • Only one IMU bias is inferred during calibration instead of a wandering bias.
  • Shape mode arguments now follow the order metrical shape [mode] [arguments] [plex] [output] (docs).
  • license and report-path arguments are now global arguments, and can be passed to any mode (docs).
  • Lower the minimum required points to fit a circle detector.

Fixed​

  • Init mode now properly handles differences in the seeded plex (passed through with -p) and the created plex. This has been a bug for longer than we care to admit; we're glad it's fixed (docs)!
  • Observations are no longer held in memory while motion filtering occurs. This greatly reduces memory usage on LiDAR-heavy datasets.

Removed​

  • Caching of detections and filtered output is no longer supported in Calibrate and Evaluate modes.

Version 10.0.0 (Yanked)​

Yanked!

This release was yanked due to a critical bug introduced in Init mode that wasn't caught in time. The odds of many users running into this bug were low, but we played it safe and yanked this version entirely.

All relevant changes will be added to the changelog for 11.0.0.

Version 9.0.0​

Release Page

MetriCal Sensor Calibration Utilities repository for v9.0.0: https://gitlab.com/tangram-vision/platform/metrical/-/releases/v9.0.0

Overview​

Version 9.0.0 can be considered a refinement of v8.0, with focus on improving the user experience and clarifying outputs. It also introduces a few new intrinsics models across components. Some default behavior has changed as well, so be sure to check the changelog for details.

This release also includes a big update to rendering. Be sure to update your Rerun version to v0.14!

Changelog​

Added​

  • Introduced LidarSummary summary statistics to report lidar-specific metrics (docs).
  • Support for new IMU intrinsics: Scale, Shear, Rotation, and G-Sensitivity (docs).
  • Support for the Omnidirectional camera model (docs).

Changed​

  • MetriCal now uses Rerun v0.14! 🎊 Make sure to update your version of Rerun accordingly.
  • The summary statistics table is now three tables, for optimization, cameras, and lidar respectively (docs).
  • PerComponentRMSE in Summary Statistics is now CameraSummary (docs).
  • Circle detector's detect_interior_points option is now a mandatory variable, and has no default value (docs).
  • Circle detector now takes an x_offset and y_offset variable to describe the center of the circle w.r.t. the full board frame (docs).
  • Object relative extrinsics (OREs) are now generated by default. In turn, the --enable-ore-inference flag has been removed and replaced with --disable-ore-inference (docs).
  • The camera component initialization process during calibration has been improved to better handle significant distortion.

Fixed​

  • Rerun rendering code has been completely refactored for user clarity and speed of execution.
    • Lidar-lidar datasets are now rendered and registered along with camera-lidar.
    • Object relative extrinsics are now rendered when available.
    • Images now use lookup tables properly for quick correction.
    • Spaces have been reorganized for clarity and ease of use.
  • Datasets without cameras no longer print empty camera tables.

Version 8.0.1​

Release Page

MetriCal Sensor Calibration Utilities repository for v8.0.1: https://gitlab.com/tangram-vision/platform/metrical/-/releases/v8.0.1

Overview​

This version fixes a small bug found in pipeline license validation.

Changelog​

Fixed​

  • null license values in a pipeline configuration are discarded, not interpreted as a provided license key.

Version 8.0.0​

Release Page

MetriCal Sensor Calibration Utilities repository for v8.0.0: https://gitlab.com/tangram-vision/platform/metrical/-/releases/v8.0.0

Overview​

This release brings a ton of new features to the MetriCal CLI, most of them focused on improving the user experience. The biggest difference is one you won't see: all of the math done during optimization is now fully sparse, which means it takes a lot less memory to run a calibration. And smart convergence criteria means that calibrations are faster, too!

We've also added a new mode, pipeline, which allows you to run a series of commands in serial. Find out more about it in the Pipeline Mode section of the documentation.

Changelog​

Added​

  • Pipeline mode. This executes a series of Commands in serial, as they're written in a pipeline JSON file.
  • Render the optimized plex at the end of a calibration.
  • The subplex ID for a spatial constraint now shows up in the Extrinsics table.
  • Input JSON files with comments are now accepted as valid.

Changed​

  • All calibrations now undergo outlier detection and reweighting as part of the BA process. Outliers are detected for cameras, lidar, and relative extrinsics.
  • Summary table is sorted by component name, not by UUID.
  • Summary statistics in console are now computed using a weighted RMSE.
  • The bundle adjustment is now a fully sparse operation, relieving memory pressure on larger datasets.

Fixed​

  • The height of the sync group chart now adjusts with the number of components present in the dataset.
  • Bug in Init mode when using a RealSense435Imu preset.
  • All stereo pairs are now derived and graphed in console output

Removed​

  • The --metrics-with-outliers flag and the --outlier-filter flag have been removed.

Version 7.0.1​

Release Page

MetriCal Sensor Calibration Utilities for v7.0.1: https://gitlab.com/tangram-vision/platform/metrical/-/releases/v7.0.1

Overview​

This patch release fixes various errata found in the v7.0.0 release.

Changelog​

Fixed​

  • Rendering the correction at the end of a calibration actually uses the corrected plex (rather than the input plex).
  • The extrinsics table now only shows delta values if an input plex is provided.
  • Camera-lidar extrinsics rendering in Rerun now takes the spatial constraint with the minimum covariance. This is different from the previous behavior where all spatial constraints were rendered, regardless of quality.

Version 7.0.0​

Release Page

MetriCal Sensor Calibration Utilities for v7.0.0: https://gitlab.com/tangram-vision/platform/metrical/-/releases/v7.0.0

Overview​

Welcome, v7.0.0! Yes, merely a week after v6.0.0, we bump major versions. Classic.

Revised Documentation​

It's finally here! The revised Tangram Vision documentation site is live: https://docs.tangramvision.com/.

This documentation site holds readmes and tutorials on all of Tangram Vision's products. The MetriCal section is fully-featured, and based on this release. We will be maintaining all documentation for this and newer versions on the official docs site from here on out.

LiDAR-LiDAR Calibration​

MetriCal now supports LiDAR-LiDAR calibration, no cameras needed. Users will need a circular markerboard to calibrate LiDAR.

New Modes - pretty-print and evaluate​

v7.0.0 introduces two new modes:

The Calibrate mode, by extension, no longer has an --evaluate flag. This is just Evaluate mode.

Revamped Rendering options + Deprecated Review mode​

Review mode is no longer! Instead, passing the --render flag to either Calibrate or Evaluate mode will render the corrected calibration at the end of the run. Also, --render and --render-socket options are no longer global. Instead, they are only applicable for Calibrate and Evaluate modes.

Changelog​

Added​

  • Support for calibrating multi-LiDAR, no-camera datasets. This still leverages MetriCal's circle target, but no longer requires a camera or any image topics to be present in order to calibrate.
  • Pretty Print mode for printing out a plex in a human readable format.
  • Evaluate mode to evaluate the quality of a calibration on a test dataset. This is a reinterpretation of the --evaluate flag that was in the Calibrate mode; it's just been given its own command for ease of use.
  • A verbose flag to the shape mode to print the plex that has been created from the command.
  • Additional descriptions to errors that can be generated by calling the calibrate mode.

Changed​

  • Calibrate + Evaluate mode now renders its own corrections (rather than punting that capability to review).
  • The --render flag at the global level has been moved to the Calibrate & Evaluate modes.

Removed​

  • Review mode and README mode have been removed completely. Review mode's previous functionality is now split between Pretty Print mode and Calibrate mode.
  • The --evaluate flag in Calibrate mode.

Fixed​

  • Summary statistics tables now have the correct units displayed alongside their quantities.
  • Printing the results of a plex with no extrinsics will now print an empty table, rather than nothing at all.
  • Nominal extrinsics deltas in tables are now represented by the string "--".

Errata​

  • The "corrected" rendering at the end of a calibration run mistakenly uses the input plex, not the output plex. Scheduled fix: v7.0.1.
  • The output extrinsics table does not correctly calculate the delta between the input and output plex. Scheduled fix: v7.0.1.
  • Rendering the corrected camera-lidar registration would take the first spatial constraints available, rather than taking the constraint with the minimum covariance. This often makes calibrations appear wildly incorrect, despite a good calibration. Scheduled fix: v7.0.1.