File size: 47,062 Bytes

---
license: other
library_name: pytorch
tags:
  - change-detection
  - remote-sensing
  - pytorch
---

# CD-Models: A Unified Change Detection Benchmark Suite

> **A multi-dataset, multi-model benchmark for binary remote sensing change detection.**  
> Covers 21 registered models spanning CNN, Transformer, and Mamba architectures, evaluated across the dataset configs in this repository with a shared training pipeline.

![Python](https://img.shields.io/badge/python-3.10%20recommended-blue)
![PyTorch](https://img.shields.io/badge/PyTorch-2.6.0%2Bcu124-ee4c2c)
![Models](https://img.shields.io/badge/models-21-0f766e)
![Datasets](https://img.shields.io/badge/datasets-8-7c3aed)
![License](https://img.shields.io/badge/license-see%20upstream-lightgrey)

## Overview

CD-Models is a benchmark harness for binary remote sensing change detection. It brings original research repositories and newly added model wrappers under one launcher, one dataset-config convention, one weight-management layer, and one result aggregation layout. The repository exists to make model comparisons reproducible across the same prepared dataset folders instead of relying on isolated, model-specific scripts. It also keeps the limits visible: result tables are populated only from `results/*/*/metrics_test.json`, and framework-specific models remain marked until their required stacks are installed.

## Supported Models

The model list below is taken from `configs/models/registry.yaml`, which is what `run_training.py` uses for `--model` choices.

| Model | Paper | Venue | Backbone | Params | Training Script | Status |
|-------|-------|-------|----------|--------|-----------------|--------|
| `bifa` | BiFA: Remote Sensing Image Change Detection with Bitemporal Feature Alignment | IEEE TGRS 2024 | MixTransformer | — | `train/train_bifa.py` | 🔄 In Progress |
| `bit_cd` | Remote Sensing Image Change Detection with Transformers | IEEE TGRS 2021 | ResNet-18 + base transformer | ~11M† | `train/train_bit_cd.py` | ✅ Working |
| `cdmamba` | CDMamba: Incorporating Local Clues into Mamba for Binary Change Detection | IEEE TGRS 2025 | Mamba | — | `train/train_cdmamba.py` | 🔄 In Progress |
| `cgnet` | Change Guiding Network | IEEE JSTARS 2023 | CGNet custom backbone | — | `train/train_cgnet.py` | ✅ Working |
| `change3d` | Change3D: Revisiting Change Detection and Captioning from a Video Modeling Perspective | CVPR 2025 Highlight | X3D-L | — | `train/train_change3d.py` | ✅ Working |
| `changeformer` | A Transformer-Based Siamese Network for Change Detection | IGARSS 2022 | MiT-b4 | ~41M† | `train/train_changeformer.py` | ✅ Working |
| `changemamba` | ChangeMamba: Remote Sensing Change Detection with Spatio-Temporal State Space Model | IEEE TGRS 2024 | VMamba | — | `train/train_changemamba.py` | ⚠️ Framework Required |
| `changer` | Changer: Feature Interaction is What You Need for Change Detection | IEEE TGRS / Open-CD | ResNet-18 | — | `train/train_changer.py` | ⚠️ Framework Required |
| `dsamnet` | Deeply-supervised Attention Metric-based Network | IEEE TGRS 2021 | ResNet | — | `train/train_dsamnet.py` | ✅ Working |
| `dsifn` | Deeply Supervised Image Fusion Network | ISPRS JPRS 2020 | VGG-16 | — | `train/train_dsifn.py` | 🔄 In Progress |
| `elgcnet` | ELGC-Net: Efficient Local-Global Context Aggregation | IEEE TGRS 2024 | ResNet-18 / ELGCA | — | `train/train_elgcnet.py` | ✅ Working |
| `fc_ef` | Fully Convolutional Early Fusion | ICIP 2018 | FCN | — | `train/train_fc_variants.py` | ✅ Working |
| `fc_siam_conc` | Fully Convolutional Siamese Concatenation | ICIP 2018 | Siamese FCN | — | `train/train_fc_variants.py` | ✅ Working |
| `fc_siam_diff` | Fully Convolutional Siamese Difference | ICIP 2018 | Siamese FCN | — | `train/train_fc_variants.py` | ✅ Working |
| `hanet` | HANet: Hierarchical Attention Network | IEEE JSTARS 2023 | HANet custom backbone | — | `train/train_hanet.py` | ✅ Working |
| `ifnet` | Deeply Supervised Image Fusion Network | ISPRS JPRS 2020 | VGG-16 | — | `train/train_ifnet.py` | 🔄 In Progress |
| `rsm_cd` | RS-Mamba for Large Remote Sensing Image Dense Prediction | arXiv 2024 | VMamba/RSM-CD tiny | — | `train/train_rsm_cd.py` | ❌ Failed |
| `schanger` | SChanger: Semantic Change and Spatial Consistency Perspective | IEEE JSTARS 2025 | SChanger-base | — | `train/train_schanger.py` | 🔄 In Progress |
| `siam_nestedunet` | SNUNet-CD / Siamese NestedUNet | IEEE GRSL 2021 | UNet++ | — | `train/train_siam_nestedunet.py` | 🔄 In Progress |
| `stanet` | Spatial-Temporal Attention Network | Remote Sensing 2020 | ResNet-18 + PAM | ~17M† | `train/train_stanet.py` | ✅ Working |
| `tinycd` | TinyCD: A Not So Deep Learning Model for Change Detection | Neural Computing and Applications 2023 | EfficientNet-B4 | — | `train/train_tinycd.py` | ✅ Working |

† Parameter counts are inherited from the previous project README or upstream publications, not measured by the current harness.

## Supported Datasets

Every dataset below is a real YAML file under `configs/datasets/`. The harness expands `${DATA_ROOT}` through `utils/config_loader.py`; if `${DATA_ROOT}` is unset, it first checks `/new-home/buddhiw/Datasets` and then the sibling `mamba-cd/datasets` fallback.

### LEVIR-CD+

| Property | Value |
|---|---|
| Task | Binary building change detection |
| Source | [LEVIR-CD project page](https://justchenhao.github.io/LEVIR/) |
| Train / Val / Test | Determined by files under `$DATA_ROOT/LEVIR-CD-plus-256/{train,val,test}` |
| Image size | 256 x 256 |
| Resolution | Original LEVIR-CD is 0.5 m/pixel; this config uses prepared 256 patches |
| Channels | RGB |
| Label convention | Thresholded binary mask; `Mask/` folder, changed pixels above `127` |
| Mean / Std (A) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Mean / Std (B) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Config | `configs/datasets/levir_cd.yaml` |
| Root pattern | `${DATA_ROOT}/LEVIR-CD-plus-256` |

### LEVIR-CD+ Test-as-Val

| Property | Value |
|---|---|
| Task | Binary building change detection with literature-style test-as-validation protocol |
| Source | [LEVIR-CD project page](https://justchenhao.github.io/LEVIR/) |
| Train / Val / Test | Determined by files under `$DATA_ROOT/LEVIR-CD-plus-256-test-as-val/{train,val,test}` |
| Image size | 256 x 256 |
| Channels | RGB |
| Label convention | Thresholded binary mask; `Mask/` folder, changed pixels above `127` |
| Mean / Std (A) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Mean / Std (B) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Config | `configs/datasets/levir_cd_test_as_val.yaml` |
| Root pattern | `${DATA_ROOT}/LEVIR-CD-plus-256-test-as-val` |

### WHU-CD

| Property | Value |
|---|---|
| Task | Binary building change detection |
| Source | [WHU building dataset page](https://study.rsgis.whu.edu.cn/pages/download/building_dataset.html) |
| Train / Val / Test | Determined by files under `$DATA_ROOT/WHU-CD/{train,val,test}` |
| Image size | 256 x 256 |
| Channels | RGB |
| Label convention | Thresholded binary mask; `OUT/` folder, changed pixels above `127` |
| Mean / Std (A) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Mean / Std (B) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Config | `configs/datasets/whu_cd.yaml` |
| Root pattern | `${DATA_ROOT}/WHU-CD` |

### DSIFN-CD

| Property | Value |
|---|---|
| Task | Binary high-resolution change detection |
| Source | [DSIFN dataset reference](https://github.com/GeoZcx/A-deeply-supervised-image-fusion-network-for-change-detection-in-remote-sensing-images/tree/master/dataset) |
| Train / Val / Test | Determined by files under `$DATA_ROOT/DSIFN-CD/DSIFN/{train,val,test}` |
| Image size | 256 x 256 |
| Channels | RGB |
| Label convention | `mask/` folder; raw masks may be `0/1`; generated model views convert to `0/255` where required |
| Mean / Std (A) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Mean / Std (B) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Config | `configs/datasets/dsifn_cd.yaml` |
| Root pattern | `${DATA_ROOT}/DSIFN-CD/DSIFN` |

### WildFire-S2

| Property | Value |
|---|---|
| Task | Binary burned-area change detection from bi-temporal Sentinel-2 style imagery |
| Source | Local project dataset card in sibling `WildFire-S2/` |
| Train / Val / Test | Determined by files under `$DATA_ROOT/WildFireS2/{train,val,test}` |
| Image size | 256 x 256 |
| Channels | RGB |
| Label convention | Thresholded binary mask; `label/` folder, changed pixels above `127` |
| Mean / Std (A) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Mean / Std (B) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Config | `configs/datasets/wildfire_s2.yaml` |
| Root pattern | `${DATA_ROOT}/WildFireS2` |

### SYSU-CD

| Property | Value |
|---|---|
| Task | Binary change detection |
| Source | [SYSU-CD project page](https://github.com/liumency/SYSU-CD) |
| Train / Val / Test | Determined by files under `$DATA_ROOT/SYSU-CD-folders/{train,val,test}` |
| Image size | 256 x 256 |
| Channels | RGB |
| Label convention | Thresholded binary mask; `Mask/` folder, changed pixels above `127` |
| Mean / Std (A) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Mean / Std (B) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Config | `configs/datasets/sysu_cd.yaml` |
| Root pattern | `${DATA_ROOT}/SYSU-CD-folders` |

### KATE-CD-256

| Property | Value |
|---|---|
| Task | Binary change detection |
| Source | Local prepared dataset config |
| Train / Val / Test | Determined by files under `$DATA_ROOT/KATE-CD-256/{train,val,test}` |
| Image size | 256 x 256 |
| Channels | RGB |
| Label convention | Thresholded binary mask; `label/` folder, changed pixels above `127` |
| Mean / Std (A) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Mean / Std (B) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Config | `configs/datasets/kate_cd.yaml` |
| Root pattern | `${DATA_ROOT}/KATE-CD-256` |

### Custom-CD

| Property | Value |
|---|---|
| Task | User-supplied binary change detection |
| Source | Local template config |
| Train / Val / Test | Determined by files under `$DATA_ROOT/Custom-CD/{train,val,test}` |
| Image size | 256 x 256 |
| Channels | RGB |
| Label convention | Thresholded binary mask; `Mask/` folder, changed pixels above `127` |
| Mean / Std (A) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Mean / Std (B) | `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
| Config | `configs/datasets/custom_cd.yaml` |
| Root pattern | `${DATA_ROOT}/Custom-CD` |

## Results and released checkpoints

Only completed `metrics_test.json` evaluations are eligible for rankings. Rankings are computed per dataset by test-set F1 (descending), and the canonical `best_model.pth` checkpoint for every ranked model is released.

All accuracy values are fractions. GPU memory is the PyTorch peak reserved memory for inference, with peak allocated memory used only when reserved memory is absent. FPS is model-only throughput. A dash means the evaluator did not record that metric; values are never estimated.

The current evaluator records BF1 but not boundary mean IoU (BmIoU), so BmIoU remains explicitly unavailable rather than being inferred from BF1. Boundary IoU and boundary F1 are distinct measures.

The LEVIR-CD+ comparison combines the project-compatible `levir_cd_test_as_val` and `levir_val_as_test` result records. The ChangeMamba row uses the completed `levir_val_as_test` evaluation over 5,568 samples.

### Dataset summary

| Dataset | Tested models | F1 leader | Best test F1 |
| --- | --- | --- | --- |
| DSIFN-CD | 14 | BIT-CD | 0.6732 |
| LEVIR-CD+ comparison | 14 | ChangeMamba | 0.8753 |
| SYSU-CD | 8 | ChangeMamba | 0.8216 |
| WHU-CD | 8 | ChangeMamba | 0.9521 |

### DSIFN-CD

| Rank | Model | F1 | mIoU | Overall accuracy | Recall | Precision | BF1 | BmIoU | GFLOPs | GPU (GB) | FPS | Parameters (M) | Checkpoint |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | BIT-CD | 0.6732 | 0.6929 | 0.8919 | 0.6552 | 0.6923 | 0.2819 | — | 10.63 | 2.24 | 127.76 | 12.40 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/bit_cd/dsifn_cd/checkpoints/best_model.pth?download=true) |
| 2 | SChanger | 0.6629 | 0.6835 | 0.8857 | 0.6612 | 0.6647 | 0.2847 | — | — | 2.45 | 24.05 | — | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/schanger/dsifn_cd/checkpoints/best_model.pth?download=true) |
| 3 | ChangeMamba | 0.6435 | 0.6729 | 0.8849 | 0.6113 | 0.6792 | 0.1903 | — | 28.70 | 1.93 | 15.42 | 54.00 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/changemamba/dsifn_cd/checkpoints/best_model.pth?download=true) |
| 4 | CGNet | 0.6204 | 0.6290 | 0.8343 | 0.7970 | 0.5079 | 0.2903 | — | 82.23 | 6.52 | 65.39 | 38.99 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/cgnet/dsifn_cd/checkpoints/best_model.pth?download=true) |
| 5 | FC-EF | 0.6078 | 0.6400 | 0.8604 | 0.6365 | 0.5816 | 0.1955 | — | 3.58 | 0.74 | 204.13 | 1.35 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/fc_ef/dsifn_cd/checkpoints/best_model.pth?download=true) |
| 6 | ChangeFormer | 0.5964 | 0.6152 | 0.8299 | 0.7397 | 0.4996 | 0.2422 | — | 21.18 | 4.07 | 49.74 | 29.75 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/changeformer/dsifn_cd/checkpoints/best_model.pth?download=true) |
| 7 | BiFA | 0.5876 | 0.6111 | 0.8296 | 0.7142 | 0.4991 | 0.2692 | — | 53.00 | 15.10 | 13.81 | 9.87 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/bifa/dsifn_cd/checkpoints/best_model.pth?download=true) |
| 8 | Siam-NestedUNet | 0.5839 | 0.6024 | 0.8188 | 0.7482 | 0.4788 | 0.2374 | — | 54.83 | 7.34 | 29.18 | 12.03 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/siam_nestedunet/dsifn_cd/checkpoints/best_model.pth?download=true) |
| 9 | FC-Siam-diff | 0.5829 | 0.6277 | 0.8593 | 0.5784 | 0.5875 | 0.1691 | — | 4.73 | 1.06 | 113.98 | 1.35 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/fc_siam_diff/dsifn_cd/checkpoints/best_model.pth?download=true) |
| 10 | STANet | 0.5483 | 0.6258 | 0.8829 | 0.4184 | 0.7953 | 0.1613 | — | 13.16 | 14.11 | 133.96 | 16.93 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/stanet/dsifn_cd/checkpoints/best_model.pth?download=true) |
| 11 | FC-Siam-conc | 0.5479 | 0.5665 | 0.7873 | 0.7583 | 0.4288 | 0.1811 | — | 5.33 | 1.02 | 127.67 | 1.55 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/fc_siam_conc/dsifn_cd/checkpoints/best_model.pth?download=true) |
| 12 | DSAMNet | 0.5467 | 0.5757 | 0.8020 | 0.7027 | 0.4474 | 0.2374 | — | 75.39 | 2.91 | 166.43 | 16.95 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/dsamnet/dsifn_cd/checkpoints/best_model.pth?download=true) |
| 13 | HANet | 0.5347 | 0.5817 | 0.8193 | 0.6109 | 0.4754 | 0.2418 | — | 17.67 | 11.36 | 42.36 | 3.03 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/hanet/dsifn_cd/checkpoints/best_model.pth?download=true) |
| 14 | IFNet | 0.4579 | 0.5102 | 0.7524 | 0.6153 | 0.3647 | 0.1325 | — | 82.26 | 6.08 | 104.88 | 50.71 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/ifnet/dsifn_cd/checkpoints/best_model.pth?download=true) |

### LEVIR-CD+ comparison

| Rank | Model | F1 | mIoU | Overall accuracy | Recall | Precision | BF1 | BmIoU | GFLOPs | GPU (GB) | FPS | Parameters (M) | Checkpoint |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | ChangeMamba | 0.8753 | 0.8840 | 0.9901 | 0.8572 | 0.8942 | 0.8307 | — | 28.70 | 1.93 | 76.82 | 54.00 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/changemamba/levir_val_as_test/checkpoints/best_model.pth?download=true) |
| 2 | CGNet | 0.8138 | 0.8356 | 0.9856 | 0.7746 | 0.8572 | 0.7651 | — | 82.23 | 6.01 | 44.01 | 38.99 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/cgnet/levir_cd_test_as_val/checkpoints/best_model.pth?download=true) |
| 3 | Siam-NestedUNet | 0.8046 | 0.8282 | 0.9839 | 0.8129 | 0.7965 | 0.7386 | — | — | 2.67 | 108.71 | — | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/siam_nestedunet/levir_cd_test_as_val/checkpoints/best_model.pth?download=true) |
| 4 | SChanger | 0.8007 | 0.8253 | 0.9836 | 0.8112 | 0.7906 | 0.7364 | — | — | 2.45 | 48.96 | — | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/schanger/levir_cd_test_as_val/checkpoints/best_model.pth?download=true) |
| 5 | BIT-CD | 0.7996 | 0.8247 | 0.9838 | 0.7946 | 0.8047 | 0.7143 | — | 10.63 | 2.27 | 236.60 | 12.40 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/bit_cd/levir_cd_test_as_val/checkpoints/best_model.pth?download=true) |
| 6 | HANet | 0.7841 | 0.8131 | 0.9819 | 0.8064 | 0.7630 | 0.7043 | — | — | 5.04 | 84.44 | — | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/hanet/levir_cd_test_as_val/checkpoints/best_model.pth?download=true) |
| 7 | BiFA | 0.7772 | 0.8084 | 0.9818 | 0.7785 | 0.7760 | 0.6581 | — | 53.00 | 15.14 | 30.38 | 9.87 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/bifa/levir_cd_test_as_val/checkpoints/best_model.pth?download=true) |
| 8 | FC-Siam-conc | 0.7650 | 0.7999 | 0.9809 | 0.7623 | 0.7678 | 0.7175 | — | 5.33 | 1.02 | 308.81 | 1.55 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/fc_siam_conc/levir_cd_test_as_val/checkpoints/best_model.pth?download=true) |
| 9 | STANet | 0.7544 | 0.7921 | 0.9791 | 0.7865 | 0.7249 | 0.6388 | — | — | 4.45 | 174.00 | — | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/stanet/levir_cd_test_as_val/checkpoints/best_model.pth?download=true) |
| 10 | ChangeFormer | 0.7488 | 0.7887 | 0.9795 | 0.7505 | 0.7472 | 0.6525 | — | 21.18 | 4.03 | 157.64 | 29.75 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/changeformer/levir_cd_test_as_val/checkpoints/best_model.pth?download=true) |
| 11 | DSAMNet | 0.7444 | 0.7850 | 0.9779 | 0.7897 | 0.7040 | 0.5370 | — | 75.39 | 2.90 | 37.84 | 16.95 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/dsamnet/levir_cd_test_as_val/checkpoints/best_model.pth?download=true) |
| 12 | IFNet | 0.7410 | 0.7833 | 0.9786 | 0.7510 | 0.7313 | 0.3489 | — | 82.26 | 6.08 | 105.44 | 50.71 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/ifnet/levir_cd_test_as_val/checkpoints/best_model.pth?download=true) |
| 13 | FC-EF | 0.7319 | 0.7766 | 0.9768 | 0.7785 | 0.6905 | 0.6497 | — | 3.58 | 0.74 | 457.44 | 1.35 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/fc_ef/levir_cd_test_as_val/checkpoints/best_model.pth?download=true) |
| 14 | FC-Siam-diff | 0.7196 | 0.7667 | 0.9725 | 0.8650 | 0.6160 | 0.5447 | — | 4.73 | 1.06 | 262.80 | 1.35 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/fc_siam_diff/levir_cd_test_as_val/checkpoints/best_model.pth?download=true) |

### SYSU-CD

| Rank | Model | F1 | mIoU | Overall accuracy | Recall | Precision | BF1 | BmIoU | GFLOPs | GPU (GB) | FPS | Parameters (M) | Checkpoint |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | ChangeMamba | 0.8216 | 0.8006 | 0.9214 | 0.7677 | 0.8836 | 0.3197 | — | 28.70 | 1.93 | 77.65 | 54.00 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/changemamba/sysu_cd/checkpoints/best_model.pth?download=true) |
| 2 | FC-Siam-conc | 0.7778 | 0.7558 | 0.8975 | 0.7609 | 0.7955 | 0.1939 | — | 5.33 | 1.02 | 356.94 | 1.55 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/fc_siam_conc/sysu_cd/checkpoints/best_model.pth?download=true) |
| 3 | STANet | 0.7728 | 0.7482 | 0.8913 | 0.7841 | 0.7619 | 0.1962 | — | — | 4.45 | 176.02 | — | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/stanet/sysu_cd/checkpoints/best_model.pth?download=true) |
| 4 | FC-EF | 0.7710 | 0.7489 | 0.8936 | 0.7596 | 0.7828 | 0.1857 | — | 3.58 | 0.73 | 553.75 | 1.35 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/fc_ef/sysu_cd/checkpoints/best_model.pth?download=true) |
| 5 | ChangeFormer | 0.7635 | 0.7382 | 0.8851 | 0.7863 | 0.7420 | 0.1591 | — | 21.18 | 4.03 | 143.73 | 29.75 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/changeformer/sysu_cd/checkpoints/best_model.pth?download=true) |
| 6 | FC-Siam-diff | 0.7630 | 0.7457 | 0.8956 | 0.7129 | 0.8208 | 0.1853 | — | 4.73 | 1.08 | 552.90 | 1.35 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/fc_siam_diff/sysu_cd/checkpoints/best_model.pth?download=true) |
| 7 | BIT-CD | 0.7618 | 0.7395 | 0.8881 | 0.7584 | 0.7652 | 0.1780 | — | 10.63 | 2.24 | 111.11 | 12.40 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/bit_cd/sysu_cd/checkpoints/best_model.pth?download=true) |
| 8 | IFNet | 0.7145 | 0.7020 | 0.8724 | 0.6772 | 0.7562 | 0.1158 | — | — | 3.29 | 109.80 | — | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/ifnet/sysu_cd/checkpoints/best_model.pth?download=true) |

### WHU-CD

| Rank | Model | F1 | mIoU | Overall accuracy | Recall | Precision | BF1 | BmIoU | GFLOPs | GPU (GB) | FPS | Parameters (M) | Checkpoint |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | ChangeMamba | 0.9521 | 0.9519 | 0.9954 | 0.9401 | 0.9644 | 0.8605 | — | 28.70 | 1.93 | 75.28 | 54.00 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/changemamba/whu_cd/checkpoints/best_model.pth?download=true) |
| 2 | CGNet | 0.9331 | 0.9340 | 0.9936 | 0.9299 | 0.9364 | 0.8138 | — | 82.23 | 5.62 | 129.54 | 38.99 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/cgnet/whu_cd/checkpoints/best_model.pth?download=true) |
| 3 | BIT-CD | 0.8940 | 0.8989 | 0.9899 | 0.8845 | 0.9037 | 0.6879 | — | 10.63 | 2.24 | 46.28 | 12.40 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/bit_cd/whu_cd/checkpoints/best_model.pth?download=true) |
| 4 | DSAMNet | 0.8905 | 0.8956 | 0.9891 | 0.9167 | 0.8657 | 0.5855 | — | 75.39 | 2.90 | 116.58 | 16.95 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/dsamnet/whu_cd/checkpoints/best_model.pth?download=true) |
| 5 | IFNet | 0.8389 | 0.8534 | 0.9849 | 0.8147 | 0.8644 | 0.3245 | — | 82.26 | 6.08 | 104.98 | 50.71 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/ifnet/whu_cd/checkpoints/best_model.pth?download=true) |
| 6 | FC-EF | 0.8385 | 0.8531 | 0.9850 | 0.8067 | 0.8729 | 0.5818 | — | 3.58 | 0.74 | 498.55 | 1.35 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/fc_ef/whu_cd/checkpoints/best_model.pth?download=true) |
| 7 | FC-Siam-conc | 0.7789 | 0.8062 | 0.9756 | 0.8907 | 0.6920 | 0.4733 | — | 5.33 | 1.03 | 397.86 | 1.55 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/fc_siam_conc/whu_cd/checkpoints/best_model.pth?download=true) |
| 8 | FC-Siam-diff | 0.7135 | 0.7580 | 0.9631 | 0.9540 | 0.5699 | 0.2148 | — | 4.73 | 1.09 | 567.87 | 1.35 | [Download](https://huggingface.co/dineth18/CD-Models/resolve/main/results/fc_siam_diff/whu_cd/checkpoints/best_model.pth?download=true) |

### Datasets without a released checkpoint

WildFire-S2, KATE-CD-256, the standard LEVIR-CD+ configuration, and Custom-CD currently have no eligible completed test result. Their validation-only or incomplete checkpoints are intentionally not uploaded.


## Installation

### 1. Clone this repository

```bash
git clone https://github.com/<your-username>/CD-Models.git
cd CD-Models
```

### 2. Create and activate environment

```bash
conda create -n cd-models python=3.10 -y
conda activate cd-models
```

### 3. Install PyTorch (CUDA 12.4)

```bash
pip install torch==2.6.0 torchvision==0.21.0 --index-url https://download.pytorch.org/whl/cu124
```

Adjust the CUDA version for your system. See [PyTorch Get Started](https://pytorch.org/get-started/locally/).

### 4. Run automatic setup

```bash
python setup.py
```

This single command:

- Checks all required Python packages.
- Auto-installs safe pure-Python/common packages when missing.
- Clones confirmed model repositories into `model_repos/`.
- Downloads or warms pretrained backbone weights.
- Generates dataset list files for datasets already present on disk.
- Prints a full status report.

### 5. ChangeMamba / Changer MMSeg stack

These two models require OpenMMLab packages that should be installed after PyTorch:

```bash
pip install mmengine==0.10.1
pip install mmcv==2.1.0 -f https://download.openmmlab.com/mmcv/dist/cu124/torch2.6/index.html
pip install mmsegmentation==1.2.2 mmdet==3.3.0 mmpretrain==1.2.0
```

### 6. Set your dataset root

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

Add the export to `~/.bashrc` or your scheduler job script if you want it to persist.

## Dataset Preparation

All datasets follow the same high-level split structure: `train/`, `val/`, and `test/`, each with a pre-change image folder, a post-change image folder, and a mask folder. Folder names differ by dataset and are encoded in YAML.

### LEVIR-CD+

**Download:** [Official LEVIR page](https://justchenhao.github.io/LEVIR/)

Expected structure:

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

Prepare list files:

```bash
python setup.py --dataset levir_cd
```

Config: `configs/datasets/levir_cd.yaml`

### LEVIR-CD+ Test-as-Val

**Download:** Use the same source data as LEVIR-CD+ and prepare the test-as-validation split protocol locally.

Expected structure:

```text
$DATA_ROOT/LEVIR-CD-plus-256-test-as-val/
├── train/
│   ├── A/
│   ├── B/
│   └── Mask/
├── val/
│   ├── A/
│   ├── B/
│   └── Mask/
└── test/
    ├── A/
    ├── B/
    └── Mask/
```

Prepare list files:

```bash
python setup.py --dataset levir_cd_test_as_val
```

Config: `configs/datasets/levir_cd_test_as_val.yaml`

### WHU-CD

**Download:** [WHU building dataset page](https://study.rsgis.whu.edu.cn/pages/download/building_dataset.html)

Expected structure:

```text
$DATA_ROOT/WHU-CD/
├── train/
│   ├── A/
│   ├── B/
│   └── OUT/
├── val/
│   ├── A/
│   ├── B/
│   └── OUT/
└── test/
    ├── A/
    ├── B/
    └── OUT/
```

Prepare list files:

```bash
python setup.py --dataset whu_cd
```

Config: `configs/datasets/whu_cd.yaml`

### DSIFN-CD

**Download:** [DSIFN dataset reference](https://github.com/GeoZcx/A-deeply-supervised-image-fusion-network-for-change-detection-in-remote-sensing-images/tree/master/dataset)

Expected structure:

```text
$DATA_ROOT/DSIFN-CD/DSIFN/
├── train/
│   ├── t1/
│   ├── t2/
│   └── mask/
├── val/
│   ├── t1/
│   ├── t2/
│   └── mask/
└── test/
    ├── t1/
    ├── t2/
    └── mask/
```

Prepare list files:

```bash
python setup.py --dataset dsifn_cd
```

Config: `configs/datasets/dsifn_cd.yaml`

Important DSIFN note: some masks are encoded as `0/1`. The generated compatibility views convert those masks to exact `0/255` PNG data for loaders that use `ToTensor()` and then cast labels to integer classes.

### WildFire-S2

**Download:** Local sibling dataset project, documented in `../WildFire-S2/DATASET_CARD.md`.

Expected structure:

```text
$DATA_ROOT/WildFireS2/
├── train/
│   ├── A/
│   ├── B/
│   └── label/
├── val/
│   ├── A/
│   ├── B/
│   └── label/
└── test/
    ├── A/
    ├── B/
    └── label/
```

Prepare list files:

```bash
python setup.py --dataset wildfire_s2
```

Config: `configs/datasets/wildfire_s2.yaml`

### SYSU-CD

**Download:** [SYSU-CD repository](https://github.com/liumency/SYSU-CD)

Expected structure:

```text
$DATA_ROOT/SYSU-CD-folders/
├── train/
│   ├── A/
│   ├── B/
│   └── Mask/
├── val/
│   ├── A/
│   ├── B/
│   └── Mask/
└── test/
    ├── A/
    ├── B/
    └── Mask/
```

Prepare list files:

```bash
python setup.py --dataset sysu_cd
```

Config: `configs/datasets/sysu_cd.yaml`

### KATE-CD-256

**Download:** Local prepared dataset; no official source URL was found in the audited repo files.

Expected structure:

```text
$DATA_ROOT/KATE-CD-256/
├── train/
│   ├── A/
│   ├── B/
│   └── label/
├── val/
│   ├── A/
│   ├── B/
│   └── label/
└── test/
    ├── A/
    ├── B/
    └── label/
```

Prepare list files:

```bash
python setup.py --dataset kate_cd
```

Config: `configs/datasets/kate_cd.yaml`

### Custom-CD

**Download:** User supplied.

Expected structure:

```text
$DATA_ROOT/Custom-CD/
├── train/
│   ├── A/
│   ├── B/
│   └── Mask/
├── val/
│   ├── A/
│   ├── B/
│   └── Mask/
└── test/
    ├── A/
    ├── B/
    └── Mask/
```

Prepare list files:

```bash
python setup.py --dataset custom_cd
```

Config: `configs/datasets/custom_cd.yaml`

## Training

All registered models share the same outer interface through `run_training.py`.

### Train a single model on a single dataset

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

### Train a single model on all datasets

```bash
python run_training.py --model changemamba --dataset all
```

### Train all models on a single dataset

```bash
python run_training.py --model all --dataset levir_cd
```

### Full benchmark sweep

```bash
python run_training.py --model all --dataset all
```

Already-completed runs are skipped when `results/{model}/{dataset}/metrics_test.json` exists. To retry anyway:

```bash
python run_training.py --model bifa --dataset levir_cd --force
```

Resume interrupted training:

```bash
python run_training.py --model bifa --dataset levir_cd --resume
```

Run command-construction checks without training:

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

Run a single wrapper smoke test:

```bash
python train/train_bifa.py --dataset levir_cd --smoke-test
```

### Available models

Original and legacy integrated models:

```text
bifa
bit_cd
cdmamba
change3d
changeformer
dsifn
ifnet
rsm_cd
schanger
siam_nestedunet
stanet
```

Newly added external or direct adapters:

```text
fc_ef
fc_siam_conc
fc_siam_diff
changemamba
elgcnet
changer
hanet
cgnet
dsamnet
tinycd
```

Available datasets:

```text
custom_cd
dsifn_cd
kate_cd
levir_cd
levir_cd_test_as_val
sysu_cd
whu_cd
wildfire_s2
```

### Training outputs

Each completed run is expected to save under:

```text
results/
└── bifa/
    └── levir_cd/
        ├── checkpoints/
        │   ├── best_model.pth
        │   └── latest.pth
        ├── logs/
        │   ├── train_stdout.log
        │   ├── train_stderr.log
        │   ├── eval_stdout.log
        │   └── eval_stderr.log
        ├── predictions/
        │   ├── test/
        │   └── test_prob/
        ├── visuals/
        │   └── selected_20/
        ├── metrics_val.json
        └── metrics_test.json
```

The master launcher appends run status to `results/training_log.jsonl`. After every run attempt, `utils.results_writer.append_to_comparison_table()` regenerates `results/comparison_table.csv`.

For qualitative comparison, the evaluator writes one deterministic sample manifest per dataset:

```text
results/qualitative_samples/<dataset>/sample_manifest.json
```

The same selected test samples are then reused for every model on that dataset. Binary predictions use exact `0` and `255` PNG values.

### Dataset-specific notes

| Model | Dataset | Note |
|---|---|---|
| `tinycd` | `wildfire_s2` | Skipped automatically by `run_training.py`; current exclusion is explicit in `DATASET_EXCLUSIONS`. |
| `changemamba` | all | Requires VMamba weights and the MMSeg/OpenMMLab stack. |
| `changer` | all | Runs through Open-CD and requires the MMSeg/OpenMMLab stack. |
| `dsifn` / `ifnet` | `dsifn_cd` | Uses VGG-16 family loaders; DSIFN masks need careful binary scaling. |
| `rsm_cd` | all | Marked unresolved because the upstream training path has prior initialization/runtime issues. |

## Evaluation

### Evaluate a trained checkpoint

```bash
python evaluate.py --model bifa --dataset levir_cd
```

The central evaluator uses `utils/model_adapters.py` for verified in-process PyTorch model construction, checkpoint loading, forward calls, and output normalization. Current smoke-tested adapters are:

```text
bit_cd
cgnet
changeformer
dsamnet
elgcnet
fc_ef
fc_siam_conc
fc_siam_diff
hanet
siam_nestedunet
stanet
tinycd
```

For these adapters, evaluation loads `checkpoints/best_model.pth`, computes split-level metrics, saves all test predictions, writes selected qualitative panels, records timing/profiling fields, writes `metrics_test.json`, and regenerates the aggregate comparison table.

For remaining subprocess/upstream wrappers, central evaluation fails explicitly until a real architecture construction and checkpoint-loading adapter is added. It does not evaluate dummy models, random initialized models, or guessed output formats.

### Explicit checkpoint path

```bash
python evaluate.py --model bifa --dataset levir_cd --checkpoint results/bifa/levir_cd/checkpoints/best_model.pth
```

### Regenerate comparison table

```bash
python evaluate.py --model all --dataset all --dry-run
```

### Metrics computed

For binary change detection, metrics are intended for the positive changed class.

| Metric | Description |
|--------|-------------|
| F1 | Harmonic mean of precision and recall |
| IoU | Intersection over Union / Jaccard index |
| mIoU | Mean IoU over unchanged/background and changed classes |
| OA | Overall accuracy across both classes |
| Precision | `TP / (TP + FP)` |
| Recall | `TP / (TP + FN)` |
| Kappa | Cohen's kappa coefficient |
| BF1 | Boundary F1 with configurable tolerance, default 2 pixels |
| TP / FP / TN / FN | Accumulated confusion counts over the full split |

The implementation lives in `utils/metrics.py`. The evaluator also records measured parameter counts, FLOPs when `thop` or `fvcore` is installed, FPS, PyTorch peak GPU memory, and NVML GPU utilization when `pynvml` is installed. Missing profiler dependencies are recorded with explicit error fields; values are not guessed.

`metrics_test.json` includes the model, dataset, split, checkpoint path, threshold, confusion counts, F1, IoU, mIoU, precision, recall, OA, kappa, BF1, parameter counts, FLOPs fields, FPS fields, GPU profiling fields, test sample count, prediction and visual directories, timestamp, and status.

## Pre-trained Weights

Backbone weights are downloaded or cache-warmed by `python setup.py` and by `utils/weight_downloader.py`.

### Backbone weights

| Model(s) | Backbone | Source | Auto-Downloaded | Size |
|----------|----------|--------|-----------------|------|
| ChangeMamba-T | VMamba-Tiny | [Zenodo 14037770](https://zenodo.org/records/14037770) | yes | ~86 MB |
| ChangeMamba-S | VMamba-Small | [Zenodo 14037770](https://zenodo.org/records/14037770) | yes | ~178 MB |
| ChangeMamba-B | VMamba-Base | [Zenodo 14037770](https://zenodo.org/records/14037770) | yes | ~391 MB |
| TinyCD | EfficientNet-B4 | timm | yes | ~75 MB |
| ChangeFormer, ELGC-Net | MiT variants | timm | yes | 15-82 MB |
| BIT_CD, STANet, Changer | ResNet-18 | torchvision | yes | ~45 MB |
| DSAMNet, HANet, CGNet | ResNet-50 / ResNet family | torchvision | yes | ~98 MB |
| DSIFN / IFNet | VGG-16 | torchvision | yes | ~528 MB |

Pre-download all managed weights:

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

List managed VMamba weights:

```bash
python utils/weight_downloader.py --list
```

### Trained checkpoints

All completed test-run checkpoints and direct download links are listed in [Results and released checkpoints](#results-and-released-checkpoints). Local training still writes checkpoints under `results/{model}/{dataset}/checkpoints/`.

## Repository Structure

```text
CD-Models/
├── configs/
│   ├── datasets/                  # one YAML per dataset
│   │   ├── custom_cd.yaml
│   │   ├── dsifn_cd.yaml
│   │   ├── kate_cd.yaml
│   │   ├── levir_cd.yaml
│   │   ├── levir_cd_test_as_val.yaml
│   │   ├── sysu_cd.yaml
│   │   ├── whu_cd.yaml
│   │   └── wildfire_s2.yaml
│   └── models/                    # model hyperparameters and registry
│       ├── bifa.yaml
│       ├── bit_cd.yaml
│       ├── cdmamba.yaml
│       ├── cgnet.yaml
│       ├── change3d.yaml
│       ├── changeformer.yaml
│       ├── changemamba.yaml
│       ├── changer.yaml
│       ├── dsamnet.yaml
│       ├── dsifn.yaml
│       ├── elgcnet.yaml
│       ├── fc_ef.yaml
│       ├── fc_siam_conc.yaml
│       ├── fc_siam_diff.yaml
│       ├── hanet.yaml
│       ├── ifnet.yaml
│       ├── registry.yaml
│       ├── rsm_cd.yaml
│       ├── schanger.yaml
│       ├── siam_nestedunet.yaml
│       ├── stanet.yaml
│       └── tinycd.yaml
├── datasets/
│   ├── __init__.py
│   └── cd_dataset.py              # shared dataset validation/loader
├── train/
│   ├── fc_adapter.py              # direct FC-EF / FC-Siam trainer
│   ├── train_bifa.py
│   ├── train_bit_cd.py
│   ├── train_cdmamba.py
│   ├── train_cgnet.py
│   ├── train_change3d.py
│   ├── train_changeformer.py
│   ├── train_changemamba.py
│   ├── train_changer.py
│   ├── train_dsamnet.py
│   ├── train_dsifn.py
│   ├── train_elgcnet.py
│   ├── train_fc_variants.py
│   ├── train_hanet.py
│   ├── train_ifnet.py
│   ├── train_rsm_cd.py
│   ├── train_schanger.py
│   ├── train_siam_nestedunet.py
│   ├── train_stanet.py
│   ├── train_tinycd.py
│   └── wrapper_common.py           # shared wrapper logic and generated views
├── utils/
│   ├── config.py                   # generic YAML/JSON loading and merge helpers
│   ├── config_loader.py            # dataset/model config expansion and validation
│   ├── dataset_list_generator.py   # create list/train.txt, list/val.txt, list/test.txt
│   ├── env_checker.py              # import checks for required packages
│   ├── legacy_config_writer.py     # generated JSON/list views for legacy trainers
│   ├── metrics.py                  # binary CD metrics
│   ├── results.py                  # JSON/CSV helpers
│   ├── results_writer.py           # metrics_test.json and comparison CSV writer
│   └── weight_downloader.py        # Zenodo, timm, torchvision weight management
├── model_repos/                    # cloned external repositories
│   ├── CGNet-CD/
│   ├── ChangeMamba/
│   ├── DSAMNet/
│   ├── HANet-CD/
│   ├── TinyCD/
│   ├── Tiny_model_4_CD/
│   ├── elgcnet/
│   ├── fully_convolutional_change_detection/
│   └── open-cd/
├── results/
│   ├── comparison_table.csv
│   ├── download_log.jsonl
│   └── training_log.jsonl
├── generated_configs/              # generated model-specific config files
├── generated_dataset_views/        # generated compatibility views for upstream repos
├── BIT_CD/                         # original model repository copy
├── BiFA/
├── CDMamba/
├── Change3D/
├── ChangeFormer/
├── IFNet/
├── RSM-CD/
├── SChanger/
├── Siam-NestedUNet/
├── STANet/
├── evaluate.py
├── run_training.py
├── setup.py
└── TRAINING_GUIDE.md
```

## Known Issues

| Model | Issue | Status | Workaround |
|-------|-------|--------|------------|
| `rsm_cd` | Upstream RS-Mamba training path has prior initialization/runtime issues. | ❌ Unresolved | Run explicitly only after auditing the upstream environment; skip in broad sweeps if needed. |
| `changemamba` | Requires VMamba kernels and OpenMMLab stack. | ⚠️ Separate install needed | Install MMSeg stack in Installation section and run `setup.py` for VMamba weights. |
| `changer` | Requires Open-CD / mmengine / mmcv / mmsegmentation. | ⚠️ Separate install needed | Install MMSeg stack in Installation section. |
| `tinycd` | RGB-only model path; explicitly excluded for `wildfire_s2`. | ⚠️ By design | Use RGB datasets or edit dataset config only when the data is actually RGB. |
| `evaluate.py` | Central checkpoint loading is adapter-based and currently smoke-tested for `bit_cd`, `cgnet`, `changeformer`, `dsamnet`, `elgcnet`, FC variants, `hanet`, `siam_nestedunet`, `stanet`, and `tinycd`. Remaining custom/OpenMMLab models still need verified adapters. | 🔄 In Progress | Add a real in-process model construction/checkpoint adapter or call a verified upstream evaluator and convert its outputs. |
| `dsifn_cd` masks | Raw DSIFN masks may be `0/1`, which some upstream loaders can scale to all zeros. | ✅ Fixed in generated views | Regenerate views by launching training or running dataset preparation. |
| `SChanger` repo URL | Official clone URL was not confirmed from audited files. | 🔄 In Progress | `setup.py` skips automatic clone for this entry and prints a warning. |
| root license | No root `LICENSE` file was found during audit. | 🔄 Documentation gap | Check upstream model licenses before redistribution. |

## Adding a New Model

1. Clone the upstream repository into `model_repos/<name>`.
2. Create `configs/models/<name>.yaml` with `name`, epochs, optimizer, LR, scheduler, loss, backbone, pretrained weights, and image size.
3. Write `train/train_<name>.py`.
4. Reuse `train/wrapper_common.py` if the model is a subprocess adapter.
5. Use `datasets/cd_dataset.py` directly if the model can train in the unified process.
6. Register the model in `configs/models/registry.yaml`.
7. Add pretrained weight handling to `utils/weight_downloader.py` or `setup.py` when needed.
8. Run `python run_training.py --model <name> --dataset levir_cd --dry-run`.
9. Run the wrapper smoke-test using the real script path, for example `python train/train_bifa.py --dataset levir_cd --smoke-test`.
10. Run a short real training pass on one dataset before adding the model to a full sweep.
11. Ensure final metrics are saved as `results/<model>/<dataset>/metrics_test.json`.
12. Regenerate `results/comparison_table.csv`.

## Citation

If you use this benchmark suite in your research, please cite the individual model papers. Key references:

<details>
<summary>BibTeX references</summary>

```bibtex
@article{chen2021bit,
  title={Remote Sensing Image Change Detection with Transformers},
  author={Chen, Hao and Qi, Zipeng and Shi, Zhenwei},
  journal={IEEE Transactions on Geoscience and Remote Sensing},
  year={2021}
}

@article{zhang2020dsifn,
  title={A deeply supervised image fusion network for change detection in high resolution bi-temporal remote sensing images},
  author={Zhang, Chenxiao and Yue, Peng and Tapete, Deodato and Jiang, Linlin and Shangguan, Bo and Huang, Liangpei and Liu, Guoxiang},
  journal={ISPRS Journal of Photogrammetry and Remote Sensing},
  year={2020}
}

@article{bandara2022changeformer,
  title={A Transformer-Based Siamese Network for Change Detection},
  author={Bandara, Wele Gedara Chaminda and Patel, Vishal M.},
  journal={IGARSS},
  year={2022}
}

@article{zhou2025schanger,
  title={SChanger: Change Detection from a Semantic Change and Spatial Consistency Perspective},
  author={Zhou, Ziyu and Hu, Keyan and Fang, Yutian and Rui, Xiaoping},
  journal={IEEE JSTARS},
  year={2025}
}
```

</details>

## Acknowledgements

We thank the authors of all included models for their open-source implementations. This benchmark builds on:

- [Open-CD](https://github.com/likyoo/open-cd) for Changer and the Open-CD toolbox.
- [VMamba](https://github.com/MzeroMiko/VMamba) for the VMamba backbone family.
- [timm](https://github.com/huggingface/pytorch-image-models) for pretrained backbone weights.
- University of Peradeniya for computational resources.


### Setup Commands
`python setup.py`
Runs environment checks, clones repos, fetches weights, and prepares dataset lists.
`python setup.py --status`
Prints status without changes.
`python setup.py --skip-weights`
Skips weight downloads.
`python setup.py --env-check-only`
Checks packages only.
`python setup.py --dataset levir_cd`
Prepares list files for one dataset config.

### Training Commands
`python run_training.py --model bifa --dataset levir_cd`
Trains one model on one dataset.
`python run_training.py --model all --dataset levir_cd`
Runs every registered model on one dataset.
`python run_training.py --model bifa --dataset all`
Runs one model across all configured datasets with available roots.
`python run_training.py --model all --dataset all`
Runs the full configured sweep.
`python run_training.py --model all --dataset dsifn_cd --dry-run`
Checks launch commands without training.

### Evaluation Commands
`python evaluate.py --model bifa --dataset levir_cd`
Attempts central evaluation for a trained checkpoint.
`python evaluate.py --model all --dataset all --dry-run`
Checks evaluation config resolution.
`python utils/weight_downloader.py --prefetch-all`
Fetches managed pretrained weights.
`python utils/weight_downloader.py --list`
Lists managed VMamba weight files.


## Audit Appendix: Environment Snapshot

The local `Mamba` environment used during audit reported:

```text
torch 2.6.0+cu124
torchvision 0.21.0+cu124
numpy 2.1.2
PIL 12.2.0
cv2 4.13.0
yaml 6.0.2
tqdm 4.68.1
timm 0.4.12
einops 0.8.1
sklearn 1.6.1
```

`timm 0.4.12` does not expose every modern MiT alias. The weight downloader treats missing `mit_b0` and `mit_b1` aliases as optional warmup warnings unless the model explicitly requires them.