Skip to main content

aruco-pose

Tests PyPI License: Apache 2.0

Turn printed markers into a useful reference frame.

Print a target, calibrate a camera, and track its position and orientation through one shared Python API. Use CSV for experiments or the optional ROS 2 example for stamped poses, TF and tracking status. Start with a synthetic replay if you have no camera handy.

Project page & demos · API guide · ROS 2 guide · 0.3.0 changelog

Start here What you get
Camera-free starter Calibration video, four-marker board, tracking and CSV
Dodecahedron kit A4 print sheet, assembly guide, matching model and 3D replay
Python API Rigid-target pose, outlier rejection and explicit ambiguity/loss
ROS 2 Jazzy Raw or rectified Image/CameraInfo, acquisition-time pose, TF and diagnostics

Synthetic dodecahedron tracking preview; click to watch the demo

Synthetic software demo, not a physical accuracy benchmark. Source release: 0.3.0; the PyPI badge above shows the version currently published.

The core requires Python 3.9+. CI exercises Windows/Linux with Python 3.11; ROS integration uses Jazzy's system Python 3.12 on Ubuntu 24.04. Physical camera accuracy and all GUI/platform combinations have not been validated.

Install

For the core CLI and Python API:

python -m pip install aruco-pose

For the repository's examples, assets and optional ROS node, clone Jshulgach/aruco-pose and run from its root using a working Python installation. ROS itself is installed separately; the core PyPI package has no ROS dependency.

python -m venv .venv
# Windows PowerShell (activation is optional):
.venv\Scripts\python.exe -m pip install -e .
# Optional activation, so the remaining commands can use `python`:
.venv\Scripts\Activate.ps1

On macOS/Linux, use .venv/bin/python instead. In the commands below, python means that environment's interpreter. You can activate it, or substitute its full path. The installed aruco-pose command is equivalent to python -m aruco_pose. aruco-cli remains a compatibility alias. The distribution is named aruco-pose and the import package is aruco_pose; publishing instructions are in the release guide. Use a fresh environment: install only opencv-contrib-python, not both OpenCV wheel variants, because they share the same cv2 module. A graphical desktop is needed only for --preview or printing SVGs through a browser.

Try it without a camera

For ROS 2, see the optional target pose + TF example. It runs the dodecahedron replay or raw/rectified Image/CameraInfo topics on ROS 2 Jazzy, publishes measured poses and tracking diagnostics, and includes acquisition-time and calibration rules, frame conventions, camera-topic instructions and an RViz view.

For a 3D target, try the dodecahedron print + replay kit: an A4 PDF/SVG with glue tabs and paired edge labels, a matching 25 mm-edge model, and a ten-second raw synthetic replay. Download the complete kit to use it with the published package, or use assets/dodecahedron/ in this checkout. The guide covers both camera-free tracking and assembling/calibrating a physical target. The printable model is a prototype; physical accuracy is not yet validated.

The repository includes a 30-view checkerboard clip and a six-second tracking clip under assets/starter/. They are explicitly synthetic perspective renders, not evidence of real-world accuracy. No downloads or camera calibration files from your own machine are needed after installation.

python -m aruco_pose kit calibrate --source assets/starter/calibration.mp4 --stride 1 --output output/sample_calibration.json
python -m aruco_pose kit track --source assets/starter/tracking.mp4 --model assets/starter/board.json --calibration output/sample_calibration.json --csv output/sample_poses.csv --output-video output/sample_tracked.mp4

Expected: 120 CSV rows, 110 measured poses and 10 lost frames. Frames 50-59 hide the whole board; frames 85-99 hide two markers while tracking continues with the other two. Add --preview to see the overlay while processing, or open output/sample_tracked.mp4 afterward. Defaults are headless.

Outputs:

  • output/sample_calibration.json: estimated camera matrix, distortion, resolution, calibration RMS and view count.
  • output/sample_poses.csv: one row per decoded frame, including explicit losses.
  • output/sample_poses.summary.json: counts, model/calibration snapshots, units, coordinate conventions, time basis and quality thresholds.
  • output/sample_tracked.mp4: annotated video.

assets/starter/reference_camera.json and ground_truth.csv describe the known synthetic camera and motion. The quick start deliberately estimates calibration from the checkerboard clip instead of using the reference values. Regenerate all sample inputs with python -m aruco_pose kit sample --output output/new_sample.

Use a real camera: print -> calibrate -> track -> CSV

1. Print and mount the targets

python -m aruco_pose kit print --output output/print

Open the SVGs in a browser and print at 100% / actual size, with fit-to-page, headers and footers disabled. Targets are A4. Verify the 50 mm reference line and measure the black marker squares: they must be 40 mm wide, with 20 mm gaps. Mount the entire marker board flat on rigid backing; do not rearrange the markers. The checkerboard is a separate target with 9 x 6 inner corners and 20 mm squares. Keep it flat too. Inspect the print for clipping or smudged black/white cells.

The generated board.json defines the exact four-marker layout, IDs 0-3 in DICT_5X5_100. Keep it with its printed target. Never use a model with a different printed scale or arrangement.

2. Calibrate at your tracking resolution

python -m aruco_pose kit calibrate --source 0 --preview --output output/my_camera.json

Show the complete checkerboard and press SPACE to capture each view. Move and tilt it between captures: near/far, left/right, top/bottom, with varied angles. Use at least 8 distinct observations; aim for 20-30. Press Q to solve, or let capture stop at 40 accepted views. Keep camera resolution, focus and zoom fixed between calibration and tracking. The command reports RMS reprojection error; values above 1 pixel prompt a warning. Low RMS alone does not establish accuracy.

For a checkerboard video instead, pass its path and choose --stride 10 (or a suitable interval). Change --cols, --rows and --square-size only when using a different measured calibration target. Camera indexes such as 0 and 1 are supported. If you need a particular capture resolution, configure the camera beforehand and confirm it remains unchanged for both steps.

3. Track and export

python -m aruco_pose kit track --source 0 --model output/print/board.json --calibration output/my_camera.json --csv output/my_poses.csv --preview --output-video output/my_tracking.mp4

Press Q to stop. For a recorded board video, replace 0 with its path. At least two recognized board markers are required by default. --min-markers 1 permits single-marker estimates but increases planar-pose ambiguity. Unknown IDs are ignored. The shared solver rejects corner/marker outliers before fitting. A pose is rejected without majority support, when inlier reprojection RMSE exceeds --max-error (default 3 pixels), or when accepted points have invalid depth. Close planar alternatives are reported as ambiguous unless a recent compatible measurement resolves the choice. No prediction is substituted for a missing measurement. The entire CSV remains available after a normal quit.

Understand the CSV

Columns Meaning
frame, time_s Zero-based frame and elapsed seconds; video time is frame/FPS, camera time is monotonic host receipt time.
object_id, status starter_board; measured, lost, rejected, or ambiguous.
marker_ids, marker_count Accepted inlier marker IDs separated by semicolons, and their count.
tx_m, ty_m, tz_m Board origin in camera coordinates, in meters.
qx, qy, qz, qw Unit quaternion rotating board coordinates into camera coordinates.
reprojection_rmse_px Root mean squared 2D corner-distance residual; not a physical accuracy estimate.

Transform: p_camera = R_object_to_camera @ p_object + t_object_to_camera. Camera axes: x right, y down, z forward. Board origin: center of the four-marker layout, x printed right, y printed down, z into the paper. This is not a robot's world-frame pose. Lost/rejected/ambiguous rows have blank position/quaternion fields. Do not replace blanks with zeros or carry forward old poses without labeling them.

File timestamps assume constant frame rate. Camera timestamps describe host frame receipt, not hardware exposure time. The calibration resolution is checked against every frame; mismatches fail rather than silently scaling camera intrinsics.

Troubleshooting

  • No detections: verify print scale/dictionary, lighting, focus, full black borders and white margins; move closer until the markers occupy more pixels.
  • Not enough calibration views: show the complete checkerboard, use inner-corner counts, and vary its position/tilt. Reduce video stride for short clips.
  • Wrong physical distance: measure the print and verify the matching model. Calibration square size and marker positions must be in meters.
  • Pose flips/jitter: planar boards have ambiguous poses in difficult views; improve viewing angle, resolution and lighting. The shared solver rejects corner/marker outliers and flags close planar alternatives; a recent compatible measurement may resolve them. It does not smooth poses or substitute predictions for missing observations.
  • Video cannot open/write: confirm the path and codec. Output .avi uses MJPG; other output extensions use mp4v (use .mp4).
  • Python command fails: choose an installed interpreter explicitly; do not reuse an old virtual environment pointing at a removed Python installation.

Shared Python pose API

The CLI and updated tracking examples now share Tracker and PoseResult:

from aruco_pose import Tracker, TrackerConfig
# model is an explicit-corner model dict; K/D are camera intrinsics/distortion.
tracker = Tracker(model, K, D, config=TrackerConfig(min_markers=2))
result = tracker.process(frame, timestamp_s=timestamp_s, previous=previous_result)
if result.pose is not None:
    position_m = result.pose.translation_m
    quaternion_xyzw = result.pose.quaternion_xyzw

See the complete API guide for a runnable example, transform conventions, outlier/ambiguity policies and legacy adapters. Run python examples/pose_api_demo.py --preview for a looping camera-free Python example. It writes no data files unless --csv PATH is passed. Stop with Q, Escape, window close or Ctrl+C; use --seconds 20 for a time limit, or --once for one pass. The CSV/summary schema is version 2: old columns are preserved, with support, reason, candidate and frame diagnostics appended. Read fields by name and handle ambiguous rows.

See package migration notes when updating an existing installation or imports from the old src namespace.

Development and other examples

python -m pip install -e ".[dev]"
python -m pytest -q

The starter kit commands are the supported end-to-end path. Older top-level CLI commands and examples are experimental and have different formats. Dodecahedron tracking remains available under examples/04_custom_models/; see model scaling before using the saved 17 mm and 25 mm models. The flat starter board uses a separate explicit-corner model, not those legacy JSON formats. Roadmap describes remaining target tooling and robotics integrations.

Sample assets are generated by this repository and covered by its Apache 2.0 license.

Acknowledgements

Built on OpenCV ArUco and inspired by the original GSNCodes ArUco examples. See LICENSE for the existing Apache 2.0 terms.

The release review records verification evidence, packaging/media scope and remaining physical-validation limits.

Metadata

Release files for aruco-pose 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aruco-pose 0.3.0
File Size Uploaded Provenance Actions
aruco_pose-0.3.0.tar.gz 3.8 MB Without provenance Details for aruco_pose-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aruco-pose 0.3.0
File Interpreter ABI Platform Actions
aruco_pose-0.3.0-py3-none-any.whl Python 3 none any Details for aruco_pose-0.3.0-py3-none-any.whl

Total release size: 3.9 MB

Release files / aruco_pose-0.3.0.tar.gz

Download URL aruco_pose-0.3.0.tar.gz
Size 3.8 MB
Tags Source
SHA-256 checksum
How to use checksums
79a913e58cea2889c8c70090f3c28430520a4f4e500a08c369aec2cfbc4814e0
BLAKE2b-256 checksum
How to use checksums
e4e01d8342dcf5e0fc18373cecc4498696efe02e54bf1500fbcc04a87fbff0c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.4

Release files / aruco_pose-0.3.0-py3-none-any.whl

Download URL aruco_pose-0.3.0-py3-none-any.whl
Size 60.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7d7578142574415cc4d46cd37a8e2e7fd0adacd6b38573ab53adcce77a407dea
BLAKE2b-256 checksum
How to use checksums
c4a03d5cc1dbf9e99de5530682d3521b8b8e45a8b71e8695de8e39b06b694056
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.4

Security for aruco-pose 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page