# mattiamtzlr/ray-tracing architecture

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

- Interactive diagram: https://gitdiagram.com/mattiamtzlr/ray-tracing
- Repository: https://github.com/mattiamtzlr/ray-tracing

## Overview

##### Main Subsystems/Components
- Camera & Viewing Components: Include the Camera class, which defines the viewing parameters (position, look-at point), and is responsible for generating rays for the scene.
- Materials & Textures: Identify the Material and Texture classes that encapsulate the surface properties and how light interacts with objects.
- Mathematical Foundations: Classes like Vec3, Point3, and Perlin show that the project relies on its own vector mathematics and noise generation utilities.
- Auxiliary Utilities: Elements such as Utility.java provide support functions. They’re essential even if not the core focus.
- (Optional) Python Side: Although the Java version is the primary, note that there is a Python version available with a similar set of modules (e.g., ray.py, sphere.py, etc.) that might be mentioned as a legacy or educational comparison.

##### Relationships and Interactions
- That Main communicates with the Camera to generate the rays and sets up the Scene.
- That when a ray is cast, it passes through modules that check intersections with these Hittable objects.

##### Architectural Patterns/Design Principles
- Use “composition” to show how complex scenes are built (Scene composed of HittableList objects, which in turn may use acceleration structures).
- Strategy-like implementations where different materials or rotation classes (RotateX, RotateZ) are swapped in to achieve different effects.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Ray Tracing Engine Core
    subgraph "Ray Tracing Engine Core"
        MAIN["Main"]
        RAY["Ray"]
        COLOR["Color"]
        UTIL["Utility"]
    end

    %% Geometry & Scene Representation
    subgraph "Geometry & Scene Representation"
        HITTABLE["Hittable"]
        HITTABLELIST["HittableList"]
        SPHERE["Sphere"]
        MOVINGSPHERE["MovingSphere"]
        BOX["Box"]
        CONSTANTMEDIUM["ConstantMedium"]
        AARECT["AARect"]
        SCENES["Scenes"]
    end

    %% Camera & Viewing Components
    subgraph "Camera & Viewing Components"
        CAM["Camera"]
    end

    %% Materials & Textures
    subgraph "Materials & Textures"
        MATERIAL["Material"]
        TEXTURE["Texture"]
    end

    %% Acceleration Structures
    subgraph "Acceleration Structures"
        BVHNODE["BVHNode"]
        AABB["AABB"]
    end

    %% Mathematical Foundations
    subgraph "Mathematical Foundations"
        VEC3["Vec3"]
        POINT3["Point3"]
        PERLIN["Perlin"]
    end

    %% Auxiliary Utilities
    subgraph "Auxiliary Utilities"
        HITRECORD["HitRecord"]
    end

    %% Legacy Python Version (Experimental)
    subgraph "Legacy Python Version"
        PY_MAIN["main.py"]
        PY_RAY["ray.py"]
        PY_SPHERE["sphere.py"]
        PY_CAM["camera.py"]
        PY_HITTABLE["hittable.py"]
        PY_HITTABLELIST["hittableList.py"]
        PY_COLOR["color.py"]
        PY_VEC3["vec3.py"]
        PY_UTIL["utility.py"]
    end

    %% Main rendering flow
    MAIN -->|"initializes"| CAM
    MAIN -->|"sets up scene"| SCENES
    CAM -->|"generates rays"| RAY
    SCENES -->|"builds scene"| HITTABLELIST
    HITTABLELIST -->|"composed of"| HITTABLE
    HITTABLELIST -->|"contains"| SPHERE
    HITTABLELIST -->|"contains"| MOVINGSPHERE
    HITTABLELIST -->|"contains"| BOX
    HITTABLELIST -->|"contains"| CONSTANTMEDIUM
    HITTABLELIST -->|"contains"| AARECT
    %% Acceleration structure integrates with scene geometry
    HITTABLELIST -->|"optimized by"| BVHNODE
    BVHNODE -->|"uses bounds"| AABB
    %% Materials applied to geometry
    SPHERE -->|"has"| MATERIAL
    BOX -->|"has"| MATERIAL
    CONSTANTMEDIUM -->|"has"| MATERIAL
    %% Textures influence material appearance
    MATERIAL -->|"may use"| TEXTURE
    %% Mathematical utilities support almost every module
    RAY --> VEC3
    CAM --> VEC3
    SPHERE --> VEC3
    PERLIN --> VEC3
    POINT3 --> VEC3
    %% Auxiliary hit record for intersections
    HITTABLE --> HITRECORD
    %% Legacy Python version has similar structure
    PY_MAIN -->|"entry point"| PY_CAM
    PY_MAIN -->|"entry point"| PY_RAY
    PY_CAM --> PY_VEC3
    PY_RAY --> PY_VEC3
    PY_HITTABLELIST --> PY_HITTABLE
    PY_HITTABLE -->|"contains"| PY_SPHERE
    PY_HITTABLE --> PY_COLOR

    %% Click Events for Ray Tracing Engine Core
    click MAIN "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Main.java"
    click RAY "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Ray.java"
    click COLOR "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Color.java"
    click UTIL "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Utility.java"

    %% Click Events for Geometry & Scene Representation
    click HITTABLE "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Hittable.java"
    click HITTABLELIST "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/HittableList.java"
    click SPHERE "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Sphere.java"
    click MOVINGSPHERE "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/MovingSphere.java"
    click BOX "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Box.java"
    click CONSTANTMEDIUM "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/ConstantMedium.java"
    click AARECT "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/AARect.java"
    click SCENES "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Scenes.java"

    %% Click Events for Camera & Viewing Components
    click CAM "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Camera.java"

    %% Click Events for Materials & Textures
    click MATERIAL "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Material.java"
    click TEXTURE "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Texture.java"

    %% Click Events for Acceleration Structures
    click BVHNODE "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/BVHNode.java"
    click AABB "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/AABB.java"

    %% Click Events for Mathematical Foundations
    click VEC3 "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Vec3.java"
    click POINT3 "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Point3.java"
    click PERLIN "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/Perlin.java"

    %% Click Events for Auxiliary Utilities
    click HITRECORD "https://github.com/mattiamtzlr/ray-tracing/blob/master/Java/Ray Tracing/src/com/raytracing/HitRecord.java"

    %% Click Events for Legacy Python Version
    click PY_MAIN "https://github.com/mattiamtzlr/ray-tracing/blob/master/Python/main.py"
    click PY_RAY "https://github.com/mattiamtzlr/ray-tracing/blob/master/Python/ray.py"
    click PY_SPHERE "https://github.com/mattiamtzlr/ray-tracing/blob/master/Python/sphere.py"
    click PY_CAM "https://github.com/mattiamtzlr/ray-tracing/blob/master/Python/camera.py"
    click PY_HITTABLE "https://github.com/mattiamtzlr/ray-tracing/blob/master/Python/hittable.py"
    click PY_HITTABLELIST "https://github.com/mattiamtzlr/ray-tracing/blob/master/Python/hittableList.py"
    click PY_COLOR "https://github.com/mattiamtzlr/ray-tracing/blob/master/Python/color.py"
    click PY_VEC3 "https://github.com/mattiamtzlr/ray-tracing/blob/master/Python/vec3.py"
    click PY_UTIL "https://github.com/mattiamtzlr/ray-tracing/blob/master/Python/utility.py"

    %% Styles
    classDef core fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef geometry fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef camera fill:#ccccff,stroke:#0000cc,stroke-width:2px;
    classDef material fill:#fff2cc,stroke:#e69900,stroke-width:2px;
    classDef accel fill:#e6e6ff,stroke:#6600cc,stroke-width:2px;
    classDef math fill:#ffe6ff,stroke:#cc0099,stroke-width:2px;
    classDef aux fill:#f2ffe6,stroke:#99cc00,stroke-width:2px;
    classDef legacy fill:#e6ffff,stroke:#009999,stroke-width:2px;

    %% Assign classes
    class MAIN,RAY,COLOR,UTIL core;
    class HITTABLE,HITTABLELIST,SPHERE,MOVINGSPHERE,BOX,CONSTANTMEDIUM,AARECT,SCENES geometry;
    class CAM camera;
    class MATERIAL,TEXTURE material;
    class BVHNODE,AABB accel;
    class VEC3,POINT3,PERLIN math;
    class HITRECORD aux;
    class PY_MAIN,PY_RAY,PY_SPHERE,PY_CAM,PY_HITTABLE,PY_HITTABLELIST,PY_COLOR,PY_VEC3,PY_UTIL legacy;
```
