Open-source tools for herbarium digitization workflows
Generic, reusable tools for reviewing and analyzing digitized herbarium specimens. Built to work with Darwin Core data from any herbarium digitization project.
Tools Included:
- 📱 Mobile PWA Review Interface - Touch-optimized specimen review for tablets and phones
- 📊 Analytics Utilities - DuckDB-based analysis for specimen data
- 📝 Example Workflows - Sample pipelines and usage patterns
Progressive Web App for reviewing specimen extractions on mobile devices.
Key Features:
- Touch-optimized UI for tablets and phones
- Offline support for field work
- Darwin Core field editing
- GBIF validation display
- Priority-based workflow
- Image viewer with Fit/1:1/Fullscreen modes
- Native pinch-zoom with iOS fullscreen fallback
- Username-only auth (network trust model)
- Structured logging and request tracking
Use Cases:
- Field curation on tablets
- Mobile review during collection visits
- Remote specimen validation
- Offline data refinement
DuckDB-based analysis for extracted specimen data.
Key Features:
- Field coverage analysis
- Confidence score distributions
- Quality assessment
- Bulk data exploration
- SQL-based queries over JSONL
Use Cases:
- Quality assessment of extraction runs
- Identifying low-confidence records
- Coverage analysis by field
- Model performance comparison
Get started in under 2 minutes with automated setup:
macOS/Linux:
./scripts/quick_start.shWindows:
scripts\quick_start.batThis automated script will:
- ✅ Install uv package manager (if needed)
- ✅ Create and activate virtual environment
- ✅ Install all dependencies
- ✅ Generate sample specimen images
- ✅ Configure .env file interactively
- ✅ Display next steps
After completion, start the server:
python mobile/run_mobile_server.py --devThen open http://localhost:8080 and enter your name to start reviewing.
Using uv (recommended - fastest):
# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone and install
git clone https://github.com/devvyn/herbarium-specimen-tools.git
cd herbarium-specimen-tools
uv venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
uv pip install -e .Using pip (traditional):
git clone https://github.com/devvyn/herbarium-specimen-tools.git
cd herbarium-specimen-tools
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -e .# Start review server with included sample data
./start_review_server.sh
# Or manually:
# python mobile/run_mobile_server.py --dev
# Access the mobile interface
# Open http://localhost:8080 in your browser
# Enter your name to start reviewing (no password required)Note: Sample data is included in examples/sample_data/ but does not include images. The server will start successfully, but image viewing will fail until you add your own specimen images.
# Start mobile review server with your own data
python mobile/run_mobile_server.py \
--extraction-dir path/to/extractions \
--image-dir path/to/images \
--port 8000
# Access from phone/tablet
# http://YOUR_IP:8000See mobile/README.md for detailed setup.
# Run analysis on extraction data
python scripts/analyze_specimens.py \
--input extractions/raw.jsonl \
--analysis coverage
# Available analyses:
# - coverage: Field coverage statistics
# - confidence: Confidence score distributions
# - quality: Quality issue detectionSee docs/analytics.md for examples.
- Mobile Interface Guide - Setup and usage
- Analytics Guide - Data analysis examples
- Example Workflows - Sample pipelines
- API Reference - Developer documentation
- Architecture Diagrams - Visual system documentation
- Python 3.11 or higher
- Modern web browser (for mobile PWA)
- Optional: DuckDB for analytics (installed via pip)
Use these tools to:
- Review extracted specimen data on mobile devices
- Analyze extraction quality and coverage
- Validate Darwin Core field mapping
- Refine data in the field
- Field data validation during collection trips
- Quality assessment of batch extractions
- Coverage analysis for publication planning
- Confidence-based prioritization
The examples/sample_data/ directory includes anonymized sample specimens for testing:
# Test mobile interface with samples
python mobile/run_mobile_server.py \
--extraction-dir examples/sample_data \
--image-dir examples/sample_data/images
# Test analytics with samples
python scripts/analyze_specimens.py \
--input examples/sample_data/raw.jsonlSee examples/workflows/ for:
- Basic review workflow
- Quality assessment pipeline
- Field-based curation example
Contributions welcome! See CONTRIBUTING.md for guidelines.
Ways to Contribute:
- Report bugs and request features via GitHub Issues
- Submit pull requests for improvements
- Share your herbarium digitization workflows
- Improve documentation
MIT License - see LICENSE file for details.
In short: Free to use, modify, and distribute. Commercial use allowed. Attribution appreciated.
This toolkit was extracted from a production herbarium digitization project and generalized for community use. The tools have been used successfully for reviewing thousands of specimen extractions.
Other Herbarium Tools:
- GBIF IPT - Data publication platform
- Symbiota - Collection management
- iNaturalist - Field identification
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: docs/
These tools were developed during a herbarium digitization project at a regional research institution. Anonymized and released as open source to benefit the wider herbarium community.
Technologies Used:
- FastAPI - Mobile API backend
- Vue.js - Mobile UI framework
- DuckDB - Analytics engine
- Darwin Core - Data standard
Status: Active Development Version: 0.2.0 Maintained by: @devvyn