# yangyang12318/lgcn architecture

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

- Interactive diagram: https://gitdiagram.com/yangyang12318/lgcn
- Repository: https://github.com/yangyang12318/lgcn

## Overview

1. **What this repository is**
   - This is a **PyTorch-based research codebase** for **self-supervised real SAR despeckling** using a **Local–Global Collaborative Network (LGCN)**.
   - The repo is organized around a classic deep-learning pipeline: **dataset loading → model/network construction → training/validation/inference**.

2. **Primary execution entry points**
   - `train/train_all.py` is the main training driver.
   - `validate/validate.py` is the evaluation/validation entry point.
   - `submit_test/test.py` is a separate inference/testing path, likely for generating final outputs or submission-style results.
   - `train_all.sh` is the shell wrapper for launching training with the expected environment and config.

3. **Configuration boundary**
   - `option/all.json` centralizes run-time settings such as dataset paths, model choices, and training hyperparameters.
   - `utils/option.py` likely parses and exposes those settings to the rest of the codebase.
   - This indicates the repo is **config-driven**, with the JSON file acting as the main control plane for experiments.

4. **Dataset subsystem**
   - `dataset/base.py` is the shared dataset abstraction.
   - `dataset/SAR_sRGB.py` is a concrete dataset/preprocessing module for SAR-related data, likely handling the conversion or pairing between SAR and displayable formats.
   - `dataset/__init__.py` exposes dataset classes so the training code can instantiate them without depending on file-level details.
   - The data boundary is external: the README points to **GF-3, TerraSAR-X, Sentinel-1**, and a **PolSAR land-cover classification dataset** as input sources.

5. **Network subsystem**
   - `network/all.py` and `network/__init__.py` suggest the actual LGCN architecture is implemented here and exported as a package.
   - This layer is where the paper-specific building blocks live: the **local branch**, **global branch**, and their collaborative fusion.
   - In architectural terms, this package is the **pure forward-pass / layer-definition layer**, separate from training logic.

6. **Model subsystem**
   - `model/base.py` and `model/all.py` likely wrap the network with training-oriented behavior: loss computation, optimization hooks, checkpoint handling, and experiment-level orchestration.
   - This separation implies a clean split between:
     - **network** = architecture definition
     - **model** = how that architecture is trained/evaluated
   - `model/__init__.py` exposes the chosen model implementation to the training scripts.

7. **Utility layer**
   - `utils/build.py` likely constructs datasets, models, and other components from the config.
   - `utils/io.py` probably handles filesystem concerns such as saving logs, checkpoints, and results.
   - `utils/option.py` manages option parsing/loading.
   - These utilities form the glue between configuration, data, and runtime execution.

8. **Training data flow**
   - Training begins in `train/train_all.py`, which reads configuration, builds the dataset and model, then launches optimization.
   - Data flows from the dataset package into the model/network stack through PyTorch dataloading and batching.
   - Checkpoints and logs are likely emitted through `utils/io.py`, while experiment parameters come from `option/all.json`.

9. **Validation and test flow**
   - `validate/validate.py` uses the trained model to run evaluation on held-out data, likely computing despeckling quality metrics and/or saving predicted outputs.
   - `submit_test/test.py` appears to be a lightweight inference path, separated from validation so test-time generation can be run independently.
   - This suggests the repo distinguishes **model assessment** from **final inference/export**.

10. **Project boundaries and runtime**
   - The repo is a **standalone research training/inference project**, not a service or web application.
   - Its main external dependency is **PyTorch** on **Python 3.9.5** with CUDA-enabled execution.
   - The architectural boundary is clear: **raw SAR datasets in**, **trained despeckling model**, then **denoised outputs / validation metrics out**.

11. **What to show in an architecture diagram**
   - A useful diagram should show:
     - external SAR datasets feeding into `dataset/*`
     - config from `option/all.json` into `utils/option.py`
     - `train/validate/submit_test` as separate entry points
     - `utils/build.py` assembling components
     - `model/*` wrapping `network/*`
     - outputs to checkpoints, logs, and inference results
   - The key internal distinction is between **data handling**, **network definition**, and **experiment orchestration**.

Main entry points: [`train/train_all.py`](https://github.com/yangyang12318/lgcn/blob/main/train/train_all.py) (Train), [`dataset/__init__.py`](https://github.com/yangyang12318/lgcn/blob/main/dataset/__init__.py) (Dataset API), [`model/__init__.py`](https://github.com/yangyang12318/lgcn/blob/main/model/__init__.py) (Model API), [`utils/build.py`](https://github.com/yangyang12318/lgcn/blob/main/utils/build.py) (Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_train_all["Train<br/>entry script<br/>[train_all.py]"]
  node_validate["Validate<br/>entry script<br/>[validate.py]"]
  node_test["Test<br/>entry script<br/>[test.py]"]
  node_shell["Launcher<br/>shell wrapper<br/>[train_all.sh]"]
end

subgraph group_config["Config"]
  node_options_json["Run config<br/>json config<br/>[all.json]"]
  node_option_util["Option load<br/>config parser<br/>[option.py]"]
end

subgraph group_data["Data subsystem"]
  node_dataset_base["Dataset base<br/>dataset abstraction<br/>[base.py]"]
  node_sar_dataset["SAR data<br/>dataset module<br/>[SAR_sRGB.py]"]
  node_dataset_pkg["Dataset API<br/>package export<br/>[__init__.py]"]
  node_sar_sources[("SAR sources<br/>external data")]
end

subgraph group_core["Core model"]
  node_network_all["LGCN net<br/>network architecture<br/>[all.py]"]
  node_network_pkg["Network API<br/>package export<br/>[__init__.py]"]
  node_model_base["Model base<br/>training wrapper<br/>[base.py]"]
  node_model_all["Model impl<br/>model wrapper<br/>[all.py]"]
  node_model_pkg["Model API<br/>package export<br/>[__init__.py]"]
end

subgraph group_runtime["Runtime utils"]
  node_build_util["Builder<br/>factory<br/>[build.py]"]
  node_io_util["IO utils<br/>artifact manager<br/>[io.py]"]
end

subgraph group_outputs["Outputs"]
  node_train_artifacts[("Checkpoints<br/>artifact")]
  node_predictions[("Results<br/>artifact")]
end

node_shell -->|"launches"| node_train_all
node_options_json -->|"loaded by"| node_option_util
node_option_util -->|"drives"| node_build_util
node_train_all -->|"reads"| node_option_util
node_validate -->|"reads"| node_option_util
node_test -->|"reads"| node_option_util
node_train_all -->|"builds"| node_build_util
node_validate -->|"builds"| node_build_util
node_test -->|"builds"| node_build_util
node_build_util -->|"creates"| node_dataset_pkg
node_build_util -->|"creates"| node_model_pkg
node_dataset_pkg -->|"extends"| node_dataset_base
node_dataset_pkg -->|"exports"| node_sar_dataset
node_sar_dataset -->|"consumes"| node_sar_sources
node_train_all -->|"trains on"| node_dataset_pkg
node_validate -->|"evaluates on"| node_dataset_pkg
node_test -->|"infers on"| node_dataset_pkg
node_model_pkg -->|"wraps"| node_model_base
node_model_pkg -->|"exports"| node_model_all
node_model_all -->|"uses"| node_network_pkg
node_network_pkg -->|"exports"| node_network_all
node_train_all -->|"optimizes"| node_model_pkg
node_validate -->|"scores"| node_model_pkg
node_test -->|"runs"| node_model_pkg
node_train_all -->|"writes"| node_io_util
node_validate -->|"writes"| node_io_util
node_test -->|"writes"| node_io_util
node_io_util -->|"saves"| node_train_artifacts
node_io_util -->|"saves"| node_predictions

click node_train_all "https://github.com/yangyang12318/lgcn/blob/main/train/train_all.py"
click node_validate "https://github.com/yangyang12318/lgcn/blob/main/validate/validate.py"
click node_test "https://github.com/yangyang12318/lgcn/blob/main/submit_test/test.py"
click node_shell "https://github.com/yangyang12318/lgcn/blob/main/train_all.sh"
click node_options_json "https://github.com/yangyang12318/lgcn/blob/main/option/all.json"
click node_option_util "https://github.com/yangyang12318/lgcn/blob/main/utils/option.py"
click node_dataset_base "https://github.com/yangyang12318/lgcn/blob/main/dataset/base.py"
click node_sar_dataset "https://github.com/yangyang12318/lgcn/blob/main/dataset/SAR_sRGB.py"
click node_dataset_pkg "https://github.com/yangyang12318/lgcn/blob/main/dataset/__init__.py"
click node_network_all "https://github.com/yangyang12318/lgcn/blob/main/network/all.py"
click node_network_pkg "https://github.com/yangyang12318/lgcn/blob/main/network/__init__.py"
click node_model_base "https://github.com/yangyang12318/lgcn/blob/main/model/base.py"
click node_model_all "https://github.com/yangyang12318/lgcn/blob/main/model/all.py"
click node_model_pkg "https://github.com/yangyang12318/lgcn/blob/main/model/__init__.py"
click node_build_util "https://github.com/yangyang12318/lgcn/blob/main/utils/build.py"
click node_io_util "https://github.com/yangyang12318/lgcn/blob/main/utils/io.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_train_all,node_validate,node_test,node_shell toneBlue
class node_options_json,node_option_util toneAmber
class node_dataset_base,node_sar_dataset,node_dataset_pkg,node_sar_sources toneMint
class node_network_all,node_network_pkg,node_model_base,node_model_all,node_model_pkg toneRose
class node_build_util,node_io_util toneIndigo
class node_train_artifacts,node_predictions toneTeal
```

## Components

### Entry points

Run commands for training, validation, and test-time inference

- [Train](https://github.com/yangyang12318/lgcn/blob/main/train/train_all.py): entry script · Main training driver · `train/train_all.py`
- [Validate](https://github.com/yangyang12318/lgcn/blob/main/validate/validate.py): entry script · Evaluation entry point · `validate/validate.py`
- [Test](https://github.com/yangyang12318/lgcn/blob/main/submit_test/test.py): entry script · Submission-style inference path · `submit_test/test.py`
- [Launcher](https://github.com/yangyang12318/lgcn/blob/main/train_all.sh): shell wrapper · Convenience script for training launch · `train_all.sh`

### Config

Experiment settings and option loading

- [Run config](https://github.com/yangyang12318/lgcn/blob/main/option/all.json): json config · Central experiment configuration · `option/all.json`
- [Option load](https://github.com/yangyang12318/lgcn/blob/main/utils/option.py): config parser · Loads and exposes runtime options · `utils/option.py`

### Data subsystem

Dataset abstractions and SAR preprocessing

- [Dataset base](https://github.com/yangyang12318/lgcn/blob/main/dataset/base.py): dataset abstraction · Shared dataset interface · `dataset/base.py`
- [SAR data](https://github.com/yangyang12318/lgcn/blob/main/dataset/SAR_sRGB.py): dataset module · SAR-specific loading and preprocessing · `dataset/SAR_sRGB.py`
- [Dataset API](https://github.com/yangyang12318/lgcn/blob/main/dataset/__init__.py): package export · Dataset package entry · `dataset/__init__.py`
- **SAR sources**: external data · Input datasets such as GF-3, TerraSAR-X, Sentinel-1

### Core model

Network definition and training-oriented wrapping

- [LGCN net](https://github.com/yangyang12318/lgcn/blob/main/network/all.py): network architecture · Local-global collaborative despeckling network · `network/all.py`
- [Network API](https://github.com/yangyang12318/lgcn/blob/main/network/__init__.py): package export · Network package entry · `network/__init__.py`
- [Model base](https://github.com/yangyang12318/lgcn/blob/main/model/base.py): training wrapper · Model-level training and evaluation hooks · `model/base.py`
- [Model impl](https://github.com/yangyang12318/lgcn/blob/main/model/all.py): model wrapper · Concrete model orchestration · `model/all.py`
- [Model API](https://github.com/yangyang12318/lgcn/blob/main/model/__init__.py): package export · Model package entry · `model/__init__.py`

### Runtime utils

Build, option, and IO helpers

- [Builder](https://github.com/yangyang12318/lgcn/blob/main/utils/build.py): factory · Constructs datasets and models from config · `utils/build.py`
- [IO utils](https://github.com/yangyang12318/lgcn/blob/main/utils/io.py): artifact manager · Handles logs, checkpoints, and result files · `utils/io.py`

### Outputs

Artifacts produced by training and inference

- **Checkpoints**: artifact · Saved training state and logs
- **Results**: artifact · Validation metrics and inference outputs

## Connections

- Launcher → Train: launches · Shell wrapper starts the main trainer
- Run config → Option load: loaded by · Configuration file is parsed into runtime options
- Option load → Builder: drives · Parsed options control component construction
- Train → Option load: reads · Training entry point loads experiment options
- Validate → Option load: reads · Validation entry point loads experiment options
- Test → Option load: reads · Test entry point loads experiment options
- Train → Builder: builds · Training assembles data and model through builder
- Validate → Builder: builds · Validation reuses builder for loaded model and data
- Test → Builder: builds · Inference path constructs needed runtime components
- Builder → Dataset API: creates · Builder instantiates datasets through the package API
- Builder → Model API: creates · Builder instantiates the selected model implementation
- Dataset API → Dataset base: extends · Package exports shared dataset abstraction
- Dataset API → SAR data: exports · Package exposes SAR dataset implementation
- SAR data → SAR sources: consumes · Dataset implementation reads external SAR inputs
- Train → Dataset API: trains on · Training consumes batched dataset samples
- Validate → Dataset API: evaluates on · Validation consumes held-out dataset samples
- Test → Dataset API: infers on · Test path consumes dataset samples for output generation
- Model API → Model base: wraps · Model package exposes training-oriented base behavior
- Model API → Model impl: exports · Package exposes the concrete model implementation
- Model impl → Network API: uses · Model implementation depends on network definitions
- Network API → LGCN net: exports · Network package exposes LGCN architecture
- Train → Model API: optimizes · Training runs optimization over the model
- Validate → Model API: scores · Validation uses the model for evaluation
- Test → Model API: runs · Inference uses the model to generate outputs
- Train → IO utils: writes · Training emits logs and checkpoints through IO utilities
- Validate → IO utils: writes · Validation stores metrics and predictions through IO utilities
- Test → IO utils: writes · Inference stores generated results through IO utilities
- IO utils → Checkpoints: saves · IO utilities persist training artifacts
- IO utils → Results: saves · IO utilities persist outputs and metrics