WildDetect Monorepo

A complete ecosystem for wildlife monitoring and conservation using aerial imagery.

WildDetect is an integrated monorepo containing three specialized packages for the entire wildlife detection workflow—from data management to model training and deployment.

📦 Packages

🗂️ WilData - Data Management

Unified data pipeline for dataset management and preparation.

Multi-format import/export (COCO, YOLO, Label Studio)
Data transformations (tiling, augmentation, clipping)
ROI dataset creation for classification
DVC integration for version control
REST API for programmatic access

📖 WilData Documentation

🎓 WildTrain - Model Training

Modular training framework for detection and classification models.

YOLO and MMDetection support
PyTorch Lightning for classification
MLflow experiment tracking
Hyperparameter optimization (Optuna)
Model registration and versioning

📖 WildTrain Documentation

🔍 WildDetect - Detection & Analysis

Production-ready detection system with census capabilities.

Multi-threaded detection pipelines
Large raster image support (GeoTIFF)
Census campaign orchestration
Geographic analysis and visualization
FiftyOne integration
Comprehensive reporting (JSON, CSV, PDF)

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/fadelmamar/wildetect.git
cd wildetect

# Create virtual environment
uv venv --python 3.10
.venv\Scripts\activate  # Windows

# Install all packages
cd wildata && uv pip install -e . && cd ..
cd wildtrain && uv pip install -e . && cd ..
uv pip install -e .

📖 Full Installation Guide

Quick Detection

# Run detection
wildetect detect /path/to/images --model model.pt --output results/

# Run census campaign
wildetect census campaign_2024 /path/to/images --model model.pt --output campaign_results/

📖 Quick Start Guide

📚 Documentation

Complete documentation is available at: WildDetect Documentation

Getting Started

Architecture

Tutorials

Reference

Support

🎯 Main Features

Detection & Analysis

Multi-species detection optimized for aerial imagery
Batch processing of large datasets
Raster detection for GeoTIFF files
Multi-threaded pipelines for performance

Data Management

Import from COCO, YOLO, Label Studio
Data transformations (tiling, augmentation)
ROI extraction for classification
DVC integration for versioning

Model Training

YOLO and MMDetection frameworks
PyTorch Lightning for classification
MLflow experiment tracking
Hyperparameter optimization

Geographic Analysis

GPS metadata extraction and management
Flight path analysis and coverage maps
Population density calculations
Interactive visualizations with FiftyOne

Census Capabilities

Full census campaign orchestration
Species counting and statistics
Distribution analysis
Comprehensive PDF reports

🔧 Main CLI Commands

WildDetect

wildetect detect      # Run wildlife detection
wildetect census      # Census campaign
wildetect analyze     # Analyze results
wildetect visualize   # Create visualizations
wildetect fiftyone    # Launch FiftyOne viewer
wildetect ui          # Launch web interface

WilData

wildata import-dataset    # Import dataset
wildata dataset list      # List datasets
wildata dataset export    # Export dataset
wildata create-roi        # Create ROI dataset
wildata visualize-dataset # Visualize data

WildTrain

wildtrain train classifier  # Train classification model
wildtrain train detector    # Train detection model
wildtrain eval classifier   # Evaluate model
wildtrain register         # Register to MLflow

For all options:

wildetect --help
wildata --help
wildtrain --help

🐾 WildDetect Command-Line Interface (CLI)

WildDetect provides a powerful and flexible command-line interface (CLI) built with Typer, making it easy to run wildlife detection, census campaigns, analysis, visualization, and more—all from your terminal.

How to Use

After installing WildDetect, simply run:

wildetect [COMMAND] [OPTIONS]

You can always see all available commands and options with:

wildetect --help

Main Commands

detect
Run wildlife detection on images or directories of images.
```
wildetect detect /path/to/images --model model.pt --output results/
```
Options include model type, confidence threshold, device (CPU/GPU), batch size, tiling, and more.
census
Orchestrate a full wildlife census campaign, including detection, statistics, and reporting.
```
wildetect census campaign_2024 /path/to/images --model model.pt --output campaign_results/
```
Supports campaign metadata, pilot info, target species, and advanced analysis.
analyze
Analyze detection results for statistics and insights.
```
wildetect analyze results.json --output analysis/
```
visualize
Create interactive geographic maps and visualizations from detection results.
```
wildetect visualize results.json --output maps/
```
info
Display system and environment information, including dependencies and hardware support.
```
wildetect info
```
ui
Launch the WildDetect web interface (Streamlit-based) for interactive exploration.
```
wildetect ui
```

fiftyone
Manage FiftyOne datasets: launch the app, get info, or export data.

wildetect fiftyone --action launch
wildetect fiftyone --action info --dataset my_dataset
wildetect fiftyone --action export --format coco --output export_dir/

clear-results
Delete all detection results in a specified directory (with confirmation).

General CLI Features

Rich Output: Uses rich for beautiful tables, progress bars, and colored logs.
Flexible Input: Accepts both individual image files and directories.
Advanced Options: Fine-tune detection, tiling, device selection, and more.
Batch Processing: Efficiently processes large datasets.
Integration: Seamless export to FiftyOne, JSON, and CSV formats.
Help for Every Command: Use wildetect [COMMAND] --help for detailed options.

📁 Repository Structure

wildetect/                    # Monorepo root
├── wildata/                  # Data management package
│   ├── src/wildata/
│   ├── configs/
│   ├── scripts/
│   └── tests/
├── wildtrain/                # Training framework package
│   ├── src/wildtrain/
│   ├── configs/
│   ├── scripts/
│   └── tests/
├── src/wildetect/            # Detection package
│   ├── core/
│   ├── cli/
│   ├── api/
│   └── ui/
├── config/                   # WildDetect configurations
├── scripts/                  # Batch scripts
├── docs/                     # Documentation
└── tests/                    # Tests

🔄 Common Workflows

Detection Workflow

# 1. Run detection
wildetect detect images/ --model model.pt --output results/

# 2. View in FiftyOne
wildetect fiftyone --action launch

# 3. Analyze results
wildetect analyze results/detections.json

Data Preparation Workflow

# 1. Import dataset
cd wildata
wildata import-dataset annotations.json --format coco --name dataset

# 2. Apply transformations (tiling)
# (configured in import config)

# 3. Export for training
wildata dataset export dataset --format yolo

Training Workflow

# 1. Train model
cd wildtrain
wildtrain train detector -c configs/detection/yolo.yaml

# 2. Evaluate
wildtrain eval detector -c configs/detection/yolo_eval.yaml

# 3. Register to MLflow
wildtrain register detector config/registration.yaml

Census Workflow

# 1. Configure census (edit config/census.yaml)

# 2. Run census
wildetect census campaign_2024 images/ -c config/census.yaml

# 3. View report
# Open census_results/report.pdf

🌟 Key Technologies

Python 3.9+ - Primary language
PyTorch - Deep learning framework
YOLO / MMDetection - Object detection
PyTorch Lightning - Training framework
MLflow - Experiment tracking
FiftyOne - Dataset visualization
FastAPI - REST API
Streamlit - Web interfaces
DVC - Data versioning
Hydra - Configuration management
Typer - CLI interfaces

🤝 Contributing

Contributions are welcome! This is an open-source project for the conservation community.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please ensure:

Code follows project style (use ruff)
Tests pass (uv run pytest tests/ -v)
Documentation is updated
Commit messages are descriptive

📄 License

MIT License - see LICENSE for details.

📧 Support & Contact

Documentation: docs/index.md
Issues: GitHub Issues
Discussions: GitHub Discussions

🙏 Acknowledgments

Conservation organizations using this toolkit
Open-source community
YOLO and MMDetection teams
PyTorch and Lightning teams

Ready to get started? Head to the Installation Guide or Quick Start!

Name		Name	Last commit message	Last commit date
Latest commit History 361 Commits
.cursor/rules		.cursor/rules
assets		assets
checkpoints/classification		checkpoints/classification
config		config
docs		docs
examples		examples
scripts		scripts
site		site
src/wildetect		src/wildetect
tests		tests
wildata		wildata
wildtrain		wildtrain
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
README.md		README.md
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml

FadelMamar/wildetect

Folders and files

Latest commit

History

Repository files navigation