pyapriltags: Python bindings for the Apriltags library

These are Python bindings for the Apriltags 3 library developed by AprilRobotics. Inspired by the Apriltags2 bindings by Matt Zucker. Forked from dt-apriltags.

The original library is published with a BSD 2-Clause license.

Installation

The easy way

You can install using pip (or pip3 for Python 3):

pip install pyapriltags

And if you want a particular release, add it like this:

pip install pyapriltags@v3.3.0

Build it yourself

Clone this repository and navigate in it. Then initialize the Apriltags submodule:

$ git submodule init
$ git submodule update

Build the Apriltags C library and embed the newly-built library into the pip wheel.

$ make build

The new wheel will be available in the directory dist/. You can now install the wheel

pip install pyapriltags-VERSION-py3-none-ARCH.whl

NOTE: based on the current VERSION of this library and your OS, together with the architecture of your CPU ARCH, the filename above varies.

Release wheels

All the wheels built inside dist/ can be released (pushed to Pypi.org) by running the command

make upload

Release all

Use the following command to build and release wheels for Python 3 and CPU architecture amd64, aarch64 and arm32v7.

make release-all

Usage

Some examples of usage can be seen in the test.py file. The Detector class is a wrapper around the Apriltags functionality. You can initialize it as following:

at_detector = Detector(searchpath=['apriltags'],
                       families='tag36h11',
                       nthreads=1,
                       quad_decimate=1.0,
                       quad_sigma=0.0,
                       refine_edges=1,
                       decode_sharpening=0.25,
                       debug=0)

The options are:

Detection of tags in images is done by running the detect method of the detector:

tags = at_detector.detect(img, estimate_tag_pose=False, camera_params=None, tag_size=None)

If you also want to extract the tag pose, estimate_tag_pose should be set to True and camera_params ([fx, fy, cx, cy]) and tag_size (in meters) should be supplied. The detect method returns a list of Detection objects each having the following attributes (note that the ones with an asterisks are computed only if estimate_tag_pose=True):

Custom layouts

If you want to use a custom layout, you need to create the C source and header files for it and then build the library again. Then use the new libapriltag.so library. You can find more information on the original Apriltags repository.

Developer notes

The wheel is built inside a Docker container. The Dockerfile in the root of this repository is a template for the build environment. The build environment is based on ubuntu:latest and python3 is installed on the fly. The make build command will create the build environment if it does not exist before building the wheel.

Once the build environment (Docker image) is ready, a Docker container is launched with the following configuration:

• the root of this repository mounted to /apriltag;
• the directory dist/ is mounted as destination directory under /out;

The building script from assets/build.sh will be executed inside the container. The build steps are:

• configure a cmake build in /builds/<arch> from the apriltag library from submodule apriltags/
• run cmake build
• copy so/.dylib/.dll library file to /dist/<arch> (inside the container)
• repeat above steps for: win64, macos arm64, macos x86_64, linux x86_64, linux aarch64, linux armv7l
• build python wheel (the .so library is embedded as package_data)
• copy wheel file to /out (will pop up in dist/ outside the container)