From 50ddcb60add6e061bd410496fcf3004c30fe3557 Mon Sep 17 00:00:00 2001 From: everbarry Date: Wed, 1 Apr 2026 15:35:17 +0200 Subject: [PATCH] add model description --- MODEL_CARD.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 MODEL_CARD.md diff --git a/MODEL_CARD.md b/MODEL_CARD.md new file mode 100644 index 0000000..fd16802 --- /dev/null +++ b/MODEL_CARD.md @@ -0,0 +1,123 @@ +# 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.*