124 lines
5.7 KiB
Markdown
124 lines
5.7 KiB
Markdown
# Model Card: EfficientNet V2-S — Wild Forest Animals
|
||
|
||
This document describes the image classifier used by the Wildlife Monitoring Dashboard (0HM340 Human–AI Interaction, TU/e). It follows the spirit of [Model Cards for Model Reporting](https://arxiv.org/abs/1810.03993).
|
||
|
||
---
|
||
|
||
## Model summary
|
||
|
||
| Field | Value |
|
||
|--------|--------|
|
||
| **Model family** | EfficientNet V2-S (`torchvision.models.efficientnet_v2_s`) |
|
||
| **Pre-training** | ImageNet-1K (`EfficientNet_V2_S_Weights.IMAGENET1K_V1`) |
|
||
| **Task** | Multi-class image classification (single label per image) |
|
||
| **Output** | 7 logits → softmax probabilities over fixed classes |
|
||
| **Weights file** | `efficientnet_v2_wild_forest_animals.pt` (state dict only; not shipped in the repo) |
|
||
| **Input** | RGB images resized to **224×224**, ImageNet normalization |
|
||
| **Framework** | PyTorch |
|
||
|
||
---
|
||
|
||
## Intended use
|
||
|
||
- **Primary:** Educational / research prototype for human–AI interaction and explainability (dashboard with ScoreCAM, LIME, nearest-neighbour views).
|
||
- **Deployment context:** Simulated camera-trap workflow in a demo UI; **not** validated for real wildlife management, safety-critical decisions, or law enforcement.
|
||
|
||
**Out-of-scope uses:** Do not rely on this model for operational conservation decisions, species surveys with legal implications, or any setting where errors could cause harm without independent verification.
|
||
|
||
---
|
||
|
||
## Output classes
|
||
|
||
Fixed label set (order matches the classifier head):
|
||
|
||
| Index | Class |
|
||
|------|--------|
|
||
| 0 | bear |
|
||
| 1 | deer |
|
||
| 2 | fox |
|
||
| 3 | hare |
|
||
| 4 | moose |
|
||
| 5 | person |
|
||
| 6 | wolf |
|
||
|
||
The dashboard narrative may reference a specific national park; **the model was not trained on data from that park only** — see *Training data*.
|
||
|
||
---
|
||
|
||
## Training data
|
||
|
||
- **Source:** Roboflow project `wild-forest-animals-and-person`, workspace `forestanimals`, **version 1**, export format **multiclass**.
|
||
- **Local layout:** `wild-forest-animals-and-person-1/` with `train/`, `valid/`, `test/` splits and `_classes.csv` per split (one-hot columns per class).
|
||
- **Label handling:** Rows with multiple positive labels in the CSV use the **first** positive class only (single-label training).
|
||
- **Domain:** Mixed camera-trap / wild-animal imagery bundled by the dataset authors; distribution across species, geography, lighting, and quality follows that dataset — **not** guaranteed to match any real park’s fauna or camera setup.
|
||
|
||
---
|
||
|
||
## Training procedure
|
||
|
||
Implemented in `train.py` (see repository for exact defaults).
|
||
|
||
| Setting | Default |
|
||
|---------|---------|
|
||
| Optimizer | Adam |
|
||
| Loss | Cross-entropy |
|
||
| Mixed precision | Enabled on CUDA (`autocast` + `GradScaler`) |
|
||
| Train augmentations | Random horizontal flip (p=0.5), then ToTensor, Resize 224, ImageNet normalize |
|
||
| Evaluation augmentations | ToTensor, Resize 224, ImageNet normalize |
|
||
| DataLoader shuffle (train) | Yes, with fixed generator seed |
|
||
| Reproducibility | `SEED = 42`; CUDNN deterministic mode enabled in training script |
|
||
|
||
**Default hyperparameters (CLI overridable):** epochs `3`, batch size `32`, learning rate `1e-3`. Example overrides: `--epochs 5`, `--lr 0.0005`, `--batch-size 16`.
|
||
|
||
**Reported metrics:** The training script prints validation loss/accuracy per epoch and **test** loss/accuracy after the last epoch. Exact numbers depend on run, hardware, and hyperparameters; **record your own metrics** when you train. Weights in the repo are not pinned to a single certified benchmark run.
|
||
|
||
---
|
||
|
||
## Evaluation
|
||
|
||
- **Split:** Held-out `test` folder from the Roboflow export.
|
||
- **Metric:** Top-1 accuracy and cross-entropy loss on the test loader (see console output from `train.py`).
|
||
- **Limitations:** No per-class confusion matrix or calibration analysis in the default pipeline; no external geographic or temporal holdout.
|
||
|
||
---
|
||
|
||
## Ethical and fairness considerations
|
||
|
||
- **“Person” class:** Predictions can affect privacy perceptions in camera-trap settings; treat as a coarse label, not identity or intent.
|
||
- **Wildlife labels:** Errors could misrepresent which species are present; the UI supports **manual verification** — use it when stakes matter.
|
||
- **Deployment:** Automated alerts (e.g. wolf/bear warnings in the demo) are **illustrative**; they should not replace expert assessment or park regulations.
|
||
|
||
---
|
||
|
||
## Caveats and limitations
|
||
|
||
1. **Domain shift:** Performance will drop on images that differ strongly from the training distribution (new sensors, night IR, heavy occlusion, rare poses).
|
||
2. **Single label:** Images with multiple species only contribute one label during training; the model is not trained for multi-label detection.
|
||
3. **Geographic / ecological claims:** Class names refer to species types; **the model does not prove** an animal’s presence in any specific jurisdiction or ecosystem.
|
||
4. **Weights:** If you did not train the checkpoint yourself, treat reported behaviour as **unknown** until you evaluate on your data.
|
||
5. **API keys / data download:** Training and dashboard can auto-download data via Roboflow; use your own keys and comply with Roboflow terms in production-like setups.
|
||
|
||
---
|
||
|
||
## How to reproduce
|
||
|
||
```bash
|
||
uv sync
|
||
uv run python train.py
|
||
# Optional: uv run python train.py --epochs 5 --lr 0.0005 --batch-size 16
|
||
```
|
||
|
||
This produces `efficientnet_v2_wild_forest_animals.pt` compatible with `dashboard.py` and `main.py`.
|
||
|
||
---
|
||
|
||
## Citation / contact
|
||
|
||
- **Course / context:** 0HM340 Human–AI Interaction, Eindhoven University of Technology.
|
||
- **Base architecture:** Tan & Le, *EfficientNetV2*, 2021 (via torchvision).
|
||
- For questions about this card or the codebase, refer to the project `README.md` and `DEVELOPER_GUIDE.md`.
|
||
|
||
---
|
||
|
||
*Last updated to match repository layout and training script defaults; update this file if classes, dataset version, or training recipe change.*
|