# lichard49/pose-viewer architecture

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

- Interactive diagram: https://gitdiagram.com/lichard49/pose-viewer
- Repository: https://github.com/lichard49/pose-viewer

## Overview

##### Project Type and Purpose
- This is a visualization tool that renders human poses in 3D using web technologies.
- It uses FastAPI as the backend to serve the viewer and expose endpoints.
- Visualization on the frontend is powered by three.js (found in the static assets), and the user interacts with the system via a web browser.
- The project supports multiple data streaming inputs – one for posing (from a pre-generated dataset with .pkl files) and another for orientation input using a mouse tracker.

##### Analyzing the File Structure
- Top-level Files & Folders:
– The README.md file explains the startup instructions and purpose.
– The "src" directory includes the main Python scripts:
- pose_viewer_server.py – the FastAPI server that acts as the backend.
- pose_file_reader_client.py – reads pose data (from a dataset file such as the one in "dataset") and sends it to the server.
- mouse_tracker_client.py – handles orientation data through mouse input.
- pose_utils.py – utility functions that likely support data parsing or processing.
– The "src/templates" folder holds the front-end:
- index.html – the main HTML page.
- The "static" subfolder contains CSS, JavaScript (including three.js and OrbitControls) for interactive visualization.
- Supporting Directories:
– "dataset": Contains sample pickle files (like sit_to_stands-wham_output.pkl) with pose data.
– "body_models": Represents SMPL models (female, male, neutral) stored as pickle files that could be used for rendering body poses.

##### Key Components to Highlight
a. Frontend Component:
- The Browser: Displaying the index.html view.
- Static Assets: CSS & JavaScript files (three.js, OrbitControls, script.js) used for rendering and interacting with the viewer.
b. Backend Component:
- FastAPI Server: Represented by src/pose_viewer_server.py, handling requests and serving static content/templates.
- API Endpoints: Expose functionalities for visualizing pose/orientation data.
c. Data Streaming Clients:
- Pose Data Client: src/pose_file_reader_client.py that reads preformatted pose data (from the dataset) and streams it to the server.
- Orientation Input Client: src/mouse_tracker_client.py that sends orientation updates (likely via the API) to update the view.
d. Supporting Data and Models:
- Dataset: The "dataset" folder containing pose data pickle files.
e. Utility Module:
- pose_utils.py: Provides auxiliary functionality to handle processing/logging of pose data.

##### Relationships and Interactions
- The FastAPI server (backend) pulls together the static templates and assets to render the visualization page.
- External data streams from the two client modules (pose file reader and mouse tracker) feed data into the backend, which then pushes updates to the browser.
- The generated visuals likely involve 3D rendering logic in three.js, getting configuration data from the backend and SMPL models as needed.
- The application design displays a clear separation of concerns: backend services (data handling, API, static file serving) and frontend display (browser rendering, user interaction).

##### Architectural Patterns / Design Principles
- Clear Client-Server separation: The FastAPI server is isolated from the data-providing clients.
- Modularity: Each module (data reader, orientation tracker, viewer server) is responsible for a specific aspect of the data pipeline.
- Web-based 3D Visualization: Leverages a modern web framework (FastAPI) together with static client-side libraries (three.js) for rendering.
- Use of external data models (SMPL) enhances the realism and accuracy of the visualizations.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Data Clients"
        PD["Pose Data Client"]:::client
        OT["Mouse Tracker Client"]:::client
    end

    subgraph "Backend Services"
        FAPI["FastAPI Pose Viewer Server"]:::backend
        UTIL["Utility Module"]:::backend
        DATA["Dataset"]:::database
        BM["Body Models"]:::database
    end

    subgraph "Frontend Layer"
        BROWSER["Browser"]:::frontend
        STATIC["Static Assets"]:::frontend
    end

    PD -->|"streams_pose_data"| FAPI
    OT -->|"streams_orientation_data"| FAPI
    FAPI -->|"serves_view"| BROWSER
    FAPI -->|"load_utilities"| UTIL
    FAPI -->|"reads_data"| DATA
    FAPI -->|"uses_models"| BM
    BROWSER -->|"loads_assets"| STATIC

    click PD "https://github.com/lichard49/pose-viewer/blob/main/src/pose_file_reader_client.py"
    click OT "https://github.com/lichard49/pose-viewer/blob/main/src/mouse_tracker_client.py"
    click FAPI "https://github.com/lichard49/pose-viewer/blob/main/src/pose_viewer_server.py"
    click UTIL "https://github.com/lichard49/pose-viewer/blob/main/src/pose_utils.py"
    click BROWSER "https://github.com/lichard49/pose-viewer/blob/main/src/templates/index.html"
    click STATIC "https://github.com/lichard49/pose-viewer/tree/main/src/templates/static"
    click DATA "https://github.com/lichard49/pose-viewer/tree/main/dataset"
    click BM "https://github.com/lichard49/pose-viewer/tree/main/body_models/smpl"

    classDef client fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef frontend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef database fill:#FFFF99,stroke:#000,stroke-width:2px;
```
