Add complete SADER model card and usage guide

README.md

@@ -1,16 +1,164 @@
 ---
 license: other
+library_name: pytorch-lightning
+pipeline_tag: image-to-image
+tags:
+- remote-sensing
+- cloud-removal
+- image-restoration
+- diffusion
+- multi-temporal
+- sentinel-2
+- pytorch
+- pytorch-lightning
+- geospatial
+- arxiv:2602.00536
 ---
-# TGRS-CREDM weights
 
-Cloud-removal diffusion model weights and configs (TGRS-CREDM project).
+# SADER
 
-| 目录 | 内容 | 权重大小 |
-|---|---|---|
-| `tsdesign/` | TS-design 最终模型 final_ckpt | 1.23 GB |
-| `newdesign/` | New-design 最终模型 final_ckpt | 0.31 GB |
-| `tsmask/` | TS-mask 最终模型 final_ckpt | 0.83 GB |
-| `pretrained/` | MAE 预训练骨干(5 组:eurosat rgb/ms/rgbn × mask 比例,含 loss 曲线)| ~0.16 GB |
+Official checkpoints for **SADER: Structure-Aware Diffusion Framework with Deterministic Resampling for Multi-Temporal Remote Sensing Cloud Removal**.
 
-每个目录内含:`final_ckpt/last.ckpt`(或 `checkpoint.pth`)、`configs/*.yaml`(project/lightning 配置)、`testtube/`(hparams 与 metrics.csv)。
-权重为 PyTorch Lightning checkpoint(dict 格式),大于 10 MB 的文件由 HF LFS 自动托管。
+SADER combines a multi-temporal conditional denoising network, a cloud-aware training objective, and deterministic resampling for cloud-free reconstruction from temporally aligned Sentinel-2 observations.
+
+- **Paper:** [arXiv:2602.00536](https://arxiv.org/abs/2602.00536)
+- **Code and inference instructions:** [github.com/zyfzs0/SADER](https://github.com/zyfzs0/SADER)
+- **Issues:** [github.com/zyfzs0/SADER/issues](https://github.com/zyfzs0/SADER/issues)
+
+## Released checkpoints
+
+The two primary SADER checkpoints correspond to the benchmark settings reported in the paper.
+
+| Directory | Dataset / setting | Model output | Main checkpoint | MAE checkpoint used by deterministic resampling |
+|---|---|---|---|---|
+| `newdesign/` | Sen2_MTC_New; three temporal RGB+NIR observations | RGB | `newdesign/final_ckpt/last.ckpt` | `pretrained/imputation_mask0.5_MAE_eurosat_rgb_dm192_bs16_lr0.001_Exp_0/checkpoint.pth` |
+| `tsdesign/` | SEN12MS-CR-TS(EA); three temporal Sentinel-2 observations with 13 bands | 13 Sentinel-2 bands | `tsdesign/final_ckpt/last.ckpt` | `pretrained/imputation_mask0.5_MAE_eurosat_ms_dm192_bs16_lr0.001_Exp_0/checkpoint.pth` |
+
+The repository also contains:
+
+- `tsmask/`: an additional mask-conditioned SEN12MS-CR-TS(EA) experimental checkpoint and its run snapshots.
+- `pretrained/`: five EuroSAT MAE checkpoints used in the final configurations or auxiliary pretraining experiments.
+- `*/configs/`: the original project and PyTorch Lightning configuration snapshots.
+- `*/testtube/`: saved hyperparameters and training metric logs.
+
+The configuration snapshots preserve the paths used for the original runs. Replace all dataset paths and checkpoint paths with locations on your system before running the code.
+
+## Download
+
+Install the Hugging Face CLI:
+
+```bash
+pip install -U huggingface_hub
+```
+
+Download the complete release (approximately 2.7 GB):
+
+```bash
+hf download zyfz0um/SADER --local-dir ./sader_weights
+```
+
+Download only the Sen2_MTC_New model and its MAE checkpoint:
+
+```bash
+hf download zyfz0um/SADER \
+  newdesign/final_ckpt/last.ckpt \
+  pretrained/imputation_mask0.5_MAE_eurosat_rgb_dm192_bs16_lr0.001_Exp_0/checkpoint.pth \
+  --local-dir ./sader_weights
+```
+
+Download only the SEN12MS-CR-TS(EA) model and its MAE checkpoint:
+
+```bash
+hf download zyfz0um/SADER \
+  tsdesign/final_ckpt/last.ckpt \
+  pretrained/imputation_mask0.5_MAE_eurosat_ms_dm192_bs16_lr0.001_Exp_0/checkpoint.pth \
+  --local-dir ./sader_weights
+```
+
+## Use with the official code
+
+Clone the code and initialize the MAE submodule:
+
+```bash
+git clone --recursive https://github.com/zyfzs0/SADER.git
+cd SADER
+pip install -r requirements.txt
+```
+
+Download the required checkpoint pair into the code repository, then edit the corresponding YAML file:
+
+| Dataset | Official YAML file |
+|---|---|
+| Sen2_MTC_New | `configs/example_training/sen2_mtc_new_TemporalAdm_repaint_mae.yaml` |
+| SEN12MS-CR-TS(EA) | `configs/example_training/sentinelts_new_repaint_mae.yaml` |
+
+Update the following entries in the YAML file:
+
+1. `model.ckpt_path`: path to the SADER `last.ckpt` file.
+2. `sampler_config.params.mae_config.params.configs.model_path`: path to the corresponding MAE `checkpoint.pth` file.
+3. Dataset paths under `data.params`.
+
+Run evaluation:
+
+```bash
+python main.py \
+  --base configs/example_training/<CONFIG_FILE>.yaml \
+  --enable_tf32 \
+  -t false
+```
+
+Run prediction and save reconstructed images:
+
+```bash
+python main.py \
+  --base configs/example_training/<CONFIG_FILE>.yaml \
+  --enable_tf32 \
+  -t false \
+  --no-test true \
+  --predict true
+```
+
+See the [official GitHub README](https://github.com/zyfzs0/SADER#tadausage) for dataset preparation, environment setup, training, testing, and prediction details.
+
+## Input and output settings
+
+| Dataset | Temporal input | Auxiliary information | Reconstruction target |
+|---|---|---|---|
+| Sen2_MTC_New | Three aligned observations | NIR is used together with RGB as conditional information | RGB image |
+| SEN12MS-CR-TS(EA) | Three aligned Sentinel-2 observations | No additional auxiliary channel | All 13 Sentinel-2 bands |
+
+The released configurations use 256 × 256 image patches and `T = 3` temporal observations.
+
+## Reported results
+
+The following results use the evaluation protocol reported in the paper.
+
+| Dataset | PSNR ↑ | SSIM ↑ | LPIPS ↓ | SAM (°) ↓ |
+|---|---:|---:|---:|---:|
+| Sen2_MTC_New | 20.941 | 0.729 | 0.228 | — |
+| SEN12MS-CR-TS(EA) | 31.234 | 0.937 | — | 5.885 |
+
+## Intended use and limitations
+
+These checkpoints are intended for research and reproducibility in multi-temporal remote sensing cloud removal. Performance may change for sensors, spectral configurations, geographic regions, temporal lengths, or preprocessing pipelines that differ from the two reported benchmarks. The full MTCDN is computationally demanding despite its compact parameter count.
+
+The `.ckpt` and `.pth` files use PyTorch serialization, which may rely on pickle. Load checkpoint files only from a source you trust.
+
+## License
+
+This repository currently declares the license as `other`; no separate license for the released weights has been specified. Please contact the authors with licensing questions.
+
+## Citation
+
+```bibtex
+@article{zhang2026sader,
+  title={SADER: Structure-Aware Diffusion Framework with Deterministic Resampling for Multi-Temporal Remote Sensing Cloud Removal},
+  author={Zhang, Yifan and Chen, Qian and Liu, Yi and Li, Wengen and Guan, Jihong},
+  journal={arXiv preprint arXiv:2602.00536},
+  year={2026}
+}
+```
+
+## Contact
+
+For questions, please open an issue in the [SADER GitHub repository](https://github.com/zyfzs0/SADER/issues) or contact `yifanzhg@umich.edu` / `2250951@tongji.edu.cn`.