# orenliu/soup3d architecture

> Architecture diagram of the GitHub repository orenliu/soup3d, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/orenliu/soup3d
- Repository: https://github.com/orenliu/soup3d

## Overview

soup3D is a Python 3D engine built on OpenGL, intended for interactive rendering, games, visualization, and graphics work. Its documented user workflow initializes the engine in a pygame OpenGL window, creates a shader-backed face and model, displays it, then calls update in the application loop. The architecture also includes asset loading, lighting, camera control, skeletal animation, 2D overlays, off-screen render targets, and scene snapshots. Connections below follow the README workflow and sampled source references; unsampled render internals are not expanded into assumed call chains.

Main entry points: [`soup3D/__init__.py`](https://github.com/orenliu/soup3d/blob/master/soup3D/__init__.py) (Engine API), [`soup3D/shader.py`](https://github.com/orenliu/soup3d/blob/master/soup3D/shader.py) (Shaders and Textures), [`soup3D/scene.py`](https://github.com/orenliu/soup3d/blob/master/soup3D/scene.py) (Scene Snapshots), [`soup3D/camera.py`](https://github.com/orenliu/soup3d/blob/master/soup3D/camera.py) (Camera)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Engine Core"]
  node_api["Engine API<br/>[__init__.py]"]
  node_model["Models and Faces<br/>[__init__.py]"]
  node_names["Render Constants<br/>[name.py]"]
end

subgraph group_render["Rendering"]
  node_shaders["Shaders and Textures<br/>[shader.py]"]
end

subgraph group_scene["Scene Features"]
  node_camera["Camera<br/>[camera.py]"]
  node_lighting["Lighting<br/>[light.py]"]
  node_skeleton["Skeletons<br/>[skeleton.py]"]
end

subgraph group_assets["Assets and Math"]
  node_assets["Asset Loading<br/>[__init__.py]"]
  node_math["3D Math<br/>[s3dm.py]"]
end

subgraph group_extensions["Output Extensions"]
  node_ui["2D UI<br/>[ui.py]"]
  node_target["Render Targets<br/>[target.py]"]
  node_snapshot["Scene Snapshots<br/>[scene.py]"]
end

node_developer(("Application"))
node_pygame["Pygame Window"]
node_opengl["OpenGL"]

node_developer -->|"initializes and updates"| node_api
node_developer -->|"creates and displays"| node_model
node_developer -->|"creates window"| node_pygame
node_api -.->|"uses window context"| node_pygame
node_api -->|"uses"| node_camera
node_api -->|"uses"| node_lighting
node_api -->|"uses"| node_shaders
node_api -->|"uses"| node_skeleton
node_api -->|"loads and builds"| node_assets
node_model -->|"renders with"| node_shaders
node_shaders -->|"issues rendering calls"| node_opengl
node_api -.->|"initializes rendering"| node_opengl
node_camera -->|"uses rotations"| node_math
node_lighting -->|"uses rotations"| node_math
node_skeleton -->|"uses transforms"| node_math
node_shaders -->|"skins meshes"| node_skeleton
node_shaders -->|"samples target textures"| node_target
node_api -->|"exposes"| node_ui
node_api -->|"exposes"| node_target
node_api -->|"exposes"| node_snapshot
node_snapshot -->|"extracts scene state"| node_model
node_snapshot -->|"captures camera state"| node_camera
node_snapshot -->|"captures light state"| node_lighting

click node_api "https://github.com/orenliu/soup3d/blob/master/soup3D/__init__.py"
click node_model "https://github.com/orenliu/soup3d/blob/master/soup3D/__init__.py"
click node_camera "https://github.com/orenliu/soup3d/blob/master/soup3D/camera.py"
click node_lighting "https://github.com/orenliu/soup3d/blob/master/soup3D/light.py"
click node_shaders "https://github.com/orenliu/soup3d/blob/master/soup3D/shader.py"
click node_skeleton "https://github.com/orenliu/soup3d/blob/master/soup3D/skeleton.py"
click node_assets "https://github.com/orenliu/soup3d/blob/master/soup3D/__init__.py"
click node_math "https://github.com/orenliu/soup3d/blob/master/soup3D/s3dm.py"
click node_names "https://github.com/orenliu/soup3d/blob/master/soup3D/name.py"
click node_ui "https://github.com/orenliu/soup3d/blob/master/soup3D/ui.py"
click node_target "https://github.com/orenliu/soup3d/blob/master/soup3D/target.py"
click node_snapshot "https://github.com/orenliu/soup3d/blob/master/soup3D/scene.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_model,node_names toneBlue
class node_shaders toneAmber
class node_camera,node_lighting,node_skeleton toneMint
class node_assets,node_math toneRose
class node_ui,node_target,node_snapshot,node_developer,node_pygame,node_opengl toneIndigo
```

## Components

### Engine Core

- [Engine API](https://github.com/orenliu/soup3d/blob/master/soup3D/__init__.py): `soup3D/__init__.py`
- [Models and Faces](https://github.com/orenliu/soup3d/blob/master/soup3D/__init__.py): `soup3D/__init__.py`
- [Render Constants](https://github.com/orenliu/soup3d/blob/master/soup3D/name.py): `soup3D/name.py`

### Rendering

- [Shaders and Textures](https://github.com/orenliu/soup3d/blob/master/soup3D/shader.py): `soup3D/shader.py`

### Scene Features

- [Camera](https://github.com/orenliu/soup3d/blob/master/soup3D/camera.py): `soup3D/camera.py`
- [Lighting](https://github.com/orenliu/soup3d/blob/master/soup3D/light.py): `soup3D/light.py`
- [Skeletons](https://github.com/orenliu/soup3d/blob/master/soup3D/skeleton.py): `soup3D/skeleton.py`

### Assets and Math

- [Asset Loading](https://github.com/orenliu/soup3d/blob/master/soup3D/__init__.py): `soup3D/__init__.py`
- [3D Math](https://github.com/orenliu/soup3d/blob/master/soup3D/s3dm.py): `soup3D/s3dm.py`

### Output Extensions

- [2D UI](https://github.com/orenliu/soup3d/blob/master/soup3D/ui.py): `soup3D/ui.py`
- [Render Targets](https://github.com/orenliu/soup3d/blob/master/soup3D/target.py): `soup3D/target.py`
- [Scene Snapshots](https://github.com/orenliu/soup3d/blob/master/soup3D/scene.py): `soup3D/scene.py`

### Other components

- **Application**
- **Pygame Window**
- **OpenGL**

## Connections

- Application → Engine API: initializes and updates (evidence: `README.md`)
- Application → Models and Faces: creates and displays (evidence: `README.md`)
- Application → Pygame Window: creates window (evidence: `README.md`)
- Engine API → Pygame Window: uses window context
- Engine API → Camera: uses (evidence: `soup3D/__init__.py`)
- Engine API → Lighting: uses (evidence: `soup3D/__init__.py`)
- Engine API → Shaders and Textures: uses (evidence: `soup3D/__init__.py`)
- Engine API → Skeletons: uses (evidence: `soup3D/__init__.py`)
- Engine API → Asset Loading: loads and builds (evidence: `soup3D/__init__.py`)
- Models and Faces → Shaders and Textures: renders with (evidence: `README.md`)
- Shaders and Textures → OpenGL: issues rendering calls (evidence: `soup3D/shader.py`)
- Engine API → OpenGL: initializes rendering
- Camera → 3D Math: uses rotations (evidence: `soup3D/camera.py`)
- Lighting → 3D Math: uses rotations (evidence: `soup3D/light.py`)
- Skeletons → 3D Math: uses transforms (evidence: `soup3D/skeleton.py`)
- Shaders and Textures → Skeletons: skins meshes (evidence: `soup3D/shader.py`)
- Shaders and Textures → Render Targets: samples target textures (evidence: `soup3D/target.py`)
- Engine API → 2D UI: exposes (evidence: `soup3D/__init__.py`)
- Engine API → Render Targets: exposes (evidence: `soup3D/__init__.py`)
- Engine API → Scene Snapshots: exposes (evidence: `soup3D/__init__.py`)
- Scene Snapshots → Models and Faces: extracts scene state (evidence: `soup3D/scene.py`)
- Scene Snapshots → Camera: captures camera state (evidence: `soup3D/scene.py`)
- Scene Snapshots → Lighting: captures light state (evidence: `soup3D/scene.py`)
