pyapriltags

https://github.com/willb97/pyapriltags
Admin
pyapriltags is a Python binding for the AprilTags library that enables efficient detection and pose...
Tokens:6,280
Snippets:42
Trust Score:7.9
License:BSD-2-Clause
Update:6 months ago
Show doc for...
Tokens:
Raw
### Complete Pipeline Example with OpenCV

Source: https://context7.com/willb97/pyapriltags/llms.txt

A full example demonstrating loading images, detecting tags, estimating poses, and visualizing results using OpenCV. Initializes the detector with optimized settings.

```python
from pyapriltags import Detector
import cv2
import numpy as np
import time

# Initialize detector with optimized settings
detector = Detector(
    families='tag36h11',
    nthreads=4,
    quad_decimate=2.0,      # Trade accuracy for speed
    quad_sigma=0.0,
    refine_edges=1,
    decode_sharpening=0.25,
    debug=0
)

# Camera calibration (from camera calibration procedure)
camera_matrix = np.array([
    [600.0, 0.0, 320.0],
    [0.0, 600.0, 240.0],
    [0.0, 0.0, 1.0]
])
camera_params = (
    camera_matrix[0, 0],  # fx
    camera_matrix[1, 1],  # fy
    camera_matrix[0, 2],  # cx
    camera_matrix[1, 2]   # cy
)


```

--------------------------------

### Install pyapriltags Wheel

Source: https://github.com/willb97/pyapriltags/blob/master/README.md

Install the pyapriltags library from a local wheel file. Replace VERSION and ARCH with your specific details.

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

--------------------------------

### Install pyapriltags using pip

Source: https://github.com/willb97/pyapriltags/blob/master/README.md

Install the pyapriltags library using pip. This is the recommended method for most users.

```bash
pip install pyapriltags
```

--------------------------------

### AprilTag Pose Estimation Setup

Source: https://context7.com/willb97/pyapriltags/llms.txt

Prepare for AprilTag pose estimation by initializing the detector and loading a grayscale image. Camera intrinsic parameters (focal lengths and principal point) and the physical size of the AprilTag are required for accurate 3D pose calculation.

```python
from pyapriltags import Detector
import cv2
import numpy as np

# Initialize detector
detector = Detector(families='tag36h11', nthreads=4, quad_decimate=1.0)

# Load grayscale image
image = cv2.imread('robot_scene.png', cv2.IMREAD_GRAYSCALE)

# Camera intrinsic parameters [fx, fy, cx, cy]
# fx, fy: focal lengths in pixels
# cx, cy: principal point (usually image center)
camera_params = (600.0, 600.0, 320.0, 240.0)  # Example for 640x480 image

# Tag size in meters (edge length of the black square)
tag_size = 0.165  # 16.5 cm tag
```

--------------------------------

### Install a specific pyapriltags release

Source: https://github.com/willb97/pyapriltags/blob/master/README.md

Install a specific version of the pyapriltags library by appending the version number to the package name.

```bash
pip install pyapriltags@v3.3.0
```

--------------------------------

### Build and Release All Wheels

Source: https://github.com/willb97/pyapriltags/blob/master/README.md

Build and release wheels for Python 3 across multiple CPU architectures (amd64, aarch64, arm32v7).

```bash
make release-all
```

--------------------------------

### Initialize Detector with Custom Configuration

Source: https://context7.com/willb97/pyapriltags/llms.txt

Initialize the Detector class with custom parameters for AprilTag detection. Supported tag families can be specified, and parameters like thread count, resolution decimation, blur, edge refinement, and sharpening can be tuned for performance and accuracy.

```python
from pyapriltags import Detector
import numpy as np

# Initialize detector with custom configuration
detector = Detector(
    families='tag36h11',      # Tag family to detect (can be space-separated for multiple)
    nthreads=4,               # Number of threads for parallel processing
    quad_decimate=2.0,        # Reduce resolution for faster detection (1.0 = full res)
    quad_sigma=0.0,           # Gaussian blur for noisy images (0.8 for noisy)
    refine_edges=1,           # Snap edges to strong gradients (recommended: 1)
    decode_sharpening=0.25,   # Sharpening for small tag decoding
    debug=0                   # Set to 1 to save debug images (slow)
)

# Supported tag families:
# 'tag16h5', 'tag25h9', 'tag36h11', 'tagCircle21h7',
# 'tagCircle49h12', 'tagCustom48h12', 'tagStandard41h12', 'tagStandard52h13'

# Detect multiple tag families simultaneously
multi_family_detector = Detector(
    families='tag36h11 tag25h9 tagCircle21h7',
    nthreads=2
)
```

--------------------------------

### Initialize the Detector class

Source: https://github.com/willb97/pyapriltags/blob/master/README.md

Configures the detector with specific parameters such as tag families, threading, and image processing settings.

```python
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)
```

--------------------------------

### Build Apriltags C Library

Source: https://github.com/willb97/pyapriltags/blob/master/README.md

Build the Apriltags C library. This command compiles the C library and embeds it into the pip wheel.

```bash
make build
```

--------------------------------

### Custom Layouts

Source: https://github.com/willb97/pyapriltags/blob/master/README.md

Instructions for using custom AprilTag layouts.

```APIDOC
## Custom Layouts

### Description
To utilize custom AprilTag layouts, you must create the necessary C source and header files for your layout and then recompile the library. This will generate a new `libapriltag.so` file that includes your custom layout.

### Usage
1. Create C source and header files for your custom layout.
2. Rebuild the `apriltags` library using your custom files.
3. Replace the existing `libapriltag.so` with the newly compiled version.

For more detailed information, refer to the original [Apriltags repository](https://github.com/AprilRobotics/apriltags).
```

--------------------------------

### Initialize and Update Apriltags Submodule

Source: https://github.com/willb97/pyapriltags/blob/master/README.md

Initialize and update the Apriltags C library submodule. This is a required step before building the library from source.

```bash
git submodule init
git submodule update
```

--------------------------------

### Detector Initialization

Source: https://github.com/willb97/pyapriltags/blob/master/README.md

Initializes the Detector class wrapper for AprilTag functionality.

```APIDOC
## Detector Initialization

### Description
Initializes the detector instance with specific configuration parameters for tag detection.

### Parameters
#### Request Body
- **searchpath** (list) - Optional - Where to look for the Apriltag 3 library. Default: ['apriltags']
- **families** (string) - Optional - Tag families, separated with a space. Default: 'tag36h11'
- **nthreads** (int) - Optional - Number of threads. Default: 1
- **quad_decimate** (float) - Optional - Detection of quads on lower-resolution image. Default: 2.0
- **quad_sigma** (float) - Optional - Gaussian blur applied to the segmented image. Default: 0.0
- **refine_edges** (int) - Optional - Adjust edges to snap to strong gradients. Default: 1
- **decode_sharpening** (float) - Optional - Sharpening applied to decoded images. Default: 0.25
- **debug** (int) - Optional - If 1, saves debug images. Default: 0
```

--------------------------------

### Upload Wheels to PyPI

Source: https://github.com/willb97/pyapriltags/blob/master/README.md

Upload all built wheels in the 'dist/' directory to PyPI. This command is used for releasing new versions.

```bash
make upload
```

--------------------------------

### detect() Method

Source: https://context7.com/willb97/pyapriltags/llms.txt

Processes a grayscale image to identify AprilTags and optionally estimate their 3D pose.

```APIDOC
## detect() Method

### Description
Processes a grayscale image to detect AprilTags. If camera parameters and tag size are provided, it performs 3D pose estimation.

### Parameters
- **image** (numpy.ndarray) - Required - Grayscale image of type uint8.
- **camera_params** (tuple) - Optional - Camera intrinsics (fx, fy, cx, cy).
- **tag_size** (float) - Optional - Physical size of the tag in meters.

### Response
- **detections** (list) - A list of Detection objects containing tag_family, tag_id, hamming, decision_margin, center, corners, and homography.
```

--------------------------------

### Detector Class Initialization

Source: https://context7.com/willb97/pyapriltags/llms.txt

Configures the AprilTag detector with specific families, threading, and image processing parameters.

```APIDOC
## Detector Class Initialization

### Description
Initializes the detector instance with specific configuration parameters for tag detection performance and accuracy.

### Parameters
- **families** (string) - Required - Space-separated list of tag families (e.g., 'tag36h11', 'tag25h9').
- **nthreads** (int) - Optional - Number of threads for parallel processing.
- **quad_decimate** (float) - Optional - Resolution reduction factor (1.0 = full resolution).
- **quad_sigma** (float) - Optional - Gaussian blur applied to images.
- **refine_edges** (int) - Optional - Flag to snap edges to strong gradients.
- **decode_sharpening** (float) - Optional - Sharpening factor for small tag decoding.
- **debug** (int) - Optional - Flag to save debug images.
```

--------------------------------

### Detect Tags with Pose Estimation Enabled

Source: https://context7.com/willb97/pyapriltags/llms.txt

Enables pose estimation for detected tags. Requires camera parameters and tag size. Prints tag ID, size, rotation matrix, translation vector, and pose error.

```python
detections = detector.detect(
    image,
    estimate_tag_pose=True,
    camera_params=camera_params,
    tag_size=tag_size
)

for detection in detections:
    print(f"Tag ID: {detection.tag_id}")
    print(f"Tag Size: {detection.tag_size} meters")

    # Rotation matrix (3x3) - tag orientation relative to camera
    print(f"Rotation Matrix:\n{detection.pose_R}")

    # Translation vector (3x1) - tag position relative to camera [x, y, z] in meters
    print(f"Translation: {detection.pose_t.flatten()}")

    # Pose estimation error (lower is better)
    print(f"Pose Error: {detection.pose_err}")

    # Extract position in camera frame
    x, y, z = detection.pose_t.flatten()
    print(f"Distance from camera: {np.sqrt(x**2 + y**2 + z**2):.3f} meters")
```

--------------------------------

### Detect Tags with Variable Tag Sizes

Source: https://context7.com/willb97/pyapriltags/llms.txt

Handles scenes with multiple tags of different sizes by passing a dictionary mapping tag IDs to their sizes. Tags not in the dictionary will be detected but won't have pose estimation.

```python
from pyapriltags import Detector
import cv2
import numpy as np

detector = Detector(families='tag36h11', nthreads=4)

image = cv2.imread('multi_size_scene.png', cv2.IMREAD_GRAYSCALE)

# Camera parameters
camera_params = (800.0, 800.0, 640.0, 480.0)

# Different tag sizes by ID (in meters)
tag_sizes = {
    0: 0.10,    # Tag ID 0 is 10cm
    1: 0.05,    # Tag ID 1 is 5cm
    2: 0.20,    # Tag ID 2 is 20cm
    5: 0.165,   # Tag ID 5 is 16.5cm
}

detections = detector.detect(
    image,
    estimate_tag_pose=True,
    camera_params=camera_params,
    tag_size=tag_sizes  # Pass dictionary instead of single value
)

for det in detections:
    if det.pose_R is not None:
        print(f"Tag {det.tag_id}: position = {det.pose_t.flatten()}, size = {det.tag_size}m")
    else:
        print(f"Tag {det.tag_id}: detected but size unknown, no pose estimate")
```

--------------------------------

### Detect AprilTags in Video Stream with Pose Estimation

Source: https://context7.com/willb97/pyapriltags/llms.txt

This code snippet captures video frames, converts them to grayscale, detects AprilTags with pose estimation, and visualizes the results including tag outlines, IDs, and distances. It also displays the detection FPS. Press 'q' to quit.

```python
cap = cv2.VideoCapture(0)  # Or video file path

while True:
    ret, frame = cap.read()
    if not ret:
        break

    # Convert to grayscale (required by detector)
    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)

    # Detect tags with pose estimation
    start_time = time.time()
    detections = detector.detect(
        gray,
        estimate_tag_pose=True,
        camera_params=camera_params,
        tag_size=0.165  # 16.5cm tags
    )
    detection_time = time.time() - start_time

    # Visualize detections
    for det in detections:
        # Draw tag outline
        corners = det.corners.astype(int)
        cv2.polylines(frame, [corners], True, (0, 255, 0), 2)

        # Draw tag ID and distance
        if det.pose_t is not None:
            distance = np.linalg.norm(det.pose_t)
            label = f"ID:{det.tag_id} D:{distance:.2f}m"
        else:
            label = f"ID:{det.tag_id}"

        cv2.putText(frame, label, tuple(corners[0]),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 0, 0), 2)

    # Display FPS
    fps = 1.0 / detection_time if detection_time > 0 else 0
    cv2.putText(frame, f"FPS: {fps:.1f}", (10, 30),
                cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 255), 2)

    cv2.imshow('AprilTag Detection', frame)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()
```

--------------------------------

### detect Method

Source: https://github.com/willb97/pyapriltags/blob/master/README.md

Detects AprilTags in an image and optionally estimates their pose.

```APIDOC
## detect Method

### Description
Processes an image to detect AprilTags. Can optionally compute pose if camera parameters and tag size are provided.

### Parameters
#### Request Body
- **img** (image) - Required - The input image to process.
- **estimate_tag_pose** (bool) - Optional - Whether to compute tag pose. Default: False
- **camera_params** (list) - Optional - Camera parameters [fx, fy, cx, cy]. Required if estimate_tag_pose is True.
- **tag_size** (float) - Optional - Tag size in meters. Required if estimate_tag_pose is True.

### Response
#### Success Response (200)
- **tags** (list) - A list of Detection objects.
```

--------------------------------

### Accessing Detection Class Attributes

Source: https://context7.com/willb97/pyapriltags/llms.txt

Demonstrates accessing attributes of the Detection class, including always available data and optional pose estimation data. Pose attributes are only populated when estimate_tag_pose is True.

```python
from pyapriltags import Detector, Detection
import numpy as np

detector = Detector(families='tag36h11')
camera_params = (600.0, 600.0, 320.0, 240.0)

# Assuming 'image' is a grayscale numpy array
detections = detector.detect(image, estimate_tag_pose=True,
                             camera_params=camera_params, tag_size=0.1)

# Detection attributes (always available)
detection = detections[0]
tag_family: bytes = detection.tag_family         # b'tag36h11'
tag_id: int = detection.tag_id                   # Unique ID within family
Hamming: int = detection.hamming                 # Error correction bits used
decision_margin: float = detection.decision_margin  # Decode confidence
homography: np.ndarray = detection.homography    # 3x3 projection matrix
center: np.ndarray = detection.center            # [x, y] center in pixels
corners: np.ndarray = detection.corners          # 4x2 corner coordinates

# Pose attributes (only when estimate_tag_pose=True)
pose_R: np.ndarray = detection.pose_R            # 3x3 rotation matrix
pose_t: np.ndarray = detection.pose_t            # 3x1 translation vector
pose_err: float = detection.pose_err             # Estimation error metric
tag_size: float = detection.tag_size             # Tag size used for pose

# String representation for debugging
print(detection)
# Output:
# Detection object:
# tag_family = b'tag36h11'
# tag_id = 0
# tag_size = 0.1
# hamming = 0
# decision_margin = 125.5
# homography = [[ 9.99e-01 -1.23e-02  3.20e+02]...]
# center = [320. 240.]
# corners = [[280. 200.] [360. 200.] [360. 280.] [280. 280.]]
# pose_R = [[ 1.  0.  0.]...]
# pose_t = [[0.] [0.] [0.5]]
# pose_err = 1.23e-05
```

--------------------------------

### Basic AprilTag Detection

Source: https://context7.com/willb97/pyapriltags/llms.txt

Perform basic AprilTag detection on a grayscale image using the detect() method. The input image must be a NumPy array of type uint8. The method returns a list of Detection objects, each containing information about a detected tag such as its ID, family, center, corners, and homography matrix.

```python
from pyapriltags import Detector
import cv2
import numpy as np

# Initialize detector
detector = Detector(families='tag36h11', nthreads=1, quad_decimate=1.0)

# Load and convert image to grayscale
image = cv2.imread('image_with_tags.png', cv2.IMREAD_GRAYSCALE)

# Basic detection without pose estimation
detections = detector.detect(image)

# Process each detected tag
for detection in detections:
    print(f"Tag Family: {detection.tag_family}")      # e.g., b'tag36h11'
    print(f"Tag ID: {detection.tag_id}")              # Decoded tag ID number
    print(f"Hamming: {detection.hamming}")            # Error bits corrected (0-2)
    print(f"Decision Margin: {detection.decision_margin}")  # Decode quality score
    print(f"Center: {detection.center}")              # [x, y] pixel coordinates
    print(f"Corners: {detection.corners}")            # 4x2 array of corner pixels
    print(f"Homography:\n{detection.homography}")     # 3x3 homography matrix

# Draw detected tags on image
color_image = cv2.cvtColor(image, cv2.COLOR_GRAY2RGB)
for tag in detections:
    # Draw tag outline
    corners = tag.corners.astype(int)
    for i in range(4):
        cv2.line(color_image, tuple(corners[i-1]), tuple(corners[i]), (0, 255, 0), 2)
    # Draw tag ID
    cv2.putText(color_image, str(tag.tag_id),
                (corners[0, 0] + 10, corners[0, 1] + 10),
                cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 0, 255), 2)

cv2.imwrite('detected_tags.png', color_image)
```

--------------------------------

### Detector.detect()

Source: https://context7.com/willb97/pyapriltags/llms.txt

Detects AprilTags in an image and optionally estimates their pose relative to the camera.

```APIDOC
## Detector.detect()

### Description
Detects AprilTags in a grayscale image. Can perform pose estimation if camera parameters and tag sizes are provided.

### Parameters
#### Request Body
- **image** (numpy.ndarray) - Required - Grayscale image array.
- **estimate_tag_pose** (bool) - Optional - Whether to calculate pose estimation.
- **camera_params** (tuple) - Optional - Camera intrinsic parameters (fx, fy, cx, cy).
- **tag_size** (float or dict) - Optional - Size of the tag in meters. Can be a single float or a dictionary mapping tag IDs to sizes.

### Response
- **detections** (list) - A list of Detection objects containing tag information and pose data.
```

--------------------------------

### Detect tags in an image

Source: https://github.com/willb97/pyapriltags/blob/master/README.md

Executes the detection process on an image, with optional parameters for pose estimation.

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

--------------------------------

### Detection Class

Source: https://context7.com/willb97/pyapriltags/llms.txt

The Detection class represents a single identified AprilTag and its associated metadata.

```APIDOC
## Detection Class

### Description
A NamedTuple containing information about a detected tag.

### Attributes
- **tag_family** (bytes) - The family of the detected tag.
- **tag_id** (int) - Unique ID within the family.
- **hamming** (int) - Error correction bits used.
- **decision_margin** (float) - Decode confidence.
- **homography** (np.ndarray) - 3x3 projection matrix.
- **center** (np.ndarray) - [x, y] center in pixels.
- **corners** (np.ndarray) - 4x2 corner coordinates.
- **pose_R** (np.ndarray) - 3x3 rotation matrix (if pose estimation enabled).
- **pose_t** (np.ndarray) - 3x1 translation vector (if pose estimation enabled).
- **pose_err** (float) - Estimation error metric (if pose estimation enabled).
- **tag_size** (float) - Tag size used for pose calculation.
```

--------------------------------

### AprilTag Detection Results

Source: https://github.com/willb97/pyapriltags/blob/master/README.md

Details of the information returned for each detected AprilTag.

```APIDOC
## AprilTag Detection Results

### Description
This section describes the fields returned for each detected AprilTag.

### Fields
- **tag_family** (string) - The family of the tag.
- **tag_id** (integer) - The decoded ID of the tag.
- **hamming** (integer) - The number of error bits corrected during detection. Note: High values can increase false positives. This detector supports a maximum Hamming distance of 2.
- **decision_margin** (float) - A measure of the quality of the binary decoding process. Higher values generally indicate better decodes, but this is more reliable for smaller tags.
- **homography** (list of lists of floats) - The 3x3 homography matrix representing the tag's projection in the image.
- **center** (list of floats) - The [x, y] coordinates of the tag's center in image pixels.
- **corners** (list of lists of floats) - The [x, y] coordinates of the tag's corners in image pixels, ordered counter-clockwise.
- **pose_R** (list of lists of floats) - The rotation matrix component of the estimated tag pose.
- **pose_t** (list of floats) - The translation vector component of the estimated tag pose.
- **pose_err** (float) - The object-space error of the pose estimation.

### Response Example
```json
{
  "tag_family": "tag36h11",
  "tag_id": 10,
  "hamming": 0,
  "decision_margin": 120.5,
  "homography": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
  "center": [100.0, 150.0],
  "corners": [[80.0, 130.0], [120.0, 130.0], [120.0, 170.0], [80.0, 170.0]],
  "pose_R": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
  "pose_t": [0.0, 0.0, 10.0],
  "pose_err": 0.01
}
```
```
Tokens:
Raw