TRAINING_GUIDE.md

# CD-Models Training Guide

## Prerequisites

- Python 3.10 is recommended.
- CUDA/PyTorch requirements vary by model. Check each model directory or cloned repo requirements file before training:
  - `BiFA/requirements.txt`
  - `CDMamba/requirement.txt`
  - `Change3D/requirements.txt`
  - `ChangeFormer/requirements.txt`
  - `RSM-CD/requirements.txt`
- Set `DATA_ROOT` before using central configs:

```bash
export DATA_ROOT=/path/to/datasets
```

All central configs use `${DATA_ROOT}` and avoid hardcoded absolute dataset paths.

## Dataset Setup

The shared loader expects split folders under each dataset root. Folder names are configured in `configs/datasets/*.yaml`.

LEVIR-CD+:

```text
$DATA_ROOT/LEVIR-CD-plus-256/
  train/A train/B train/Mask
  val/A   val/B   val/Mask
  test/A  test/B  test/Mask
```

WHU-CD:

```text
$DATA_ROOT/WHU-CD/
  train/A train/B train/OUT
  val/A   val/B   val/OUT
  test/A  test/B  test/OUT
```

WildFireS2:

```text
$DATA_ROOT/WildFireS2/
  train/A train/B train/label
  val/A   val/B   val/label
  test/A  test/B  test/label
```

Download sources should be confirmed from the original dataset pages before publication. Keep raw data outside this repo and point `DATA_ROOT` at the prepared benchmark folders.

## Pretrained Weights

| Model | Backbone | Download URL | Local Path |
|---|---|---|---|
| change3d | X3D-L | Original Change3D README/model release | `Change3D/model/X3D_L.pyth` |
| ifnet / dsifn | VGG-16 | Torchvision or original DSIFN README | `model_repos/DSIFN/pretrained/vgg16.pth` |
| changemamba | VMamba | ChangeMamba README Zenodo/HuggingFace link | `model_repos/ChangeMamba/pretrained/vmamba_tiny.pth` |
| changer | ResNet-18 | open-cd / torchvision ResNet-18 | `model_repos/open-cd/pretrained/resnet18.pth` |
| tinycd | EfficientNet-B4 | TinyCD README | `model_repos/TinyCD/pretrained/efficientnet_b4.pth` |

Wrappers print a clear required-weight block when a required file is missing.

## Automatic Weight Downloads

All pretrained backbone weights are downloaded automatically on first training run. VMamba weights for ChangeMamba are downloaded from Zenodo record `14037770` by `utils/weight_downloader.py`.

| Model | Backbone | Download Source | Auto? | Est. Size |
|---|---|---|---|---|
| ChangeMamba | VMamba-Tiny | Zenodo records/14037770 | yes | ~86 MB |
| ChangeMamba | VMamba-Small | Zenodo records/14037770 | yes | ~178 MB |
| ChangeMamba | VMamba-Base | Zenodo records/14037770 | yes | ~391 MB |
| Changer | ResNet-18 | PyTorch Hub / torchvision | yes | ~45 MB |
| DSAMNet | ResNet-18 | PyTorch Hub / torchvision | yes | ~45 MB |
| TinyCD | EfficientNet-B4 | timm / torchvision backend | yes | ~75 MB |
| HANet | ResNet-50 | PyTorch Hub / torchvision | yes | ~98 MB |
| CGNet | ResNet-50 | PyTorch Hub / torchvision | yes | ~98 MB |
| DSIFN | VGG-16 | PyTorch Hub / torchvision | yes | ~528 MB |
| ELGC-Net | MiT-b0 | timm / HuggingFace | yes | ~15 MB |
| ChangeFormer | MiT-b1 | timm / HuggingFace | yes | ~28 MB |

To pre-download all managed weights before training:

```bash
python utils/weight_downloader.py --prefetch-all
```

## Quick Start

Train one model on one dataset:

```bash
python run_training.py --model bifa --dataset wildfire_s2
```

Train all models on one dataset:

```bash
python run_training.py --model all --dataset wildfire_s2 --dry-run
```

Run evaluation only:

```bash
python run_training.py --model bifa --dataset wildfire_s2 --eval-only
```

## Adding A New Model

1. Confirm the official GitHub URL and license.
2. Clone into `model_repos/<model_name>`.
3. Read the cloned README, configs, model code, and training code.
4. Add `configs/models/<model_name>.yaml`.
5. Add or update `train/train_<model_name>.py`.
6. Register the model in `configs/models/registry.yaml`.
7. Ensure the wrapper accepts `--dataset`, `--gpu`, `--resume`, `--eval-only`, and `--dry-run`.
8. Save final metrics with `utils.results_writer.save_metrics()`.

## Results

Per-run metrics are written to:

```text
results/<model>/<dataset>/metrics_test.json
```

The aggregate table is regenerated at:

```text
results/comparison_table.csv
```

Columns: `Model`, `Dataset`, `F1`, `IoU`, `OA`, `Precision`, `Recall`, `Kappa`.

## Known Issues

### Existing WildFire Wrappers

**Partially resolved.** Central wrappers now accept every configured dataset and validate the requested dataset through `CDDataset`. The original nested research scripts still contain their own model-specific data loops, so full non-WildFire training requires each upstream loop to be run against compatible prepared data or rewritten in detail.

### ChangeMamba

**Resolved for setup.** Cloned to `model_repos/ChangeMamba`. Requires running `python model_repos/ChangeMamba/install_deps.py` once before training. VMamba pretrained weights are downloaded automatically from Zenodo record `14037770` on first training run.

### Changer

**Resolved for setup.** Uses open-cd cloned to `model_repos/open-cd`. It requires the same mmengine/mmcv family of dependencies as open-cd. ResNet-18 weights download automatically through torchvision on first run.

### DSAMNet

**Resolved for setup.** Cloned from `liumency/DSAMNet`. The original repo exposes `loss/BCL.py` and `loss/DiceLoss.py`; wrappers must use that metric-learning loss path rather than replacing it with BCE+Dice. Labels are expected as binary 0/1 maps; `CDDataset` converts 255-valued masks to 1.

### TinyCD

**Resolved for setup.** Cloned from `AndreaCodegoni/Tiny_model_4_CD`. EfficientNet-B4 weights download automatically through the weight downloader/timm warmup. TinyCD is RGB-only; `run_training.py` skips `tinycd/wildfire_s2` by default.

### HANet / CGNet

**Resolved for setup.** Cloned from `ChengxiHAN/HANet-CD` and `ChengxiHAN/CGNet-CD`. Both repos use similar custom training utilities and include dataset helpers under `utils/`. ResNet-50 weights are warmed automatically through torchvision.