70 lines
2.8 KiB
Markdown
70 lines
2.8 KiB
Markdown
# Bookmark
|
|
|
|
A camera-driven book intake and checkout inventory system, built for
|
|
[Books in Hand](https://git.opensourcesolarpunk.com/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)
|
|
|
|
1. A downward-facing webcam looks at a fixed platform with printed
|
|
nested size-boundary markers (small / medium / large).
|
|
2. A volunteer centers the book; capture fires automatically or on a
|
|
button press (configurable).
|
|
3. 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.
|
|
4. 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+.
|
|
|
|
```bash
|
|
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`.
|