OPEN SOURCE · PYTHON · APACHE 2.0
Turn paper
into pose.
A practical toolkit for turning printed markers into a useful reference frame. Calibrate a camera, track a rigid object, and take its 3D pose into your next experiment.
pip install aruco-poseA camera is optional. Start with the included synthetic replay.
Watch the 3D target
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.
- 01
Print a target
Print at actual size and mount the whole board on a flat, rigid surface. Measure the reference line before tracking.
Open the marker board 40 mm markers / 20 mm gaps - 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 - 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 - 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 kitPreview 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.
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.
pip install aruco-pose
python -m aruco_pose kit track --source tracking.mp4 --model model.json --calibration replay_camera.json --csv output/replay.csv02 / 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 packSynthetic clips, reference camera, ground truth and printable targets.
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 --previewfrom 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.
Reject bad observations
Corner and whole-marker rejection keeps a coherent majority in the fit, with the exclusions exposed in the result.
Make ambiguity visible
Close planar solutions are reported as ambiguous. An explicitly supplied, recent compatible measurement may select a branch.
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.
- 01 / INPUTImage + CameraInfoChoose raw or rectified pixels.
- 02 / ESTIMATEOne rigid-target poseVisible markers, checked geometry.
- 03 / PUBLISHPose · TF · StatusOne acquisition timestamp.
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 replayROS is installed separately. Examples live in the GitHub checkout; PyPI provides the core CLI and API. This example does not command robot motion.
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--image-space raw for raw pixels.camera optical frametarget object frame05 / 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 roadmapPRINT SOMETHING. TRACK SOMETHING.