# k-dx/raytracer architecture

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

- Interactive diagram: https://gitdiagram.com/k-dx/raytracer
- Repository: https://github.com/k-dx/raytracer

## Overview

##### Project Type and Purpose
- This is a full-fledged raytracing engine that reads scene files (typically in XML) and produces rendered images.
- It was developed as part of a computer graphics course, so it both illustrates fundamentals (vector/matrix math, scene parsing, multi-threading) and supports advanced features like denoising (with OpenImageDenoise) and multi-threading (via CTPL).
- There is a Blender exporter module integrated, allowing for scene creation in Blender to be exported into a format understood by the renderer.

##### Main Components Identified from the File Structure
- Core Rendering Engine (located in src/):
– Core modules such as scene construction, parsing (XML and PLY file readers), main rendering loop, camera models, integrators (like pathtracer, direct, AOV), and postprocessing.
- Components/Plugins Subsystems:
- Supporting Libraries and Utilities:
– A collection of math utilities, logging, profiling, transformation functions, and multi-threading helpers.
– External dependencies (e.g., deps/catch2 for testing, deps/ctpl for threading, deps/miniz, deps/stb, deps/tinyexr, and deps/tinyformat) which provide functionality without requiring custom implementation.
- Blender Exporter:
– Found under the blender_exporter directory, this is a specialized module that exports Blender scene elements into the lightwave format.
– The importer tool has its own build scripts and Python modules (as seen by .py files under blender_exporter/lightwave_blender/).
- Testing Infrastructure:
– Multiple test directories (tests/, unittests/, run_tests.py) indicate thorough test coverage across image comparisons, mesh loading, and scene parsing.
- Documentation and Feature Demos:
– Example scenes (example_scene.xml) and feature-specific folders (features/) illustrate testing with real-world cases (denoising, area lights, thinlens effects, etc).

##### Relationships and Interactions
- Scene Input and Parsing:
- Core Rendering Pipeline:
– The core module (src/core/) takes the scene graph and feeds it into the integrators (found in src/integrators/), which use various sampling strategies (from src/samplers/) to trace rays.
- Output and Post-Processing:
– Rendered images are output via file I/O functions into image formats (handled by the core modules and possibly postprocess/denoise.cpp) and can be streamed live to the tev viewer.
- Modular Plug-in Architecture:
- Blender Exporter’s Role:
– Separately, the blender_exporter scripts facilitate the creation of scene files from Blender that are then compatible with the renderer.
- Testing and Validation:
– A series of tests in tests/ and unittests/ ensure the correctness of various components. They simulate end-to-end scenarios such as reading a mesh, rendering with different lighting conditions, or comparing images.

##### Architectural Patterns and Design Principles
- Modularity:
– Clear separation among rendering components, scene parsing, and image output.
– A plugin-based design allows for easy swapping or addition of different algorithms.
- Layered Architecture:
– Lower layers provide utilities (math, logging, multi-threading) that support higher-level rendering processes.
- Separation of Concerns:
– Input (scene file parsing), processing (integrators, core rendering loop), and output (image writing, streaming to tev) are distinct.
- Use of External Dependencies:
– The system leverages multiple third-party libraries (as seen in the deps/ directory) ensuring not to reinvent wheels such as image processing and threading.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Blender Exporter Module"]:::exporter
    B["Scene Input & Parser"]:::inputParser
    C["Core Rendering Engine"]:::core
    E["Output & Post-processing"]:::output
    F["External Dependencies"]:::external
    G["Testing Framework"]:::test

    subgraph "Modular Plugins"
        D1["Cameras Plugin"]:::plugin
        D2["BSDFs Plugin"]:::plugin
        D3["Lights Plugin"]:::plugin
        D4["Shapes Plugin"]:::plugin
        D5["Emissions Plugin"]:::plugin
        D6["Textures Plugin"]:::plugin
        D7["Samplers Plugin"]:::plugin
    end

    A -->|"exports"| B
    B -->|"builds_scene_graph"| C
    C -->|"uses"| D1
    C -->|"uses"| D2
    C -->|"uses"| D3
    C -->|"uses"| D4
    C -->|"uses"| D5
    C -->|"uses"| D6
    C -->|"uses"| D7
    C -->|"renders_output"| E
    F -->|"supports"| C
    F -->|"supports"| D1
    F -->|"supports"| D2
    F -->|"supports"| D3
    F -->|"supports"| D4
    F -->|"supports"| D5
    F -->|"supports"| D6
    F -->|"supports"| D7
    G -->|"validates"| C
    G -->|"validates"| E

    click A "https://github.com/k-dx/raytracer/tree/main/blender_exporter/"
    click B "https://github.com/k-dx/raytracer/blob/main/src/core/parser.cpp"
    click C "https://github.com/k-dx/raytracer/blob/main/src/core/core.cpp"
    click D1 "https://github.com/k-dx/raytracer/tree/main/src/cameras/"
    click D2 "https://github.com/k-dx/raytracer/tree/main/src/bsdfs/"
    click D3 "https://github.com/k-dx/raytracer/tree/main/src/lights/"
    click D4 "https://github.com/k-dx/raytracer/tree/main/src/shapes/"
    click D5 "https://github.com/k-dx/raytracer/tree/main/src/emissions/"
    click D6 "https://github.com/k-dx/raytracer/tree/main/src/textures/"
    click D7 "https://github.com/k-dx/raytracer/tree/main/src/samplers/"
    click E "https://github.com/k-dx/raytracer/blob/main/src/core/image.cpp"
    click F "https://github.com/k-dx/raytracer/tree/main/deps/"
    click G "https://github.com/k-dx/raytracer/tree/main/tests/"

    classDef inputParser fill:#ffeb99,stroke:#d4a017,stroke-width:2px
    classDef core fill:#b0c4de,stroke:#4682b4,stroke-width:2px
    classDef plugin fill:#90ee90,stroke:#32cd32,stroke-width:2px
    classDef output fill:#ffa07a,stroke:#ff4500,stroke-width:2px
    classDef exporter fill:#ffb6c1,stroke:#ff69b4,stroke-width:2px
    classDef external fill:#dda0dd,stroke:#8a2be2,stroke-width:2px
    classDef test fill:#f08080,stroke:#dc143c,stroke-width:2px
```
