path-tracing

name	path-tracing
description	Guidance for implementing path tracers and ray tracers to reconstruct or generate images. This skill applies when tasks involve writing C/C++ ray tracing code, reconstructing images from reference images, or building rendering systems with spheres, shadows, and procedural textures. Use for image reconstruction tasks requiring similarity matching.

Path Tracing and Ray Tracing Implementation

This skill provides guidance for implementing path tracers and ray tracers, particularly for image reconstruction tasks where a target image must be matched within a similarity threshold.

When to Use This Skill

• Implementing ray tracers or path tracers in C/C++
• Reconstructing images by reverse-engineering scene parameters
• Building rendering systems with geometric primitives (spheres, planes)
• Tasks requiring image similarity matching (L2 norm, cosine similarity)
• Rendering scenes with shadows, reflections, or procedural textures

Workflow: Baseline-First Development

Phase 1: Establish a Working Baseline

Before any optimization or parameter tuning, establish a complete working render:

1. Start with minimal samples - Use S=1 or S=2 to verify the pipeline produces complete output
2. Verify output file completeness - Check that the output file contains valid, complete image data before proceeding
3. Test in target environment early - If the task specifies a chroot jail, sandbox, or specific execution environment, test there immediately
4. Fix all compiler warnings first - Treat warnings as errors; typos like doubled instead of double d cause undefined behavior

Phase 2: Scene Analysis

When reconstructing from a reference image:

1. Read and parse image header - Extract dimensions, format, color depth
2. Sample key pixels systematically - Sample corners, center, and regions of interest
3. Identify scene elements - Count all objects (spheres, planes, lights) before implementing
4. Analyze gradients and patterns - Sample multiple points to derive mathematical relationships for sky gradients, floor patterns
5. Document derived parameters - Write down calculated values (camera FOV, sphere position/radius, light direction)

Phase 3: Incremental Implementation

1. One feature at a time - Add sphere, then floor, then shadows, then soft shadows
2. Validate each addition - Render and compare after each feature
3. Calculate render time before choosing sample count - For a 2400×1800 image at 50 samples, estimate: pixels × samples × rays_per_sample × time_per_ray
4. Never modify code while renders are running - This creates race conditions and confusion about which version produced which output

Phase 4: Validation

1. Use the exact similarity metric - If grading uses normalized L2 or cosine similarity, compute that metric, not RMS error or other proxies
2. Create a reusable validation script early - Avoid rewriting comparison code repeatedly
3. Verify output file before submission - Check file size, parse the image, confirm dimensions match expected

Common Scene Elements

Sky Gradients

Analyze by sampling multiple y-coordinates at a fixed x to derive the vertical gradient formula. Sample multiple x-coordinates at a fixed y to check for horizontal variation.

Checkered Floor

To match checker patterns:

• Sample points across the floor to determine checker scale
• Identify the checker color values precisely
• Verify pattern origin and orientation

Spheres

Derive sphere parameters by:

• Finding the visual center of the sphere in image coordinates
• Estimating radius from the sphere's apparent size
• Calculating reflection and shadow geometry to verify position

Shadows

• Hard shadows: Single ray to light source
• Soft shadows: Multiple samples with jittered light directions
• Verify shadow direction matches light position

Time Management

Calculate Expected Render Time First

render_time ≈ (width × height × samples × bounces) / rays_per_second

Typical ray tracer performance: 100K-1M rays/second depending on scene complexity.

For a 2400×1800 image:

• S=1: ~4M rays, seconds to complete
• S=10: ~40M rays, minutes to complete
• S=50: ~200M rays, could take 10+ minutes
• S=100: ~400M rays, may exceed time limits

Adjust Parameters for Time Budget

If the task has a time limit:

1. Calculate maximum feasible sample count
2. Start with that limit, not above
3. Consider rendering at lower resolution first for validation

Common Pitfalls to Avoid

Code Quality Issues

• Typos in type declarations - doubled vs double d causes undefined behavior
• Ignoring compiler warnings - Fix all warnings before running long processes
• Race conditions - Never edit code while a render is still running

Validation Mistakes

• Wrong similarity metric - Match the exact metric used for grading
• Incomplete output files - Always verify file completeness before considering done
• Downsampled validation - If final output must be full resolution, validate at full resolution

Time Management Mistakes

• Starting with high sample counts - Always start low (S=1) to verify correctness
• Not calculating expected render time - Lead to timeout and wasted iterations
• Iterating without completing - Better to have one complete low-quality render than many incomplete high-quality attempts

Analysis Mistakes

• Missing scene elements - Thoroughly identify all objects before implementing
• Arbitrary parameter guessing - Derive parameters mathematically from reference image samples
• Sign errors in gradients - Double-check gradient direction by sampling multiple points

Verification Checklist

Before considering the task complete:

• Code compiles without warnings
• Output file exists and is complete (correct size, valid format)
• Output dimensions match expected dimensions
• Similarity metric meets the required threshold
• Tested in the target execution environment
• All scene elements from reference are present in output