Metadata-Version: 2.4
Name: birdpreen
Version: 0.1.1
Summary: Scan macOS Photos library, detect and identify birds, write species captions
Author: Dazhen Pan
License: AGPL-3.0-or-later
Keywords: birds,photos,macos,identification,osea,yolo
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: osxphotos>=0.68.0
Requires-Dist: Pillow>=9.0.0
Requires-Dist: pillow-heif>=0.10.0
Requires-Dist: pi-heif
Requires-Dist: ultralytics>=8.0.0
Requires-Dist: torch>=2.0.0
Requires-Dist: torchvision
Requires-Dist: numpy>=1.20.0
Requires-Dist: huggingface_hub
Requires-Dist: photoscript>=0.3.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# 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](https://gitcode.com/Jamesphotography/SuperPicky/tree/master)'s OSEA classifier (10,964 species), and writes "中文名 (English Name)" as captions — visible on iPhone.

## 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
- Writes captions via persistent Photos.app connection (photoscript)
- SQLite checkpoint — pause/resume, incremental or full rescan
- Deduplicates species in multi-bird captions

## Requirements

- macOS with Photos.app
- Python 3.11+

## Installation

```bash
pipx install birdpreen
```

Or with pip:

```bash
pip install birdpreen
```

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

## Usage

```bash
# 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

# Check progress
preen status

# Reset checkpoint to start over
preen reset
```

## Credits

- OSEA bird classification model (10,964 species) by [Sun Jiao](https://gitcode.com/sunjiao)
- Bird identification logic (OSEA classifier, AVONET geographic filtering, eBird species data) extracted from [SuperPicky](https://gitcode.com/Jamesphotography/SuperPicky/tree/master)
- YOLO11 segmentation model by [Ultralytics](https://github.com/ultralytics/ultralytics)
- Photos library access via [osxphotos](https://github.com/RhetTbull/osxphotos)
- Photos.app integration via [photoscript](https://github.com/RhetTbull/photoscript)
