# pavolulicny/rasterminal architecture

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

- Interactive diagram: https://gitdiagram.com/pavolulicny/rasterminal
- Repository: https://github.com/pavolulicny/rasterminal

## Overview

rasterminal is a CPU-based 3D model viewer that turns a model file into an interactive terminal display. The main workflow parses launch options, loads mesh and material data, renders frames, and presents them through a terminal graphics backend; input updates the camera and viewing settings for subsequent frames. The README also documents native OBJ, PLY, STL, and glTF support, broader Assimp format support, and Kitty, Sixel, and half-block presentation. Some subsystem wiring is inferred from documentation because the sampled excerpts are partial.

Main entry points: [`src/main.cpp`](https://github.com/pavolulicny/rasterminal/blob/main/src/main.cpp) (Viewer runtime), [`src/loaders/mesh.cpp`](https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh.cpp) (Mesh loading), [`src/loaders/mesh.h`](https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh.h) (Mesh and materials), [`src/terminal/graphics.cpp`](https://github.com/pavolulicny/rasterminal/blob/main/src/terminal/graphics.cpp) (Backend selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Viewer runtime"]
  node_options["Launch options<br/>[args.cpp]"]
  node_runtime["Viewer runtime<br/>[main.cpp]"]
  node_viewer_state["Viewer state<br/>[state.h]"]
  node_input_controller["Input controls<br/>[input_controller.h]"]
end

subgraph group_import["Model import"]
  node_mesh_dispatch["Mesh loading<br/>[mesh.cpp]"]
  node_obj_loader["OBJ loader<br/>[mesh_obj.cpp]"]
  node_ply_loader["PLY loader<br/>[mesh_ply.cpp]"]
  node_stl_loader["STL loader<br/>[mesh_stl.cpp]"]
  node_gltf_loader["glTF loader<br/>[mesh_gltf.cpp]"]
  node_assimp_loader["Assimp loader<br/>[mesh_assimp.cpp]"]
  node_mesh_data["Mesh and materials<br/>[mesh.h]"]
end

subgraph group_render["CPU rendering"]
  node_camera["Camera<br/>[camera.cpp]"]
  node_renderer["Renderer<br/>[renderer.cpp]"]
  node_rasterizer["Rasterizer<br/>[rasterize.cpp]"]
  node_texture["Texture sampling<br/>[texture.cpp]"]
end

subgraph group_terminal["Terminal I/O"]
  node_input_reader["Input reader<br/>[input_reader.h]"]
  node_framebuffer["Framebuffer<br/>[framebuffer.cpp]"]
  node_graphics_select["Backend selection<br/>[graphics.cpp]"]
  node_kitty["Kitty output<br/>[kitty.cpp]"]
  node_sixel["Sixel output<br/>[sixel.cpp]"]
  node_halfblocks["Half-block output<br/>[color.cpp]"]
  node_term_query["Terminal query<br/>[terminal_query.h]"]
end

node_user(("Viewer user"))
node_model["Model file"]
node_terminal_out["Terminal"]

node_user -->|"launches"| node_runtime
node_user -->|"chooses"| node_model
node_runtime -->|"parses"| node_options
node_runtime -->|"loads model"| node_mesh_dispatch
node_model -->|"provides file"| node_mesh_dispatch
node_mesh_dispatch -->|"dispatches"| node_obj_loader
node_mesh_dispatch -->|"dispatches"| node_ply_loader
node_mesh_dispatch -->|"dispatches"| node_stl_loader
node_mesh_dispatch -->|"dispatches"| node_gltf_loader
node_mesh_dispatch -->|"dispatches"| node_assimp_loader
node_obj_loader -->|"fills"| node_mesh_data
node_ply_loader -->|"fills"| node_mesh_data
node_stl_loader -->|"fills"| node_mesh_data
node_gltf_loader -->|"fills"| node_mesh_data
node_assimp_loader -->|"fills"| node_mesh_data
node_runtime -->|"initializes"| node_viewer_state
node_runtime -->|"renders frames"| node_renderer
node_runtime -->|"presents frames"| node_framebuffer
node_runtime -->|"queries terminal"| node_term_query
node_term_query -->|"reports capabilities"| node_graphics_select
node_runtime -->|"reads input"| node_input_reader
node_input_reader -->|"passes events"| node_input_controller
node_input_controller -->|"updates settings"| node_viewer_state
node_viewer_state -->|"configures"| node_camera
node_mesh_data -->|"supplies scene"| node_renderer
node_camera -->|"supplies view"| node_renderer
node_renderer -->|"rasterizes"| node_rasterizer
node_rasterizer -->|"samples textures"| node_texture
node_rasterizer -->|"writes pixels"| node_framebuffer
node_framebuffer -->|"uses backend"| node_graphics_select
node_graphics_select -->|"selects Kitty"| node_kitty
node_graphics_select -->|"selects Sixel"| node_sixel
node_graphics_select -->|"selects fallback"| node_halfblocks
node_kitty -->|"emits graphics"| node_terminal_out
node_sixel -->|"emits graphics"| node_terminal_out
node_halfblocks -->|"emits colored cells"| node_terminal_out

click node_options "https://github.com/pavolulicny/rasterminal/blob/main/src/args.cpp"
click node_runtime "https://github.com/pavolulicny/rasterminal/blob/main/src/main.cpp"
click node_viewer_state "https://github.com/pavolulicny/rasterminal/blob/main/src/viewer/state.h"
click node_input_controller "https://github.com/pavolulicny/rasterminal/blob/main/src/viewer/input_controller.h"
click node_input_reader "https://github.com/pavolulicny/rasterminal/blob/main/src/platform/input_reader.h"
click node_mesh_dispatch "https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh.cpp"
click node_obj_loader "https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh_obj.cpp"
click node_ply_loader "https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh_ply.cpp"
click node_stl_loader "https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh_stl.cpp"
click node_gltf_loader "https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh_gltf.cpp"
click node_assimp_loader "https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh_assimp.cpp"
click node_mesh_data "https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh.h"
click node_camera "https://github.com/pavolulicny/rasterminal/blob/main/src/render/camera.cpp"
click node_renderer "https://github.com/pavolulicny/rasterminal/blob/main/src/render/renderer.cpp"
click node_rasterizer "https://github.com/pavolulicny/rasterminal/blob/main/src/render/rasterize.cpp"
click node_texture "https://github.com/pavolulicny/rasterminal/blob/main/src/render/texture.cpp"
click node_framebuffer "https://github.com/pavolulicny/rasterminal/blob/main/src/terminal/framebuffer.cpp"
click node_graphics_select "https://github.com/pavolulicny/rasterminal/blob/main/src/terminal/graphics.cpp"
click node_kitty "https://github.com/pavolulicny/rasterminal/blob/main/src/terminal/kitty.cpp"
click node_sixel "https://github.com/pavolulicny/rasterminal/blob/main/src/terminal/sixel.cpp"
click node_halfblocks "https://github.com/pavolulicny/rasterminal/blob/main/src/terminal/color.cpp"
click node_term_query "https://github.com/pavolulicny/rasterminal/blob/main/src/platform/terminal_query.h"

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_options,node_runtime,node_viewer_state,node_input_controller,node_user toneBlue
class node_mesh_dispatch,node_obj_loader,node_ply_loader,node_stl_loader,node_gltf_loader,node_assimp_loader,node_mesh_data toneAmber
class node_camera,node_renderer,node_rasterizer,node_texture toneMint
class node_input_reader,node_framebuffer,node_graphics_select,node_kitty,node_sixel,node_halfblocks,node_term_query toneRose
class node_model,node_terminal_out toneIndigo
```

## Components

### Viewer runtime

- [Launch options](https://github.com/pavolulicny/rasterminal/blob/main/src/args.cpp): `src/args.cpp`
- [Viewer runtime](https://github.com/pavolulicny/rasterminal/blob/main/src/main.cpp): `src/main.cpp`
- [Viewer state](https://github.com/pavolulicny/rasterminal/blob/main/src/viewer/state.h): `src/viewer/state.h`
- [Input controls](https://github.com/pavolulicny/rasterminal/blob/main/src/viewer/input_controller.h): `src/viewer/input_controller.h`

### Model import

- [Mesh loading](https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh.cpp): `src/loaders/mesh.cpp`
- [OBJ loader](https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh_obj.cpp): `src/loaders/mesh_obj.cpp`
- [PLY loader](https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh_ply.cpp): `src/loaders/mesh_ply.cpp`
- [STL loader](https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh_stl.cpp): `src/loaders/mesh_stl.cpp`
- [glTF loader](https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh_gltf.cpp): `src/loaders/mesh_gltf.cpp`
- [Assimp loader](https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh_assimp.cpp): `src/loaders/mesh_assimp.cpp`
- [Mesh and materials](https://github.com/pavolulicny/rasterminal/blob/main/src/loaders/mesh.h): `src/loaders/mesh.h`

### CPU rendering

- [Camera](https://github.com/pavolulicny/rasterminal/blob/main/src/render/camera.cpp): `src/render/camera.cpp`
- [Renderer](https://github.com/pavolulicny/rasterminal/blob/main/src/render/renderer.cpp): `src/render/renderer.cpp`
- [Rasterizer](https://github.com/pavolulicny/rasterminal/blob/main/src/render/rasterize.cpp): `src/render/rasterize.cpp`
- [Texture sampling](https://github.com/pavolulicny/rasterminal/blob/main/src/render/texture.cpp): `src/render/texture.cpp`

### Terminal I/O

- [Input reader](https://github.com/pavolulicny/rasterminal/blob/main/src/platform/input_reader.h): `src/platform/input_reader.h`
- [Framebuffer](https://github.com/pavolulicny/rasterminal/blob/main/src/terminal/framebuffer.cpp): `src/terminal/framebuffer.cpp`
- [Backend selection](https://github.com/pavolulicny/rasterminal/blob/main/src/terminal/graphics.cpp): `src/terminal/graphics.cpp`
- [Kitty output](https://github.com/pavolulicny/rasterminal/blob/main/src/terminal/kitty.cpp): `src/terminal/kitty.cpp`
- [Sixel output](https://github.com/pavolulicny/rasterminal/blob/main/src/terminal/sixel.cpp): `src/terminal/sixel.cpp`
- [Half-block output](https://github.com/pavolulicny/rasterminal/blob/main/src/terminal/color.cpp): `src/terminal/color.cpp`
- [Terminal query](https://github.com/pavolulicny/rasterminal/blob/main/src/platform/terminal_query.h): `src/platform/terminal_query.h`

### Other components

- **Viewer user**
- **Model file**
- **Terminal**

## Connections

- Viewer user → Viewer runtime: launches
- Viewer user → Model file: chooses
- Viewer runtime → Launch options: parses
- Viewer runtime → Mesh loading: loads model
- Model file → Mesh loading: provides file
- Mesh loading → OBJ loader: dispatches
- Mesh loading → PLY loader: dispatches
- Mesh loading → STL loader: dispatches
- Mesh loading → glTF loader: dispatches
- Mesh loading → Assimp loader: dispatches
- OBJ loader → Mesh and materials: fills
- PLY loader → Mesh and materials: fills
- STL loader → Mesh and materials: fills
- glTF loader → Mesh and materials: fills
- Assimp loader → Mesh and materials: fills
- Viewer runtime → Viewer state: initializes
- Viewer runtime → Renderer: renders frames
- Viewer runtime → Framebuffer: presents frames
- Viewer runtime → Terminal query: queries terminal
- Terminal query → Backend selection: reports capabilities
- Viewer runtime → Input reader: reads input
- Input reader → Input controls: passes events
- Input controls → Viewer state: updates settings
- Viewer state → Camera: configures
- Mesh and materials → Renderer: supplies scene
- Camera → Renderer: supplies view
- Renderer → Rasterizer: rasterizes
- Rasterizer → Texture sampling: samples textures
- Rasterizer → Framebuffer: writes pixels
- Framebuffer → Backend selection: uses backend
- Backend selection → Kitty output: selects Kitty
- Backend selection → Sixel output: selects Sixel
- Backend selection → Half-block output: selects fallback
- Kitty output → Terminal: emits graphics
- Sixel output → Terminal: emits graphics
- Half-block output → Terminal: emits colored cells