# papagiannakis/elements architecture

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

- Interactive diagram: https://gitdiagram.com/papagiannakis/elements
- Repository: https://github.com/papagiannakis/elements

## Overview

##### Main components
- Python Environment
– Conda/Pip + runtime dependencies (e.g., PyOpenGL, imgui-binding, USD)
- Core Libraries
– pyECSS: Entity-Component-System + Scenegraph manager (entities, components, systems, events)
– pyGLV: Graphics and GUI layer on top of pyECSS (Scene, Shader, Texture, VertexArray, ImGui Viewer)
– pyEEL: Educational Jupyter-notebook hub (CG, DL, SciCom, GATE, neuralCG modules)
- Extensions / Features (“plugins”)
– BasicShapes, GA, Gizmos, SkinnedMesh, Slicing, Voronoi2D, bezier, plane_fitting, plotting, rigid_body_animation, usd importer
- Utilities
– Utility modules (Converter, ShapeClassifierInterface, atlas generation, obj importer, terrain, ChatGPT wrapper, etc.)
- Static Assets (Files)
– Models (.obj, .fbx), pickles, shaders (.vert/.frag), textures, scenes (.usd), SCV data
- Clients / Examples / Notebooks
– Python scripts in Elements/examples
– Jupyter notebooks in pyEEL/notebooks
- Documentation (Sphinx / ReadTheDocs)

##### Relationships & data‐flow
- The “User” (student, researcher, or application code)
↳ imports Elements packages (pyECSS, pyGLV, pyEEL, utils)
↳ writes examples or notebooks that compose Entities, attach Components, register Systems
- pyECSS
↳ manages the Scenegraph and event dispatch
↳ instantiates Entities ←→ attaches Components ←→ schedules Systems
- pyGLV
↳ provides rendering and GUI Systems (RenderSystem, CameraSystem, ImGUI system) that plug into pyECSS
↳ issues OpenGL calls via Shader, Texture, VertexArray abstractions
- Extensions
↳ register extra Components & Systems with the ECSSManager
↳ consume static Assets via Files module (models, shaders, textures)
↳ expose helper functions to user code
- pyEEL
↳ loads core libraries in notebook context for teaching/demo
↳ may leverage utilities and static Assets for Deep Learning or CG demos

##### Architectural patterns & principles
- Modular plugin architecture: Core (pyECSS) ← extensions ← user code
- Separation of concerns:
– ECS (data & logic) vs. Graphics (GLV) vs. Education (EEL) vs. Utils vs. Assets
- Inversion-of-control: Systems are registered with ECSSManager and invoked each frame/tick
- Dependency injection: Graphics & utility modules import only what they need from core

##### Relevant technologies, frameworks & libraries
- Python 3.8+
- Conda/Pip for environment management
- PyOpenGL / SDL2 / ImGui (via pyGLV)
- Pixar USD for scene import/export
- Sphinx, ReadTheDocs for docs
- Jupyter notebooks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Python Environment
    subgraph "Python Environment"
        PE["Conda/Pip + Dependencies"]:::env
    end

    %% Core Libraries
    subgraph "Core Libraries"
        pyECSS["pyECSS<br/>ECS manager & scenegraph"]:::core
        pyGLV["pyGLV<br/>Graphics & GUI layer"]:::core
        pyEEL["pyEEL<br/>Educational notebooks & modules"]:::core
    end

    %% Extensions / Features
    subgraph "Extensions / Features"
        ES["BasicShapes, Slicing, Voronoi2D, …"]:::ext
    end

    %% Utilities
    subgraph "Utilities"
        UT["Converter, ChatGPT wrapper, ShapeClassifier, etc."]:::util
    end

    %% Static Assets
    FA["Files<br/>(models, shaders, textures, scenes)"]:::assets

    %% Clients / Examples / Notebooks
    subgraph "Clients"
        CL["Examples & Notebooks"]:::client
    end

    %% External Dependencies
    subgraph "External Dependencies"
        ED1["PyOpenGL, SDL2, ImGui"]:::extdep
        ED2["Pixar USD"]:::extdep
        ED3["Jupyter"]:::extdep
    end

    %% Connections
    CL -->|imports| pyECSS
    CL -->|imports| pyGLV
    CL -->|imports| pyEEL
    CL -->|uses plugins| ES
    CL -->|uses utils| UT

    pyECSS -->|invokes systems| pyGLV
    pyECSS -->|loads assets| FA

    ES -->|registers with| pyECSS
    ES -->|loads assets| FA

    UT -->|assists| pyECSS
    UT -->|assists| pyGLV

    pyGLV -->|renders via| ED1
    pyEEL -->|imports USD via| ED2
    pyEEL -->|runs in| ED3

    %% Click Events
    click PE "https://github.com/papagiannakis/elements/blob/develop/setup.py"
    click pyECSS "https://github.com/papagiannakis/elements/blob/develop/Elements/pyECSS/ECSSManager.py"
    click pyGLV "https://github.com/papagiannakis/elements/blob/develop/Elements/pyGLV/GL/Scene.py"
    click pyEEL "https://github.com/papagiannakis/elements/blob/develop/Elements/pyEEL/__init__.py"
    click ES "https://github.com/papagiannakis/elements/tree/develop/Elements/extensions/BasicShapes/"
    click UT "https://github.com/papagiannakis/elements/blob/develop/Elements/utils/Converter.py"
    click FA "https://github.com/papagiannakis/elements/tree/develop/Elements/files/models/"
    click CL "https://github.com/papagiannakis/elements/blob/develop/Elements/examples/README.md"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef ext fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef util fill:#FFFF99,stroke:#333,stroke-width:1px;
    classDef assets fill:#CCCCCC,stroke:#333,stroke-width:1px,shape:cylinder;
    classDef client fill:#FFA500,stroke:#333,stroke-width:1px,rx:5,ry:5;
    classDef env fill:none,stroke:#333,stroke-dasharray:5 5;
    classDef extdep fill:#F0F0F0,stroke:#999,stroke-dasharray:2 2;
```
