# hmaddocks/raytracing architecture

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

- Interactive diagram: https://gitdiagram.com/hmaddocks/raytracing
- Repository: https://github.com/hmaddocks/raytracing

## Overview

##### Project Type and Purpose
- This is a single-binary, command-line ray tracer implemented in Rust, based on the “Ray Tracing in One Weekend” tutorial.

##### File Structure Analysis
- Top‐level files:
- Cargo.toml / Cargo.lock: Rust crate manifest and lockfile.
- README.md: Project description.
- image_*.ppm: Sample output files.
- src directory: all source modules; no subdirectories, so it’s a monolith with clear module separation:
- main.rs: entry point – sets up camera, scene, loops over pixels, invokes ray tracing.
- ray.rs: Ray struct and ray operations.
- hittable.rs (trait), hittable_list.rs: defines objects that can be hit by rays and a container for them.
- sphere.rs: concrete hittable implementation.
- material.rs: surface‐interaction logic (Lambertian, metal, dielectric).
- camera.rs: virtual camera model, ray generation for each pixel.
- utilities.rs: random helpers, sampling, PPM writer.

##### Key Architectural Insights from README
- No external dependencies beyond standard Rust crates.
- Linear, batch‐processing pipeline: setup → trace → shade → write PPM.

a. Main Components
1. CLI/Main Orchestrator (main.rs)
3. Ray Module (ray.rs)
4. Geometry Abstractions
– Hittable trait
– HittableList container
– Primitive (Sphere)
– AABB / Interval helper
5. Material System (material.rs)
6. Camera (camera.rs)
7. Utilities (utilities.rs: random sampling, PPM writer)
8. Output (PPM image file)
b. Relationships & Data Flow
- Main invokes Camera to generate primary rays per pixel.
- Rays feed into the HittableList, which iterates primitives and uses AABB tests to find nearest hit.
- Hit record passed to Material to compute scattered ray & attenuation.
c. Architectural Patterns
- Trait‐based polymorphism: Hittable trait decouples geometry from ray logic.
- Module separation: clear responsibilities (math, geometry, materials, I/O).
- Single-threaded pipeline (can be extended to parallel loops).
d. Technologies & Frameworks
- Rust standard library
- No external crates (all custom code)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main orchestrator
    Main["CLI / Main Orchestrator\n(main.rs)"]:::orchestrator
    click Main "https://github.com/hmaddocks/raytracing/blob/main/src/main.rs"

    %% Math core
    subgraph "Math Core" 
        Vec3["vec3"]:::core
        click Vec3 "https://github.com/hmaddocks/raytracing/blob/main/src/vec3.rs"
        Point3["point3"]:::core
        click Point3 "https://github.com/hmaddocks/raytracing/blob/main/src/point3.rs"
        ColorUtil["color"]:::core
        click ColorUtil "https://github.com/hmaddocks/raytracing/blob/main/src/color.rs"
    end

    %% Ray module
    RayModule["Ray Module\n(ray.rs)"]:::core
    click RayModule "https://github.com/hmaddocks/raytracing/blob/main/src/ray.rs"

    %% Camera
    Camera["Camera Module\n(camera.rs)"]:::camera
    click Camera "https://github.com/hmaddocks/raytracing/blob/main/src/camera.rs"

    %% Geometry
    subgraph "Geometry Abstractions"
        Hittable["Hittable Trait"]:::interface
        click Hittable "https://github.com/hmaddocks/raytracing/blob/main/src/hittable.rs"
        HittableList["HittableList Container"]:::geometry
        click HittableList "https://github.com/hmaddocks/raytracing/blob/main/src/hittable_list.rs"
        Sphere["Sphere Primitive"]:::geometry
        click Sphere "https://github.com/hmaddocks/raytracing/blob/main/src/sphere.rs"
        AABB["AABB"]:::geometry
        click AABB "https://github.com/hmaddocks/raytracing/blob/main/src/aabb.rs"
        Interval["Interval"]:::geometry
        click Interval "https://github.com/hmaddocks/raytracing/blob/main/src/interval.rs"
    end

    %% Material system
    Material["Material System\n(material.rs)"]:::material
    click Material "https://github.com/hmaddocks/raytracing/blob/main/src/material.rs"

    %% Utilities
    Utilities["Utilities\n(random & PPM writer)"]:::util
    click Utilities "https://github.com/hmaddocks/raytracing/blob/main/src/utilities.rs"

    %% Output
    Output["PPM Output\n(image_*.ppm)"]:::output
    click Output "https://github.com/hmaddocks/raytracing/blob/main/image_*.ppm"

    %% Data flow
    Main -->|"setup scene\n& config"| Camera
    Camera -->|"generate_rays\n(Ray)"| RayModule
    RayModule -->|"trace(Ray)"| HittableList
    HittableList -->|"iterate primitives"| Sphere
    Sphere -->|"hit? returns HitRecord"| HittableList
    HittableList -->|"use AABB/Interval"| AABB
    HittableList -->|"use AABB/Interval"| Interval
    HittableList -->|"closest hit\nHitRecord"| Material
    Material -->|"scatter(Ray)\n& attenuation"| RayModule
    RayModule -->|"accumulate radiance"| ColorUtil
    ColorUtil -->|"convert to RGB"| Utilities
    Utilities -->|"write PPM"| Output

    %% Styles
    classDef orchestrator fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#ccf,stroke:#333,stroke-width:1px
    classDef camera fill:#afa,stroke:#333,stroke-width:1px
    classDef geometry fill:#cfc,stroke:#333,stroke-width:1px
    classDef material fill:#fcc,stroke:#333,stroke-width:1px
    classDef util fill:#ffc,stroke:#333,stroke-width:1px
    classDef output fill:#fcf,stroke:#333,stroke-width:1px
    classDef interface stroke-dasharray: 5 5,fill:#fff,stroke:#333,stroke-width:1px
```
