fiducial 0.0.1.dev1

Fiducial — Fiducial-marker detection toolkit for computer vision and robotics

fiducial

Fiducial-marker detection, fast. A clean Python API for detecting AprilTag, ArUco, ChArUco, and chessboard targets on top of an extensible C++ core with optional CUDA acceleration.

pip install fiducial

Public API

The package exposes three building blocks plus a detectors namespace for concrete implementations.

Symbol	Kind	Description
fiducial.Detector	typing.Protocol (runtime-checkable)	detect(image) -> list[Marker]
fiducial.Marker	frozen dataclass	family, id, points, detector_meta
fiducial.Observation	frozen dataclass	pixel, point_3d, point_id
fiducial.detectors.AprilTagDetector	class	conforms to Detector

Any object that implements detect(image) satisfies the protocol — there is no required base class.

Architecture

Top-level public API:

• fiducial.Detector — typing.Protocol (runtime-checkable). Method: detect(image: np.ndarray) -> list[Marker].
• fiducial.Marker — frozen dataclass. Fields: family: str, id: int | None, points: list[Observation], detector_meta: dict.
• fiducial.Observation — frozen dataclass. Fields: pixel: tuple[float, float], point_3d: tuple[float, float, float], point_id: int | None.

fiducial.detectors namespace exposes one entry:

• AprilTagDetector — conforms to the Detector protocol.

src/fiducial/
├── __init__.py          Public re-exports + version
├── _core.py             Detector protocol + Marker / Observation
└── detectors/
    ├── __init__.py      Detector implementations namespace
    └── apriltag.py      AprilTagDetector

The native core is a small C++17 / nanobind extension (_fiducial) with optional CUDA support (-DBUILD_CUDA=ON).

Status

fiducial is in early development. The public surface is intentionally small while the detector backends are being built out.

Documentation

Full documentation will be available at vistralis.org/fiducial.

Development

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

To build with CUDA support:

pip install -e ".[dev]" \
    --config-settings=cmake.define.BUILD_CUDA=ON

License

Apache-2.0 — see LICENSE for details.

Copyright (c) 2026 Vistralis Labs.