# peizhuoli/ganimator architecture

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

- Interactive diagram: https://gitdiagram.com/peizhuoli/ganimator
- Repository: https://github.com/peizhuoli/ganimator

## Overview

##### Project type and purpose
- This is a PyTorch-based research library and demo application for neural motion synthesis (GANimator). It reads BVH motion files, trains a 1D GAN generator (and discriminator), and provides downstream tasks such as style transfer, motion mixing, keyframe editing, conditional generation, evaluation, and interactive demos.

##### File structure
- Top-level:
- bvh/             → BVH I/O and skeleton utilities (Quaternions, parser, writer, skeleton database)
- data/            → raw BVH sequences organized by character (Crab, Joe, Elephant, etc.)
- dataset/         → dataset/motion.py builds PyTorch Dataset from BVH files
- models/          → model definitions and helpers:
– architecture.py    (generator, discriminator)
– gan1d.py           (1D GAN modules)
– kinematics.py      (forward/inverse FK)
– contact.py         (foot contact modules)
– skeleton.py        (skeleton graph)
– transforms.py      (spatial/temporal data transforms)
– utils.py           (masking, conditioning)
- train.py         → training entry point (config via option.py)
- evaluate.py      → quantitative evaluation module
- demo.py / demo.sh→ demo runner for generation, style transfer, mixing, key-frame editing, conditional gen
- fix_contact.py   → post-processing to correct foot sliding
- interactive_utils.py → streaming input for interactive mode
- loss_recorder.py → logging losses to TensorBoard
- option.py        → CLI options parser
- utils.py         → shared utilities (file paths, logging)

##### README for additional insights
- Stack: Python ≥3.8, PyTorch ≥1.10, TensorBoard, SciPy
- Workflow described: environment setup, quick start with pretrained models, training instructions, conditional training, applications (mixing, style transfer, keyframe editing), evaluation prerequisites

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawData[(Raw BVH Data)]:::data
        Quaternions["Quaternions"]:::data
        bvh_io["bvh_io"]:::data
        bvh_parser["bvh_parser"]:::data
        bvh_writer["bvh_writer"]:::data
        skeleton_database["skeleton_database"]:::data
    end

    %% Dataset Layer
    subgraph "Dataset Layer"
        direction TB
        motion["motion.py"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        architecture["architecture.py"]:::model
        gan1d["gan1d.py"]:::model
        kinematics["kinematics.py"]:::model
        skeleton["skeleton.py"]:::model
        contact["contact.py"]:::model
        transforms["transforms.py"]:::model
        utils_mod["utils.py"]:::model
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        train["train.py"]:::script
        option["option.py"]:::script
        loss_recorder["loss_recorder.py"]:::script
        fix_contact["fix_contact.py"]:::script
    end

    %% Evaluation Pipeline
    subgraph "Evaluation Pipeline"
        direction TB
        evaluate["evaluate.py"]:::script
        patched_nn["patched_nn.py"]:::script
        perwindow_nn["perwindow_nn.py"]:::script
    end

    %% Demo/Application Layer
    subgraph "Demo/Application Layer"
        direction TB
        demo_py["demo.py"]:::script
        demo_sh["demo.sh"]:::script
        interactive_utils["interactive_utils.py"]:::script
    end

    %% Shared Utilities
    shared_utils["utils.py"]:::script

    %% Environment & External Tools
    subgraph "External Services & Tools"
        direction TB
        environment["environment.yaml"]:::ext
        conda[(Conda Env)]:::ext
        pytorch[(PyTorch & CUDA)]:::ext
        tensorboard[(TensorBoard)]:::ext
        blender[(Blender)]:::ext
    end

    %% Connections
    RawData -->|"reads"| bvh_parser
    bvh_parser -->|"parses"| motion
    motion -->|"provides DataLoader"| architecture
    architecture -->|"uses"| gan1d
    architecture -->|"imports"| kinematics
    architecture -->|"imports"| skeleton
    architecture -->|"imports"| contact
    architecture -->|"imports"| transforms
    architecture -->|"imports"| utils_mod

    gan1d -->|"training loop"| train
    train -->|"config via"| option
    train -->|"logs"| loss_recorder
    train -->|"calls fix"| fix_contact

    architecture -->|"saved weights"| demo_py
    demo_py -->|"runs"| demo_sh
    demo_py -->|"streams"| interactive_utils
    demo_py -->|"writes BVH"| bvh_writer
    bvh_writer --> blender

    evaluate -->|"loads weights + data"| patched_nn
    evaluate -->|"calculates metrics"| perwindow_nn
    evaluate --> tensorboard

    shared_utils --> train
    shared_utils --> evaluate
    shared_utils --> demo_py

    %% External deps
    train --> conda
    train --> pytorch
    evaluate --> pytorch
    demo_py --> pytorch
    loss_recorder --> tensorboard

    %% Click Events
    click Quaternions "https://github.com/peizhuoli/ganimator/blob/main/bvh/Quaternions.py"
    click bvh_io "https://github.com/peizhuoli/ganimator/blob/main/bvh/bvh_io.py"
    click bvh_parser "https://github.com/peizhuoli/ganimator/blob/main/bvh/bvh_parser.py"
    click bvh_writer "https://github.com/peizhuoli/ganimator/blob/main/bvh/bvh_writer.py"
    click skeleton_database "https://github.com/peizhuoli/ganimator/blob/main/bvh/skeleton_database.py"
    click RawData "https://github.com/peizhuoli/ganimator/tree/main/data/"
    click motion "https://github.com/peizhuoli/ganimator/blob/main/dataset/motion.py"
    click architecture "https://github.com/peizhuoli/ganimator/blob/main/models/architecture.py"
    click gan1d "https://github.com/peizhuoli/ganimator/blob/main/models/gan1d.py"
    click kinematics "https://github.com/peizhuoli/ganimator/blob/main/models/kinematics.py"
    click skeleton "https://github.com/peizhuoli/ganimator/blob/main/models/skeleton.py"
    click contact "https://github.com/peizhuoli/ganimator/blob/main/models/contact.py"
    click transforms "https://github.com/peizhuoli/ganimator/blob/main/models/transforms.py"
    click utils_mod "https://github.com/peizhuoli/ganimator/blob/main/models/utils.py"
    click train "https://github.com/peizhuoli/ganimator/blob/main/train.py"
    click option "https://github.com/peizhuoli/ganimator/blob/main/option.py"
    click loss_recorder "https://github.com/peizhuoli/ganimator/blob/main/loss_recorder.py"
    click fix_contact "https://github.com/peizhuoli/ganimator/blob/main/fix_contact.py"
    click evaluate "https://github.com/peizhuoli/ganimator/blob/main/evaluate.py"
    click patched_nn "https://github.com/peizhuoli/ganimator/blob/main/evaluations/patched_nn.py"
    click perwindow_nn "https://github.com/peizhuoli/ganimator/blob/main/evaluations/perwindow_nn.py"
    click demo_py "https://github.com/peizhuoli/ganimator/blob/main/demo.py"
    click demo_sh "https://github.com/peizhuoli/ganimator/blob/main/demo.sh"
    click interactive_utils "https://github.com/peizhuoli/ganimator/blob/main/interactive_utils.py"
    click shared_utils "https://github.com/peizhuoli/ganimator/blob/main/utils.py"
    click environment "https://github.com/peizhuoli/ganimator/blob/main/environment.yaml"

    %% Styles
    classDef data fill:#D6E9F8,stroke:#31708F
    classDef model fill:#dff0d8,stroke:#3c763d
    classDef script fill:#fcf8e3,stroke:#8a6d3b
    classDef ext fill:#f2f2f2,stroke:#666
```
