AprilTag 3

AprilTag is a visual fiducial system popular in robotics research. This repository contains the most recent version of AprilTag, AprilTag 3, which includes a faster (>2x) detector, improved detection rate on small tags, flexible tag layouts, and pose estimation. AprilTag consists of a small C library with minimal dependencies.

You can find tag images for the pre-generated layouts here. We recommend using the tagStandard41h12 layout.

Table of Contents

• Papers
• Install
• Usage
  • Choosing a Tag Family
  • Getting Started with the Detector
    • Python
    • C
    • Matlab
    • Julia
  • Upgrading from AprilTag 2
  • OpenCV Integration
  • Tuning the Detector Parameters
    • Increasing speed.
    • Increasing detection distance.
  • Pose Estimation.
• Debugging
• Flexible Layouts
• Support

Papers

AprilTag is the subject of the following papers.

AprilTag: A robust and flexible visual fiducial system

AprilTag 2: Efficient and robust fiducial detection

Flexible Layouts for Fiducial Tags

Install

Officially only Linux operating systems are supported, although users have had success installing on Windows too.

The default installation will place headers in /usr/local/include and shared library in /usr/local/lib. It also installs a pkg-config script into /usr/local/lib/pkgconfig and will install a python wrapper if python3 is installed.

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --target install

This will build shared (*.so) libraries by default. If you need static (*.a) libraries set BUILD_SHARED_LIBS to OFF:

cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF
cmake --build build --target install

If you have Ninja (sudo apt install ninja-build) installed, you can use:

cmake -B build -GNinja -DCMAKE_BUILD_TYPE=Release
cmake --build build --target install

to generate and compile via the ninja build script. It will be much faster than with cmake’s default Makefile generator.

You can omit --target install if you only want to use this locally without installing.

Usage

Choosing a Tag Family

For the vast majority of applications, the tagStandard41h12 family will be the correct choice. You can find the images for the tags in the apriltag-imgs repo. Scale up the images in your favorite editor and print them out.

Some heuristics for when to choose other tag families:

1. If you need more tags, use tagStandard52h13
2. If you need to maximize the use of space on a small circular object, use tagCircle49h12 (or tagCircle21h7).
3. If you want to make a recursive tag use tagCustom48h12.
4. If you want compatibility with the ArUcO detector use tag36h11

If none of these fit your needs, generate your own custom tag family here.

Getting Started with the Detector

Python

import cv2
import numpy as np
from apriltag import apriltag

imagepath = 'test.jpg'
image = cv2.imread(imagepath, cv2.IMREAD_GRAYSCALE)
detector = apriltag("tagStandard41h12")

detections = detector.detect(image)

Alternately you can use the AprilTag python bindings created by duckietown.

C

image_u8_t* im = image_u8_create_from_pnm("test.pnm");
if (im == NULL) {
    fprintf(stderr, "Failed to load pnm image.\n");
    exit(1);
}

File truncated at 100 lines see the full file