$ show wlfcss/PlumeLens
PlumeLens (ι΄ηΏ) is a local bird photo analysis and culling workstation for bird photographers. It uses on-device ML modelsβYOLOv26l for detection, a custom 11-keypoint pose estimator, CLIPIQA+/HyperIQA for quality assessment, and DINOv3 with LoRA adapters for species classificationβto process photos without any cloud upload. The system scans user photo directories (read-only), performs detection, pose estimation, quality scoring, and species identification, then presents a grading interface (reject/record/usable/select) with manual review and species override capabilities. Export supports JPG/RAW with XMP sidecars, and a geographic archive module visualizes species sightings on an interactive map with conservation status. The architecture is a desktop application split into an Electron+React frontend and a Python FastAPI backend. The backend runs as a subprocess managed by Electron, communicating via REST APIs and Server-Sent Events for progress. The ML pipeline is orchestrated in `engine/pipeline/manager.py` with ONNX Runtime and PyTorch inferences. The frontend uses React 19, TanStack Query, Zustand, and a virtualized grid for handling large photo sets. The application is packaged for macOS (arm64) via electron-builder and PyInstaller. While the primary delivery is a desktop application, the repository also contains extensive model training scripts, evaluation frameworks (`evals/`), and dataset preparation utilities, making it a hybrid project with significant research and data engineering components. Model integrity is enforced via SHA-256 manifest verification at startup, and all inference is deterministic with versioned pipeline hashes to invalidate caches on updates.
The LLM identified 5 files worth highlighting for reuse:
Implements a robust async task queue with a strict state machine (TaskStatus), illegal transition detection, permanent failure identification via error string patterns, a stuck task sweeper, and configurable max retry attempts (MAX_ATTEMPTS=3). Self-contained and decoupled from business logic, it can be extracted as a generic task queue for any async processing pipeline.
A responsive virtual grid layout that uses ResizeObserver and requestAnimationFrame throttling to efficiently render photo grids with scroll margin support. It handles grouped and flat modes with stack expansion. The implementation is framework-agnostic (plain TypeScript) and can be reused in any web application needing a performant, reactive grid.
Provides process-level caching of SHA-256 hash verification for all model assets (ONNX, PyTorch, calibration JSON). It ensures model integrity at startup and during pipeline initialization, preventing silent corruption. The pattern of manifest-driven verification with version pinning is reusable for any application that ships ML models.
Manages thumbnail repair operations with a cooldown queue to avoid thrashing the backend. It queues repair requests, applies a debounce timeout, and triggers batch repair via a custom hook. The pattern is reusable for any UI component that needs to handle deferred background repair tasks with rate limiting.
Implements a reverse geocoding service with a chain of providers (Amap, Baidu, Tencent, Nominatim, offline GeoNames) and an LRU cache keyed by geographic coordinates at ~110m resolution to reduce API quota consumption. The provider fallback pattern and resolution-rounded caching are reusable for any geocoding integration.