AprilTag 3 Documentation

For most applications, use tagStandard41h12.

Heuristics for other families:

• More tags: Use tagStandard52h13.
• Small circular objects: Use tagCircle49h12 or tagCircle21h7.
• Recursive tags: Use tagCustom48h12.
• ArUco support: Use native ArUco families (e.g., tagAruco4x4_50, tagAruco5x5_100, etc.).

Custom families can be generated using the AprilTag-Generation repository.

Increasing speed

• Increase quad_decimate (at the cost of detection distance).
• Increase nthreads if you have extra CPU cores.
• Increase quad_sigma if the image is noisy.

Increasing detection distance

1. Run the detector with debug=1 to generate debug images showing the pipeline steps.
2. If the tag border is not detected as a quadrilateral, decrease quad_decimate (down to 1).
3. If the border is detected but detection fails, experiment with decode_sharpening.

AprilTag 3 officially supports Linux. The default installation places headers in /usr/local/include and shared libraries in /usr/local/lib. It also installs a pkg-config script and a Python wrapper if python3 is present.

To build shared libraries (default):

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

To build static libraries (*.a):

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

To use Ninja for faster compilation (requires ninja-build installed):

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

To enable AddressSanitizer (ASan) for Debug builds, use the ASAN=ON flag during CMake configuration:

cmake -B build -GNinja -DCMAKE_BUILD_TYPE=Debug -DASAN=ON
cmake --build build

If you encounter an error stating ASan runtime does not come first in initial library list, you must preload the library using LD_PRELOAD:

LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libasan.so.5 ./build/opencv_demo

Use the apriltag module to detect tags in a grayscale image. Note that you can also use the Duckietown Python bindings for an alternative implementation.

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)

You can pass cv::Mat data to AprilTag without a deep copy by creating an image_u8_t header that points directly to the cv::Mat data buffer.

cv::Mat img;

image_u8_t img_header = { .width = img.cols,
    .height = img.rows,
    .stride = img.cols,
    .buf = img.data
};

The C API involves creating a detector, adding a family to it, and then running the detection on an image_u8_t structure. Remember to clean up all allocated resources.

image_u8_t* im = image_u8_create_from_pnm("test.pnm");
if (im == NULL) {
    fprintf(stderr, "Failed to load pnm image.\n");
    exit(1);
}
apriltag_detector_t *td = apriltag_detector_create();
apriltag_family_t *tf = tagStandard41h12_create();
apriltag_detector_add_family(td, tf);
zarray_t *detections = apriltag_detector_detect(td, im);

for (int i = 0; i < zarray_size(detections); i++) {
    apriltag_detection_t *det;
    zarray_get(detections, i, &det);

    // Do stuff with detections here.
}
// Cleanup.
apriltag_detections_destroy(detections);
tagStandard41h12_destroy(tf);
apriltag_detector_destroy(td);

For multi-threaded applications or when storing detections beyond the detector's lifecycle, use these utility functions:

• apriltag_detector_copy(td): Clones the detector configuration.
• apriltag_detections_copy(detections): Returns a new zarray_t with deep copies of all apriltag_detection_t objects.
• apriltag_detection_copy(src, dst): Deep copies a single detection into an existing structure.