# apaarraina/cartoon-to-realistic-using-cyclegan architecture

> Architecture diagram of the GitHub repository apaarraina/cartoon-to-realistic-using-cyclegan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apaarraina/cartoon-to-realistic-using-cyclegan
- Repository: https://github.com/apaarraina/cartoon-to-realistic-using-cyclegan

## Overview

##### Project Type and Purpose
- This is a machine-learning/deep-learning research pipeline implementing a cycleGAN to translate cartoon faces (domain A) into realistic human faces (domain B).
- Core purpose: ingest two image domains, train generator & discriminator networks in adversarial fashion, and produce a model that can map cartoons → realistic faces (and vice versa).

##### File Structure
- Top-level scripts:
- discriminator.py – discriminator network definition
- generator.py – generator network definition
- train.py – standard cycleGAN training script
- train_with_diversity_loss.py – alternative training script with an added diversity loss
- test_realistic_to_cartoon.py – evaluation / inference script for one direction
- train.py/test scripts read/write model checkpoints and images
- preprocessing_scripts/ directory:
- detec_faces.py – face detection on raw images
- filter_frontal_face.py – remove non-frontal faces
- split.py – split cleaned images into trainA, trainB, testA, testB
- Data directories (implied by README):
- cartoonset10k/ – raw cartoon images
- img_align_celeba/ – raw real images
- cartoon2realistic/{trainA, trainB, testA, testB} – post-split image folders

##### README for Additional Insights
- Mentions pretrained model files (genz.pth, genh.pth, criticz.pth, critich.pth).
- Outlines basic project structure under “cartoon2realistic/”.

##### Main Components & Their Interactions
a. Data Ingestion Layer
- External Storage (Google Drive links) → Local raw folders: “cartoonset10k/” and “img_align_celeba/”.
b. Preprocessing Layer
- filter_frontal_face.py → keep only good frontal faces
- split.py → shard into trainA, trainB, testA, testB under “cartoon2realistic/”
c. Model Definition Layer
- generator.py → Generator architecture (two networks: G_A2B, G_B2A)
- discriminator.py → Discriminator architecture (D_A, D_B)
d. Training Layer
- train.py / train_with_diversity_loss.py
- Inputs: images from trainA, trainB; network modules; hyperparameters
- Outputs: checkpoint files (genz.pth, genh.pth, criticz.pth, critich.pth)
e. Evaluation/Inference Layer
- test_realistic_to_cartoon.py
- Inputs: test set images from testA or testB, pretrained checkpoints
- Outputs: translated images for qualitative assessment
f. Storage & Artifacts
- Model checkpoint directory
- Generated images directory
- (Optionally) logs and metrics (e.g., loss curves)

##### Architectural Patterns & Design Principles
- CycleGAN pattern: two generators + two discriminators + cycle consistency losses
- Modular code-separation: distinct scripts for network definitions, training, testing, preprocessing
- Data-pipeline pattern: clear separation of raw data → cleaned data → train/test splits
- Extensibility: alternative training script (diversity loss) demonstrates plug-and-play of new objectives

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion Layer
    subgraph "Data Ingestion Layer"
        RawCartoon["Cartoon10k (Raw Images)"]:::data
        RawCelebA["img_align_celeba (Raw Images)"]:::data
    end

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        Preprocessing["preprocessing_scripts/"]:::processing
        FaceDetect["detec_faces.py"]:::processing
        Filter["filter_frontal_face.py"]:::processing
        Split["split.py"]:::processing
    end

    %% Cleaned Data
    subgraph "Cleaned Data"
        TrainA["cartoon2realistic/trainA"]:::data
        TrainB["cartoon2realistic/trainB"]:::data
        TestA["cartoon2realistic/testA"]:::data
        TestB["cartoon2realistic/testB"]:::data
    end

    %% Model Definition Layer
    subgraph "Model Definition Layer"
        Generator["generator.py"]:::model
        Discriminator["discriminator.py"]:::model
    end

    %% Training Layer
    subgraph "Training Layer"
        Train["train.py"]:::training
        TrainDiverse["train_with_diversity_loss.py"]:::training
    end

    %% Artifacts
    Checkpoints["Model Checkpoints (genz.pth, genh.pth, criticz.pth, critich.pth)"]:::artifact

    %% Inference Layer
    subgraph "Inference Layer"
        Inference["test_realistic_to_cartoon.py"]:::inference
    end

    %% Output Artifacts
    Output["Translated Images"]:::output

    %% Connections
    RawCartoon -->|"raw images"| Preprocessing
    RawCelebA -->|"raw images"| Preprocessing

    Preprocessing -->|"start detection"| FaceDetect
    FaceDetect -->|"faces detected"| Filter
    Filter -->|"frontal faces"| Split
    Split -->|"train/test splits"| TrainA
    Split -->|"train/test splits"| TrainB
    Split -->|"train/test splits"| TestA
    Split -->|"train/test splits"| TestB

    TrainA -->|"training data"| Train
    TrainB -->|"training data"| Train
    Generator -->|"network modules"| Train
    Discriminator -->|"network modules"| Train

    TrainA -->|"training data"| TrainDiverse
    TrainB -->|"training data"| TrainDiverse
    Generator -->|"network modules"| TrainDiverse
    Discriminator -->|"network modules"| TrainDiverse

    Train -->|"model weights"| Checkpoints
    TrainDiverse -->|"model weights"| Checkpoints

    Checkpoints -->|"pretrained weights"| Inference
    TestA -->|"test images A"| Inference
    TestB -->|"test images B"| Inference

    Inference -->|"translated images"| Output

    %% Click Events
    click Preprocessing "https://github.com/apaarraina/cartoon-to-realistic-using-cyclegan/tree/main/preprocessing_scripts/"
    click FaceDetect "https://github.com/apaarraina/cartoon-to-realistic-using-cyclegan/blob/main/preprocessing_scripts/detec_faces.py"
    click Filter "https://github.com/apaarraina/cartoon-to-realistic-using-cyclegan/blob/main/preprocessing_scripts/filter_frontal_face.py"
    click Split "https://github.com/apaarraina/cartoon-to-realistic-using-cyclegan/blob/main/preprocessing_scripts/split.py"
    click Generator "https://github.com/apaarraina/cartoon-to-realistic-using-cyclegan/blob/main/generator.py"
    click Discriminator "https://github.com/apaarraina/cartoon-to-realistic-using-cyclegan/blob/main/discriminator.py"
    click Train "https://github.com/apaarraina/cartoon-to-realistic-using-cyclegan/blob/main/train.py"
    click TrainDiverse "https://github.com/apaarraina/cartoon-to-realistic-using-cyclegan/blob/main/train_with_diversity_loss.py"
    click Inference "https://github.com/apaarraina/cartoon-to-realistic-using-cyclegan/blob/main/test_realistic_to_cartoon.py"

    %% Styles
    classDef data fill:#BBEFFF,stroke:#333,stroke-width:1px;
    classDef processing fill:#C8E6C9,stroke:#333,stroke-width:1px;
    classDef model fill:#D1C4E9,stroke:#333,stroke-width:1px;
    classDef training fill:#FFCC80,stroke:#333,stroke-width:1px;
    classDef artifact fill:#FFAB91,stroke:#333,stroke-width:1px;
    classDef inference fill:#B0BEC5,stroke:#333,stroke-width:1px;
    classDef output fill:#EEEEEE,stroke:#333,stroke-width:1px;
```
