# lumina-layer-studio/lumina-layers architecture

> Architecture diagram of the GitHub repository lumina-layer-studio/lumina-layers, 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/lumina-layer-studio/lumina-layers
- Repository: https://github.com/lumina-layer-studio/lumina-layers

## Overview

Lumina Studio turns a user image and a material-calibration preset into a multi-material 3D model for slicing and printing. The documented 1.x workflow first produces and photographs a fixed calibration board to build a preset; conversion then color-matches the image against that preset and generates a 3MF. The tree also exposes separate calibration, extraction, five-color, and slicer domains. The API factory and converter excerpts establish some backend wiring; unsampled router and UI internals are represented only where their paths and roles are clear.

Main entry points: [`api/app.py`](https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/app.py) (FastAPI app), [`core/converter.py`](https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/converter.py) (Conversion coordinator), [`api/routers/converter.py`](https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/converter.py) (Converter routes), [`api/routers/lut.py`](https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/lut.py) (LUT routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_calibration["Calibration assets"]
  node_calibration["Calibration processing<br/>[calibration.py]"]
  node_lut_manager["Preset management<br/>[lut_manager.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_ui["Gradio studio<br/>[layout_new.py]"]
  node_api["FastAPI app<br/>[app.py]"]
  node_calibration_api["Calibration routes<br/>[calibration.py]"]
  node_converter_api["Converter routes<br/>[converter.py]"]
  node_worker_pool["Process pool<br/>[worker_pool.py]"]
  node_converter_workers["Conversion workers"]
  node_session[("Conversion sessions<br/>[session_store.py]")]
  node_lut_api["LUT routes<br/>[lut.py]"]
end

subgraph group_conversion["Image conversion"]
  node_converter["Conversion coordinator<br/>[converter.py]"]
  node_image_processing["Image processing"]
  node_color_matching["Color matching"]
  node_mesh["Mesh generation<br/>[mesh_generators.py]"]
  node_vector_engine["SVG vector engine<br/>[vector_engine.py]"]
end

subgraph group_print_tools["Print workflows"]
  node_extractor_api["Extractor routes<br/>[extractor.py]"]
  node_extractor["Image extraction<br/>[extractor.py]"]
  node_five_color_api["Five-color routes<br/>[five_color.py]"]
  node_five_color["Five-color combinations"]
  node_slicer_api["Slicer routes<br/>[slicer.py]"]
  node_slicer["Slicer preparation<br/>[slicer.py]"]
  node_writer["3MF writer"]
end

node_user(("Studio user"))
node_printer(("Slicer and printer"))

node_user -->|"uses"| node_ui
node_user -->|"submits image"| node_api
node_api -->|"registers routes"| node_calibration_api
node_api -->|"registers routes"| node_converter_api
node_api -->|"registers routes"| node_lut_api
node_api -->|"registers routes"| node_extractor_api
node_api -->|"registers routes"| node_five_color_api
node_api -->|"registers routes"| node_slicer_api
node_user -->|"calibrates materials"| node_calibration
node_calibration -->|"builds preset"| node_lut_manager
node_user -->|"manages presets"| node_lut_api
node_lut_api -->|"accesses presets"| node_lut_manager
node_converter_api -->|"stores conversion state"| node_session
node_converter_api -->|"submits CPU tasks"| node_worker_pool
node_worker_pool -->|"dispatches tasks"| node_converter_workers
node_converter_workers -->|"calls conversion"| node_converter
node_converter -->|"processes image"| node_image_processing
node_converter -->|"matches colors"| node_color_matching
node_converter -->|"builds geometry"| node_mesh
node_converter -.->|"uses vector path"| node_vector_engine
node_converter -->|"loads preset"| node_lut_manager
node_converter -->|"exports 3MF"| node_writer
node_writer -->|"provides model"| node_printer
node_extractor_api -->|"handles extraction"| node_extractor
node_five_color_api -->|"handles combinations"| node_five_color
node_slicer_api -->|"handles slicing"| node_slicer
node_slicer -->|"prepares print"| node_printer

click node_ui "https://github.com/lumina-layer-studio/lumina-layers/blob/main/ui/layout_new.py"
click node_api "https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/app.py"
click node_calibration_api "https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/calibration.py"
click node_converter_api "https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/converter.py"
click node_worker_pool "https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/worker_pool.py"
click node_converter_workers "https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/workers/converter_workers.py"
click node_session "https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/session_store.py"
click node_lut_api "https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/lut.py"
click node_calibration "https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/calibration.py"
click node_lut_manager "https://github.com/lumina-layer-studio/lumina-layers/blob/main/utils/lut_manager.py"
click node_converter "https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/converter.py"
click node_image_processing "https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/image_processing.py"
click node_color_matching "https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/color_matching_hue_aware.py"
click node_mesh "https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/mesh_generators.py"
click node_vector_engine "https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/vector_engine.py"
click node_extractor_api "https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/extractor.py"
click node_extractor "https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/extractor.py"
click node_five_color_api "https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/five_color.py"
click node_five_color "https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/five_color_combination.py"
click node_slicer_api "https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/slicer.py"
click node_slicer "https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/slicer.py"
click node_writer "https://github.com/lumina-layer-studio/lumina-layers/blob/main/utils/bambu_3mf_writer.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_calibration,node_lut_manager,node_user toneBlue
class node_ui,node_api,node_calibration_api,node_converter_api,node_worker_pool,node_converter_workers,node_session,node_lut_api toneAmber
class node_converter,node_image_processing,node_color_matching,node_mesh,node_vector_engine toneMint
class node_extractor_api,node_extractor,node_five_color_api,node_five_color,node_slicer_api,node_slicer,node_writer toneRose
class node_printer toneIndigo
```

## Components

### Calibration assets

- [Calibration processing](https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/calibration.py): `core/calibration.py`
- [Preset management](https://github.com/lumina-layer-studio/lumina-layers/blob/main/utils/lut_manager.py): `utils/lut_manager.py`

### User interfaces

- [Gradio studio](https://github.com/lumina-layer-studio/lumina-layers/blob/main/ui/layout_new.py): `ui/layout_new.py`
- [FastAPI app](https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/app.py): `api/app.py`
- [Calibration routes](https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/calibration.py): `api/routers/calibration.py`
- [Converter routes](https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/converter.py): `api/routers/converter.py`
- [Process pool](https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/worker_pool.py): `api/worker_pool.py`
- [Conversion workers](https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/workers/converter_workers.py): `api/workers/converter_workers.py`
- [Conversion sessions](https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/session_store.py): `api/session_store.py`
- [LUT routes](https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/lut.py): `api/routers/lut.py`

### Image conversion

- [Conversion coordinator](https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/converter.py): `core/converter.py`
- [Image processing](https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/image_processing.py): `core/image_processing.py`
- [Color matching](https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/color_matching_hue_aware.py): `core/color_matching_hue_aware.py`
- [Mesh generation](https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/mesh_generators.py): `core/mesh_generators.py`
- [SVG vector engine](https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/vector_engine.py): `core/vector_engine.py`

### Print workflows

- [Extractor routes](https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/extractor.py): `api/routers/extractor.py`
- [Image extraction](https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/extractor.py): `core/extractor.py`
- [Five-color routes](https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/five_color.py): `api/routers/five_color.py`
- [Five-color combinations](https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/five_color_combination.py): `core/five_color_combination.py`
- [Slicer routes](https://github.com/lumina-layer-studio/lumina-layers/blob/main/api/routers/slicer.py): `api/routers/slicer.py`
- [Slicer preparation](https://github.com/lumina-layer-studio/lumina-layers/blob/main/core/slicer.py): `core/slicer.py`
- [3MF writer](https://github.com/lumina-layer-studio/lumina-layers/blob/main/utils/bambu_3mf_writer.py): `utils/bambu_3mf_writer.py`

### Other components

- **Studio user**
- **Slicer and printer**

## Connections

- Studio user → Gradio studio: uses
- Studio user → FastAPI app: submits image
- FastAPI app → Calibration routes: registers routes
- FastAPI app → Converter routes: registers routes
- FastAPI app → LUT routes: registers routes
- FastAPI app → Extractor routes: registers routes
- FastAPI app → Five-color routes: registers routes
- FastAPI app → Slicer routes: registers routes
- Studio user → Calibration processing: calibrates materials
- Calibration processing → Preset management: builds preset
- Studio user → LUT routes: manages presets
- LUT routes → Preset management: accesses presets
- Converter routes → Conversion sessions: stores conversion state
- Converter routes → Process pool: submits CPU tasks
- Process pool → Conversion workers: dispatches tasks
- Conversion workers → Conversion coordinator: calls conversion
- Conversion coordinator → Image processing: processes image
- Conversion coordinator → Color matching: matches colors
- Conversion coordinator → Mesh generation: builds geometry
- Conversion coordinator → SVG vector engine: uses vector path
- Conversion coordinator → Preset management: loads preset
- Conversion coordinator → 3MF writer: exports 3MF
- 3MF writer → Slicer and printer: provides model
- Extractor routes → Image extraction: handles extraction
- Five-color routes → Five-color combinations: handles combinations
- Slicer routes → Slicer preparation: handles slicing
- Slicer preparation → Slicer and printer: prepares print