nanofractal 0.1.0__tar.gz

nanofractal-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: build & test (system OpenCV)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install OpenCV dev headers
+        run: sudo apt-get update && sudo apt-get install -y libopencv-dev
+      - name: Build and install
+        run: pip install -e ".[test]"
+      - name: Run tests
+        run: python -m pytest tests -q --ignore tests/test_benchmarks.py

nanofractal-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,48 @@
+name: release
+
+# Build portable manylinux wheels + sdist and publish to PyPI on a version tag.
+# Push a tag like v0.1.0 to trigger a release:
+#   git tag v0.1.0 && git push origin v0.1.0
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  wheels:
+    name: Build wheels (manylinux x86_64)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build wheels (cibuildwheel + static OpenCV)
+        run: pipx run cibuildwheel --output-dir wheelhouse
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels
+          path: wheelhouse/*.whl
+
+  sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build sdist
+        run: pipx run build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: Publish to PyPI
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

nanofractal-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+build/
+dist/
+*.egg-info/
+__pycache__/
+*.so
+.pytest_cache/
+.benchmarks/
+_skbuild/
+.venv/
+# secrets — never commit a real token
+.pypirc
+.env
+docs/

nanofractal-0.1.0/CMakeLists.txt

@@ -0,0 +1,47 @@
+cmake_minimum_required(VERSION 3.18)
+project(nanofractal LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+find_package(Python 3.9 COMPONENTS Interpreter Development.Module REQUIRED)
+
+# Locate nanobind shipped with the build environment
+execute_process(
+  COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+  OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE nanobind_ROOT)
+list(APPEND CMAKE_PREFIX_PATH "${nanobind_ROOT}")
+find_package(nanobind CONFIG REQUIRED)
+
+# OpenCV: system by default. CI (Plan B) overrides via -DOpenCV_DIR=<minimal build>
+find_package(OpenCV REQUIRED COMPONENTS core imgproc calib3d features2d)
+
+nanobind_add_module(_nanofractal NB_STATIC src/_bindings.cpp)
+
+target_include_directories(_nanofractal PRIVATE
+  "${CMAKE_SOURCE_DIR}/third_party"
+  "${CMAKE_SOURCE_DIR}/src"
+  ${OpenCV_INCLUDE_DIRS})
+target_link_libraries(_nanofractal PRIVATE ${OpenCV_LIBS})
+
+# Release already implies -O3 on GCC/Clang; keep it explicit but MSVC-safe.
+target_compile_options(_nanofractal PRIVATE
+  $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-O3>)
+
+# Single source of truth for the version: injected by scikit-build-core from
+# pyproject.toml. Falls back for non-skbuild direct cmake builds.
+if(DEFINED SKBUILD_PROJECT_VERSION)
+  set(_NF_VERSION "${SKBUILD_PROJECT_VERSION}")
+else()
+  set(_NF_VERSION "0.0.0")
+endif()
+target_compile_definitions(_nanofractal PRIVATE NF_VERSION="${_NF_VERSION}")
+
+include(CheckIPOSupported)
+check_ipo_supported(RESULT _ipo_ok OUTPUT _ipo_msg)
+if(_ipo_ok)
+  set_property(TARGET _nanofractal PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
+endif()
+
+install(TARGETS _nanofractal LIBRARY DESTINATION nanofractal)

nanofractal-0.1.0/DEV.md

@@ -0,0 +1,33 @@
+# Development notes
+
+## Environment
+
+Use the project virtualenv at `.venv` for all builds and tests:
+
+```bash
+.venv/bin/python -m pip install -e ".[test]"
+```
+
+### IMPORTANT: strip PYTHONPATH when running Python/pytest
+
+This machine sources a ROS (Jazzy) + Livox workspace in the shell, which sets a
+`PYTHONPATH` pointing at `/opt/ros/jazzy/...` and a `ws_livox` workspace. Those
+directories contain pytest plugins (ament/launch_testing_ros) that get
+autoloaded and crash during collection (e.g. `ModuleNotFoundError: No module
+named 'yaml'`). The fix is to unset `PYTHONPATH` for our commands:
+
+```bash
+env -u PYTHONPATH .venv/bin/python -m pytest tests/ -v
+env -u PYTHONPATH .venv/bin/python -m pip install -e ".[test]"
+```
+
+Always prefix Python/pytest invocations with `env -u PYTHONPATH`.
+
+## Build
+
+The extension is built by scikit-build-core + CMake (nanobind). A normal
+editable install recompiles after C++ changes:
+
+```bash
+env -u PYTHONPATH .venv/bin/python -m pip install -e ".[test]"
+```

nanofractal-0.1.0/PATCHES.md

@@ -0,0 +1,39 @@
+# Patches to vendored headers
+
+We vendor `third_party/aruco_nano_v6.h` and `third_party/nanofractal.h` from
+upstream and keep them as close to upstream as possible. The unmodified upstream
+of `nanofractal.h` is recoverable from git history (the commit immediately before
+the patch described below). The only intentional divergences are listed here.
+
+## third_party/nanofractal.h — guard the inner-point path against empty FAST keypoints
+
+**Symptom:** `FractalMarkerDetector::detect(img, p3d, p2d)` (the `with_inner_points`
+path) segfaulted on valid `uint8` images when `cv::FastFeatureDetector` returned
+zero keypoints (e.g. clean/synthetic markers with no sub-cell texture).
+
+**Root cause:** `_private::kfilter()` did `kpoints[0].response` without checking
+for an empty vector; downstream, the picoflann kdtree `radiusSearch` would also
+index an empty index.
+
+**Patch (2 guards):**
+1. In `kfilter()`: `if (kpoints.empty()) return;` before touching `kpoints[0]`.
+2. In `detect(img, p3d, p2d)`, after `assignClass`: `if (kpoints.empty()) return detected;`
+   so the kdtree matching is skipped and the markers are returned with empty
+   `p2d`/`p3d`.
+
+Both are marked inline with `// nanofractal patch:` comments. With no keypoints
+there are simply no inner-corner correspondences, which is the correct result.
+
+Regression tests: `tests/test_fractal.py::test_detect_with_inner_points_empty_is_safe`
+(clean image → empty, no crash) and `::test_detect_with_inner_points_nonempty`
+(noisy image → populated correspondences).
+
+## Both headers — remove unused `#include <opencv2/highgui.hpp>`
+
+`aruco_nano_v6.h` and `nanofractal.h` each `#include <opencv2/highgui.hpp>`, but
+their detection/pose/draw code paths call **no** highgui functions (highgui only
+appears in the example snippets in the file comments, e.g. `imread`/`imwrite`).
+The include is removed (replaced by a `// nanofractal patch:` comment) so the
+library builds against a **minimal OpenCV** without the `highgui` module — which
+is how the portable wheels are built in CI (`ci/build-opencv.sh`). Builds against
+a full system OpenCV are unaffected.

nanofractal-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.1
+Name: nanofractal
+Version: 0.1.0
+Summary: High-performance fiducial marker detection (ArUco Nano v6 + Fractal)
+License: Apache-2.0
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-benchmark>=4; extra == "test"
+Description-Content-Type: text/markdown
+
+# nanofractal
+
+High-performance fiducial-marker detection for Python. `nanofractal` wraps two
+compact, header-only C++ detectors with [nanobind](https://github.com/wjakob/nanobind):
+
+- **ArUco Nano v6** — square markers (`ARUCO_MIP_36h12` and AprilTag `36h11`).
+- **Fractal markers** — nested markers that stay detectable under heavy occlusion
+  and expose many inner corner correspondences for accurate, long-range pose.
+
+It is built for speed: **zero-copy** NumPy ↔ `cv::Mat`, the **GIL is released**
+during detection, and a **parallel batch** API scales across cores.
+
+```text
+single-frame detect():   ~0.43 ms @ 640x480   ~1.3 ms @ 1280x720   ~2.9 ms @ 1920x1080
+batch detect_batch():    ~3.2x throughput on 4 threads
+```
+
+> Measured on a desktop CPU with `max_attempts=1`; your numbers will vary.
+
+---
+
+## Installation
+
+```bash
+pip install nanofractal
+```
+
+Wheels bundle a minimal OpenCV, so no system OpenCV is required at runtime.
+
+### Build from source
+
+You need a C++17 compiler, CMake ≥ 3.18 and a development OpenCV
+(`core`, `imgproc`, `calib3d`, `features2d`):
+
+```bash
+# Debian/Ubuntu
+sudo apt-get install -y build-essential cmake libopencv-dev
+
+pip install .
+```
+
+---
+
+## Quick start
+
+Inputs are plain NumPy `uint8` arrays — either `(H, W)` grayscale or `(H, W, 3)`
+BGR, and **C-contiguous** (use `np.ascontiguousarray` if unsure). Any image loader
+works; the examples use OpenCV.
+
+### Detect ArUco / AprilTag markers
+
+```python
+import cv2
+import nanofractal as nf
+
+image = cv2.imread("scene.png")                  # (H, W, 3) uint8 BGR
+det = nf.ArucoDetector(nf.Dict.ARUCO_MIP_36h12)  # or nf.Dict.APRILTAG_36h11
+
+res = det.detect(image)
+print(res.ids)        # int32   (N,)       e.g. [ 7 42]
+print(res.corners)    # float32 (N, 4, 2)  clockwise corners, subpixel
+```
+
+### Estimate pose
+
+`estimate_pose` runs `solvePnP` (IPPE) for every detected marker at once.
+
+```python
+import numpy as np
+
+camera_matrix = np.array([[600, 0, 320],
+                          [0, 600, 240],
+                          [0,   0,   1]], dtype=np.float64)
+dist_coeffs = np.zeros(5, dtype=np.float64)
+
+rvecs, tvecs = det.estimate_pose(res.corners, camera_matrix, dist_coeffs,
+                                 marker_size=0.05)   # marker side in metres
+# rvecs, tvecs: float64 (N, 3) — rotation (Rodrigues) and translation per marker
+```
+
+### Detect fractal markers
+
+```python
+fdet = nf.FractalDetector("FRACTAL_5L_6", marker_size=0.85)  # size in metres (optional)
+
+res = fdet.detect(image)
+print(res.ids, res.corners.shape)   # outer 4 corners of each fractal marker
+```
+
+### Fractal pose + visualization (occlusion-robust)
+
+`FractalDetector.estimate_pose` returns one marker pose `(rvec, tvec, reproj_err)`
+or `None`. It uses every visible inner **and** outer corner correspondence when
+available (accurate, robust to occlusion) and otherwise falls back to the four
+outer corners — so you never call `solvePnP` yourself or worry about the
+empty-inner-points case. `reproj_err` (RMS pixels) lets you gate noisy poses.
+
+```python
+fdet = nf.FractalDetector("FRACTAL_5L_6", marker_size=0.85)  # size in metres
+
+res = fdet.detect(image, with_inner_points=True)
+pose = fdet.estimate_pose(res, camera_matrix, dist_coeffs)
+if pose is not None:
+    rvec, tvec, reproj_err = pose      # rvec, tvec: float64 (3,); reproj_err: px
+    fdet.draw(image, res, camera_matrix, dist_coeffs, rvec, tvec)  # corners + axes
+```
+
+`draw(image, result, ...)` overlays marker outlines, ids and (given a pose) the
+frame axes in place — no `cv2.polylines`/`drawFrameAxes` boilerplate. Without a
+pose, `fdet.draw(image, res)` just draws the outlines.
+
+The raw correspondences are still exposed if you prefer to run PnP yourself:
+
+```python
+res.points_2d   # float32 (M, 2) image points  (None unless with_inner_points=True)
+res.points_3d   # float32 (M, 3) object points (planar, z = 0)
+```
+
+### Parallel batch (offline throughput)
+
+Process many frames across a thread pool. The GIL is released, so it scales with
+cores. `num_threads=0` uses all cores.
+
+```python
+frames = [cv2.imread(p) for p in paths]            # list of uint8 arrays
+results = det.detect_batch(frames, num_threads=0)  # list[DetectionResult]
+for r in results:
+    print(r.ids)
+```
+
+---
+
+## API
+
+### `ArucoDetector(dictionary=Dict.ARUCO_MIP_36h12, max_attempts=1)`
+- `dictionary: Dict` — `ARUCO_MIP_36h12` or `APRILTAG_36h11`.
+- `max_attempts: int` — retries per candidate with small corner jitter. `1` is
+  fastest (real-time default); raise (up to ~10) for harder images.
+- `detect(image) -> DetectionResult`
+- `detect_batch(images, num_threads=0) -> list[DetectionResult]`
+- `estimate_pose(corners, camera_matrix, dist_coeffs, marker_size) -> (rvecs, tvecs)`
+  — `corners` is `(N, 4, 2)` float32; outputs are `(N, 3)` float64.
+
+### `FractalDetector(config, marker_size=-1.0)`
+- `config: str` — one of `FRACTAL_2L_6`, `FRACTAL_3L_6`, `FRACTAL_4L_6`,
+  `FRACTAL_5L_6`.
+- `marker_size: float` — outer marker side in metres; if set, `points_3d` is
+  returned in metres (otherwise normalized).
+- `detect(image, with_inner_points=False) -> DetectionResult`
+- `detect_batch(images, num_threads=0) -> list[DetectionResult]`
+- `estimate_pose(result, camera_matrix, dist_coeffs) -> (rvec, tvec, reproj_err) | None`
+  — single-marker pose; uses inner+outer points when ≥ 4, else the 4 outer
+  corners; `rvec`/`tvec` are float64 `(3,)`, `reproj_err` is RMS pixels.
+- `draw(image, result, camera_matrix=None, dist_coeffs=None, rvec=None, tvec=None, axis_length=None) -> image`
+  — draw outlines + ids (and frame axes when a pose is given) in place; `image`
+  must be a writable BGR `uint8` array.
+
+### `DetectionResult`
+| field | dtype / shape | meaning |
+|-------|---------------|---------|
+| `ids` | int32 `(N,)` | marker ids |
+| `corners` | float32 `(N, 4, 2)` | outer corners (subpixel, clockwise) |
+| `points_2d` | float32 `(M, 2)` or `None` | inner+outer image points (fractal, `with_inner_points=True`) |
+| `points_3d` | float32 `(M, 3)` or `None` | matching object points |
+
+Empty results are returned as correctly-shaped empty arrays (`(0,)`, `(0, 4, 2)`),
+never `None`.
+
+### Errors
+- Wrong dtype / non-contiguous input → `TypeError`.
+- Unsupported shape, empty frame, invalid dictionary or fractal config → `ValueError`.
+
+---
+
+## Performance notes
+
+- **Zero-copy input.** A contiguous `uint8` array is wrapped as a `cv::Mat` over
+  the same buffer — no copy. Non-contiguous or wrong-dtype inputs raise instead of
+  silently copying.
+- **GIL released** during the native detection, so other Python threads keep
+  running and `detect_batch` scales.
+- **Thread safety.** The ArUco detector is stateless and shared across batch
+  workers. The fractal detector is not thread-safe, so `detect_batch` uses a pool
+  of independent detectors (one per worker). A single detector object is fine to
+  call from one thread at a time.
+
+---
+
+## Citation
+
+If you use this in research, please cite the original work:
+
+- F. J. Romero-Ramirez, R. Muñoz-Salinas, R. Medina-Carnicer,
+  *"Speeded up detection of squared fiducial markers"*, Image and Vision
+  Computing, 76, 2018.
+- S. Garrido-Jurado, R. Muñoz-Salinas, F. J. Madrid-Cuevas, R. Medina-Carnicer,
+  *"Generation of fiducial marker dictionaries using mixed integer linear
+  programming"*, Pattern Recognition, 51, 2016.
+- F. J. Romero-Ramirez, R. Muñoz-Salinas, R. Medina-Carnicer,
+  *"Fractal Markers: A New Approach for Long-Range Marker Pose Estimation Under
+  Occlusion"*, IEEE Access, 7, 2019.
+
+## License
+
+Apache-2.0. The vendored detectors (ArUco Nano, Fractal markers) are © their
+authors and used under their terms; see `third_party/` and `PATCHES.md`.

nanofractal-0.1.0/PUBLISHING.md

@@ -0,0 +1,42 @@
+# Publishing to PyPI
+
+Releases are automated by GitHub Actions (`.github/workflows/release.yml`):
+pushing a version tag builds portable `manylinux` wheels (with a minimal static
+OpenCV linked in — see `ci/build-opencv.sh`) plus an sdist, and uploads them to
+PyPI.
+
+## One-time setup: PyPI token as a repo secret
+
+The release workflow authenticates with a PyPI API token stored as the GitHub
+Actions secret **`PYPI_API_TOKEN`**.
+
+- GitHub → repo → Settings → Secrets and variables → Actions → New repository secret
+- Name: `PYPI_API_TOKEN`
+- Value: a token from https://pypi.org/manage/account/token/ (starts with `pypi-`)
+
+(Or, instead of `gh`'s web UI: `gh secret set PYPI_API_TOKEN`.)
+
+## Cut a release
+
+```bash
+# bump version in pyproject.toml first if needed, commit, then:
+git tag v0.1.0
+git push origin main
+git push origin v0.1.0     # this triggers the release workflow -> PyPI
+```
+
+Each release needs a **new version** — PyPI rejects re-uploading an existing one.
+Pushing to `main` only runs the fast `ci` checks; it does **not** publish.
+
+## Manual / local publish (fallback)
+
+`.pypirc` at the repo root (git-ignored) holds your token for manual uploads:
+
+```bash
+.venv/bin/python -m pip install build twine
+.venv/bin/python -m build
+.venv/bin/python -m twine upload --config-file .pypirc -r pypi dist/*
+```
+
+Note: a locally built wheel links your **system OpenCV** and is not portable —
+use it only for a TestPyPI smoke test. The CI wheels are the portable ones.

nanofractal-0.1.0/README.md

@@ -0,0 +1,206 @@
+# nanofractal
+
+High-performance fiducial-marker detection for Python. `nanofractal` wraps two
+compact, header-only C++ detectors with [nanobind](https://github.com/wjakob/nanobind):
+
+- **ArUco Nano v6** — square markers (`ARUCO_MIP_36h12` and AprilTag `36h11`).
+- **Fractal markers** — nested markers that stay detectable under heavy occlusion
+  and expose many inner corner correspondences for accurate, long-range pose.
+
+It is built for speed: **zero-copy** NumPy ↔ `cv::Mat`, the **GIL is released**
+during detection, and a **parallel batch** API scales across cores.
+
+```text
+single-frame detect():   ~0.43 ms @ 640x480   ~1.3 ms @ 1280x720   ~2.9 ms @ 1920x1080
+batch detect_batch():    ~3.2x throughput on 4 threads
+```
+
+> Measured on a desktop CPU with `max_attempts=1`; your numbers will vary.
+
+---
+
+## Installation
+
+```bash
+pip install nanofractal
+```
+
+Wheels bundle a minimal OpenCV, so no system OpenCV is required at runtime.
+
+### Build from source
+
+You need a C++17 compiler, CMake ≥ 3.18 and a development OpenCV
+(`core`, `imgproc`, `calib3d`, `features2d`):
+
+```bash
+# Debian/Ubuntu
+sudo apt-get install -y build-essential cmake libopencv-dev
+
+pip install .
+```
+
+---
+
+## Quick start
+
+Inputs are plain NumPy `uint8` arrays — either `(H, W)` grayscale or `(H, W, 3)`
+BGR, and **C-contiguous** (use `np.ascontiguousarray` if unsure). Any image loader
+works; the examples use OpenCV.
+
+### Detect ArUco / AprilTag markers
+
+```python
+import cv2
+import nanofractal as nf
+
+image = cv2.imread("scene.png")                  # (H, W, 3) uint8 BGR
+det = nf.ArucoDetector(nf.Dict.ARUCO_MIP_36h12)  # or nf.Dict.APRILTAG_36h11
+
+res = det.detect(image)
+print(res.ids)        # int32   (N,)       e.g. [ 7 42]
+print(res.corners)    # float32 (N, 4, 2)  clockwise corners, subpixel
+```
+
+### Estimate pose
+
+`estimate_pose` runs `solvePnP` (IPPE) for every detected marker at once.
+
+```python
+import numpy as np
+
+camera_matrix = np.array([[600, 0, 320],
+                          [0, 600, 240],
+                          [0,   0,   1]], dtype=np.float64)
+dist_coeffs = np.zeros(5, dtype=np.float64)
+
+rvecs, tvecs = det.estimate_pose(res.corners, camera_matrix, dist_coeffs,
+                                 marker_size=0.05)   # marker side in metres
+# rvecs, tvecs: float64 (N, 3) — rotation (Rodrigues) and translation per marker
+```
+
+### Detect fractal markers
+
+```python
+fdet = nf.FractalDetector("FRACTAL_5L_6", marker_size=0.85)  # size in metres (optional)
+
+res = fdet.detect(image)
+print(res.ids, res.corners.shape)   # outer 4 corners of each fractal marker
+```
+
+### Fractal pose + visualization (occlusion-robust)
+
+`FractalDetector.estimate_pose` returns one marker pose `(rvec, tvec, reproj_err)`
+or `None`. It uses every visible inner **and** outer corner correspondence when
+available (accurate, robust to occlusion) and otherwise falls back to the four
+outer corners — so you never call `solvePnP` yourself or worry about the
+empty-inner-points case. `reproj_err` (RMS pixels) lets you gate noisy poses.
+
+```python
+fdet = nf.FractalDetector("FRACTAL_5L_6", marker_size=0.85)  # size in metres
+
+res = fdet.detect(image, with_inner_points=True)
+pose = fdet.estimate_pose(res, camera_matrix, dist_coeffs)
+if pose is not None:
+    rvec, tvec, reproj_err = pose      # rvec, tvec: float64 (3,); reproj_err: px
+    fdet.draw(image, res, camera_matrix, dist_coeffs, rvec, tvec)  # corners + axes
+```
+
+`draw(image, result, ...)` overlays marker outlines, ids and (given a pose) the
+frame axes in place — no `cv2.polylines`/`drawFrameAxes` boilerplate. Without a
+pose, `fdet.draw(image, res)` just draws the outlines.
+
+The raw correspondences are still exposed if you prefer to run PnP yourself:
+
+```python
+res.points_2d   # float32 (M, 2) image points  (None unless with_inner_points=True)
+res.points_3d   # float32 (M, 3) object points (planar, z = 0)
+```
+
+### Parallel batch (offline throughput)
+
+Process many frames across a thread pool. The GIL is released, so it scales with
+cores. `num_threads=0` uses all cores.
+
+```python
+frames = [cv2.imread(p) for p in paths]            # list of uint8 arrays
+results = det.detect_batch(frames, num_threads=0)  # list[DetectionResult]
+for r in results:
+    print(r.ids)
+```
+
+---
+
+## API
+
+### `ArucoDetector(dictionary=Dict.ARUCO_MIP_36h12, max_attempts=1)`
+- `dictionary: Dict` — `ARUCO_MIP_36h12` or `APRILTAG_36h11`.
+- `max_attempts: int` — retries per candidate with small corner jitter. `1` is
+  fastest (real-time default); raise (up to ~10) for harder images.
+- `detect(image) -> DetectionResult`
+- `detect_batch(images, num_threads=0) -> list[DetectionResult]`
+- `estimate_pose(corners, camera_matrix, dist_coeffs, marker_size) -> (rvecs, tvecs)`
+  — `corners` is `(N, 4, 2)` float32; outputs are `(N, 3)` float64.
+
+### `FractalDetector(config, marker_size=-1.0)`
+- `config: str` — one of `FRACTAL_2L_6`, `FRACTAL_3L_6`, `FRACTAL_4L_6`,
+  `FRACTAL_5L_6`.
+- `marker_size: float` — outer marker side in metres; if set, `points_3d` is
+  returned in metres (otherwise normalized).
+- `detect(image, with_inner_points=False) -> DetectionResult`
+- `detect_batch(images, num_threads=0) -> list[DetectionResult]`
+- `estimate_pose(result, camera_matrix, dist_coeffs) -> (rvec, tvec, reproj_err) | None`
+  — single-marker pose; uses inner+outer points when ≥ 4, else the 4 outer
+  corners; `rvec`/`tvec` are float64 `(3,)`, `reproj_err` is RMS pixels.
+- `draw(image, result, camera_matrix=None, dist_coeffs=None, rvec=None, tvec=None, axis_length=None) -> image`
+  — draw outlines + ids (and frame axes when a pose is given) in place; `image`
+  must be a writable BGR `uint8` array.
+
+### `DetectionResult`
+| field | dtype / shape | meaning |
+|-------|---------------|---------|
+| `ids` | int32 `(N,)` | marker ids |
+| `corners` | float32 `(N, 4, 2)` | outer corners (subpixel, clockwise) |
+| `points_2d` | float32 `(M, 2)` or `None` | inner+outer image points (fractal, `with_inner_points=True`) |
+| `points_3d` | float32 `(M, 3)` or `None` | matching object points |
+
+Empty results are returned as correctly-shaped empty arrays (`(0,)`, `(0, 4, 2)`),
+never `None`.
+
+### Errors
+- Wrong dtype / non-contiguous input → `TypeError`.
+- Unsupported shape, empty frame, invalid dictionary or fractal config → `ValueError`.
+
+---
+
+## Performance notes
+
+- **Zero-copy input.** A contiguous `uint8` array is wrapped as a `cv::Mat` over
+  the same buffer — no copy. Non-contiguous or wrong-dtype inputs raise instead of
+  silently copying.
+- **GIL released** during the native detection, so other Python threads keep
+  running and `detect_batch` scales.
+- **Thread safety.** The ArUco detector is stateless and shared across batch
+  workers. The fractal detector is not thread-safe, so `detect_batch` uses a pool
+  of independent detectors (one per worker). A single detector object is fine to
+  call from one thread at a time.
+
+---
+
+## Citation
+
+If you use this in research, please cite the original work:
+
+- F. J. Romero-Ramirez, R. Muñoz-Salinas, R. Medina-Carnicer,
+  *"Speeded up detection of squared fiducial markers"*, Image and Vision
+  Computing, 76, 2018.
+- S. Garrido-Jurado, R. Muñoz-Salinas, F. J. Madrid-Cuevas, R. Medina-Carnicer,
+  *"Generation of fiducial marker dictionaries using mixed integer linear
+  programming"*, Pattern Recognition, 51, 2016.
+- F. J. Romero-Ramirez, R. Muñoz-Salinas, R. Medina-Carnicer,
+  *"Fractal Markers: A New Approach for Long-Range Marker Pose Estimation Under
+  Occlusion"*, IEEE Access, 7, 2019.
+
+## License
+
+Apache-2.0. The vendored detectors (ArUco Nano, Fractal markers) are © their
+authors and used under their terms; see `third_party/` and `PATCHES.md`.