C++ Ray Tracer – University Project

A ray tracing engine developed as part of a university Image Synthesis course. The engine renders 3D scenes with physically-based lighting, depth of field, and acceleration structures.

---

Project Structure

raytracer/
├── src/                      # Source code
│   ├── main.cpp              # Entry point and CLI handling
│   ├── options.h/cpp         # Command-line argument parsing
│   ├── config.h              # Global constants
│   ├── geometry.h            # Geometric primitives (Triangle, Sphere, Plane, AABB)
│   ├── bvh.h/cpp             # Bounding Volume Hierarchy
│   ├── scene.h/cpp           # Scene management and OBJ loading
│   ├── rendering.h/cpp       # Ray tracing and lighting
│   └── image_utils.h/cpp     # OpenCV post-processing
├── lib/gkit3/                # Graphics library (vectors, matrices, I/O)
├── data/                     # 3D models (.obj files)
├── docs/                     # Screenshots and documentation
├── .vscode/                  # VSCode configuration
├── CMakeLists.txt            # CMake configuration
├── Makefile                  # Build shortcuts
├── build.sh                  # Build script
└── README.md

---

Build & Run

Requirements

• CMake 3.16+
• C++20 compiler (GCC 10+, Clang 10+)
• OpenCV 4.x
• OpenMP

Ubuntu/Debian:

sudo apt install cmake g++ libopencv-dev libomp-dev

Commands

make              # Build the project (Release)
make debug        # Build the project (Debug)
make run          # Build and run with default settings
make run-fast     # Build and run quick preview (256x256, 64 samples)
make run-high     # Build and run high quality (1024x1024, 4096 samples)
make clean        # Remove build artifacts and generated images
make help         # Show available targets

Direct execution

./bin/raytracer               # Run with default settings
./bin/raytracer --help        # Show all options
./bin/raytracer --fast        # Quick preview (256x256, 64 samples)

---

Features

Rendering

• Monte Carlo ray tracing with configurable samples per pixel
• Phong illumination model (diffuse + specular)
• Soft shadows via shadow rays
• Single-bounce mirror reflections
• Night sky with moon light source

Camera

• Depth of field simulation via aperture sampling
• Configurable focal length and aperture size
• Pinhole mode available (--no-dof)

Acceleration

• Bounding Volume Hierarchy (BVH) for mesh intersection
• Parallel rendering with OpenMP

Post-Processing (OpenCV)

• Gaussian blur filter
• Bilateral filter for edge-preserving smoothing

Supported Geometry

• Triangles (OBJ mesh import)
• Spheres (mirror or diffuse)
• Infinite planes with checkerboard pattern

---

Usage Examples

# Quick preview
./bin/raytracer --fast

# High quality render (1024x1024, 4096 samples)
./bin/raytracer --high

# Custom resolution and samples
./bin/raytracer -r 1920x1080 -s 1024

# Sharp focus (disable depth of field)
./bin/raytracer --no-dof

# Disable all effects for raw geometry
./bin/raytracer --no-dof --no-mirrors --no-shadows --no-postprocess

# Render a different mesh
./bin/raytracer -m data/monkey_head.obj -o monkey_head_render

# Verbose output
./bin/raytracer --fast -v

CLI Options

Option	Description	Default
-w, --width	Image width	512
-H, --height	Image height	512
-r, --resolution	Width x Height (e.g., 1920x1080)	-
-s, --samples	Samples per pixel	2048
--focal	Focal length	200.0
--aperture	Aperture size (DoF intensity)	0.02
--no-dof	Disable depth of field	-
--no-mirrors	Disable reflections	-
--no-shadows	Disable shadows	-
--no-postprocess	Disable OpenCV filters	-
-m, --mesh	Path to OBJ file	data/bea_sekeleton_psx.obj
-o, --output	Output filename (without .png)	render
--fast	Preset: 256x256, 64 spp	-
--medium	Preset: 512x512, 512 spp	-
--high	Preset: 1024x1024, 4096 spp	-
-v, --verbose	Verbose output	-

---

Technical Details

• Language: C++20
• Build System: CMake
• Graphics Library: gKit3 (custom vectors, matrices, image I/O)
• Image Processing: OpenCV 4.x
• Parallelization: OpenMP

---

Author

Yanis Laassibi