# 00danii/nebula architecture

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

- Interactive diagram: https://gitdiagram.com/00danii/nebula
- Repository: https://github.com/00danii/nebula

## Overview

1. **Purpose and shape of the system**  
   Nébula is a desktop image editor written in Python, centered on applying “scientific/astronomical” visual treatments to a single image. The repository is organized around a Tkinter UI, an image-processing engine, separate creative-style and metadata-style pipelines, and a canvas-based preview/export flow.

2. **Application bootstrap and runtime entrypoints**  
   `main.py` is the normal entrypoint for development runs. `ui/app.py` likely constructs the main window and wires the rest of the application together. The repo also includes `Nebula.spec`, `build/`, `dist/`, `scripts/build_exe.bat`, and `ejecutar.bat`, which show the project is packaged as a standalone Windows executable with PyInstaller.

3. **UI layer as the interaction boundary**  
   The `ui/` package is the presentation layer: `app.py` for the main window, `canvas.py` for preview rendering, `controls.py` for the adjustment panels, and `theme.py` for the dark UI styling. This layer owns user interaction, keyboard shortcuts, fullscreen behavior, and the visible state of sliders, comboboxes, and color pickers.

4. **Core processing pipeline**  
   The `core/` package is the main application logic. `engine.py` is the orchestration boundary between UI and processing. `image_processor.py` is where image transformations are applied. `grid_renderer.py` and `metadata_renderer.py` are responsible for overlay generation. `data_generator.py` likely computes the synthetic scientific measurements and labels used by metadata overlays.

5. **Data flow from user action to preview**  
   The typical flow is: the user opens an image in the UI, the engine stores it as the current working image, style settings are adjusted through controls, and the engine re-runs the processing pipeline to produce a preview. The rendered result is then drawn onto the canvas. Saving uses the same processed output path, but writes to file instead of the on-screen canvas.

6. **Creative style subsystem**  
   The `styles/` package contains the major visual effects applied to the image itself. `base_style.py` defines the shared style contract, `style_manager.py` selects and configures styles, and the concrete style modules implement effects such as sepia, CRT, thermal, noir, neon, duotone, tritone, invert, custom, and alien signal. This is a self-contained transformation layer that can be composed with basic adjustments like brightness, gamma, temperature, and saturation.

7. **Metadata overlay subsystem**  
   The `metadata_styles/` package is separate from the creative image filters. It contains `base_metadata_style.py`, `manager.py`, and concrete overlay styles such as alien HUD, minimal, scientific HUD, astronomical plate, and geometric. These styles draw the simulated instrument readouts, labels, coordinates, bars, and technical annotations that make the output look like a scientific plate rather than just a filtered photo.

8. **Overlay and framing logic**  
   The grid and metadata layers are distinct from the core image effects. `core/grid_renderer.py` adds telescope-like grid elements, axes, ticks, cardinal directions, and legends. The metadata styles add their own annotations and coordinate readouts. This creates a layered composition: original image → creative filter → scientific grid → metadata overlay.

9. **Shared utilities and resources**  
   `utils/font_utils.py` provides font handling for the rendered overlays and UI text, which matters because the output relies on precise technical-looking typography. `utils/__init__.py` contains resource-path handling so assets resolve correctly both in source runs and in the PyInstaller executable. The `assets/` folder stores the logo and example renders used by the app and README.

10. **State management and architectural boundaries**  
   The README explicitly calls out an Observer pattern between UI and engine, which suggests the UI does not directly manipulate rendering internals but publishes control changes to the engine. It also notes Singleton-style managers for fonts and styles, implying centralized registry objects for reusable rendering resources and style selection. These boundaries keep presentation, processing, and style configuration separated.

11. **Input/output characteristics**  
   The app is image-file oriented rather than batch-oriented or network-oriented. It loads PNG, JPG/JPEG, BMP, and TIFF, and exports PNG or JPG. The processing stack depends on OpenCV, NumPy, and Pillow, which indicates pixel-level transformations, color-space conversions, image compositing, and blur/colormap operations are core to the design.

12. **What to emphasize in an architecture diagram**  
   The most important boxes are: UI shell, engine/orchestrator, image processor, creative styles, metadata styles, grid renderer, and output canvas/export. The key arrows are user events into UI, UI state changes into engine, engine into processing/rendering modules, and processed image back to canvas/save. The packaging/build files are peripheral support, not part of runtime flow, but they matter if the diagram includes deployment.

Main entry points: [`core/engine.py`](https://github.com/00danii/nebula/blob/main/core/engine.py) (Engine), [`ui/app.py`](https://github.com/00danii/nebula/blob/main/ui/app.py) (App), [`styles/style_manager.py`](https://github.com/00danii/nebula/blob/main/styles/style_manager.py) (Style mgr), [`metadata_styles/manager.py`](https://github.com/00danii/nebula/blob/main/metadata_styles/manager.py) (Meta mgr)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>entrypoint<br/>[main.py]"]
end

subgraph group_ui["UI"]
  node_ui_app["App<br/>tk window<br/>[app.py]"]
  node_ui_canvas["Canvas<br/>preview view<br/>[canvas.py]"]
  node_ui_controls["Controls<br/>settings panel<br/>[controls.py]"]
  node_ui_theme["Theme<br/>styling<br/>[theme.py]"]
end

subgraph group_core["Core"]
  node_engine["Engine<br/>orchestrator<br/>[engine.py]"]
  node_processor["Processor<br/>image pipeline<br/>[image_processor.py]"]
  node_grid["Grid<br/>overlay renderer<br/>[grid_renderer.py]"]
  node_meta_render["Metadata<br/>overlay renderer"]
  node_data_gen["Data gen<br/>measurement source<br/>[data_generator.py]"]
end

subgraph group_styles["Creative styles"]
  node_style_mgr["Style mgr<br/>style registry<br/>[style_manager.py]"]
  node_style_base["Style base<br/>style contract<br/>[base_style.py]"]
  node_creative_styles["Creative styles<br/>effect set<br/>[creative_styles.py]"]
end

subgraph group_metadata["Metadata styles"]
  node_meta_mgr["Meta mgr<br/>style registry<br/>[manager.py]"]
  node_meta_base["Meta base<br/>overlay contract"]
  node_meta_styles["Overlay styles<br/>style set"]
end

subgraph group_support["Support"]
  node_fonts["Fonts<br/>font helper<br/>[font_utils.py]"]
  node_utils_pkg["Paths<br/>resource helper<br/>[__init__.py]"]
  node_assets["Assets<br/>resource bundle"]
  node_build["PyInstaller<br/>packaging<br/>[Nebula.spec]"]
end

node_main -->|"starts"| node_ui_app
node_ui_app -->|"hosts"| node_ui_controls
node_ui_app -->|"drives"| node_ui_canvas
node_ui_app -->|"applies"| node_ui_theme
node_ui_controls -->|"events"| node_engine
node_ui_canvas -->|"requests"| node_engine
node_engine -->|"runs"| node_processor
node_engine -->|"adds"| node_grid
node_engine -->|"adds"| node_meta_render
node_engine -->|"selects"| node_style_mgr
node_style_mgr -->|"implements"| node_style_base
node_style_mgr -->|"loads"| node_creative_styles
node_engine -->|"selects"| node_meta_mgr
node_meta_mgr -->|"implements"| node_meta_base
node_meta_mgr -->|"loads"| node_meta_styles
node_meta_render -->|"feeds"| node_data_gen
node_processor -->|"uses"| node_fonts
node_ui_app -->|"uses"| node_fonts
node_utils_pkg -->|"resolves"| node_assets
node_build -.->|"packages"| node_assets
node_build -.->|"ships"| node_ui_app

click node_main "https://github.com/00danii/nebula/blob/main/main.py"
click node_ui_app "https://github.com/00danii/nebula/blob/main/ui/app.py"
click node_ui_canvas "https://github.com/00danii/nebula/blob/main/ui/canvas.py"
click node_ui_controls "https://github.com/00danii/nebula/blob/main/ui/controls.py"
click node_ui_theme "https://github.com/00danii/nebula/blob/main/ui/theme.py"
click node_engine "https://github.com/00danii/nebula/blob/main/core/engine.py"
click node_processor "https://github.com/00danii/nebula/blob/main/core/image_processor.py"
click node_grid "https://github.com/00danii/nebula/blob/main/core/grid_renderer.py"
click node_meta_render "https://github.com/00danii/nebula/blob/main/core/metadata_renderer.py"
click node_data_gen "https://github.com/00danii/nebula/blob/main/core/data_generator.py"
click node_style_mgr "https://github.com/00danii/nebula/blob/main/styles/style_manager.py"
click node_style_base "https://github.com/00danii/nebula/blob/main/styles/base_style.py"
click node_creative_styles "https://github.com/00danii/nebula/blob/main/styles/creative_styles.py"
click node_meta_mgr "https://github.com/00danii/nebula/blob/main/metadata_styles/manager.py"
click node_meta_base "https://github.com/00danii/nebula/blob/main/metadata_styles/base_metadata_style.py"
click node_fonts "https://github.com/00danii/nebula/blob/main/utils/font_utils.py"
click node_utils_pkg "https://github.com/00danii/nebula/blob/main/utils/__init__.py"
click node_assets "https://github.com/00danii/nebula/tree/main/assets"
click node_build "https://github.com/00danii/nebula/blob/main/Nebula.spec"

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_main toneBlue
class node_ui_app,node_ui_canvas,node_ui_controls,node_ui_theme toneAmber
class node_engine,node_processor,node_grid,node_meta_render,node_data_gen toneMint
class node_style_mgr,node_style_base,node_creative_styles toneRose
class node_meta_mgr,node_meta_base,node_meta_styles toneIndigo
class node_fonts,node_utils_pkg,node_assets,node_build toneTeal
```

## Components

### Runtime

Application entrypoints and execution flow

- [Main](https://github.com/00danii/nebula/blob/main/main.py): entrypoint · Development entrypoint that starts the desktop app · `main.py`

### UI

Tkinter presentation layer and interaction boundary

- [App](https://github.com/00danii/nebula/blob/main/ui/app.py): tk window · Builds the main window and wires the application together · `ui/app.py`
- [Canvas](https://github.com/00danii/nebula/blob/main/ui/canvas.py): preview view · Renders the processed image preview and overlays · `ui/canvas.py`
- [Controls](https://github.com/00danii/nebula/blob/main/ui/controls.py): settings panel · Hosts sliders, pickers, and user-adjustable settings · `ui/controls.py`
- [Theme](https://github.com/00danii/nebula/blob/main/ui/theme.py): styling · Defines the dark look and UI styling tokens · `ui/theme.py`

### Core

Image orchestration, processing, and overlays

- [Engine](https://github.com/00danii/nebula/blob/main/core/engine.py): orchestrator · Coordinates UI events, state, processing, preview, and export · `core/engine.py`
- [Processor](https://github.com/00danii/nebula/blob/main/core/image_processor.py): image pipeline · Applies image transformations and compositing steps · `core/image_processor.py`
- [Grid](https://github.com/00danii/nebula/blob/main/core/grid_renderer.py): overlay renderer · Draws telescope-like grid, axes, ticks, and legends · `core/grid_renderer.py`
- [Metadata](https://github.com/00danii/nebula/blob/main/core/metadata_renderer.py): overlay renderer · Renders metadata annotations and plate-style overlays · `core/metadata_renderer.py`
- [Data gen](https://github.com/00danii/nebula/blob/main/core/data_generator.py): measurement source · Generates synthetic scientific values and labels for overlays · `core/data_generator.py`

### Creative styles

Image effect pipeline and style selection

- [Style mgr](https://github.com/00danii/nebula/blob/main/styles/style_manager.py): style registry · Selects and configures creative image styles · `styles/style_manager.py`
- [Style base](https://github.com/00danii/nebula/blob/main/styles/base_style.py): style contract · Shared interface for creative image effects · `styles/base_style.py`
- [Creative styles](https://github.com/00danii/nebula/blob/main/styles/creative_styles.py): effect set · Collection of concrete image effects such as sepia, CRT, thermal, and noir · `styles/creative_styles.py`

### Metadata styles

Scientific overlay templates and metadata rendering

- [Meta mgr](https://github.com/00danii/nebula/blob/main/metadata_styles/manager.py): style registry · Selects and configures metadata overlay styles · `metadata_styles/manager.py`
- [Meta base](https://github.com/00danii/nebula/blob/main/metadata_styles/base_metadata_style.py): overlay contract · Shared interface for metadata overlay styles · `metadata_styles/base_metadata_style.py`
- **Overlay styles**: style set · Concrete HUD, plate, minimal, and geometric metadata overlays

### Support

Shared utilities, assets, and packaging

- [Fonts](https://github.com/00danii/nebula/blob/main/utils/font_utils.py): font helper · Handles font loading and text rendering consistency · `utils/font_utils.py`
- [Paths](https://github.com/00danii/nebula/blob/main/utils/__init__.py): resource helper · Resolves resource paths for source runs and packaged executables · `utils/__init__.py`
- [Assets](https://github.com/00danii/nebula/tree/main/assets): resource bundle · Logo and example renders used by the app and documentation · `assets`
- [PyInstaller](https://github.com/00danii/nebula/blob/main/Nebula.spec): packaging · Executable packaging and Windows build artifacts · `Nebula.spec`

## Connections

- Main → App: starts · Launches the main application window
- App → Controls: hosts · Creates and wires the control panels
- App → Canvas: drives · Connects preview rendering to the main window
- App → Theme: applies · Uses shared UI styling
- Controls → Engine: events · Publishes user adjustments to the orchestrator
- Canvas → Engine: requests · Receives processed frames from engine state changes
- Engine → Processor: runs · Invokes the image transformation pipeline
- Engine → Grid: adds · Overlays grid and framing elements
- Engine → Metadata: adds · Composites metadata overlays onto the image
- Engine → Style mgr: selects · Chooses the active creative style
- Style mgr → Style base: implements · Uses the shared style contract
- Style mgr → Creative styles: loads · Instantiates concrete visual effects
- Engine → Meta mgr: selects · Chooses the active metadata style
- Meta mgr → Meta base: implements · Uses the shared metadata contract
- Meta mgr → Overlay styles: loads · Instantiates concrete overlay styles
- Metadata → Data gen: feeds · Consumes generated values for annotations and labels
- Processor → Fonts: uses · Depends on font handling for overlays and text
- App → Fonts: uses · Uses font utilities for interface text consistency
- Paths → Assets: resolves · Helps locate bundled resources and example media
- PyInstaller → Assets: packages · Bundles resources into the standalone executable
- PyInstaller → App: ships · Packages the desktop application entry path