Metadata-Version: 2.4
Name: fiducial-targets
Version: 0.0.1.dev1
Summary: Print-ready calibration target generation (chessboards, circle grids, AprilTag, ArUco) with cairo-rendered PDF/SVG/PNG output.
Project-URL: Homepage, https://vistralis.org/fiducial-targets
Project-URL: Documentation, https://vistralis.org/fiducial-targets/docs
Project-URL: Source, https://github.com/vistralis/fiducial-targets
Project-URL: Issues, https://github.com/vistralis/fiducial-targets/issues
Project-URL: Changelog, https://github.com/vistralis/fiducial-targets/blob/main/CHANGELOG.md
Author-email: Vistralis Labs <support@vistralis.org>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: apriltag,aruco,calibration,chessboard,circle-grid,computer-vision,fiducial,marker-generation,robotics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.10
Requires-Dist: fiducial>=0.0.1.dev1
Requires-Dist: numpy>=1.24
Requires-Dist: pycairo>=1.25
Requires-Dist: pypdf>=4.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pillow>=10.0; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# fiducial-targets

![CI](https://github.com/vistralis/fiducial-targets/actions/workflows/ci.yml/badge.svg)
[![PyPI](https://img.shields.io/pypi/v/fiducial-targets)](https://pypi.org/project/fiducial-targets/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

**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.

```bash
pip install fiducial-targets
```

Imports live under the `fiducial.targets` namespace (the package ships
as a subpackage of [`fiducial`](https://pypi.org/project/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

```python
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`](https://pypi.org/project/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](https://github.com/AprilRobotics/apriltag).
- ArUco predefined dictionaries: Apache-2.0, from
  [opencv/opencv_contrib](https://github.com/opencv/opencv_contrib).

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

## Development

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

## License

Apache-2.0 — see [LICENSE](LICENSE).

Copyright (c) 2026 Vistralis Labs.
