Package: pyapriltags
pyapriltags: Python bindings for the Apriltags libraryThese are Python bindings for theApriltags 3library developed byAprilRobotics.
Inspired by theApriltags2 bindingsbyMatt Zucker.
Forked fromdt-apriltags.The original library is published with aBSD 2-Clause license.InstallationThe easy wayYou can install usingpip(orpip3for Python 3):pip install pyapriltagsAnd if you want a particular release, add it like this:pip install pyapriltags@v3.3.0Build it yourselfClone this repository and navigate in it. Then initialize the Apriltags submodule:$ git submodule init
$ git submodule updateBuild the Apriltags C library and embed the newly-built library into the pip wheel.$ make buildThe new wheel will be available in the directorydist/.
You can now install the wheelpip install pyapriltags-VERSION-py3-none-ARCH.whlNOTE: based on the currentVERSIONof this library and your OS, together with the architecture of your CPUARCH, the filename above varies.Release wheelsAll the wheels built insidedist/can be released (pushed to Pypi.org) by running the commandmake uploadRelease allUse the following command to build and release wheels for Python 3 and CPU architectureamd64,aarch64andarm32v7.make release-allUsageSome examples of usage can be seen in thetest.pyfile.
TheDetectorclass 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:OptionDefaultExplanationfamilies'tag36h11'Tag families, separated with a spacenthreads1Number of threadsquad_decimate2.0Detection of quads can be done on a lower-resolution image, improving speed at a cost of pose accuracy and a slight decrease in detection rate. Decoding the binary payload is still done at full resolution. Set this to 1.0 to use the full resolution.quad_sigma0.0What Gaussian blur should be applied to the segmented image. Parameter is the standard deviation in pixels. Very noisy images benefit from non-zero values (e.g. 0.8)refine_edges1When non-zero, the edges of the each quad are adjusted to "snap to" strong gradients nearby. This is useful when decimation is employed, as it can increase the quality of the initial quad estimate substantially. Generally recommended to be on (1). Very computationally inexpensive. Option is ignored if quad_decimate = 1decode_sharpening0.25How much sharpening should be done to decoded images? This can help decode small tags but may or may not help in odd lighting conditions or low light conditionssearchpath['apriltags']Where to look for the Apriltag 3 library, must be a listdebug0If 1, will save debug images. Runs very slowDetection of tags in images is done by running thedetectmethod 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_poseshould be set toTrueandcamera_params([fx, fy, cx, cy]) andtag_size(in meters) should be supplied. Thedetectmethod returns a list ofDetectionobjects each having the following attributes (note that the ones with an asterisks are computed only ifestimate_tag_pose=True):AttributeExplanationtag_familyThe family of the tag.tag_idThe decoded ID of the tag.hammingHow many error bits were corrected? Note: accepting large numbers of corrected errors leads to greatly increased false positive rates. NOTE: As of this implementation, the detector cannot detect tags with a Hamming distance greater than 2.decision_marginA measure of the quality of the binary decoding process: the average difference between the intensity of a data bit versus the decision threshold. Higher numbers roughly indicate better decodes. This is a reasonable measure of detection accuracy only for very small tags-- not effective for larger tags (where we could have sampled anywhere within a bit cell and still gotten a good detection.)homographyThe 3x3 homography matrix describing the projection from an "ideal" tag (with corners at (-1,1), (1,1), (1,-1), and (-1, -1)) to pixels in the image.centerThe center of the detection in image pixel coordinates.cornersThe corners of the tag in image pixel coordinates. These always wrap counter-clock wise around the tag.pose_R*Rotation matrix of the pose estimate.pose_t*Translation of the pose estimate.pose_err*Object-space error of the estimation.Custom layoutsIf 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 newlibapriltag.solibrary. You can find more information on the originalApriltags repository.Developer notesThe 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 onubuntu:latestand python3 is installed on the fly.
Themake buildcommand 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 directorydist/is mounted as destination directory under/out;The building script fromassets/build.shwill be executed inside the container. The build steps are:configure a cmake build in/builds/<arch>from the apriltag library from submoduleapriltags/run cmake buildcopy 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 armv7lbuild python wheel (the .so library is embedded aspackage_data)copy wheel file to/out(will pop up indist/outside the container)