AprilTag
More actions
| AprilTag | |
|---|---|
| Information | |
| Type | Fiducial marker system |
| Industry | Robotics, computer vision, augmented reality |
| Developer | APRIL Robotics Laboratory, University of Michigan (Edwin Olson) |
| Written In | C (AprilTag 2 and AprilTag 3); Java (original implementation) |
| Operating System | Linux (officially supported) |
| License | BSD 2-Clause License |
| Release Date | 2011 |
| Website | https://april.eecs.umich.edu/software/apriltag |
AprilTag is an open-source visual fiducial system developed by Edwin Olson's APRIL Robotics Laboratory at the University of Michigan. It consists of printable square black-and-white tags that carry a small binary code, and detection software that finds the tags in a camera image and computes the precise 3D position, orientation and identity of each tag relative to the camera.[1] Olson introduced the system in a paper at the 2011 IEEE International Conference on Robotics and Automation (ICRA); it was followed by a redesigned detector, AprilTag 2, in 2016 and by AprilTag 3, which added flexible tag layouts, in 2019.[2][3][4]
AprilTag belongs to the same family of square, binary-coded markers as ARToolKit and ARTag, which were built for augmented reality. The lab describes AprilTag as useful for "augmented reality, robotics, and camera calibration", and the project README calls it "popular in robotics research".[1][5] In XR, its tag dictionaries are supported by the marker tracking features of the Magic Leap 2 and by a Magic Leap extension to OpenXR, and the AprilTag 2 paper shows the tags being used to test virtual reality headsets at Valve.[6][7][3] The current code is maintained on GitHub as the C library AprilTag 3 under a BSD 2-Clause license.[5][8]
History
Original system (2011)
Olson's 2011 paper presented AprilTag as "a new visual fiducial system that uses a 2D bar code style 'tag', allowing full 6 DOF localization of features from a single image". He wrote that it improved on earlier systems with "a fast and robust line detection system, a stronger digital coding system, and greater robustness to occlusion, warping, and lens distortion", and that while it was "similar in concept to the ARTag system", the method was "fully open and the algorithms are documented in detail".[2] The paper noted that visual fiducial systems are "perhaps best known for their application to augmented reality", which had produced ARToolKit and ARTag, and that robotics uses such as ground truthing and benchmarking of SLAM algorithms had led to further tag systems.[2]
In contrast to ARTag and Studierstube Tracker, whose closed nature Olson said "was a challenge" for his experimental evaluation, AprilTag was released under an open source license, and he also made the evaluation code available. The 2011 implementation was written in Java and ran at 30 frames per second on VGA-resolution images on a 2.6 GHz Intel Core2 CPU, with a C port in progress.[2]
AprilTag 2 (2016)
In 2016 John Wang and Olson published AprilTag 2, "a completely redesigned tag detector" that kept the original tag coding scheme unchanged. The authors wrote that user feedback showed that detecting tags with partly hidden borders was "of limited utility" in most deployments, because users generally rejected tags with bit errors anyway, so the new detector traded the ability to recover partially occluded tag borders for faster detection.[3] The paper stated that the improvements made robust tag detection practical on smartphones, and that a free AprilTag detector app was available on the iPhone App Store.[3] The lab's iOS app can send tag detections over UDP to another computer, and the earlier Java implementation is now deprecated in favor of the C library, which can be called from Java through JNI.[1]
AprilTag 3 (2019 to present)
AprilTag 3 was described in "Flexible Layouts for Fiducial Tags" by Maximilian Krogius, Acshi Haggenmiller and Olson at IROS 2019. It lets the data bits of a tag be arranged in user-defined shapes, including circular tags, tags with data bits outside the detection border, and tags with an empty center into which a smaller tag can be nested. The paper also introduced a faster detector that, according to the authors, had higher recall than both the AprilTag 2 and ArUco detectors while maintaining precision.[4] The project README describes AprilTag 3 as including "a faster (>2x) detector, improved detection rate on small tags, flexible tag layouts, and pose estimation".[5]
The AprilRobotics GitHub repository was created in September 2018, and the earliest release listed on its Releases page, v3.0.0, is dated 5 April 2019.[9][10] As of 15 October 2026 the latest tagged release is v3.4.5, published on 29 August 2025.[11] In May 2026 the main branch merged native support for ArUco marker dictionaries (4x4 to 7x7 and ArUcoMIP36h12), which the pull request describes as letting users detect ArUco markers with the AprilTag 3 detector; the README now lists these as natively integrated families.[12][5]
| Version | Date | Notes |
|---|---|---|
| AprilTag (original) | May 2011 | ICRA paper; lexicode-based coding system and gradient-based detector, Java implementation[2] |
| AprilTag 2 | October 2016 | IROS paper; redesigned detector with adaptive thresholding and decimated input, same tag codes[3] |
| AprilTag 3 (v3.0.0) | 5 April 2019 | Earliest release listed on GitHub[9] |
| AprilTag 3 | November 2019 | IROS paper on flexible tag layouts and a faster detector[4] |
| v3.2.0 | 4 February 2022 | Fixed a memory leak, restored the 36h10 family, switched examples to OpenCV 4[9] |
| v3.4.0 | 10 March 2024 | Breaking changes: unused parameters removed, Python module install path changed, Makefile dropped in favor of CMake[9] |
| v3.4.5 | 29 August 2025 | Latest tagged release as of October 2026[11] |
How it works
Detection
The original detector computed the gradient direction and magnitude at every pixel, clustered pixels with similar gradients using a graph-based method, and fitted line segments to each cluster. It then searched for chains of four segments that formed a quadrilateral ("quad") with a darker interior. The search was tuned for a very low false negative rate, leaving the coding system to reject the many false candidate quads.[2] AprilTag 2 replaced this with an adaptive threshold that turns the image into black and white regions, a union-find segmentation of those regions, and quad fitting along the boundaries between black and white components. Candidate codes within two bit errors of a valid tag are precomputed in a hash table, so decoding takes constant time per candidate.[3] AprilTag 3 kept the same high-level pipeline but changed decimation to point sampling, reduced union-find calls, sped up quad fitting, and used bilinear interpolation with a sharpening filter when reading the bits of very small tags.[4]
Coding system
AprilTag codes are generated with a modified lexicode. A family is named by its number of data bits and its minimum Hamming distance, so a 36-bit code with a minimum distance of 10 is a "36h10" code. The generator guarantees the minimum Hamming distance for all four 90-degree rotations of every tag, and it rejects codewords that form simple geometric patterns, measured by the number of rectangles needed to draw the tag, because such patterns are more likely to occur by chance in natural scenes.[2] AprilTag 3 replaced this rectangle-based measure for its new layouts with one based on the Ising model energy of the rendered tag, chosen after testing three candidate complexity metrics.[4] The lab notes that the tags carry much smaller payloads than QR codes, between 4 and 12 bits, which lets them be detected more robustly and from longer distances.[1]
Pose estimation
Once the four corners of a tag are found, the detector computes a homography between the tag and the image. With the camera's focal length and the tag's physical size, this gives the tag's position and orientation relative to the camera, that is, a full six degrees of freedom pose from a single image.[2] The AprilTag 3 library includes a pose estimation function that takes the tag size in meters and the camera's focal lengths and optical center in pixels; the README also suggests OpenCV's Perspective-n-Point solver with the SOLVEPNP_IPPE_SQUARE method as an alternative.[5]
Tag families
The repository ships several pre-generated families. The README recommends tagStandard41h12 "for the vast majority of applications".[5] The code counts below are taken from the family source files in the repository.[13]
| Family | Data bits | Minimum Hamming distance | Codes | Notes |
|---|---|---|---|---|
| tag16h5 | 16 | 5 | 30 | Classic layout[13] |
| tag25h9 | 25 | 9 | 35 | Classic layout[13] |
| tag36h10 | 36 | 10 | 2320 | Classic layout; restored in v3.2.0[13][9] |
| tag36h11 | 36 | 11 | 587 | Classic layout[13] |
| tagStandard41h12 | 41 | 12 | 2115 | Recommended default; data bits outside the border[13][5] |
| tagStandard52h13 | 52 | 13 | 48714 | For applications that need more tags[13][5] |
| tagCircle21h7 | 21 | 7 | 38 | Circular layout for small round objects[13][5] |
| tagCircle49h12 | 49 | 12 | 65535 | Circular layout[13][5] |
| tagCustom48h12 | 48 | 12 | 42211 | Empty center for nested (recursive) tags[13][5] |
Krogius and colleagues named the newer layout with a ring of data bits outside the border "uramaki" and the classic layout "maki", after the placement of rice and seaweed in sushi rolls.[4] The tag images for each family are published in a separate apriltag-imgs repository, and new families can be generated with the apriltag-generation tools.[5]
Software and integrations
AprilTag 3 is a small C library with no external dependencies. It is officially supported only on Linux, although the README says users have also installed it on Windows. A Python wrapper is built when Python 3 is present, and third-party bindings exist for MATLAB, Julia and a WebAssembly build for web browsers.[5] The library has no image acquisition of its own; the repository includes an example that passes OpenCV image data to the detector.[5] The apriltag package is listed in the ROS index for the ROS 2 Humble, Jazzy, Kilted, Lyrical and Rolling distributions.[14]
OpenCV's ArUco module also detects AprilTag markers. Its predefined dictionaries include DICT_APRILTAG_16h5, DICT_APRILTAG_25h9, DICT_APRILTAG_36h10 and DICT_APRILTAG_36h11, and it offers a CORNER_REFINE_APRILTAG option that the source describes as "Tag and corners detection based on the AprilTag 2 approach".[15][16]
Use in VR and AR
Olson's 2011 paper describes how real-world objects can be augmented with visual fiducials so that virtually generated imagery is superimposed on them.[2] Wang and Olson note that fiducials of this kind "were first developed and popularized by augmented reality applications" before being widely adopted in robotics.[3]
Magic Leap's developer documentation for the Magic Leap 2 states that its Marker Tracking API can track QR codes, AprilTags and ArUco markers. It lists AprilTag among the marker types that return a 3D pose, gives DICT_APRILTAG_36h11 as an example dictionary, and says the tracker supports up to 16 markers, with identical AprilTags colliding instead of being reported separately.[6] Magic Leap's Unity documentation for the OpenXR-based Marker Understanding feature uses AprilTag as one of its marker types and says the feature can estimate the size of ArUco, AprilTag and QR code markers.[17] The underlying OpenXR extension, XR_ML_marker_understanding (registered extension number 139), defines an XrMarkerAprilTagDictML enumeration covering the 16h5, 25h9, 36h10 and 36h11 dictionaries.[7][18]
The AprilTag 2 paper's figure of applications and users includes "testing of virtual reality headsets at Valve".[3] The paper does not describe that testing further.
Other applications
The same figure in the AprilTag 2 paper shows robot-to-robot localization and identification on robots built for the MAGIC robotics competition, object localization for Boston Dynamics' Atlas robot, and the tracking of individual ants in a study of their social organization.[3] The 2019 paper lists uses including tracking bees and small circular robots, ground truth for robotic arms, camera and lidar calibration, UAVs tracking cars, and tracking construction materials, and it demonstrates a quadrotor landing on a pad marked with nested tags.[4] The lab also names camera calibration, through its AprilCal tool (IROS 2013), as one useful application.[1]
In the FIRST Robotics Competition, FIRST began placing AprilTags at known poses around the field in 2023, and has used the 36h11 family since 2024, according to the WPILib documentation.[19]
Research and evaluation
In the 2011 paper, Olson tested false positives on 180,829 images from the LabelMe dataset, none of which contained a tag. ARToolKitPlus's BCH code produced the most false positives, followed by ARTag, and his 36h10 code, generated with a minimum complexity of 10, performed better than both. In ray-traced images with known ground truth, the AprilTag detector worked reliably to 50 m, while the ARToolKitPlus detector's detection rate fell below 50% at about 25 m.[2] The same paper showed the coding trade-off: a 36h15 code gave a far lower false positive rate but had only 27 distinguishable codewords, against 2,221 for the 36h10 code generated in that work.[2]
Wang and Olson reported that on 421,049 LabelMe images, using tag36h11 with up to two bit errors corrected, the AprilTag 2 detector produced 6 false detections against 145 for the original detector. Running single-threaded on an Intel Xeon E5-2640 at 2.5 GHz, the new detector averaged about 78 ms for a 640 x 480 image versus 115 ms for the old one, and about 22 ms with the input decimated by a factor of two. The authors stressed that these absolute times are meaningful only relative to each other.[3]
An independent comparison by Artur Sagitov and colleagues from Kazan Federal University and Shanghai Jiao Tong University, presented at ICINCO 2017, tested ARTag, AprilTag and CALTag markers with a common web camera. They found that ARTag and AprilTag were both highly sensitive to occlusion of the marker edges. AprilTag was more sensitive than ARTag when only the interior was covered, but it detected reliably under rotation around the normal and lateral axes in all one hundred trials, where ARTag was vulnerable to rotation. Overall, the authors concluded that CALTag performed significantly better than both ARTag and AprilTag in their tests.[20]
See also
References
- ↑ 1.0 1.1 1.2 1.3 1.4 "AprilTag". APRIL Robotics Laboratory, University of Michigan. https://april.eecs.umich.edu/software/apriltag. Retrieved 2026-10-15.
- ↑ 2.00 2.01 2.02 2.03 2.04 2.05 2.06 2.07 2.08 2.09 2.10 Edwin Olson (2011-05). "AprilTag: A robust and flexible visual fiducial system". 2011 IEEE International Conference on Robotics and Automation (ICRA), pp. 3400-3407. doi:10.1109/ICRA.2011.5979561. https://april.eecs.umich.edu/pdfs/olson2011a.pdf. Retrieved 2026-10-15.
- ↑ 3.00 3.01 3.02 3.03 3.04 3.05 3.06 3.07 3.08 3.09 John Wang, Edwin Olson (2016-10). "AprilTag 2: Efficient and robust fiducial detection". 2016 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), pp. 4193-4198. doi:10.1109/IROS.2016.7759617. https://april.eecs.umich.edu/pdfs/wang2016iros.pdf. Retrieved 2026-10-15.
- ↑ 4.0 4.1 4.2 4.3 4.4 4.5 4.6 Maximilian Krogius, Acshi Haggenmiller, Edwin Olson (2019-11). "Flexible Layouts for Fiducial Tags". 2019 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), pp. 1898-1903. doi:10.1109/IROS40897.2019.8967787. https://april.eecs.umich.edu/media/pdfs/krogius2019iros.pdf. Retrieved 2026-10-15.
- ↑ 5.00 5.01 5.02 5.03 5.04 5.05 5.06 5.07 5.08 5.09 5.10 5.11 5.12 5.13 "AprilTag 3 (README)". GitHub. AprilRobotics. https://github.com/AprilRobotics/apriltag. Retrieved 2026-10-15.
- ↑ 6.0 6.1 "Marker Tracking". Magic Leap Developer Documentation. Magic Leap. https://developer-docs.magicleap.cloud/docs/guides/features/marker-tracking/. Retrieved 2026-10-15.
- ↑ 7.0 7.1 "XrMarkerAprilTagDictML(3) Manual Page". OpenXR 1.1 Specification (version 1.1.63). The Khronos Group. https://registry.khronos.org/OpenXR/specs/1.1/man/html/XrMarkerAprilTagDictML.html. Retrieved 2026-10-15.
- ↑ "LICENSE.md". GitHub. AprilRobotics. https://github.com/AprilRobotics/apriltag/blob/master/LICENSE.md. Retrieved 2026-10-15.
- ↑ 9.0 9.1 9.2 9.3 9.4 "Releases - AprilRobotics/apriltag". GitHub. AprilRobotics. https://github.com/AprilRobotics/apriltag/releases. Retrieved 2026-10-15.
- ↑ "AprilRobotics/apriltag repository metadata". GitHub REST API. GitHub. https://api.github.com/repos/AprilRobotics/apriltag. Retrieved 2026-10-15.
- ↑ 11.0 11.1 "v3.4.5". GitHub. AprilRobotics. 2025-08-29. https://github.com/AprilRobotics/apriltag/releases/tag/v3.4.5. Retrieved 2026-10-15.
- ↑ "Add ArUco families support (pull request #436)". GitHub. AprilRobotics. 2026-05-07. https://github.com/AprilRobotics/apriltag/pull/436. Retrieved 2026-10-15.
- ↑ 13.00 13.01 13.02 13.03 13.04 13.05 13.06 13.07 13.08 13.09 "AprilRobotics/apriltag source tree (tag family files)". GitHub. AprilRobotics. https://github.com/AprilRobotics/apriltag/tree/master. Retrieved 2026-10-15.
- ↑ "apriltag package". ROS Index. https://index.ros.org/p/apriltag/. Retrieved 2026-10-15.
- ↑ "aruco_dictionary.hpp". GitHub. OpenCV. https://github.com/opencv/opencv/blob/4.x/modules/objdetect/include/opencv2/objdetect/aruco_dictionary.hpp. Retrieved 2026-10-15.
- ↑ "aruco_detector.hpp". GitHub. OpenCV. https://github.com/opencv/opencv/blob/4.x/modules/objdetect/include/opencv2/objdetect/aruco_detector.hpp. Retrieved 2026-10-15.
- ↑ "Marker Understanding API Overview". Magic Leap Developer Documentation. Magic Leap. https://developer-docs.magicleap.cloud/docs/guides/unity-openxr/marker-understanding/unity-marker-understanding-api/. Retrieved 2026-10-15.
- ↑ "XR_ML_marker_understanding(3) Manual Page". OpenXR 1.1 Specification (version 1.1.63). The Khronos Group. https://registry.khronos.org/OpenXR/specs/1.1/man/html/XR_ML_marker_understanding.html. Retrieved 2026-10-15.
- ↑ "What Are AprilTags?". WPILib Documentation. WPILib. https://docs.wpilib.org/en/stable/docs/software/vision-processing/apriltag/apriltag-intro.html. Retrieved 2026-10-15.
- ↑ Artur Sagitov, Ksenia Shabalina, Leysan Sabirova, Hongbing Li, Evgeni Magid (2017). "ARTag, AprilTag and CALTag Fiducial Marker Systems: Comparison in a Presence of Partial Marker Occlusion and Rotation". Proceedings of the 14th International Conference on Informatics in Control, Automation and Robotics (ICINCO 2017), vol. 2, pp. 182-191. doi:10.5220/0006478901820191. https://www.scitepress.org/papers/2017/64789/64789.pdf. Retrieved 2026-10-15.