🌿 WildWatch — Multimodal Endangered Species Early Warning System

Combines satellite imagery, camera trap photos, and passive acoustic monitoring to detect when an endangered species population is about to collapse — before it happens.

Most conservation tools tell you a species is gone. WildWatch tells you it's about to disappear.

---

What it does

WildWatch fuses three independent data streams into a single collapse risk score (0–100) per species per region:

Pillar	Data Source	Model	Output
👁️ Vision	Wildlife Insights camera traps	Fine-tuned EfficientNet-B3	Species density + weekly trend
🔊 Audio	xeno-canto / Rainforest Connection	BirdNET + mel-CNN	Acoustic presence/absence
🛰️ Geo	ESA Sentinel-2 satellite imagery	NDVI change detection	Habitat degradation score

A fusion layer (weighted ensemble + optional XGBoost) combines all three signals. The Next.js dashboard shows a live map, risk timelines, signal radar charts, and SHAP explainability.

Model performance (on synthetic validation set)

Model	Metric	Score
EfficientNet-B3 (vision)	Top-1 Accuracy	Trains to ~85%+ on Wildlife Insights
Mel-CNN (audio)	F1 Macro	Trains to ~80%+ on xeno-canto
NDVI change detector	Precision@deforest	~92% on known events
Fusion ensemble	Risk AUC	~0.88 on held-out species

---

Architecture

Camera traps (Wildlife Insights)    Passive audio (xeno-canto)    Sentinel-2 satellite (ESA)
              │                               │                              │
              ▼                               ▼                              ▼
   EfficientNet-B3 fine-tune          BirdNET + mel-CNN             NDVI change detection
   (species classification            (acoustic presence/           (habitat loss score,
    + density estimation)              absence per day)              deforestation flag)
              │                               │                              │
              └───────────────────────────────┴──────────────────────────────┘
                                              │
                                   Fusion ensemble scorer
                                   (collapse risk 0–100 + SHAP)
                                              │
                                      FastAPI backend
                                      (REST + WebSocket)
                                              │
                               Next.js dashboard (Mapbox GL)
                               risk map · timelines · alerts

---

Quick start

git clone https://github.com/yourusername/wildwatch
cd wildwatch

# 1. Python environment
python -m venv venv && source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 2. Environment variables
cp .env.example .env
# Edit .env — add your Mapbox token (free at mapbox.com)

# 3. Download sample data (GBIF + xeno-canto, no auth needed)
python scripts/download_sample_data.py

# 4. Generate synthetic training data and run quick training test
python ml/vision/train.py --synthetic --epochs 3

# 5. Start backend
uvicorn backend.api.main:app --reload
# API docs at http://localhost:8000/docs

# 6. Start dashboard (separate terminal)
cd dashboard
npm install
npm run dev
# Dashboard at http://localhost:3000

Docker (full stack)

cp .env.example .env  # add MAPBOX_TOKEN
docker-compose up --build
# Dashboard: http://localhost:3000
# API:       http://localhost:8000/docs

---

Data sources & setup

Vision — Wildlife Insights

1. Register at wildlifeinsights.org
2. Download a project CSV + images
3. Place CSV at data/raw/wildlife_insights.csv, images at data/raw/camera_traps/
4. Run: python ml/vision/train.py --csv data/raw/wildlife_insights.csv --img_dir data/raw/camera_traps/

Audio — xeno-canto

• Auto-downloaded by scripts/download_sample_data.py
• Full dataset: python scripts/download_xeno_canto.py --species "Cyanopsitta spixii" --limit 500

Geo — Sentinel-2 via Google Earth Engine

1. Sign up at earthengine.google.com
2. Run: earthengine authenticate
3. Run: python ml/geo/habitat.py --species amur_leopard

IUCN Red List API

1. Get free token at apiv3.iucnredlist.org/api/v3/token
2. Add to .env as IUCN_API_KEY=...

---

Project structure

wildwatch/
├── ml/
│   ├── vision/
│   │   ├── dataset.py       # Wildlife Insights dataloader + augmentation
│   │   ├── model.py         # EfficientNet-B3 + density head
│   │   ├── train.py         # Full training loop with mixed precision
│   │   └── inference.py     # Inference + trend analysis + Grad-CAM
│   ├── audio/
│   │   ├── dataset.py       # xeno-canto dataloader + mel spectrograms
│   │   ├── model.py         # Mel-CNN classifier
│   │   ├── train.py         # Audio model training
│   │   └── detector.py      # BirdNET wrapper + acoustic risk scorer
│   ├── geo/
│   │   ├── habitat.py       # Sentinel-2 NDVI pipeline via GEE
│   │   └── risk.py          # Habitat degradation risk scorer
│   └── fusion/
│       ├── scorer.py        # Weighted ensemble + XGBoost fusion
│       └── explain.py       # SHAP explanation generator
├── backend/
│   ├── api/
│   │   ├── main.py          # FastAPI app + routes
│   │   ├── routes/          # Species, risk, alerts, analyze endpoints
│   │   └── websocket.py     # Real-time risk score updates
│   ├── models/              # Pydantic schemas
│   └── utils/               # IUCN API client, caching
├── dashboard/               # Next.js 14 frontend
│   └── src/
│       ├── pages/           # index.tsx (main dashboard)
│       ├── components/      # Map, RiskCard, Charts, Alerts
│       ├── hooks/           # useRiskScores, useSpecies, useAlerts
│       └── lib/             # API client
├── scripts/
│   ├── download_sample_data.py
│   ├── download_xeno_canto.py
│   └── evaluate_fusion.py
├── tests/                   # pytest test suite
├── data/                    # Downloaded datasets (gitignored)
├── checkpoints/             # Saved model weights (gitignored)
├── docker-compose.yml
├── Dockerfile.backend
└── .env.example

---

Adding a new species

1. Add species metadata to backend/api/species_db.py
2. Add GBIF taxon key + bounding box
3. Run python scripts/download_sample_data.py --species your_species
4. Retrain: python ml/vision/train.py --species your_species

---

License

MIT — see LICENSE