birdpreen 0.5.0

Scan macOS Photos library, detect and identify birds, write species captions

preen

Groom your photo library — automatically find and name every bird.

Preen scans your macOS Photos library, detects birds with YOLO, identifies species with SuperPicky's OSEA classifier (10,964 species), and writes bilingual keywords and captions.

Features

• Scans entire Photos library including iCloud photos
• YOLO multi-bird detection — finds all birds in a photo
• OSEA species identification with GPS-based eBird regional filtering
• Keywords: 白鹭 (Little Egret) + pinyin bailu per species
• Captions: 白鹭, 苍鹭 (Little Egret, Grey Heron)
• Parallel iCloud downloads via PhotoKit (no Photos.app dependency for reads)
• SQLite checkpoint — pause/resume, incremental or full rescan
• Auto-retries failed iCloud exports on next run
• Supports JPEG, HEIC, JXL, AVIF, and RAW formats (ARW, CR2, CR3, NEF, DNG, RAF)

Requirements

• macOS with Photos.app
• Python 3.11+

Installation

pipx install birdpreen

Or with pip:

pip install birdpreen

On first scan, model files (~260 MB) are automatically downloaded from HuggingFace.

Usage

# Scan new photos (incremental)
preen scan

# Full library rescan
preen scan --full

# Dry run — detect and identify without writing
preen scan --dry-run

# Custom confidence threshold (default: 70%)
preen scan --threshold 65

# Process in batches
preen scan --batch-size 500

# Adjust parallel iCloud downloads (default: 16)
preen scan --workers 32

# Regional filter for photos without GPS (uses AVONET distribution data)
preen scan --country CN

# Regional filter using eBird species lists (more curated, supports subnational)
preen scan --region US-CA

# Scan a Shanghai photo library with English-only captions
preen scan --region CN-31 --caption-format "{en}" --keyword-format "{en} {latin}"

# Scan UK photos with Latin names, slash-separated
preen scan --country GB --caption-format "{en} ({latin})" --caption-separator " / "

# Stricter threshold when no regional filter matches (default: 90%)
preen scan --global-threshold 95

# Rescan unidentified birds with a lower global threshold
# Only re-processes photos where birds were detected but not identified
preen scan --threshold 60 --global-threshold 85

# Check progress
preen status

# Reset checkpoint (auto-creates backup)
preen reset

# Restore checkpoint from latest backup
preen restore

Regional species filtering

When photos have GPS, preen automatically filters species using a two-level fallback: AVONET 1×1° grid → country-level eBird list → global. For photos without GPS, use --country or --region:

• --country XX — queries AVONET distribution data using a bounding box. Covers 49 countries including CH, HK, TW, NP where eBird lists aren't bundled.
• --region XX or --region XX-YY — uses curated offline eBird species lists. Supports 51 countries + 92 subnational regions (all US states, CN provinces, AU states). Falls back to country-level if subnational file not found.

Caption and keyword format

The --caption-format flag controls how each species appears in the photo description. The --keyword-format flag controls which fields become individual keywords (space-delimited). Available placeholders:

Placeholder	Example
{cn}	白鹭
{cn_trad}	白鷺
{en}	Little Egret
{latin}	Egretta garzetta
{pinyin}	bailu

Tuning --workers

The --workers flag controls how many iCloud photos are downloaded in parallel (default: 16). The scan output shows a queue indicator like q:12/16 — ready/total. "Ready" means downloaded and waiting for the GPU; "total" is the queue size.

• If ready often drops to 0, downloads can't keep up — increase workers
• If queue is often full (e.g. q:16/16), GPU is the bottleneck — check for other GPU-intensive processes
• If you have plenty of RAM (each queued image uses ~50-100MB), 32 workers is safe
• For sequential processing (most reliable), use --workers 1

Credits

• OSEA bird classification model (10,964 species) by Sun Jiao
• Bird identification logic (OSEA classifier, AVONET geographic filtering, eBird species data) extracted from SuperPicky
• YOLO11 segmentation model by Ultralytics
• Photos library access via PhotoKit through PyObjC