pyr0ball
c28afe0ac4
Wires together AppConfig.load() (JSON config -> markers/guide_box), calibrate.py (one-time empty-platform reference capture), and run.py (build_strategy dispatch + camera/session/FastAPI wiring via uvicorn) to complete Phase 1 intake station integration. |
||
|---|---|---|
| bookmark | ||
| tests | ||
| .gitignore | ||
| AGENTS.md | ||
| calibrate.py | ||
| CLAUDE.md | ||
| config.example.json | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| pyproject.toml | ||
| README.md | ||
| run.py | ||
Bookmark
A camera-driven book intake and checkout inventory system, built for Books in Hand, a nonprofit that keeps books out of landfills and in people's hands.
Bookmark replaces manual book logging with a guided, camera-based workflow: a volunteer places a book on a marked platform, the system photographs the front and back, sorts it into a size category for tax/reporting purposes, and later backfills the catalogue with title, author, and ISBN — all running on local hardware, no cloud dependency.
This project is fully open source and is being built and donated as volunteer/client work — it isn't part of any commercial product line.
Status
Early / active development. The intake station (Phase 1) is being built now. Not yet runnable end-to-end.
| Phase | What it does | Status |
|---|---|---|
| 1 — Intake station | Camera capture, guided front/back flow, deterministic size bucketing, CSV catalogue | In progress |
| 2 — Batch OCR/ISBN backfill | Barcode decode + local vision-LLM fallback to fill in title/author/ISBN | Planned |
| 3 — Checkout station | Track books leaving inventory, reusing the intake identification pipeline | Planned |
How it works (Phase 1)
- A downward-facing webcam looks at a fixed platform with printed nested size-boundary markers (small / medium / large).
- A volunteer centers the book; capture fires automatically or on a button press (configurable).
- The system photographs the front, determines size — deterministically, by checking which physical markers are covered, not by any AI/ML step — then prompts the volunteer to flip the book and photographs the back.
- Every book gets a row in a CSV catalogue: images, size bucket, and a status that later pipeline stages (OCR backfill, checkout) update.
Full design rationale lives in AGENTS.md (also readable as CLAUDE.md —
same file, symlinked for compatibility with different AI coding tools).
Why this matters for a nonprofit
- No cloud costs, no vendor lock-in. Everything runs on donated hardware; no per-book or per-scan fees.
- Deterministic where it counts. Size-bucket counts feed Books in Hand's year-end tax and 501(c)(3) reporting — that number is computed from physical measurements, not inferred by a model, so it can't drift or hallucinate.
- Volunteer-friendly. The intake flow is designed to be usable by volunteers with no technical background — guided steps, big buttons, no login required.
Development
Requires Python 3.11+.
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest -v
Full setup, calibration, and end-to-end testing instructions will land here once the intake station is runnable (tracked in the project's implementation plan).
License
MIT — see LICENSE.