Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ethz-asl/kalibr/llms.txt

Use this file to discover all available pages before exploring further.

An AprilGrid is a regular grid of AprilTag fiducial markers arranged with a fixed spacing between adjacent tags. Unlike a plain checkerboard, every tag in the grid carries a unique binary ID, so the detector can identify individual tags even when parts of the board are out of frame or occluded. This makes the AprilGrid the recommended target for all Kalibr calibration workflows.

​
YAML configuration

Create a YAML file that describes the physical layout of your printed target. Pass this file to any Kalibr command with --target aprilgrid.yaml. 
target_type: 'aprilgrid'
tagCols: 6           # number of tags in the horizontal direction
tagRows: 6           # number of tags in the vertical direction
tagSize: 0.088       # side length of one tag in meters
tagSpacing: 0.3      # gap between tags as a fraction of tagSize

​
Field reference

FieldTypeDescription
target_typestringMust be 'aprilgrid'
tagColsintNumber of tags along the x-axis (minimum 3)
tagRowsintNumber of tags along the y-axis (minimum 3)
tagSizefloatPhysical side length of one printed tag, in meters
tagSpacingfloatGap between adjacent tags expressed as a fraction of tagSize (e.g. 0.3 means the gap is 30% of the tag side length)
tagSize must match the physically measured side length of one tag on your printed target. Measure with calipers after printing — do not rely on the nominal value you used when generating the PDF.

​
Generating the PDF

Use kalibr_create_target_pdf to produce a print-ready PDF: 
kalibr_create_target_pdf --type apriltag --nx 6 --ny 6 --tsize 0.08 --tspace 0.3
This generates a target.pdf file in the current directory. The arguments correspond directly to the YAML fields:
CLI flagYAML fieldDescription
--nxtagColsNumber of tags horizontally
--nytagRowsNumber of tags vertically
--tsizetagSizeTag side length in meters
--tspacetagSpacingSpacing as a fraction of tag size

​
Choosing a tag family

AprilTags come in several families that differ in the number of data bits and error correction. Use --tfam to select one:
FamilyData bitsNotes
t36h1136Default. Most codes available, highest robustness.
t25h925Fewer codes; slightly larger data bits relative to border.
t25h725Less error correction than t25h9.
t16h516Fewest codes; use only when tags must be printed very small.
kalibr_create_target_pdf --type apriltag --nx 6 --ny 6 --tsize 0.08 --tspace 0.3 --tfam t36h11
Keep the default t36h11 family unless you have a specific reason to change it. It provides the most tag codes and best detection robustness.

​
Skipping tag IDs

If you need to leave certain positions blank — for example to avoid IDs that are already in use by other tags in your environment — use --skip-ids: 
kalibr_create_target_pdf --type apriltag --nx 6 --ny 6 --tsize 0.08 --tspace 0.3 --skip-ids "0 5 10"
Provide IDs as a space-separated list. The corresponding grid positions will be left empty.

​
Saving an EPS file

Add --eps to also write an EPS vector file alongside the PDF: 
kalibr_create_target_pdf --type apriltag --nx 6 --ny 6 --tsize 0.08 --tspace 0.3 --eps
See kalibr_create_target_pdf for the complete flag reference.

​
Printing and mounting

1

Print at 100% scale

Open the PDF and disable any fit-to-page or scaling option in your printer dialog. Print at exactly 100% so the dimensions in the PDF correspond to real-world measurements.
2

Mount on a rigid surface

Glue or tape the printout to a flat, rigid backing such as an aluminum composite panel or thick foam board. Any warping will introduce systematic calibration errors.
3

Measure and update the YAML

Use calipers to measure the physical side length of one printed tag. Update tagSize in your YAML file to this measured value.

​
How detection works

The Kalibr detector locates each AprilTag independently by decoding its binary ID. It then refines the four corner positions of each tag to subpixel accuracy. The symmetric black squares printed at the inter-tag corners help with this subpixel refinement under motion blur by providing symmetric gradient patterns. Because each tag is uniquely identified, the detector can:
  • Recover observations from frames where only part of the board is visible
  • Reject false detections that would confuse an ID-less pattern like a checkerboard
  • Robustly associate detected corners with known 3D positions on the target
If the detector reports no corners for many frames, check that your tagSize and tagSpacing values in the YAML match the printed target. A mismatch in expected geometry is a common cause of failed detection.

Build docs developers (and LLMs) love

Get started for freeTalk to us