# whuyyx/magc architecture

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

- Interactive diagram: https://gitdiagram.com/whuyyx/magc
- Repository: https://github.com/whuyyx/magc

## Overview

MAGC is a map-assisted remote-sensing image compression system for extremely low bitrates. Its inference workflow loads a configured, checkpointed model, processes input images through the ControlLDM compression-and-reconstruction path, then saves results and reports bitrate and image-quality metrics. Training has two documented stages, backed by dataset loading and batch transforms. The graph also shows the latent-diffusion and entropy-coding layers that support the model. Some inference and model internals are unsampled; arrows are limited to relationships shown in excerpts, the source index, or README.

Main entry points: [`model/cldm.py`](https://github.com/whuyyx/magc/blob/main/model/cldm.py) (ControlLDM), [`ldm/models/diffusion/ddpm.py`](https://github.com/whuyyx/magc/blob/main/ldm/models/diffusion/ddpm.py) (Latent diffusion), [`inference.py`](https://github.com/whuyyx/magc/blob/main/inference.py) (Inference runner), [`train.py`](https://github.com/whuyyx/magc/blob/main/train.py) (Training entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["User workflow"]
  node_inference["Inference runner<br/>[inference.py]"]
  node_quality["Quality metrics<br/>[iqa.py]"]
  node_training["Training entry<br/>[train.py]"]
  node_dataset["Dataset loader<br/>[data_module.py]"]
  node_transforms["Batch transforms<br/>[batch_transform.py]"]
end

subgraph group_magc["MAGC model"]
  node_cldm["ControlLDM<br/>[cldm.py]"]
  node_adapter["Map adapter<br/>[adapters.py]"]
  node_sampler["Spaced sampler<br/>[spaced_sampler.py]"]
end

subgraph group_diffusion["Latent diffusion"]
  node_diffusion_model["Latent diffusion<br/>[ddpm.py]"]
  node_ddim["DDIM sampler<br/>[ddim.py]"]
  node_autoencoder["Latent autoencoder<br/>[autoencoder.py]"]
  node_unet["Diffusion networks<br/>[openaimodel.py]"]
  node_attention["Attention layers<br/>[attention.py]"]
  node_instantiation["Config instantiation<br/>[util.py]"]
end

subgraph group_compression["Compression runtime"]
  node_hyperencoder["Hyperencoder<br/>[hyperencoder.py]"]
  node_entropy["Entropy models<br/>[entropy_models.py]"]
end

node_user(("Image user"))
node_image_input["Remote-sensing images"]
node_results["Reconstructions and metrics"]
node_training_data["Training data"]

node_user -->|"runs inference"| node_inference
node_image_input -->|"supplies images"| node_inference
node_inference -->|"loads model"| node_cldm
node_inference -->|"computes metrics"| node_quality
node_inference -->|"saves results"| node_results
node_cldm -->|"extends"| node_diffusion_model
node_cldm -->|"instantiates"| node_adapter
node_cldm -->|"uses"| node_hyperencoder
node_cldm -->|"uses"| node_sampler
node_diffusion_model -->|"instantiates"| node_autoencoder
node_diffusion_model -->|"imports"| node_ddim
node_diffusion_model -->|"imports"| node_hyperencoder
node_diffusion_model -->|"configures"| node_instantiation
node_autoencoder -->|"uses layers"| node_unet
node_unet -->|"uses attention"| node_attention
node_hyperencoder -->|"uses entropy coding"| node_entropy
node_user -->|"starts training"| node_training
node_training_data -->|"provides samples"| node_dataset
node_dataset -->|"applies transforms"| node_transforms
node_training -.->|"loads data"| node_dataset
node_training -.->|"trains model"| node_cldm

click node_inference "https://github.com/whuyyx/magc/blob/main/inference.py"
click node_quality "https://github.com/whuyyx/magc/blob/main/cal_metrics/iqa.py"
click node_training "https://github.com/whuyyx/magc/blob/main/train.py"
click node_dataset "https://github.com/whuyyx/magc/blob/main/dataset/data_module.py"
click node_transforms "https://github.com/whuyyx/magc/blob/main/dataset/batch_transform.py"
click node_cldm "https://github.com/whuyyx/magc/blob/main/model/cldm.py"
click node_adapter "https://github.com/whuyyx/magc/blob/main/model/adapters.py"
click node_sampler "https://github.com/whuyyx/magc/blob/main/model/spaced_sampler.py"
click node_hyperencoder "https://github.com/whuyyx/magc/blob/main/ldm/models/hyperencoder.py"
click node_entropy "https://github.com/whuyyx/magc/blob/main/compressai/entropy_models/entropy_models.py"
click node_diffusion_model "https://github.com/whuyyx/magc/blob/main/ldm/models/diffusion/ddpm.py"
click node_ddim "https://github.com/whuyyx/magc/blob/main/ldm/models/diffusion/ddim.py"
click node_autoencoder "https://github.com/whuyyx/magc/blob/main/ldm/models/autoencoder.py"
click node_unet "https://github.com/whuyyx/magc/blob/main/ldm/modules/diffusionmodules/openaimodel.py"
click node_attention "https://github.com/whuyyx/magc/blob/main/ldm/modules/attention.py"
click node_instantiation "https://github.com/whuyyx/magc/blob/main/ldm/util.py"

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_inference,node_quality,node_training,node_dataset,node_transforms,node_user toneBlue
class node_cldm,node_adapter,node_sampler toneAmber
class node_diffusion_model,node_ddim,node_autoencoder,node_unet,node_attention,node_instantiation toneMint
class node_hyperencoder,node_entropy toneRose
class node_image_input,node_results,node_training_data toneIndigo
```

## Components

### User workflow

- [Inference runner](https://github.com/whuyyx/magc/blob/main/inference.py): `inference.py`
- [Quality metrics](https://github.com/whuyyx/magc/blob/main/cal_metrics/iqa.py): `cal_metrics/iqa.py`
- [Training entry](https://github.com/whuyyx/magc/blob/main/train.py): `train.py`
- [Dataset loader](https://github.com/whuyyx/magc/blob/main/dataset/data_module.py): `dataset/data_module.py`
- [Batch transforms](https://github.com/whuyyx/magc/blob/main/dataset/batch_transform.py): `dataset/batch_transform.py`

### MAGC model

- [ControlLDM](https://github.com/whuyyx/magc/blob/main/model/cldm.py): `model/cldm.py`
- [Map adapter](https://github.com/whuyyx/magc/blob/main/model/adapters.py): `model/adapters.py`
- [Spaced sampler](https://github.com/whuyyx/magc/blob/main/model/spaced_sampler.py): `model/spaced_sampler.py`

### Latent diffusion

- [Latent diffusion](https://github.com/whuyyx/magc/blob/main/ldm/models/diffusion/ddpm.py): `ldm/models/diffusion/ddpm.py`
- [DDIM sampler](https://github.com/whuyyx/magc/blob/main/ldm/models/diffusion/ddim.py): `ldm/models/diffusion/ddim.py`
- [Latent autoencoder](https://github.com/whuyyx/magc/blob/main/ldm/models/autoencoder.py): `ldm/models/autoencoder.py`
- [Diffusion networks](https://github.com/whuyyx/magc/blob/main/ldm/modules/diffusionmodules/openaimodel.py): `ldm/modules/diffusionmodules/openaimodel.py`
- [Attention layers](https://github.com/whuyyx/magc/blob/main/ldm/modules/attention.py): `ldm/modules/attention.py`
- [Config instantiation](https://github.com/whuyyx/magc/blob/main/ldm/util.py): `ldm/util.py`

### Compression runtime

- [Hyperencoder](https://github.com/whuyyx/magc/blob/main/ldm/models/hyperencoder.py): `ldm/models/hyperencoder.py`
- [Entropy models](https://github.com/whuyyx/magc/blob/main/compressai/entropy_models/entropy_models.py): `compressai/entropy_models/entropy_models.py`

### Other components

- **Image user**
- **Remote-sensing images**
- **Reconstructions and metrics**
- **Training data**

## Connections

- Image user → Inference runner: runs inference
- Remote-sensing images → Inference runner: supplies images
- Inference runner → ControlLDM: loads model (evidence: `inference.py`)
- Inference runner → Quality metrics: computes metrics (evidence: `inference.py`)
- Inference runner → Reconstructions and metrics: saves results (evidence: `inference.py`)
- ControlLDM → Latent diffusion: extends (evidence: `model/cldm.py`)
- ControlLDM → Map adapter: instantiates (evidence: `model/cldm.py`)
- ControlLDM → Hyperencoder: uses (evidence: `model/cldm.py`)
- ControlLDM → Spaced sampler: uses (evidence: `model/cldm.py`)
- Latent diffusion → Latent autoencoder: instantiates (evidence: `ldm/models/diffusion/ddpm.py`)
- Latent diffusion → DDIM sampler: imports (evidence: `ldm/models/diffusion/ddpm.py`)
- Latent diffusion → Hyperencoder: imports (evidence: `ldm/models/diffusion/ddpm.py`)
- Latent diffusion → Config instantiation: configures (evidence: `ldm/models/diffusion/ddpm.py`)
- Latent autoencoder → Diffusion networks: uses layers (evidence: `ldm/models/autoencoder.py`)
- Diffusion networks → Attention layers: uses attention (evidence: `ldm/modules/diffusionmodules/openaimodel.py`)
- Hyperencoder → Entropy models: uses entropy coding (evidence: `ldm/models/hyperencoder.py`)
- Image user → Training entry: starts training
- Training data → Dataset loader: provides samples (evidence: `dataset/data_module.py`)
- Dataset loader → Batch transforms: applies transforms (evidence: `dataset/data_module.py`)
- Training entry → Dataset loader: loads data
- Training entry → ControlLDM: trains model
