fiducial-targets 0.0.1.dev1__tar.gz

fiducial_targets-0.0.1.dev1/.gitignore

@@ -0,0 +1,15 @@
+.claude/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+examples/output/
+examples/output_verification/

fiducial_targets-0.0.1.dev1/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1.dev1] — 2026-06-04
+
+First public dev release. Versioned to match the sibling
+[`fiducial`](https://pypi.org/project/fiducial/) detection library, with
+which this package converges at v0.1.0.
+
+### Added
+
+- **Composition core** — `Target`, `Placement`, `PlacementGroup`. Stack
+  pattern groups and ad-hoc placements in the same target frame; mix
+  any combination.
+- **Concrete placements** — `CheckerboardSquare`, `CircleDot`, `Ring`
+  (Concentric Contrasting Circle / Gatrell), `CenteringDisk`,
+  `AprilTagMarker`, `ArucoMarker`, `Axes`, `Caption`.
+- **Patterns** (`fiducial.targets.patterns`):
+  - `checkerboard` — `board(...)`, `square(...)`.
+  - `circles` — `dot`, `grid` (symmetric / asymmetric / interleaved
+    two-radius), `ring`, `ccc`, `ring_grid` (WhyCon-style),
+    `concentric_rings`, `origin_marker`.
+  - `apriltag` — `marker(...)` and `board(...)` for nine families
+    (`tag16h5`, `tag25h9`, `tag36h10`, `tag36h11`, `tagCircle21h7`,
+    `tagCircle49h12`, `tagCustom48h12`, `tagStandard41h12`,
+    `tagStandard52h13`). Bitmap layout is an independent implementation
+    (no upstream code port).
+  - `aruco` — `marker(...)` and `board(...)` for the predefined OpenCV
+    dictionaries (`DICT_4X4_1000`, `DICT_5X5_1000`, `DICT_6X6_1000`,
+    `DICT_7X7_1000`, `DICT_ARUCO_ORIGINAL`, four `DICT_APRILTAG_*`
+    aliases).
+  - `centering_disk` — `disk(...)` (N-sector centring target, default
+    four quadrants).
+- **Composites** (`fiducial.targets.composites`):
+  - `chessboard_apriltag` — checkerboard with AprilTags in white
+    squares (ChArUco-style placement).
+  - `chessboard_aruco` — checkerboard with ArUco markers in white
+    squares.
+  - `corner_quads` — optional corner-refinement quads for AprilTag
+    boards.
+- **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. The footer
+  geometry is recorded in the YAML sidecar.
+- **Content-only bounding box** —
+  `Target.bounding_box(include_annotations=False)`.
+- **Rendering** — `CairoRenderer` with explicit `render_pdf`,
+  `render_svg`, `render_png` methods. Pure-cairo, mm-accurate via a
+  single `Context.scale`. Rendered PDFs carry
+  `/ViewerPreferences { /PrintScaling /None }` so viewers default to
+  Actual Size / 100 % rather than Fit to Page.
+- **YAML sidecar** via `sidecar.write_sidecar` — bounding box,
+  per-placement geometry, per-group keypoints (saddle points for
+  chessboards, dot centres for circles, corners for markers), and
+  footer metadata.
+- **ID ordering** — board and composite ID assignment matches
+  calib.io / OpenCV-aruco convention: ID 0 at the top-left in print
+  space, incrementing left-to-right then top-to-bottom.
+- **Page sizes** — ISO 216 A0–A6 with a landscape switch, plus a
+  custom-size override. Custom canvases have no landscape mode (swap
+  the width/height arguments instead); the `landscape=` flag only
+  applies to named paper formats.
+- **`Color`** with named factory methods.
+- **Examples** — per-marker example scripts under `examples/`:
+  `apriltag.py`, `aruco.py`, `checkerboard.py`, `circles.py`,
+  `composites.py`, `origin_markers.py`, plus
+  `print_verification.py` (physical-print ruler + per-marker
+  dimension checks) and `_validate_calib_io.py` (visual validation
+  against a calib.io-generated reference).
+- **CI workflow** — ruff + pytest on Python 3.10–3.14, x86_64 +
+  arm64.
+- **Release workflow** — tag-triggered sdist + wheel build with PyPI
+  trusted publishing. Tags are pushed manually; no auto-tagging.
+- **Apache-2.0 license.**
+
+### Packaging
+
+- Distribution name: `fiducial-targets`. Import path: `fiducial.targets`
+  (same pattern as `opencv-contrib-python` → `cv2`). The wheel writes
+  only `fiducial/targets/`; the `fiducial/__init__.py` is provided by
+  the sibling `fiducial` distribution.
+- Runtime dependencies: `fiducial>=0.0.1.dev1`, `numpy>=1.24`,
+  `pycairo>=1.25`, `pypdf>=4.0`, `pyyaml>=6.0`.
+
+### Notes on attribution
+
+The `.npz` files 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).
+
+All shipping code (the renderer, the bit decoders, the composition
+machinery) is original to this project. Attribution for the data
+tables is preserved in `NOTICE.md` files alongside each table. Any
+prior port or vendor-tooling code has been removed from the shipping
+surface (the package no longer depends on upstream rendering code).

fiducial_targets-0.0.1.dev1/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Vistralis Labs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

fiducial_targets-0.0.1.dev1/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE README.md CHANGELOG.md
+include pyproject.toml
+recursive-include src/fiducial/targets *.py *.npz NOTICE.md
+prune .github
+prune tests
+prune examples
+prune _quarantine

fiducial_targets-0.0.1.dev1/PKG-INFO

@@ -0,0 +1,155 @@
+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.

fiducial_targets-0.0.1.dev1/README.md

@@ -0,0 +1,118 @@
+# 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.