Skip to content

Performance

Locus optimises for high recall, low corner RMSE, and low latency. This page surfaces the headline numbers across the two datasets we regression-test against. The benchmarking deep-dive documents methodology, hardware, and per-stage timing.

Profiles

The shipped profiles are authored in JSON (crates/locus-core/profiles/*.json) and embedded into the wheel. Start from a profile, edit one or two fields, and hand the result back to the detector — see the Detection guide for the DetectorConfig API.

Performance Profiles

Locus optimises for high recall, low corner RMSE, and low latency. Profiles are selected by name; the three shipped profiles are authored as JSON files and embedded in the wheel.

profile Primary characteristic
"standard" Production default; balanced recall + precision.
"grid" 4-connectivity for touching tags — ChArUco / AprilGrid boards.
"high_accuracy" EdLines + axis-imbalance gate + adaptive PPB; prioritises pose precision and tail-rotation control.

Two benchmark suites

The performance numbers below come from two regression-tested benchmarks that exercise complementary regimes. We track them independently and do not trade gains on one for regressions on the other (see feedback_dataset_priority in the engineering memory).

Suite Frames Render quality Ground truth Used for
ICRA 2020 Forward 50 Lower-fidelity synthetic Tag IDs + corners Continuity with the published AprilTag-community comparison
render-tag 50 (1080p subset) High-fidelity Blender + PSF + sensor model IDs + corners + 6-DOF pose Pose-accuracy SOTA tracking, internal CI gate

Snippet-included from the README so the numbers stay consistent across the GitHub landing, the PyPI page, and this docs page — single source of truth.

ICRA 2020 Forward (community benchmark)

ICRA 2020 Forward is the closest thing the AprilTag community has to a neutral benchmark. The 50-frame subset we report on is synthetic (not real-camera), but it's public, peer-reviewed, and the basis for prior detector comparisons — we report on it for continuity with the literature.

Detector Recall Corner RMSE
Locus (standard) 96.2 % 0.315 px
AprilTag 3 (UMich) 62.3 % 0.22 px
OpenCV (cv2.aruco) 33.2 % 0.92 px

render-tag (high-fidelity Blender + PSF)

render-tag is our in-house render suite — Blender with calibrated PSF, exposure, sensor noise, and lens distortion models. The detection scenes carry pixel-accurate ground truth for both corners and 6-DOF pose, which lets us report translation / rotation percentiles in addition to recall. Numbers below are from the 2026-04-25 SOTA snapshot on the 1080p 50-scene subset (see docs/engineering/benchmarking/render_tag_sota_20260425.md for methodology).

Detector Recall Trans p50 Trans p99 Rot p50 Rot p99 Latency
Locus (high_accuracy) 100 % 0.4 mm 25.6 mm 0.058 ° 1.897 ° 11.67 ms
Locus (standard) 100 % 3.5 mm 50.3 mm 0.288 ° 27.248 ° 19.24 ms
AprilTag-C (pupil) 100 % 2.9 mm 54.4 mm 0.061 ° 65.365 ° 25.54 ms
OpenCV (cv2.aruco) 100 % 3.4 mm 141.4 mm 0.113 ° 1.228 ° 44.45 ms

Per-percentile is load-bearing: AprilTag-C's median rotation is the best in class (0.06 °) but its p99 explodes to 65 ° on the symmetric-tag IRLS branch-ambiguity failures.

How to read these numbers

  • Recall — fraction of ground-truth tags whose ID was correctly decoded. Recall counts a detection toward the corner / pose distributions even if its corners or pose are poor, so per-percentile RMSE / translation / rotation columns are how we surface fail-loudly cases (an r p99 of 65 ° is the symptom of a small number of catastrophic branch-ambiguity failures, not a distribution-wide regression).
  • Corner RMSE — root-mean-square Euclidean error of detected corners against ground truth, in pixels. Lower is better; the LM pose solver consumes the per-corner covariance and propagates it into the 6-DOF pose covariance, so corner RMSE is a leading indicator of pose precision.
  • Translation / rotation percentiles — t p99 and r p99 are the tail metrics we care most about for AV / robotics work. A robot that loses pose once per thousand frames is more dangerous than one that's slightly less accurate on every frame. Medians hide tail failures; we never accept a profile change that improves median at the cost of p99.
  • Latency — wall-clock per-frame on a single rayon thread (RAYON_NUM_THREADS=1). Multi-thread scaling is documented in the Concurrent detection how-to.

Choosing a profile

Workload Recommended profile Why
General detection "standard" Highest ICRA recall + balanced corner accuracy.
Calibration boards (ChArUco, AprilGrid) "grid" 4-connectivity recovers touching tags that "standard" rejects as overlapping.
Sub-pixel metrology, high-resolution near-field, AV pose "high_accuracy" EdLines + adaptive PPB + axis-imbalance gate. Best on render-tag across every translation percentile; trades 6 pp of ICRA recall for the pose-tail control.
  • Benchmarking methodology — how the recall / RMSE / latency numbers are measured, what hardware they ran on, and the regression suite that keeps them honest.
  • render_tag_sota_20260425.md — the snapshot the render-tag table above is sourced from, with detector-by-detector deep dive on rotation tails and recall gaps.
  • System architecture — why the pipeline is shaped to release the GIL and avoid the system allocator on the hot path.
  • Memory model — SoA DetectionBatch, arena allocation, and the FFI zero-copy contract that makes the latency numbers possible.