Update README.md

README.md

@@ -1,3 +1,138 @@
 ---
 license: cc-by-4.0
+tags:
+  - image-segmentation
+  - image-classification
+  - solar-panels
+  - photovoltaic
+  - remote-sensing
+  - aerial-imagery
+  - pytorch
+datasets:
+  - gabrielkasmi/bdappv
 ---
+
+# BDAPPV Models
+
+Baseline models for the [BDAPPV dataset](https://huggingface.co/datasets/gabrielkasmi/bdappv) — aerial images of rooftop photovoltaic installations in France and Belgium.
+
+**Paper:** [Kasmi et al., Scientific Data, 2023](https://doi.org/10.1038/s41597-023-01951-4)
+
+---
+
+## Models
+
+Two architectures, trained independently on each imagery provider:
+
+| File | Task | Architecture | Provider |
+|------|------|-------------|----------|
+| `deeplab_google_best.pth` | Segmentation | DeepLabV3-ResNet101 | Google |
+| `deeplab_ign_best.pth` | Segmentation | DeepLabV3-ResNet101 | IGN |
+| `inception_google_best.pth` | Classification | InceptionV3 | Google |
+| `inception_ign_best.pth` | Classification | InceptionV3 | IGN |
+
+---
+
+## Benchmark protocol
+
+Three evaluation tracks are defined:
+
+**Track 1 — Segmentation (single provider)**
+Train and evaluate on the same provider. Report IoU and F1 on the test split.
+
+**Track 2 — Classification (single provider)**
+Train and evaluate on the same provider. Report accuracy and F1 on the test split.
+
+**Track 3 — Distribution shift (cross-provider)**
+Train on Google, evaluate on IGN test split. This is the primary robustness benchmark. Report IoU.
+
+Rules:
+- The test split must not be used for model selection or hyperparameter tuning — validation split only.
+- The spatial holdout by department must not be modified. Re-splitting invalidates comparability with published results.
+- For Track 3, only the Google training split may be used for training.
+
+---
+
+## Results
+
+Models evaluated on the official test split (spatial holdout by French department — see dataset card for details).
+
+### Segmentation (DeepLabV3-ResNet101)
+
+| Provider | IoU | F1 |
+|----------|-----|----|
+| Google | TBD | TBD |
+| IGN | TBD | TBD |
+
+### Classification (InceptionV3)
+
+| Provider | Accuracy | F1 |
+|----------|----------|----|
+| Google | TBD | TBD |
+| IGN | TBD | TBD |
+
+### Distribution shift benchmark
+
+Train on Google, evaluate on IGN — the intended cross-provider protocol:
+
+| Model | Train | Test | IoU |
+|-------|-------|------|-----|
+| DeepLabV3-ResNet101 | Google | IGN | TBD |
+
+---
+
+## Usage
+
+A `model.py` helper is included in this repo to simplify loading:
+
+```python
+from huggingface_hub import hf_hub_download
+import importlib.util
+
+path = hf_hub_download("gabrielkasmi/bdappv-models", "model.py")
+spec = importlib.util.spec_from_file_location("bdappv_model", path)
+mod  = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(mod)
+
+seg = mod.load_segmentation_model("google")    # or "ign"
+clf = mod.load_classification_model("google")  # or "ign"
+```
+
+Both functions return the model in `eval()` mode. An optional `device` argument is supported (`"cpu"`, `"cuda"`, `"mps"`).
+
+---
+
+## Training
+
+Models trained on the official BDAPPV splits using:
+
+- **Optimizer:** AdamW (lr=1e-4, weight_decay=1e-4)
+- **Scheduler:** Cosine annealing
+- **Effective batch size:** 32 (batch 16 × grad accum 2)
+- **Early stopping:** patience=7 epochs on validation metric
+- **Input size:** 400×400 px
+- **Initialization:** checkpoints from [Mayer et al. (2022)](https://doi.org/10.1016/j.apenergy.2021.118469), who fine-tuned DeepLabV3-ResNet101 and InceptionV3 on 10 cm/px orthoimagery from North Rhine-Westphalia (Germany) for rooftop PV detection. These checkpoints were then further fine-tuned on BDAPPV using the splits above.
+
+Training scripts available in the [BDAPPV dataset repository](https://huggingface.co/datasets/gabrielkasmi/bdappv).
+
+---
+
+## Citation
+
+If you use these models, please cite:
+
+```bibtex
+@phdthesis{kasmi2024enhancing,
+  title  = {Enhancing the Reliability of Deep Learning Models to Improve
+            the Observability of French Rooftop Photovoltaic Installations},
+  author = {Kasmi, Gabriel},
+  year   = {2024},
+  school = {Universit{\'e} Paris sciences et lettres}
+}
+```
+
+## References
+
+- Mayer et al. (2022). [3D-PV-Locator: Large-scale detection of rooftop-mounted photovoltaic systems in 3D.](https://doi.org/10.1016/j.apenergy.2021.118469) *Applied Energy*, 310, 118469. *(source of the base checkpoints)*
+- Kasmi et al. (2023). [A crowdsourced dataset of aerial images with annotated solar photovoltaic arrays and installation metadata.](https://doi.org/10.1038/s41597-023-01951-4) *Scientific Data*, 10, 59. *(BDAPPV dataset)*
+- Kasmi et al. (2022). [Towards unsupervised assessment with open-source data of the accuracy of deep learning-based distributed PV mapping.](https://arxiv.org/abs/2207.07466) *arXiv:2207.07466*. *(cross-provider distribution shift)*