00danii/nebula

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.