# wjchaogit/group-activity-recognition architecture

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

- Interactive diagram: https://gitdiagram.com/wjchaogit/group-activity-recognition
- Repository: https://github.com/wjchaogit/group-activity-recognition

## Overview

##### Project Type & Purpose
- This is a research-oriented, full-stack machine-learning pipeline for video-based group activity recognition.
- Two datasets (Volleyball, Collective) are supported.
- There is a two-stage training process: Stage 1 (fine-tune backbone CNN), Stage 2 (fix backbone, train Graph Convolutional Network).

##### File Structure
- Top-level ML modules:
- backbone.py: CNN backbone feature extractor
- gcn_model.py: Graph Convolutional Network for actor relations
- base_model.py: Abstract parent for both dataset-specific models
- collective.py, volleyball.py: Dataset-specific model wrappers/combiners
- dataset.py: DataLoader for both datasets
- config.py: Hyperparameters and CLI argument definitions
- utils.py: IO, logging, metric computations
- train_net.py: Common trainer orchestrator
- Data folders:
- data/volleyball: raw images, preprocessed tracks
- data/collective: MATLAB scripts + .dat tracks
- scripts/: Stage1 and Stage2 entry points for both datasets.
- result/: Checkpoint/results storage.
- Requirements: PyTorch (0.4.1), numpy, scikit-image, RoIAlign.

##### Extract README Insights
- Two-stage training: Stage1 calls scripts/train_*_stage1.py → trains CNN only.
- Stage2 calls scripts/train_*_stage2.py → freezes CNN, trains GCN.
- config.py holds all tunable parameters.

##### Main System Components & Their Interactions
A. Data Ingestion
- Raw data (videos/frames & track annotations)
→ yields per-frame actor crops + positional info.
B. Feature Extraction
- backbone.py (ResNet or similar)
→ processes actor crops via RoIAlign
→ outputs feature vectors.
C. Relation Graph Module
- gcn_model.py
→ takes feature vectors + positional adjacency
→ builds actor relation graph
→ applies GCN layers to produce context-aware actor embeddings.
D. Classification Head
- base_model.py / dataset-specific models
→ aggregate actor embeddings
→ predict group activity labels.
E. Training Orchestrator
- train_net.py & scripts/train_*
→ parse config.py
→ pipeline: DataLoader → FeatureExtractor → (GCN) → Loss → Optimizer
→ checkpoint to result/.
F. Utilities & Configuration
- config.py: All hyperparams, paths, training flags
- utils.py: Logging, checkpoint save/load, metric reporting.

##### Architectural Patterns & Principles
- Modularity: separate data, feature extractor, GCN, head, trainer.
- Two-stage training: pipeline can toggle GCN on/off.
- Extensibility: add new datasets by writing a new dataset loader & model wrapper.
- Configuration-driven: use config.py to control architecture, learning rate, dataset paths.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Storage
    subgraph "Data Storage"
        DS_volleyball["Volleyball Dataset"]:::data
        DS_collective["Collective Dataset"]:::data
    end

    %% Data Loader
    DataLoader["DataLoader Module<br/>(dataset.py)"]:::model

    %% Feature Extraction
    FeatureExtractor["Feature Extractor<br/>(backbone.py + RoIAlign)"]:::model
    RoIAlign["RoIAlign"]:::external

    %% Relation Graph
    GCN["Relation Graph Module<br/>(gcn_model.py)"]:::model

    %% Classification Head
    subgraph "Classification Head"
        BaseModel["Abstract Base Model<br/>(base_model.py)"]:::model
        VBallModel["Volleyball Wrapper<br/>(volleyball.py)"]:::model
        CollModel["Collective Wrapper<br/>(collective.py)"]:::model
    end

    %% Training Controller & Scripts
    subgraph "Training Controller"
        Trainer["Core Trainer<br/>(train_net.py)"]:::script
        subgraph "Stage-1 Scripts"
            TS1_V["train_volleyball_stage1.py"]:::script
            TS1_C["train_collective_stage1.py"]:::script
        end
        subgraph "Stage-2 Scripts"
            TS2_V["train_volleyball_stage2.py"]:::script
            TS2_C["train_collective_stage2.py"]:::script
        end
    end

    %% Config and Utils
    Config["Configuration Controller<br/>(config.py)"]:::util
    Utils["Utilities & Metrics<br/>(utils.py)"]:::util

    %% Pipeline Flow
    DS_volleyball -->|provides frames & tracks| DataLoader
    DS_collective -->|provides frames & tracks| DataLoader

    DataLoader -->|actor crops & positions| FeatureExtractor
    FeatureExtractor -->|features| RoIAlign
    RoIAlign -->|aligned features| FeatureExtractor

    FeatureExtractor -->|feature vectors| GCN
    GCN -->|actor embeddings| BaseModel
    BaseModel --> VBallModel
    BaseModel --> CollModel

    %% Stage-1 bypass GCN
    FeatureExtractor -->|"Stage1"| BaseModel
    BaseModel --> VBallModel
    BaseModel --> CollModel

    %% Training orchestration
    TS1_V --> Trainer
    TS1_C --> Trainer
    TS2_V --> Trainer
    TS2_C --> Trainer

    Trainer -->|reads| Config
    Trainer -->|uses| Utils
    Trainer -->|executes pipeline| DataLoader
    Trainer -->|executes pipeline| FeatureExtractor
    Trainer -->|executes pipeline| GCN
    Trainer -->|executes pipeline| BaseModel

    %% Click Events
    click DS_volleyball "https://github.com/wjchaogit/group-activity-recognition/tree/master/data/volleyball"
    click DS_collective "https://github.com/wjchaogit/group-activity-recognition/tree/master/data/collective"
    click DataLoader "https://github.com/wjchaogit/group-activity-recognition/blob/master/dataset.py"
    click FeatureExtractor "https://github.com/wjchaogit/group-activity-recognition/blob/master/backbone.py"
    click GCN "https://github.com/wjchaogit/group-activity-recognition/blob/master/gcn_model.py"
    click VBallModel "https://github.com/wjchaogit/group-activity-recognition/blob/master/volleyball.py"
    click CollModel "https://github.com/wjchaogit/group-activity-recognition/blob/master/collective.py"
    click Trainer "https://github.com/wjchaogit/group-activity-recognition/blob/master/train_net.py"
    click TS1_V "https://github.com/wjchaogit/group-activity-recognition/blob/master/scripts/train_volleyball_stage1.py"
    click TS1_C "https://github.com/wjchaogit/group-activity-recognition/blob/master/scripts/train_collective_stage1.py"
    click TS2_V "https://github.com/wjchaogit/group-activity-recognition/blob/master/scripts/train_volleyball_stage2.py"
    click TS2_C "https://github.com/wjchaogit/group-activity-recognition/blob/master/scripts/train_collective_stage2.py"
    click Config "https://github.com/wjchaogit/group-activity-recognition/blob/master/config.py"
    click Utils "https://github.com/wjchaogit/group-activity-recognition/blob/master/utils.py"

    %% Styling
    classDef data fill:#ADD8E6,stroke:#000,color:#000;
    classDef model fill:#90EE90,stroke:#000,color:#000;
    classDef script fill:#FFA500,stroke:#000,color:#000;
    classDef util fill:#D3D3D3,stroke:#000,color:#000;
    classDef external fill:#E6E6FA,stroke:#000,color:#000;
```
