# ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks architecture

> Architecture diagram of the GitHub repository ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks
- Repository: https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks

## Overview

##### Project Type & Purpose
- This is a research-style deep learning pipeline implementing CycleGAN for unpaired image-to-image translation.
- It is organized as a CLI-driven training/evaluation tool, with modular data loading, model definitions, training loops, checkpointing, logging, and testing.

##### File Structure
- Top-level scripts
– train.py / train_from_checkpoint.py: entry points for training
– test.py / evaluate_fcn.py: evaluation & inference
- Configuration
– options/base_options.py, train_options.py, test_options.py: define and parse CLI args
- Data handling
– data/dataset.py, data/unaligned_dataset.py: load & preprocess two unpaired image domains
- Models
– models/generators.py: generator architectures
– models/discriminators.py: discriminator architectures
– models/networks.py: shared network blocks
– models/cycle_gan_model.py: orchestrates generator + discriminator + cycle losses
- Utilities
– utils.py, metrics.py: helper functions, loss calculations, logging, plotting
- Persistence
– model_checkpoints/: saved .pth files per epoch
– checkpoints/: raw logs for custom “horse2zebra” runs
– results/, samples/: CSV/visual output of experiments

##### Main Components & Their Interactions

a. CLI / Options Parser
– Parses user flags (epochs, lr, lambda_cycle, device).
– Feeds config into Training Orchestrator and Data Loader.

b. Data Loader
– Reads two image domains from disk via UnalignedDataset
– Applies transforms, batches data.

c. CycleGAN Model Orchestrator
– Instantiates two Generators (G_AB, G_BA) and two Discriminators (D_A, D_B).
– Coordinates forward passes:
- Real A → G_AB → Fake B → D_B → adversarial loss
- Real B → G_BA → Fake A → D_A → adversarial loss
- Cycle: Fake B → G_BA → Rec A; Fake A → G_AB → Rec B
– Computes cycle-consistency, identity, adversarial losses.

d. Optimizers & Schedulers
– Two optimizer groups: one for generators, one for discriminators.
– LR schedulers applied per epoch.

e. Training Loop
– For each epoch / batch:
1. Load real A & B
2. Forward passes through G, D
3. Compute and backprop losses
4. Step optimizers, update schedulers
5. Log scalar losses and images via utils.

f. Checkpointing & Logging
– Saves model weights (.pth) in model_checkpoints/ after specified epochs.
– Exports loss logs (CSV) to checkpoints/ and results/.

g. Evaluation & Visualization
– evaluate_fcn.py / test.py load saved checkpoints, run inference on test sets.
– Outputs samples/ images and fcn_scores.csv.

##### Architectural Patterns & Principles
- Modular separation: CLI, Data, Model, Training, Evaluation modules.
- Dependency injection via options classes.
- Clear pipeline: Data → Model → Loss → Optimizer → Checkpoint/Log.
- Extensibility: swap datasets, architectures or hyperparams via options files.

1. Sketch top-level modules in a horizontal flow: CLI → Data Loader → Training Engine.
2. Drill into Training Engine: show Generators ↔ Discriminators ↔ Cycles.
3. Side-paths: Checkpoint writer, Logger.
4. A separate branch for “Evaluation” loading saved models.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        TrainScript["train.py"]:::cli
        TrainChkptScript["train_from_checkpoint.py"]:::cli
        TestScript["test.py"]:::cli
        EvalScript["evaluate_fcn.py"]:::cli
    end

    %% CLI / Options Parser
    subgraph "CLI / Options Parser"
        BaseOpt["base_options.py"]:::cli
        TrainOpt["train_options.py"]:::cli
        TestOpt["test_options.py"]:::cli
        CLI["CLI Parser"]:::cli
    end

    %% Data Loader
    subgraph "Data Loader Module"
        DS["dataset.py"]:::data
        UD["unaligned_dataset.py"]:::data
        DataLoader["Data Loader"]:::data
    end

    %% Training Engine
    subgraph "Training Engine"
        TrainLoop["Training Loop"]:::orchestration
        subgraph "Model Components"
            GAB["Generator G_AB"]:::model
            GBA["Generator G_BA"]:::model
            DA["Discriminator D_A"]:::model
            DB["Discriminator D_B"]:::model
        end
        CycleGANModel["CycleGAN Orchestrator"]:::model
        LossCalc["Loss Computation"]:::orchestration
        OptimSched["Optimizers & Schedulers"]:::orchestration
    end

    %% Storage and Logging
    Checkpoints["model_checkpoints/"]:::storage
    Logs["checkpoints/"]:::storage
    Results["results/"]:::storage
    Samples["samples/"]:::storage

    %% Evaluation
    subgraph "Evaluation & Inference"
        Eval["Evaluation & Inference"]:::orchestration
    end

    %% Connections Entry to CLI
    TrainScript -->|starts| CLI
    TrainChkptScript -->|starts| CLI
    TestScript -->|starts| CLI
    EvalScript -->|starts| CLI

    %% CLI to Data Loader and Training Engine
    CLI -->|config| DataLoader
    CLI -->|config| Eval

    %% Data Loader to Training
    DataLoader -->|batches A & B| TrainLoop

    %% Training Loop orchestration
    TrainLoop -->|init models| CycleGANModel
    CycleGANModel -->|forward pass| LossCalc
    LossCalc -->|compute gradients| TrainLoop
    TrainLoop -->|step| OptimSched
    OptimSched -->|update params| TrainLoop

    %% Model component flows
    CycleGANModel -->|uses| GAB
    CycleGANModel -->|uses| GBA
    CycleGANModel -->|uses| DA
    CycleGANModel -->|uses| DB
    GAB -->|fake B| DB
    GBA -->|fake A| DA
    DB -->|adv loss| LossCalc
    DA -->|adv loss| LossCalc
    GAB -->|cycle input| GBA
    GBA -->|cycle input| GAB

    %% Training to storage
    TrainLoop -->|save weights| Checkpoints
    TrainLoop -->|write logs| Logs

    %% Evaluation outputs
    Eval -->|load weights| Checkpoints
    Eval -->|writes samples| Samples
    Eval -->|writes scores| Results

    %% Click Events
    click TrainScript "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/train.py"
    click TrainChkptScript "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/train_from_checkpoint.py"
    click TestScript "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/test.py"
    click EvalScript "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/evaluate_fcn.py"

    click BaseOpt "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/options/base_options.py"
    click TrainOpt "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/options/train_options.py"
    click TestOpt "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/options/test_options.py"

    click DS "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/data/dataset.py"
    click UD "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/data/unaligned_dataset.py"

    click CycleGANModel "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/models/cycle_gan_model.py"
    click GAB "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/models/generators.py"
    click GBA "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/models/generators.py"
    click DA "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/models/discriminators.py"
    click DB "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/models/discriminators.py"

    click OptimSched "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/models/cycle_gan_model.py"
    click OptimSched "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/train.py"

    click Utils "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/utils.py"
    click Metrics "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/metrics.py"

    click Checkpoints "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/tree/main/model_checkpoints/"
    click Logs "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/checkpoints/horse2zebra/loss_log.csv"
    click Results "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/blob/main/results/fcn_scores.csv"
    click Samples "https://github.com/ilyes2000/unpaired-image-to-image-translation-using-cycle-consistent-adversarial-networks/tree/main/samples/"

    %% Styles
    classDef cli fill:#dcd0ff,stroke:#7f5fff,color:#000
    classDef data fill:#d0e7ff,stroke:#3399ff,color:#000
    classDef model fill:#d0ffd6,stroke:#33cc33,color:#000
    classDef orchestration fill:#ffe6b3,stroke:#ff9900,color:#000
    classDef storage fill:#e0e0e0,stroke:#999,color:#000
```
