locus-tag

Locus detects AprilTag and ArUco markers, as well as AprilGrid and ChArUco boards. It's implemented in Rust with zero-copy Python bindings. It targets a balance of low latency, high pose accuracy and high recall.

Some Features

• Zero-copy ingestion: images cross the Rust↔Python boundary through the NumPy Buffer Protocol; no copies.
• Releases the GIL during detection, so it parallelizes cleanly across Python threads.
• 6-DOF pose: an IPPE-Square seed refined by a weighted Levenberg–Marquardt solver, and internal-edge based optional refinement.
• Allocation light: per-frame arena allocation, no malloc inside detect().

Supported markers & requirements

• Tag families: AprilTag (16h5, 36h11) and ArUco (4x4_50, 4x4_100, 6x6_250, mip_36h12). More can be registered: Add a dictionary.
• Boards: AprilGrid and ChArUco layouts over those families.
• Python: 3.10+ (abi3 wheels).
• Platforms: prebuilt wheels for Linux (x86_64 / aarch64, glibc + musl), macOS (Intel + Apple Silicon), and Windows (x64).

Installation

pip install locus-tag

The PyPI wheel targets rectified (pinhole) imagery. For unrectified cameras (Brown–Conrady, Kannala–Brandt fisheye), see Install with distortion support.

Quick start

Detect markers

import cv2
import locus

img = cv2.imread("tags.jpg", cv2.IMREAD_GRAYSCALE)
detector = locus.Detector(families=[locus.TagFamily.AprilTag36h11])

batch = detector.detect(img)  # parallel NumPy arrays
print(batch.ids)  # (N,)
print(batch.corners.shape)  # (N, 4, 2)

Estimate 6-DOF pose

from locus import Detector, CameraIntrinsics

intrinsics = CameraIntrinsics(fx=800.0, fy=800.0, cx=640.0, cy=360.0)

batch = detector.detect(
    img,
    intrinsics=intrinsics,
    tag_size=0.10,  # physical side length, meters
)

if batch.poses is not None:
    print(batch.poses[0])  # [tx, ty, tz, qw, qx, qy, qz]

Configuration is nested and Pydantic-validated: start from a shipped profile, edit the group you care about, and hand it back to the detector. The detection guide walks through the DetectorConfig API.

Performance

Profiles are selected by name and embedded in the wheel:

standard is benchmarked against pinned OpenCV aruco 4.10 (three corner refiners) and aruco_nano on real and rendered data with cargo xtask sota (2026-10-04, 1 thread, AMD EPYC-Milan):

Liu4K recall is an open gap (threshold model; see the recall lessons). Sources: the EuRoC report and the SOTA scoreboard (2026-10-04).

For single-tag pose, high_accuracy had the lowest rotation and translation tails on the 1080p render-tag suite in the 2026-07 snapshot (rotation p99 0.249° vs 0.376° for OpenCV's apriltag refiner). Details, methodology and hardware are in the performance docs.

Visual debugging

Built-in integration with the Rerun SDK emits intermediate pipeline stages:

batch = detector.detect(img, debug_telemetry=True)
if batch.telemetry:
    print(batch.telemetry.subpixel_jitter)

Documentation

• Detection guide for end-to-end usage and the config API
• Python API reference
• Performance & benchmarks
• Architecture & memory model
• Coordinate conventions

Contributing

See the engineering workflow for the dev setup and PR gates.

License

Dual-licensed under Apache 2.0 or MIT.