fiducial-targets

Print-ready calibration target generation. A Python library that produces millimetre-accurate PDF, SVG, and PNG outputs for chessboards, circle grids, AprilTag, ArUco, and arbitrary mixes of the above — with a YAML sidecar describing the geometry detectors need.

pip install fiducial-targets

Imports live under the fiducial.targets namespace (the package ships as a subpackage of fiducial — see Relationship to fiducial below).

What ships in v0.0.1.dev1

• Target composition — stack pattern groups and ad-hoc placements in the same target frame, in any mix.
• Patterns:
  • checkerboard — boards of arbitrary size.
  • circles — symmetric / asymmetric grids, interleaved two-radius grids, WhyCon-style ring grids, concentric ring patterns, plain dots and solid discs.
  • apriltag — single markers and boards for nine families (tag16h5, tag25h9, tag36h10, tag36h11, tagCircle21h7, tagCircle49h12, tagCustom48h12, tagStandard41h12, tagStandard52h13). IDs assigned top-down to match calib.io and OpenCV-aruco conventions.
  • aruco — single markers and boards for the predefined OpenCV dictionaries.
  • centering_disk, origin_marker — CCC origin markers, solid-disc origins, four-sector centering disks.
• Composites — chessboard + AprilTag (chessboard_apriltag) and chessboard + ArUco (chessboard_aruco) with markers inset in the white squares.
• Standard footer — Target.add_standard_footer(title, parameters) places an axis-orientation reference plus title and parameter captions below the content extent, never overlapping ink.
• CairoRenderer with three explicit methods: render_pdf, render_svg, render_png. Pure-cairo, mm-accurate via a single Context.scale.
• YAML sidecar emitted next to every output, with bounding box, per-placement geometry, per-group keypoints, and footer metadata.
• ISO 216 paper formats (A0–A6) with a landscape switch and a custom-size override.

Quick start

from pathlib import Path
from fiducial.targets import Target, PageSize, CairoRenderer
from fiducial.targets.patterns import checkerboard, circles

target = Target()
target.add(checkerboard.board(columns=7, rows=6, square_size=25.0))
target.add(circles.dot(center=(200.0, 50.0), radius=8.0))
target.add_standard_footer(
    title="Chess 7x6 + auxiliary dot",
    parameters=("square=25mm", "dot r=8mm"),
)

CairoRenderer().render_pdf(target, PageSize.named("A4"), Path("board.pdf"))

All length values are millimetres. Non-mm quantities carry an explicit suffix (_px, _pt).

Relationship to fiducial

fiducial-targets is the generator half of a two-package split. fiducial is the application- facing detection library — that's where production code lives and where the target-description data contract is owned. This package generates the printable targets fiducial consumes, with a YAML sidecar that documents the ground-truth layout.

Both packages converge at v0.1.0, at which point fiducial-targets will source its payload dataclasses from fiducial (no API change on either side; users continue to write from fiducial.targets import ...).

Status

Early development. The public surface is intentionally small while both packages stabilise toward the joint v0.1.0 cut. Expect minor imports to shift, but the surfaces named above are the ones intended to ship.

IP / attribution

All shipping code is original to this project. The .npz data tables under src/fiducial/targets/_codes/ are upstream code dictionaries:

• AprilTag families: BSD-2-Clause, from AprilRobotics/apriltag.
• ArUco predefined dictionaries: Apache-2.0, from opencv/opencv_contrib.

Attribution is preserved in NOTICE.md files alongside each table.

Development

pip install -e ".[dev]"
ruff check .
ruff format --check .
pytest

License

Apache-2.0 — see LICENSE.

Copyright (c) 2026 Vistralis Labs.