Using Multiple Fiducials

Fiducials

Find examples for multiple fiducial JSON in the MetriCal Sensor Calibration Utilities repository on GitLab.

MetriCal is designed to work with multiple fiducials. It doesn't require a surveyed room or exacting measurements; just a few fiducials in the field of view of each sensor will do. The most confusing part is just telling MetriCal which fiducials you're using!

Constructing the Object Space

Generating UUIDs

Each fiducial should be assigned a different UUID (v4); this is how MetriCal keeps track of them, similar to how it tracks components. If you're writing your own object space file, you can generate a valid UUID using a site like UUID Generator or, if you're on Linux, using the uuid command:

$ sudo apt install uuid
$ uuid -v4
b5e4183c-d1ae-11ee-91e7-afd8bef1d15c # <--- a valid UUID

Format

Below, we have an example of a JSON object that describes two markerboards, elegantly named 24e6df7b-b756-4b9c-a719-660d45d796bf and 7324938d-de4e-4d36-a25b-fbd8e6102026:

{
    "object_spaces": {
        "24e6df7b-b756-4b9c-a719-660d45d796bf": {
            "descriptor": {
                "variances": [0.00004, 0.00004, 0.0004]
            },
            "detector": {
                "markerboard": {
                    "checker_length": 0.1524,
                    "corner_height": 5,
                    "corner_width": 13,
                    "marker_dictionary": "Aruco4x4_1000",
                    "marker_id_offset": 0,
                    "marker_length": 0.1
                }
            }
        },
        "7324938d-de4e-4d36-a25b-fbd8e6102026": {
            "descriptor": {
                "variances": [0.00004, 0.00004, 0.0004]
            },
            "detector": {
                "markerboard": {
                    "checker_length": 0.1524,
                    "corner_height": 5,
                    "corner_width": 13,
                    "marker_dictionary": "Aruco4x4_1000",
                    "marker_id_offset": 50,
                    "marker_length": 0.1
                }
            }
        }
    }
}

Differentiating Fiducials

Careful observers will note that each fiducial in the example above has a different marker_id_offset. This indicates the lowest tag ID on the fiducial, with the rest of the tags increasing sequentially. There should be no overlap in tag IDs between fiducials; all tags should be unique. If this assumption is violated, horrible things will happen... mainly, your calibration results may make absolutely no sense.

This goes for different dictionaries as well. Counterintuitively, users have reported misdetections when using aruco markers with different dictionaries, but identical IDs.

Bottom line: make sure that all of your fiducials have unique IDs, no matter what dictionary they use.

Object Relative Extrinsics (OREs)

Since MetriCal runs a full optimization over all components and object spaces, it naturally derives extrinsics between everything as well. You'll find that the spatial_constraints field in the JSON will be populated with the extrinsics between all fiducials post-calibration.

Just like any other data source, more object spaces mean more OREs; more OREs will add time to the optimization. It's just more to solve for! If you're not interested in surveying the extrinsics between object spaces, and are just worried about the component-side calibration, we recommend setting --disable-ore-inference:

metrical calibrate --disable-ore-inference ...

It's important to note that this flag's setting shouldn't dramatically change the component-side calibration. The only meaningful difference is that your results will report spatial constraints for all objects and components.

Mutual Construction Groups

Some fiducials are designed to be used together. For example, our LiDAR circle target is a single piece of hardware, but to MetriCal, it's actually two fiducials: a markerboard and a circle. We indicate this by assigning them to the same mutual construction group:

{
    // The markerboard and circle fiducials
    "object_spaces": {
        "24e6df7b-b756-4b9c-a719-660d45d796bf": {
            ...
            "detector": {
                "markerboard": {
                    ...
                }
            }
        },
        "34e6df7b-b756-4b9c-a719-660d45d796bf": {
            ...
            "detector": {
                "circle": {
                    ...
                }
            }
        }
    },
    // Our mutual construction group, indicating these are one and the same
    "mutual_construction_groups": [
        ["24e6df7b-b756-4b9c-a719-660d45d796bf", "34e6df7b-b756-4b9c-a719-660d45d796bf"]
    ]
}

Currently, our LiDAR board is the only fiducial that uses this feature, but it's a good example of how MetriCal is designed to be extensible and future-proof.