# asebaq/rsdiff architecture

> Architecture diagram of the GitHub repository asebaq/rsdiff, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asebaq/rsdiff
- Repository: https://github.com/asebaq/rsdiff

## Overview

RSDiff is a text-conditioned remote-sensing image generator. Its documented reference workflow trains a 128² low-resolution diffusion model on RSICD, trains a 256² super-resolution stage using the base model, samples caption-conditioned images, then evaluates generated images. The legacy Imagen implementation is the documented working path; the newer `src/rsdiff` trainer and sampler are explicitly unfinished. The graph also preserves documented evaluation capabilities. Some training and evaluation wiring is documented in the README but their scripts were not sampled, so uncertain call links are omitted.

Main entry points: [`src/rsdiff/cli.py`](https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/cli.py) (Evaluation commands), [`ddpm/models/Imagen_text_sr_pytorch.py`](https://github.com/asebaq/rsdiff/blob/main/ddpm/models/Imagen_text_sr_pytorch.py) (SR training), [`ddpm/sample_grid.py`](https://github.com/asebaq/rsdiff/blob/main/ddpm/sample_grid.py) (Cascade sampler), [`src/rsdiff/eval/fid.py`](https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/eval/fid.py) (FID metric)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reference["Reference cascade"]
  node_lr_train["LR training"]
  node_sr_train["SR training"]
  node_joint_train["Joint fine-tune"]
  node_base_model["UNet builder<br/>[builders.py]"]
  node_config["Run config<br/>[config.py]"]
  node_trainer["Native trainer<br/>[trainer.py]"]
  node_cli["CLI commands<br/>[cli.py]"]
end

subgraph group_data["Dataset and inputs"]
  node_rsicd["RSICD data"]
end

subgraph group_generation["Generation outputs"]
  node_sample["Cascade sampler<br/>[sample_grid.py]"]
  node_checkpoint["Model checkpoint"]
  node_generated["Generated images"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_cli["Evaluation commands<br/>[cli.py]"]
  node_fid["FID metric<br/>[fid.py]"]
  node_oa["Zero-shot OA<br/>[zeroshot_oa.py]"]
  node_clip_eval["CLIP evaluation"]
  node_report["Evaluation results"]
end

node_user(("Engineer"))
node_hub["Hugging Face Hub"]

node_user -->|"starts training"| node_lr_train
node_rsicd -->|"training data"| node_lr_train
node_lr_train -->|"saves weights"| node_checkpoint
node_user -->|"starts training"| node_sr_train
node_rsicd -->|"training data"| node_sr_train
node_checkpoint -->|"seeds base"| node_sr_train
node_sr_train -->|"saves weights"| node_checkpoint
node_user -->|"starts fine-tune"| node_joint_train
node_rsicd -->|"training data"| node_joint_train
node_checkpoint -->|"loads weights"| node_joint_train
node_user -->|"requests samples"| node_sample
node_rsicd -->|"provides captions"| node_sample
node_checkpoint -->|"loads weights"| node_sample
node_sample -->|"writes images"| node_generated
node_user -->|"runs command"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"dispatches train or sample"| node_trainer
node_trainer -->|"builds model"| node_base_model
node_user -->|"requests metrics"| node_eval_cli
node_eval_cli -->|"runs FID"| node_fid
node_eval_cli -->|"runs classification"| node_oa
node_eval_cli -->|"reads split metadata"| node_rsicd
node_generated -->|"generated set"| node_fid
node_rsicd -->|"real image set"| node_fid
node_user -->|"runs evaluation"| node_clip_eval
node_clip_eval -->|"scores images"| node_generated
node_fid -.->|"records metrics"| node_report
node_clip_eval -.->|"records metrics"| node_report
node_hub -.->|"provides weights"| node_checkpoint

click node_lr_train "https://github.com/asebaq/rsdiff/blob/main/ddpm/models/Imagen_text_pytorch.py"
click node_sr_train "https://github.com/asebaq/rsdiff/blob/main/ddpm/models/Imagen_text_sr_pytorch.py"
click node_joint_train "https://github.com/asebaq/rsdiff/blob/main/ddpm/models/Imagen_text_joint_pytorch.py"
click node_base_model "https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/models/builders.py"
click node_config "https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/training/config.py"
click node_trainer "https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/training/trainer.py"
click node_cli "https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/cli.py"
click node_sample "https://github.com/asebaq/rsdiff/blob/main/ddpm/sample_grid.py"
click node_eval_cli "https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/cli.py"
click node_fid "https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/eval/fid.py"
click node_oa "https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/eval/zeroshot_oa.py"
click node_clip_eval "https://github.com/asebaq/rsdiff/tree/main/scripts/eval"
click node_report "https://github.com/asebaq/rsdiff/tree/main/results"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lr_train,node_sr_train,node_joint_train,node_base_model,node_config,node_trainer,node_cli toneBlue
class node_rsicd toneAmber
class node_sample,node_checkpoint,node_generated toneMint
class node_eval_cli,node_fid,node_oa,node_clip_eval,node_report toneRose
class node_user,node_hub toneIndigo
```

## Components

### Reference cascade

- [LR training](https://github.com/asebaq/rsdiff/blob/main/ddpm/models/Imagen_text_pytorch.py): `ddpm/models/Imagen_text_pytorch.py`
- [SR training](https://github.com/asebaq/rsdiff/blob/main/ddpm/models/Imagen_text_sr_pytorch.py): `ddpm/models/Imagen_text_sr_pytorch.py`
- [Joint fine-tune](https://github.com/asebaq/rsdiff/blob/main/ddpm/models/Imagen_text_joint_pytorch.py): `ddpm/models/Imagen_text_joint_pytorch.py`
- [UNet builder](https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/models/builders.py): `src/rsdiff/models/builders.py`
- [Run config](https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/training/config.py): `src/rsdiff/training/config.py`
- [Native trainer](https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/training/trainer.py): `src/rsdiff/training/trainer.py`
- [CLI commands](https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/cli.py): `src/rsdiff/cli.py`

### Dataset and inputs

- **RSICD data**

### Generation outputs

- [Cascade sampler](https://github.com/asebaq/rsdiff/blob/main/ddpm/sample_grid.py): `ddpm/sample_grid.py`
- **Model checkpoint**
- **Generated images**

### Evaluation

- [Evaluation commands](https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/cli.py): `src/rsdiff/cli.py`
- [FID metric](https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/eval/fid.py): `src/rsdiff/eval/fid.py`
- [Zero-shot OA](https://github.com/asebaq/rsdiff/blob/main/src/rsdiff/eval/zeroshot_oa.py): `src/rsdiff/eval/zeroshot_oa.py`
- [CLIP evaluation](https://github.com/asebaq/rsdiff/tree/main/scripts/eval): `scripts/eval`
- [Evaluation results](https://github.com/asebaq/rsdiff/tree/main/results): `results`

### Other components

- **Engineer**
- **Hugging Face Hub**

## Connections

- Engineer → LR training: starts training
- RSICD data → LR training: training data
- LR training → Model checkpoint: saves weights
- Engineer → SR training: starts training
- RSICD data → SR training: training data
- Model checkpoint → SR training: seeds base
- SR training → Model checkpoint: saves weights
- Engineer → Joint fine-tune: starts fine-tune
- RSICD data → Joint fine-tune: training data
- Model checkpoint → Joint fine-tune: loads weights
- Engineer → Cascade sampler: requests samples
- RSICD data → Cascade sampler: provides captions
- Model checkpoint → Cascade sampler: loads weights
- Cascade sampler → Generated images: writes images
- Engineer → CLI commands: runs command
- CLI commands → Run config: loads settings
- CLI commands → Native trainer: dispatches train or sample
- Native trainer → UNet builder: builds model
- Engineer → Evaluation commands: requests metrics
- Evaluation commands → FID metric: runs FID
- Evaluation commands → Zero-shot OA: runs classification
- Evaluation commands → RSICD data: reads split metadata
- Generated images → FID metric: generated set
- RSICD data → FID metric: real image set
- Engineer → CLIP evaluation: runs evaluation
- CLIP evaluation → Generated images: scores images
- FID metric → Evaluation results: records metrics
- CLIP evaluation → Evaluation results: records metrics
- Hugging Face Hub → Model checkpoint: provides weights