# Pywayne Cv Apriltag Detector

> AprilTag corner detection for camera calibration and pose estimation. Use when working with pywayne.cv.apriltag_detector module to detect AprilTag fiducial markers in images, extract tag IDs and four corner coordinates, choose tag families such as tag16h5 or tag36h11, apply optional preprocessing, and rely on automatic apriltag_detection installation via gettool.

- **Type:** Skill
- **Install:** `agentstack add skill-wangyendt-wayne-skills-apriltag-detector`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [wangyendt](https://agentstack.voostack.com/s/wangyendt)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [wangyendt](https://github.com/wangyendt)
- **Source:** https://github.com/wangyendt/wayne-skills/tree/main/pywayne/cv/apriltag-detector

## Install

```sh
agentstack add skill-wangyendt-wayne-skills-apriltag-detector
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Pywayne AprilTag Detector

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

## Quick Start

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

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

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

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

```bash
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:

| Field | Description |
|--------|-------------|
| `id` | Tag identifier |
| `hamming_distance` | Hamming distance (lower = more confident) |
| `center` | Tag center as (x, y) tuple |
| `corners` | 4 corner coordinates as [(x1, y1), (x2, y2), (x3, y3), (x4, y4)] |

## 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [wangyendt](https://github.com/wangyendt)
- **Source:** [wangyendt/wayne-skills](https://github.com/wangyendt/wayne-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-wangyendt-wayne-skills-apriltag-detector
- Seller: https://agentstack.voostack.com/s/wangyendt
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.