# kennymckormick/pyskl architecture

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

- Interactive diagram: https://gitdiagram.com/kennymckormick/pyskl
- Repository: https://github.com/kennymckormick/pyskl

## Overview

##### Main Components
- Input/Preprocessing: Represent the “data” side of the system. This includes the datasets, data pipelines, and augmentation modules found in pyskl/datasets, pyskl/datasets/pipelines, and even external scripts (e.g., tools/data, examples for extraction).
- Model Building: Illustrate the various neural network modules in pyskl/models. This should clearly separate the different types – the “cnns” (3D CNN components), “gcns” (graph convolution networks like AAGCN, CTRGCN, DGSTGCN, etc.), and the “heads” which combine feature extraction with final classification.
- Training and Inference API: Encapsulate the APIs in pyskl/apis (train.py, inference.py), which orchestrate the overall training, testing, and inference workflows.
- Configuration Management: The configs directory holds configuration files for different algorithms and dataset settings. This is a central module for controlling experiments.
- Utilities and Helpers: Represent the helper modules under pyskl/utils (visualization, environment collection, graph utilities) and any extra scripts (e.g., setup files, pre-commit hooks, etc.).
- Tools & Demo: Include components from the tools and demo directories that wrap command-line scripts to launch distributed training, testing, and to preprocess the data.
- External Dependencies: Mention external libraries such as PyTorch and any additional dependencies (also visible in the YAML files) which are needed for compilation, GPU training, and possibly torch.compile for PyTorch 2.0 support.

##### Relationships and Data Flow
- Data and Preprocessing Flow: Display how raw skeleton data and annotations (from datasets, label maps in tools/data) flow through the pipelines in pyskl/datasets/pipelines. Clearly show that preprocessing, augmentation, and sampling modules are applied before data is forwarded to the model.
- Model Pipeline: Show the modular structure where a configuration file (YAML) is loaded, a corresponding model (from pyskl/models/) is built, and then it is fed data from the loader. Also, include how the models are wrapped with recognition or classification heads.

##### Architectural Patterns and Design Principles
- Modularity: Emphasize that code modules are well-separated (e.g., pipelines, datasets, models, losses) which makes it easy to swap in and out different algorithms.
- Extensibility: Indicate that the design supports multiple algorithms (ST-GCN, AAGCN, etc.) by loading algorithm-specific configuration files and modules.
- Distributed Training Support: Show that the training scripts (tools/dist_train.sh, tools/dist_test.sh) indicate that the system is designed for distributed GPU training.
- Separation of Concerns: Training and inference logic is distinct from model definition and utility functions.

##### Specific Elements
- External interactions, such as links to dataset preparation scripts (tools/data and demo components) and external pre-trained weights (demo, hrnet configurations).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Subgraph: Configuration Management
    subgraph "Configuration Management"
        config["Configuration Manager"]:::config
    end

    %% Subgraph: Input/Preprocessing
    subgraph "Input / Preprocessing"
        datasets["PYSKL Data Loader (Datasets)"]:::data
        pipelines["Data Augmentation Pipeline"]:::data
        dataprep["Data Preparation Scripts"]:::data
    end

    %% Subgraph: Model Building
    subgraph "Model Building"
        cnn["3D CNN Modules"]:::model
        gcn["Graph Convolution Networks (GCNs)"]:::model
        gcn_utils["GCN Utils"]:::model
        heads["Recognition & Classification Heads"]:::model
        losses["Loss Functions"]:::model
        recognizer["Recognizer Modules"]:::model
    end

    %% Subgraph: Training and Inference
    subgraph "Training & Inference"
        trainapi["Training API"]:::train
        inferapi["Inference API"]:::train
    end

    %% Subgraph: Utilities & Tools
    subgraph "Utilities & Tools"
        utils["Helper Modules"]:::util
        tools["Command-line Tools & Scripts"]:::util
        demo["Notebooks & Demo Scripts"]:::util
    end

    %% External Dependencies Node
    external["PyTorch & Dependencies"]:::ext

    %% Connections: Configuration Management configures components
    config -->|"configures"| datasets
    config -->|"configures"| pipelines
    config -->|"configures"| cnn
    config -->|"configures"| gcn
    config -->|"configures"| heads
    config -->|"configures"| losses

    %% Data Flow
    datasets -->|"raw_data"| pipelines
    pipelines -->|"processed_data"| trainapi
    pipelines -->|"processed_data"| inferapi
    dataprep -->|"prepares"| pipelines

    %% Model Building in Training
    trainapi -->|"trains"| cnn
    trainapi -->|"trains"| gcn
    trainapi -->|"trains"| heads
    trainapi -->|"computes"| losses

    %% Inference Flow
    inferapi -->|"executes"| recognizer

    %% Tools and Demo integration
    tools -->|"orchestrates"| trainapi
    demo -->|"demonstrates"| inferapi

    %% External dependency usage
    trainapi -.->|"uses"| external
    inferapi -.->|"uses"| external

    %% Utilities logging integration
    cnn -->|"logs_to"| utils
    gcn -->|"logs_to"| utils
    losses -->|"logs_to"| utils

    %% Click Events for Component Mapping
    click datasets "https://github.com/kennymckormick/pyskl/tree/main/pyskl/datasets"
    click pipelines "https://github.com/kennymckormick/pyskl/tree/main/pyskl/datasets/pipelines"
    click dataprep "https://github.com/kennymckormick/pyskl/tree/main/tools/data"
    click cnn "https://github.com/kennymckormick/pyskl/tree/main/pyskl/models/cnns"
    click gcn "https://github.com/kennymckormick/pyskl/tree/main/pyskl/models/gcns"
    click gcn_utils "https://github.com/kennymckormick/pyskl/tree/main/pyskl/models/gcns/utils"
    click heads "https://github.com/kennymckormick/pyskl/tree/main/pyskl/models/heads"
    click losses "https://github.com/kennymckormick/pyskl/tree/main/pyskl/models/losses"
    click recognizer "https://github.com/kennymckormick/pyskl/tree/main/pyskl/models/recognizers"
    click trainapi "https://github.com/kennymckormick/pyskl/blob/main/pyskl/apis/train.py"
    click inferapi "https://github.com/kennymckormick/pyskl/blob/main/pyskl/apis/inference.py"
    click config "https://github.com/kennymckormick/pyskl/tree/main/configs"
    click utils "https://github.com/kennymckormick/pyskl/tree/main/pyskl/utils"
    click tools "https://github.com/kennymckormick/pyskl/tree/main/tools"
    click demo "https://github.com/kennymckormick/pyskl/tree/main/demo"

    %% Styles
    classDef config fill:#FCE38A,stroke:#F9BF3B,stroke-width:2px;
    classDef data fill:#E0F7FA,stroke:#0097A7,stroke-width:2px;
    classDef model fill:#E1BEE7,stroke:#9C27B0,stroke-width:2px;
    classDef train fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef util fill:#FFCDD2,stroke:#E53935,stroke-width:2px;
    classDef ext fill:#D1C4E9,stroke:#7B1FA2,stroke-width:2px;
```
