# alvinphilips/rt_weekend architecture

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

- Interactive diagram: https://gitdiagram.com/alvinphilips/rt_weekend
- Repository: https://github.com/alvinphilips/rt_weekend

## Overview

##### Project Type and Purpose
- This is a standalone command-line ray tracer written in Rust, implementing the algorithms from “Ray Tracing in One Weekend.”
- It is not a web or distributed application; it focuses on offline image generation via computational geometry.

##### File Structure
- src/main.rs: entry point; drives scene setup, image loop, and file output.
- src/camera.rs: defines the Camera struct and ray‐generation logic.
- src/ray.rs: defines the Ray struct and basic ray operations.
- src/hittable.rs & src/hittable_list.rs: the Hittable trait (scene objects interface) and a container for multiple Hittables.
- src/sphere.rs: concrete sphere implementation of Hittable.
- src/material.rs: material models (Lambertian, Metal, Dielectric) and scatter functions.
- src/utils.rs: any remaining helpers (e.g., random sampling).
- test.ppm, test_1.ppm, test_2.ppm: sample outputs.

##### Core Architectural Components
a. Main Renderer Loop (main.rs)
- Sets image dimensions and samples per pixel.
- Instantiates Camera, HittableList (scene graph), and materials.
b. Camera
- Computes origin and direction for each primary ray.
c. Ray
- Carries origin & direction; passed recursively.
d. Scene Graph
- Hittable trait: interface for any renderable object.
- HittableList: aggregates multiple Hittables, dispatching ray intersections.
- Sphere: example implementation.
e. Materials
- Scatter interface: given ray hit, return attenuation and scattered ray.
- Governs global illumination via recursive ray tracing.
f. Utilities
- Random unit vectors, clamping, gamma correction.

##### Relationships & Data Flow
- main.rs → Camera: calls get_ray(u, v) → returns Ray.
- main.rs → HittableList.hit(ray): finds nearest object intersection.
- If hit:
→ Material.scatter(hit_record, incoming_ray) → (attenuation, new_ray).

##### Architectural Patterns
- Component-based scene graph via traits (Hittable).
- Recursive functional pipeline for ray scattering.
- Separation of concerns: geometry (Sphere, Hittable), optics (Material), camera, and output.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Modules and Components
    Main["Main Renderer\n(src/main.rs)"]:::orchestration
    Camera["Camera Module\n(src/camera.rs)"]:::implementation
    Vec3["Vec3 Utilities\n(src/vec3.rs)"]:::data
    Ray["Ray Struct\n(src/ray.rs)"]:::data
    Color["Color Utilities\n(src/color.rs)"]:::data
    Hittable["Hittable Trait\n(src/hittable.rs)"]:::interface
    HittableList["HittableList Container\n(src/hittable_list.rs)"]:::implementation
    Sphere["Sphere Geometry\n(src/sphere.rs)"]:::implementation
    Material["Material Models\n(src/material.rs)"]:::implementation
    Utils["Utilities & Random\n(src/utils.rs)"]:::implementation
    Output["PPM Output Files\n(test.ppm, test_1.ppm, test_2.ppm)"]:::implementation

    %% Data Flow
    Main -->|"get_ray(u,v)"| Camera
    Camera -->|"returns Ray"| Ray
    Main -->|"uses Vec3 ops"| Vec3
    Main -->|"uses Color formatting"| Color
    Main -->|"hit(ray)"| HittableList
    HittableList -->|"dispatch hit()"| Hittable
    HittableList -->|"contains"| Sphere
    Hittable -->|"implemented by"| Sphere
    Main -->|"scatter(hit,ray)"| Material
    Material -->|"recursion new_ray"| HittableList
    Material -->|"uses utils"| Utils
    Main -->|"write PPM"| Output

    %% Click Events
    click Main "https://github.com/alvinphilips/rt_weekend/blob/main/src/main.rs"
    click Camera "https://github.com/alvinphilips/rt_weekend/blob/main/src/camera.rs"
    click Vec3 "https://github.com/alvinphilips/rt_weekend/blob/main/src/vec3.rs"
    click Ray "https://github.com/alvinphilips/rt_weekend/blob/main/src/ray.rs"
    click Color "https://github.com/alvinphilips/rt_weekend/blob/main/src/color.rs"
    click Hittable "https://github.com/alvinphilips/rt_weekend/blob/main/src/hittable.rs"
    click HittableList "https://github.com/alvinphilips/rt_weekend/blob/main/src/hittable_list.rs"
    click Sphere "https://github.com/alvinphilips/rt_weekend/blob/main/src/sphere.rs"
    click Material "https://github.com/alvinphilips/rt_weekend/blob/main/src/material.rs"
    click Utils "https://github.com/alvinphilips/rt_weekend/blob/main/src/utils.rs"
    click Output "https://github.com/alvinphilips/rt_weekend/blob/main/test.ppm"

    %% Styles
    classDef orchestration fill:#D8BFD8,stroke:#000
    classDef data fill:#98FB98,stroke:#000
    classDef interface fill:#FFD700,stroke:#000
    classDef implementation fill:#ADD8E6,stroke:#000
```
