# mirkozaff/aa-sgan architecture

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

- Interactive diagram: https://gitdiagram.com/mirkozaff/aa-sgan
- Repository: https://github.com/mirkozaff/aa-sgan

## Overview

##### Project type and purpose
- This is a research‐oriented deep learning project implementing AA-SGAN, an adversarial augmentation framework for pedestrian trajectory prediction.
- It builds on the Social GAN architecture and integrates synthetic data augmentation at training time.

##### File structure
- Top level:
- src/ (all code, scripts, datasets, checkpoints)
- Under src/:
- datasets/ – raw, preprocessed, train/val/test split for ETH, HOTEL, UNIV, ZARA1/2, plus JTA synthetic data
- checkpoint/ – model snapshots for four training modes (baseline, hybrid, jta, traj-gen) across five scenes
- sgan/ – core library: data loader, trajectory utilities, model definitions (G, D, A modules), loss functions, training steps, utils
- scripts:
– extract_trajectory.py – preprocess raw trajectory files into dataset splits
– evaluate_model.py – load checkpoints & compute metrics on held-out sets
– train_SGAN.py / train_SGAN_GEN.py – orchestrate the adversarial training loops
– aasgan_extract.sh / aasgan_train.sh – wrapper bash scripts to launch extraction and training
- requirements.txt – Python dependencies (e.g., PyTorch, NumPy)

##### README for additional insights
- The system has three logical model components—Augmenter (A), Generator (G), Discriminator (D)—arranged as an adversarial pipeline.
- Synthetic trajectories from the JTA dataset are fed into A to produce “synth-augmented” samples, which are then used alongside real trajectories for G/D training.

##### Final advice
- Break the system into the smallest functional units: data ingestion, augmentation, generation, discrimination, checkpointing, evaluation.
- Orchestration (bash scripts) at the periphery initiating the Extract → Train → Evaluate pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    DataSources(("Raw Real & Synth Datasets")):::storage
    click DataSources "https://github.com/mirkozaff/aa-sgan/tree/main/src/datasets/"

    %% Preprocessing
    EXTRACT["extract_trajectory.py"]:::orchestration
    click EXTRACT "https://github.com/mirkozaff/aa-sgan/blob/main/src/extract_trajectory.py"
    PREPROCESSED(("Processed Datasets")):::storage

    %% Data Utilities
    Loader["DataLoader"]:::data
    click Loader "https://github.com/mirkozaff/aa-sgan/blob/main/src/sgan/data/loader.py"
    TrajUtils["Trajectory Utils"]:::data
    click TrajUtils "https://github.com/mirkozaff/aa-sgan/blob/main/src/sgan/data/trajectories.py"

    %% Model Components
    subgraph "Model Modules"
        direction TB
        Augmenter["Augmenter (A)"]:::model
        Generator["Generator (G)"]:::model
        Discriminator["Discriminator (D)"]:::model
    end
    click Augmenter "https://github.com/mirkozaff/aa-sgan/blob/main/src/sgan/models.py"
    click Generator "https://github.com/mirkozaff/aa-sgan/blob/main/src/sgan/models.py"
    click Discriminator "https://github.com/mirkozaff/aa-sgan/blob/main/src/sgan/models.py"

    Losses["Loss Functions"]:::model
    click Losses "https://github.com/mirkozaff/aa-sgan/blob/main/src/sgan/losses.py"
    Steps["Training Steps & Loop"]:::model
    click Steps "https://github.com/mirkozaff/aa-sgan/blob/main/src/sgan/steps.py"
    Utils["Utility Functions"]:::data
    click Utils "https://github.com/mirkozaff/aa-sgan/blob/main/src/sgan/utils.py"

    %% Orchestration
    BashExtract["aasgan_extract.sh"]:::orchestration
    click BashExtract "https://github.com/mirkozaff/aa-sgan/blob/main/src/aasgan_extract.sh"
    TrainSGAN["train_SGAN.py"]:::orchestration
    click TrainSGAN "https://github.com/mirkozaff/aa-sgan/blob/main/src/train_SGAN.py"
    TrainGEN["train_SGAN_GEN.py"]:::orchestration
    click TrainGEN "https://github.com/mirkozaff/aa-sgan/blob/main/src/train_SGAN_GEN.py"
    BashTrain["aasgan_train.sh"]:::orchestration
    click BashTrain "https://github.com/mirkozaff/aa-sgan/blob/main/src/aasgan_train.sh"

    %% Storage & Evaluation
    Checkpoints(("Checkpoints")):::storage
    click Checkpoints "https://github.com/mirkozaff/aa-sgan/tree/main/src/checkpoint/"
    Eval["evaluate_model.py"]:::orchestration
    click Eval "https://github.com/mirkozaff/aa-sgan/blob/main/src/evaluate_model.py"
    Requirements["requirements.txt"]:::data
    click Requirements "https://github.com/mirkozaff/aa-sgan/blob/main/src/requirements.txt"
    README["README.md / TRAINING.md"]:::data
    click README "https://github.com/mirkozaff/aa-sgan/blob/main/README.md"

    %% Data Flow
    DataSources -->|raw files| EXTRACT
    EXTRACT -->|standardized data| PREPROCESSED
    PREPROCESSED -->|datasets| Loader
    Loader -->|observed traj| Generator
    Loader -->|real & synth traj| Augmenter
    Augmenter -->|augmented traj| Discriminator
    Generator -->|predictions| Discriminator
    Discriminator -->|"classification feedback"| Steps
    Augmenter -->|"aug loss grad"| Steps
    Generator -->|"gen loss grad"| Steps
    Losses --> Steps
    Utils --> Steps

    %% Training Orchestration
    BashExtract --> EXTRACT
    TrainSGAN --> Steps
    TrainGEN --> Steps
    BashTrain --> TrainSGAN
    BashTrain --> TrainGEN
    Steps -->|save models| Checkpoints

    %% Evaluation Flow
    PREPROCESSED -->|test split| Eval
    Eval -->|load checkpoint| Checkpoints
    Eval -->|metrics output| README

    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef model fill:#90ee90,stroke:#333,stroke-width:1px
    classDef orchestration fill:#ffa500,stroke:#333,stroke-width:1px
    classDef storage fill:#d3d3d3,stroke:#333,stroke-width:1px
```
