aruco–pose GitHub
SOURCE 0.3.0 PRINTED TARGET → CAMERA → ROBOTICSWhat’s new

VISUAL POSE ESTIMATION / OPEN SOURCE

Many faces.
One pose.

A printed 3D target becomes a reference frame for your robot, experiment or tracking application. Combine visible faces into one object pose, then use it through Python, CSV or ROS 2.

pip install aruco-pose

Start with the synthetic replay, or print and assemble the target.
Physical jitter reduction is not yet benchmarked.

DODECAHEDRON / SYNTHETIC REPLAY6 DOF
Changing faces. One reference point.Synthetic replay · 25 mm edges · no camera footage
TRANSFORM object → cameraPOSITION metersROTATION quaternion
One originTarget center + orientation
12 facesOne known rigid layout
Visible supportMultiple markers, one pose
Your workflowPython + CSV + ROS 2

01 / FROM PRINT TO MEASUREMENT

A reference frame,
in four straightforward steps.

No special tracking hardware to get started. Just a printed target, a calibrated camera, and a model that matches what you built.

  1. 01

    Print a target

    Assemble the twelve-face target, or mount a flat board on rigid backing. Print at actual size and measure the reference line. Open the flat board ↗

    Get the 3D target 25 mm target edges / matching model
  2. 02

    Calibrate your camera

    Capture varied views of the checkerboard. Keep focus, zoom and resolution fixed between calibration and tracking.

    Open the checkerboard 9 × 6 inner corners / 20 mm squares
  3. 03

    Track the object

    Combine visible markers into one rigid-object pose. Inspect inliers, rejected corners and competing planar solutions.

    Explore the pose API Object → camera / meters
  4. 04

    Use the result

    Stream results into your Python application, or explicitly export CSV for plots, replay and further analysis.

    See the CSV fields Translation / quaternion / quality

DEMO 02 / A TARGET IN THREE DIMENSIONS

New face.
Same reference frame.

A dodecahedron puts markers on twelve faces of one rigid target. As it turns, different markers come into view; their known geometry connects each observation to the same object frame.

This synthetic 25 mm-edge target is rendered, then detected and tracked through the shared pose API. The colored axes and visible edge overlay come from the estimated pose.

Get the dodecahedron kit

Preview the print sheet ↗ · Read the instructions ↗

A4 PDF + SVG, numbered faces and glue tabs, matching model, raw replay and reference camera. Prototype papercraft geometry; physical accuracy is not yet validated.

12 FACES / ONE RIGID OBJECTDEMO 02
Follow the object, across its faces.Synthetic 3D replay · 10 seconds · no camera footage

Replay it. Then build it.

Extract the kit and open a terminal inside its dodecahedron folder. These commands track the raw video and export CSV. Add --preview for a window.

For a physical target, print at 100%, match the edge labels, and calibrate your own camera using the included checkerboard. Follow the kit’s README for assembly and camera commands.

CAMERA-FREE / 240 FRAMES
pip install aruco-pose
python -m aruco_pose kit track --source tracking.mp4 --model model.json --calibration replay_camera.json --csv output/replay.csv

02 / TRY IT FOR YOURSELF

A first pose.
No camera required.

Generate the sample inputs, calibrate from the checkerboard clip, then track the board. Add a preview window or keep everything headless.

The sample includes total tracking loss and partial occlusion. Missing observations stay missing; they never turn into a stale “measurement.”

Download the sample pack

Synthetic clips, reference camera, ground truth and printable targets.

TERMINAL / PYTHON 3.9+
pip install aruco-pose

# Create synthetic clips and printable targets
aruco-pose kit sample --output sample

# Estimate the camera from 30 checkerboard views
aruco-pose kit calibrate --source sample/calibration.mp4 --stride 1 --output camera.json

# Track and explicitly export every frame
aruco-pose kit track --source sample/tracking.mp4 --model sample/board.json --calibration camera.json --csv poses.csv --preview
YOUR APPLICATION.PYONE SHARED API
from aruco_pose import Tracker

tracker = Tracker(model, camera_matrix, distortion)
result = tracker.process(frame, timestamp_s=time_s)

if result.pose is not None:
    position_m = result.pose.translation_m
    quaternion = result.pose.quaternion_xyzw
else:
    # lost, rejected, or ambiguous — no invented pose
    print(result.status, result.reason)

Pass your model, calibration, image and timestamp. See a complete runnable example ↗

03 / MORE THAN DRAWING AN AXIS

Know what your
estimate is built on.

01

Reject bad observations

Corner and whole-marker rejection keeps a coherent majority in the fit, with the exclusions exposed in the result.

02

Make ambiguity visible

Close planar solutions are reported as ambiguous. An explicitly supplied, recent compatible measurement may select a branch.

03

Keep frames and units explicit

Object-to-camera transforms, meter translations and x/y/z/w quaternions. No implicit world frame or invented confidence score.

04 / FROM CAMERA STREAM TO ROS FRAME

Give your robot
a measured reference.

Connect raw or rectified camera topics, or start with the synthetic replay. The optional Jazzy example brings the same pose API into ROS 2, with acquisition timestamps and an explicit status.

  1. 01 / INPUTImage + CameraInfoChoose raw or rectified pixels.
  2. 02 / ESTIMATEOne rigid-target poseVisible markers, checked geometry.
  3. 03 / PUBLISHPose · TF · StatusOne acquisition timestamp.
OPTIONAL EXAMPLE / ROS 2 JAZZY

Your camera frame stays your camera frame.

Rectified input uses the supplied projection and rectification geometry. Published poses return to the original optical frame, with translations in meters and a unit quaternion.

Lost, rejected, ambiguous or stale inputs produce invalid status. They do not refresh an old pose or TF. Downstream applications still need to check status and age.

Set up ROS 2 and try the replay

ROS is installed separately. Examples live in the GitHub checkout; PyPI provides the core CLI and API. This example does not command robot motion.

RECTIFIED CAMERA / FROM THE CHECKOUT
python examples/ros2/target_pose_node.py --image-topic /camera/image_rect --camera-info-topic /camera/camera_info --camera-frame camera_color_optical_frame --image-space rectified --model assets/dodecahedron/model.json
After the guide’s ROS setup, replace the topic and optical-frame names with your driver’s. Use --image-space raw for raw pixels.
PARENTcamera optical frame
CHILDtarget object frame

05 / BUILD SOMETHING WITH IT

A useful building block.
A clear boundary.

Inspect a robot fixture. Follow a handheld target. Give a classroom experiment a visible coordinate frame.

Start with a printable board or the twelve-face target, then use the Python API, CSV workflow or ROS 2 bridge. The core package stays independent of ROS.

Docking and landmark-navigation integrations remain roadmap work. Real-world accuracy depends on printing, geometry, calibration and imaging conditions; the synthetic demos are software demonstrations, not precision benchmarks.

Read the roadmap

PRINT SOMETHING. TRACK SOMETHING.

Start with a sheet of paper.

Get the code