Metadata-Version: 2.4
Name: fiducial
Version: 0.0.1.dev1
Summary: Fiducial — Fiducial-marker detection toolkit for computer vision and robotics
Keywords: fiducial,marker-detection,apriltag,aruco,charuco,computer-vision,robotics,calibration,cuda
Author-Email: Vistralis Labs <support@vistralis.org>
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: C++
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
Project-URL: Homepage, https://vistralis.org/fiducial
Project-URL: Documentation, https://vistralis.org/fiducial/docs
Project-URL: Source, https://github.com/vistralis/fiducial
Project-URL: Issues, https://github.com/vistralis/fiducial/issues
Project-URL: Changelog, https://github.com/vistralis/fiducial/blob/main/CHANGELOG.md
Requires-Python: >=3.10
Requires-Dist: numpy>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Description-Content-Type: text/markdown

# fiducial

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

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

```bash
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](https://vistralis.org/fiducial).

## Development

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

To build with CUDA support:

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

## License

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

Copyright (c) 2026 Vistralis Labs.
