visual-cataloguer 0.2.1

Batch catalogue physical collections using visual dividers (QR codes) and automated image processing

visual-cataloguer

Batch catalogue physical collections using visual dividers (QR codes) and automated image processing.

The Problem

You have thousands of items (retro games, books, vinyl, tools) in boxes. You need them in a searchable database. Manual entry would take weeks.

The Solution

1. Print QR code dividers (one per box)
2. Photograph: divider → items → items → black frame → divider → ...
3. Run viscatalog process ./photos
4. Browse your collection via web UI or CLI

How It Works

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Load Image  │────▶│  Classify   │────▶│   Process   │
│ (ARW/JPG)   │     │ Image Type  │     │ Accordingly │
└─────────────┘     └─────────────┘     └─────────────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
     ┌──────────┐    ┌──────────┐    ┌──────────┐
     │   BOX    │    │  BLACK   │    │   GAME   │
     │ DIVIDER  │    │  FRAME   │    │   ITEM   │
     └──────────┘    └──────────┘    └──────────┘

• Box Divider: QR code or text (e.g., "BOX-1") - starts a new box
• Black Frame: Dark image - ends current box
• Game Item: Everything else - catalogued with OCR

Features

• Merges photos from multiple cameras by EXIF timestamp
• QR code detection (OpenCV) + OCR fallback (Tesseract)
• RAW file support (.ARW Sony files via rawpy)
• SQLite database with JPEG BLOBs (single portable file)
• SHA256 deduplication for resume capability
• Web interface for browsing, searching, and editing
• Mobile-friendly UI (works on iPad/phone)
• Robust error recovery (auto-creates UNKNOWN boxes for missed dividers)

Installation

# From PyPI
pip install visual-cataloguer

# With web interface support
pip install visual-cataloguer[web]

# Or clone and install
git clone https://github.com/retroverse-studios/visual-cataloguer.git
cd visual-cataloguer
uv sync --extra web

System dependencies:

• Tesseract OCR - brew install tesseract

Usage

Process Images

# Process images from two cameras
viscatalog process \
    --input-dir-1 ./NEX3N \
    --input-dir-2 ./RX100 \
    --database ./collection.db

# View statistics
viscatalog stats -d ./collection.db

# List boxes
viscatalog list --boxes -d ./collection.db

# Search items
viscatalog search "zelda" -d ./collection.db

Web Interface

# Start the web server
viscatalog serve -d ./collection.db --port 8000

# Then open http://localhost:8000

The web interface provides:

• Browse: Grid view of all items with thumbnails
• Search: Full-text search across titles and OCR text
• Filter: By box, platform, completeness, listed/unlisted status
• Edit: Update titles, platforms, notes, and box assignments
• eBay workflow: Mark items as listed

API

The web server exposes a REST API:

# List items
curl http://localhost:8000/api/items

# Search
curl "http://localhost:8000/api/search?q=zelda"

# Get item details
curl http://localhost:8000/api/items/123

# Update item (e.g., reassign to different box)
curl -X PATCH http://localhost:8000/api/items/123 \
  -H "Content-Type: application/json" \
  -d '{"box_id": "BOX-5", "title_manual": "Legend of Zelda"}'

# Mark as listed on eBay
curl -X PATCH http://localhost:8000/api/items/123/mark-listed

# Get stats
curl http://localhost:8000/api/stats

Full API docs at http://localhost:8000/docs

Development

# Run tests
uv run pytest

# Type checking
uv run mypy cataloguer

# Linting
uv run ruff check cataloguer

License

MIT License - see LICENSE