Pywayne Cv Apriltag Detector

Pywayne AprilTag Detector

This module detects AprilTag fiducial markers for camera calibration and pose estimation.

Quick Start

from pywayne.cv.apriltag_detector import ApriltagCornerDetector

# Create detector. Default tag family is 36h11.
detector = ApriltagCornerDetector(tag_family="36h11")

# Detect from file path
detections = detector.detect('test.png', show_result=True)

# Detect from numpy array
import cv2
image = cv2.imread('test.png')
detections = detector.detect(image)

Corner Extraction Task Pattern

When the user asks to detect AprilTag corners in an image, produce IDs and corner coordinates directly. Prefer non-GUI code unless the user asks for visualization.

from pywayne.cv.apriltag_detector import ApriltagCornerDetector

detector = ApriltagCornerDetector(
    tag_family="36h11",
    preprocess=None,  # or "norm", "clahe", "equalize", "norm-clahe"
)
detections = detector.detect("image.jpg")

for det in detections:
    print({
        "id": det.id,
        "hamming_distance": det.hamming_distance,
        "center": tuple(det.center),
        "corners": [tuple(p) for p in det.corners],
    })

If detection is poor because of lighting or contrast, retry with preprocess="norm-clahe" or preprocess="clahe" before changing algorithm parameters.

Detection Methods

detect()

Detect AprilTags in an image:

detections = detector.detect(
    image,           # File path, Path object, or numpy array
    show_result=False, # Show visualization window
    preprocess=None    # Optional override for this call
)

Returns list of detection results with:

• id: Tag ID
• hamming_distance: Detection confidence
• center: Tag center coordinates (x, y)
• corners: 4 corner coordinates

detect_and_draw()

Detect AprilTags and draw results on original image:

result_image = detector.detect_and_draw(image)
cv2.imshow('Detection Result', result_image)
cv2.waitKey(0)

Visualization includes:

• Green polygon outlines
• Red corner circles
• Red ID labels at tag centers

Requirements

• cv2 (OpenCV) - Image processing
• numpy - Array operations
• gettool - Downloads apriltag_detection library automatically

Library Installation

The detector automatically checks for and installs the apriltag_detection library using gettool if not found. The pywayne wrapper uses a shared C++ module loader that distinguishes a missing module from a local extension that exists but fails to load because of missing runtime libraries or ABI mismatch.

If installation fails while cloning from GitHub, check for sandbox/proxy restrictions before blaming the user's proxy. Useful checks:

git config --global --get http.proxy
git config --global --get https.proxy
lsof -nP -iTCP:7890 -sTCP:LISTEN
nc -vz 127.0.0.1 7890
curl -I --proxy http://127.0.0.1:7890 https://github.com --connect-timeout 5

In Codex, if nc or curl fails with Operation not permitted or cannot reach 127.0.0.1:7890 inside the sandbox, rerun the essential check or gettool apriltag_detection -b with sandbox_permissions: "require_escalated" and a short justification.

Tag Families And Preprocessing

Supported tag families:

• 16h5 / tag16h5
• 25h7 / tag25h7
• 25h9 / tag25h9
• 36h9 / tag36h9
• 36h11 / tag36h11 (default)

Supported preprocessing modes:

• None (default)
• "norm" or "normalize"
• "clahe"
• "equalize" / "hist" / "eq"
• "norm-clahe"
• A sequence such as ["norm", "clahe"]

Detection Result Format

Each detection contains:

Notes

• Supports both grayscale and BGR images
• Automatic grayscale conversion for detection
• Visualization sizes scale with image dimensions
• Uses AprilTag 36h11 tag family by default
• For calibration-board photos under uneven illumination, try preprocess="norm-clahe" first