# mk4me/posepipeline architecture

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

- Interactive diagram: https://gitdiagram.com/mk4me/posepipeline
- Repository: https://github.com/mk4me/posepipeline

## Overview

##### Project Type & Purpose
- PosePipe is an open-source, modular human pose estimation (HPE) data-processing pipeline designed for clinical research movement analysis.
- It leverages DataJoint for relational data management and OpenMMLab (mmpose, mmtracking, etc.) for state-of-the-art detection, tracking, and keypoint estimation.
- It is not a classic frontend/backend web app; rather, it is a data-pipeline tool that ingests video, runs algorithms, stores outputs, and produces visualizations and analysis artifacts.

##### File Structure Analysis
Top-level directories & roles:
- 3rdparty/ — vendored configs and code from mmpose and mmtracking
- datajoint_docker/ & docker/ & .devcontainer/ — Docker, DataJoint/MariaDB service definitions, dev environments
- pose_pipeline/ — core Python package
– demo/ — example scripts for local runs (e.g., h36_dj.py)
– env.py, paths.py — environment configuration & path management
– pipeline.py — orchestrator for ingest → process → export
- utils/ — helper modules (annotation, inference, tracking, visualization, etc.)
- wrappers/ — adapter layers for each external HPE or tracking library
- weights/ — prebuilt model definitions & binaries
- scripts/ — installation helpers, data processing scripts
- tests/ — basic unit tests for package and model integration
Support files: pyproject.toml, Makefile, README.md, INSTALL.md, CHANGELOG.md, LICENSE

##### README Insights
- High-level ERD is provided in doc/erd.png showing DataJoint tables and relationships.
- Key features emphasize modular wrappers, structured data via DataJoint, and visual outputs.
- Technology stack: Python, DataJoint + MySQL, OpenMMLab suites (mmcv, mmpose, mmtracking), Docker.

a. Main Components
1. Video Ingestion
2. DataJoint Database (MySQL)
3. Orchestration Layer (pose_pipeline.pipeline)
4. Algorithm Wrappers (pose_pipeline.wrappers + 3rdparty)
5. Utilities (annotation, tracking, inference, visualization)
6. Model Weights & Configs (pose_pipeline/weights & 3rdparty/config)
7. Notebooks & Demo Scripts (user interface)
8. Containerization & Deployment (Dockerfiles, docker-compose)
b. Interactions & Data Flow
- Ingested videos → File system & DataJoint “RawVideo” table
- pipeline.py reads metadata from DataJoint → selects algorithms via wrappers → loads configs & weights → runs inference/tracking → writes results to DataJoint tables (Keypoints, Tracks)
- Utilities transform results → generate visualizations → export plots/reports
- Demo notebooks query DataJoint for results → display in Jupyter
- Docker compose spins up MySQL + Python container → persists data
c. Architectural Patterns
- Modular adapter (wrapper) pattern for each external algorithm
- Pipeline orchestration pattern: single entry point coordinating sequential, independent stages
- Data-centric design: DataJoint ensures reproducibility, provenance, and relational integrity
d. Key Technologies
- DataJoint + MySQL (DB layer)
- Python packages: pose_pipeline, OpenMMLab libs (mmpose, mmtracking)
- Docker & DevContainer for consistency
- Jupyter Notebooks for exploration & demos

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment & Deployment
    subgraph "Environment & Deployment"
        dc_datajoint["datajoint_docker/docker-compose.yaml"]:::config
        dockerfile["docker/Dockerfile"]:::config
        devcontainer_json[".devcontainer/devcontainer.json"]:::config
        dc_devcontainer[".devcontainer/docker-compose.yaml"]:::config
    end

    %% Core Package
    subgraph "Core Package"
        ingestion["Video Ingestion"]:::compute
        env_cfg["Env Config"]:::config
        paths_cfg["Path Config"]:::config
        pipeline["PosePipe Orchestrator"]:::compute
        wrappers["Algorithm Wrappers"]:::wrapper
        utils_annot["Annotation Utility"]:::compute
        utils_infer["Inference Utility"]:::compute
        utils_track["Tracking Utility"]:::compute
        utils_vis["Visualization Utility"]:::compute
        weights["Model Weights & Binaries"]:::storage
    end

    %% 3rd-Party Libraries
    subgraph "3rd-Party Libraries"
        mmpose["mmpose"]:::external
        mmtracking["mmtracking"]:::external
    end

    %% Database
    DB["DataJoint MySQL"]:::database

    %% User Interface
    subgraph "User Interface"
        demo["Demo Scripts"]:::docs
        notebooks_ui["Notebooks"]:::docs
    end

    %% Support Files
    subgraph "Support Files"
        pyproject["pyproject.toml"]:::config
        makefile["Makefile"]:::config
        readme["README.md"]:::config
        install["INSTALL.md"]:::config
        changelog["CHANGELOG.md"]:::config
        license["LICENSE"]:::config
    end

    %% Data Flows & Dependencies
    ingestion -->|"ingests video"| DB
    ingestion -->|"saves file"| weights
    ingestion --> pipeline
    env_cfg --> pipeline
    paths_cfg --> pipeline
    pipeline --> wrappers
    pipeline --> utils_infer
    pipeline --> utils_track
    utils_infer --> weights
    wrappers --> mmpose
    wrappers --> mmtracking
    pipeline --> DB
    utils_track --> DB
    utils_vis --> DB
    utils_vis --> weights
    pipeline --> utils_vis
    DB --> notebooks_ui
    DB --> demo

    %% Deployment Flows
    dc_datajoint --> DB
    dc_datajoint --> pipeline
    dockerfile --> pipeline
    devcontainer_json --> pipeline
    dc_devcontainer --> pipeline

    %% Click Events
    click ingestion "https://github.com/mk4me/posepipeline/blob/main/pose_pipeline/utils/video_format.py"
    click env_cfg "https://github.com/mk4me/posepipeline/blob/main/pose_pipeline/env.py"
    click paths_cfg "https://github.com/mk4me/posepipeline/blob/main/pose_pipeline/paths.py"
    click dc_datajoint "https://github.com/mk4me/posepipeline/blob/main/datajoint_docker/docker-compose.yaml"
    click pipeline "https://github.com/mk4me/posepipeline/blob/main/pose_pipeline/pipeline.py"
    click wrappers "https://github.com/mk4me/posepipeline/tree/main/pose_pipeline/wrappers/"
    click mmpose "https://github.com/mk4me/posepipeline/tree/main/3rdparty/mmpose/"
    click mmtracking "https://github.com/mk4me/posepipeline/tree/main/3rdparty/mmtracking/"
    click utils_annot "https://github.com/mk4me/posepipeline/blob/main/pose_pipeline/utils/annotation.py"
    click utils_infer "https://github.com/mk4me/posepipeline/blob/main/pose_pipeline/utils/inference.py"
    click utils_track "https://github.com/mk4me/posepipeline/blob/main/pose_pipeline/utils/tracking.py"
    click utils_vis "https://github.com/mk4me/posepipeline/blob/main/pose_pipeline/utils/visualization.py"
    click weights "https://github.com/mk4me/posepipeline/tree/main/pose_pipeline/weights/"
    click demo "https://github.com/mk4me/posepipeline/blob/main/pose_pipeline/demo/h36_dj.py"
    click notebooks_ui "https://github.com/mk4me/posepipeline/tree/main/notebooks/"
    click dockerfile "https://github.com/mk4me/posepipeline/tree/main/docker/Dockerfile"
    click devcontainer_json "https://github.com/mk4me/posepipeline/blob/main/.devcontainer/devcontainer.json"
    click dc_devcontainer "https://github.com/mk4me/posepipeline/blob/main/.devcontainer/docker-compose.yaml"
    click pyproject "https://github.com/mk4me/posepipeline/blob/main/pyproject.toml"
    click makefile "https://github.com/mk4me/posepipeline/tree/main/Makefile"
    click readme "https://github.com/mk4me/posepipeline/blob/main/README.md"
    click install "https://github.com/mk4me/posepipeline/blob/main/INSTALL.md"
    click changelog "https://github.com/mk4me/posepipeline/blob/main/CHANGELOG.md"
    click license "https://github.com/mk4me/posepipeline/tree/main/LICENSE"

    %% Styles
    classDef database fill:#bbdefb,stroke:#333,stroke-width:1px;
    classDef compute fill:#c8e6c9,stroke:#333,stroke-width:1px;
    classDef wrapper fill:#ffe0b2,stroke:#333,stroke-width:1px;
    classDef storage fill:#eceff1,stroke:#333,stroke-width:1px;
    classDef config fill:#fff9c4,stroke:#333,stroke-width:1px;
    classDef external fill:#ffcdd2,stroke:#333,stroke-width:1px;
    classDef docs fill:#d1c4e9,stroke:#333,stroke-width:1px;
```
