When it comes to using your Apriltag, ROS is one of the easiest ways to get started. ROS is a software framework that allows developers to create robots with ease. It features message passing, logging, visualisation, compiling, and numerous opensource packages. Specifically, it has a package for detecting Apriltags and placing them in 3D space.
AprilTag ROS
I am not going to make this a full blown tutorial on how to use the AprilTag ROS package because you can find that information here. But I will go into more detail on some of the more confusing parts of the setup.
How it works
The Apriltag ROS package takes in a rectified camera feed and returns a list of detected tags and their 3D locations. In order for this to work the software needs to know what tags it is looking for and how large they are. These are defined in 2 config files: config/settings.yaml and config/tags.yaml.
config/settings.yaml
This file configures the detection algorithm. See a sample configuration below
tag_family: 'tag36h11' # Tag family tag_border: 1 # Size (in bits) of the black border. Always 1 if made by optitag tag_threads: 2 # Number of detection thread. Tune per your CPU tag_decimate: 1.0 # Reduce the resolution of the image by this number. Increases speed at the sacrifice of detecting smaller tags tag_blur: 0.0 # tag_blur>0 blurs the image and tag_blur<0 sharpens the image
tag_refine_edges: 1 # improves edge detection and therefore improves pose estimation. Light computation
tag_refine_decode: 0 # reduces false negative detection rate. Medium computation
tag_refine_pose: 0 # improves pose estimation accuracy. Heavy computation
tag_debug: 0 # save debug images to ~/.ros Careful if running with video
publish_tf: true # publish tag/bundle poses to /tf topic
config/tags.yaml
This file tells the algorithm what tags to look for in the environment and how large they are so they can be placed in 3D space. The software assumes distance measurements are in meters and orientation is in quaternions.
standalone_tags:
[
{id: 10, size: 0.15},
{id: 20, size: 0.1},
{id: 30, size: 0.07}
]
tag_bundles:
[
{
name: 'my_bundle',
layout:
[
{id: 0, size: 0.05, x: 0.0000, y: 0.0000, z: 0.0, qw: 1.0, qx: 0.0, qy: 0.0, qz: 0.0},
{id: 4, size: 0.05, x: 0.0548, y: -0.0522, z: 0.0, qw: 1.0, qx: 0.0, qy: 0.0, qz: 0.0},
{id: 3, size: 0.05, x: -0.0580, y: -0.0553, z: 0.0, qw: 1.0, qx: 0.0, qy: 0.0, qz: 0.0},
{id: 2, size: 0.05, x: 0.0543, y: 0.0603, z: 0.0, qw: 1.0, qx: 0.0, qy: 0.0, qz: 0.0},
{id: 1, size: 0.05, x: -0.0582, y: 0.0573, z: 0.0, qw: 1.0, qx: 0.0, qy: 0.0, qz: 0.0}
]
}
]
There are 2 lists standalone_tags and tag_bundles. If you ordered from Optitag you likely will be using standalone tags. See Bundles section for more info on tag bundles. For standalone tags you provide an ID and size for each tag you want to detect. If you ordered from Optitag this information is inscribed at the base of the tag. If you didn't order through Optitag see Measuring Tag Size section.
You may have noticed that we don't specify the tag family in this file. That is because we specified it in the last file config/settings.yaml. The detector can only detect one tag family at a time so be sure that all your tags are the same tag family, otherwise you'll have to run multiple detectors.
Some important things to remember:
- No tag ID should appear twice with different sizes (this creates ambiguity in the detection);
- No tag ID should appear twice in the image (this creates ambiguity in the detection)
- It is fine for a tag with the same ID to be listed both in standalone_tags and in tag_bundles, as long as it has the same size.
Measuring Tag Size
When entering the size of your tag for pose estimation it is important to know what "size" is actually a measure of. The measurement that is called "size" is shown as "edge length" in the image below.
Bundles
Bundles are a special feature in the Apriltag ROS package the allows the software to detect multiple tags as a group. Upon detection of a single or multiple tags in the bundle, the software will report the 6 DOF pose of the bundle's origin. This is useful if you have a multifaceted surface, like a cube, and you want to track the cube and not 6 individual tags. Another benefit of bundles is redundancy. You don't need to detect all of the tags on bundle to place the bundle in 3D space. So if one tag has poor lighting or an extreme angle of inclination then another one can get detected and the object can still be tracked. The final and most compelling reason the use bundles is the improved accuracy. If you have a single tag, the pose is calculated using the 4 corners of the tag. With n number of tags the pose gets calculated using 4n number of point which should improve the pose estimate.
When you create a bundle you specify a list of tags. Each tag has a tag ID, size, and 6 DOF location of the tag in reference to the bundle's origin.
Currently, Optitag doesn't create bundled tags, but that doesn't mean you can't purchase multiple tags and create your own bundles. Just be careful when measuring the relative locations of your tags in the bundle. You can also calibrate your bundle to find the relative locations of tags without direct measurement.
Limitations
At the time of writing this article AprilTag ROS only supports AprilTag 2 families. That means 16h5, 25h9, and 36h11. They may add support for AprilTag 3 in the future. but I am unaware of that development. You can detect AprilTag 3 tags using OpenCV. Tutorial on it's way!
The accuracy of your cameras intrinsic calibration will influence the detectors ability to accurately calculate the distance to the target. So be sure your cameras are well calibrated before attempting to place Apriltags in 3D space. Lucky for you we sell calibration targets!
The accuracy of your bundle calibration/measurement will directly correlate to the quality of your bundle pose estimation, so don't skimp out on this part.
Additional Reading
If you want to learn more about how Apriltags work checkout our other blog posts or see References.
If there is something else you want to see covered leave a comment below.
References
- http://wiki.ros.org/apriltag_ros
- http://wiki.ros.org/apriltag_ros/Tutorials/Detection%20in%20a%20video%20stream
- http://wiki.ros.org/apriltag_ros/Tutorials/Bundle%20calibration