Metadata-Version: 2.4
Name: ringgrid
Version: 0.2.6
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 :: Rust
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Dist: numpy>=1.23
Requires-Dist: matplotlib>=3.7 ; extra == 'viz'
Provides-Extra: viz
Summary: Python bindings for ringgrid detector
Home-Page: https://github.com/VitalyVorobyev/ringgrid
Author-email: Vitaly Vorobyev <vit.vorobiev@gmail.com>
License: MIT OR Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://vitalyvorobyev.github.io/ringgrid/book/
Project-URL: Homepage, https://github.com/VitalyVorobyev/ringgrid
Project-URL: Repository, https://github.com/VitalyVorobyev/ringgrid

# ringgrid (Python)

Python bindings for the `ringgrid` detector, powered by PyO3 + maturin.

## Install (from source)

```bash
pip install maturin
maturin develop -m crates/ringgrid-py/Cargo.toml --release
```

## Features

- Native `Detector` API with NumPy input support
- Full `DetectionResult` model objects with JSON round-trips
- Optional plotting helpers in `ringgrid.viz` (`pip install ringgrid[viz]`)

## Input Rules

- `Detector.detect(...)` accepts:
  - `np.ndarray` with `dtype=uint8` and shape `(H, W)` (grayscale)
  - `np.ndarray` with `dtype=uint8` and shape `(H, W, 3|4)` (RGB/RGBA, auto-converted to grayscale)
  - image file path (`str` or `pathlib.Path`)
- Other dtypes/shapes raise `TypeError`.

## Examples

Run from repository root after `maturin develop`:

```bash
python crates/ringgrid-py/examples/basic_detect.py \
  --image testdata/target_3_split_00.png \
  --out testdata/target_3_split_00_det_py.json

python crates/ringgrid-py/examples/detect_with_camera.py \
  --image testdata/target_3_split_00.png \
  --out testdata/target_3_split_00_det_cam_py.json
```

Plotting example (requires matplotlib extra):

```bash
pip install -e crates/ringgrid-py[viz]
python crates/ringgrid-py/examples/plot_detection.py \
  --image testdata/target_3_split_00.png \
  --out testdata/target_3_split_00_overlay_py.png
```

