Story 3.5: Cook-Torrance Scene Material Integration

assets/cook_torrance_showcase.scene

@@ -0,0 +1,123 @@
+# Cook-Torrance Material Showcase Scene
+# Educational demonstration of microfacet theory with multiple material configurations
+# Demonstrates roughness, metallic, and specular parameter effects
+
+scene_name: Cook-Torrance Material Showcase
+description: Comprehensive demonstration of Cook-Torrance microfacet BRDF
+
+# ================================================
+# LAMBERT MATERIALS FOR COMPARISON
+# ================================================
+# These provide educational reference points to contrast with Cook-Torrance behavior
+# Lambert materials exhibit perfectly diffuse reflection (viewing angle independent)
+
+material_lambert matte_white 0.9 0.9 0.9
+material_lambert matte_red 0.8 0.3 0.3
+material_lambert matte_blue 0.3 0.3 0.8
+
+# ================================================
+# COOK-TORRANCE MATERIALS: METALLIC PROGRESSION
+# ================================================
+# These demonstrate roughness effects in metallic (conductor) materials
+# All have metallic=1.0, varying roughness from mirror-like to diffuse
+
+# Gold materials with roughness progression (metallic conductors)
+material_cook_torrance gold_mirror 1.0 0.8 0.3 0.02 1.0 0.04
+material_cook_torrance gold_brushed 1.0 0.8 0.3 0.3 1.0 0.04  
+material_cook_torrance gold_rough 1.0 0.8 0.3 0.8 1.0 0.04
+
+# Silver materials with roughness progression (metallic conductors)
+material_cook_torrance silver_mirror 0.95 0.95 0.95 0.02 1.0 0.04
+material_cook_torrance silver_brushed 0.95 0.95 0.95 0.3 1.0 0.04
+material_cook_torrance silver_rough 0.95 0.95 0.95 0.8 1.0 0.04
+
+# ================================================
+# COOK-TORRANCE MATERIALS: DIELECTRIC MATERIALS
+# ================================================
+# These demonstrate Cook-Torrance behavior in non-metallic materials
+# All have metallic=0.0, representing plastics, ceramics, etc.
+
+# Green plastic with roughness progression (dielectric materials)
+material_cook_torrance plastic_green_smooth 0.2 0.8 0.4 0.1 0.0 0.04
+material_cook_torrance plastic_green_semi 0.2 0.8 0.4 0.5 0.0 0.04
+material_cook_torrance plastic_green_rough 0.2 0.8 0.4 0.9 0.0 0.04
+
+# Red plastic with different specular values (F0 demonstration)
+material_cook_torrance plastic_red_normal 0.8 0.2 0.2 0.3 0.0 0.04
+material_cook_torrance plastic_red_glossy 0.8 0.2 0.2 0.1 0.0 0.08
+
+# ================================================
+# SCENE LAYOUT: EDUCATIONAL GRID ARRANGEMENT
+# ================================================
+# Grid layout enables side-by-side visual comparison of material theory
+# Each row demonstrates specific material concepts
+
+# TOP ROW: Gold metallic progression (smooth → rough)
+# Educational focus: How roughness affects specular highlights in metals
+sphere -3.0 2.0 -6.0 0.7 gold_mirror       # Roughness: 0.02 (mirror-like)
+sphere -1.0 2.0 -6.0 0.7 gold_brushed      # Roughness: 0.3  (brushed metal)
+sphere 1.0 2.0 -6.0 0.7 gold_rough         # Roughness: 0.8  (rough metal)
+sphere 3.0 2.0 -6.0 0.7 matte_red         # Lambert reference
+
+# SECOND ROW: Silver metallic progression (smooth → rough)
+# Educational focus: How different metals exhibit similar microfacet behavior
+sphere -3.0 0.5 -6.0 0.7 silver_mirror     # Roughness: 0.02 (mirror-like)
+sphere -1.0 0.5 -6.0 0.7 silver_brushed    # Roughness: 0.3  (brushed metal)
+sphere 1.0 0.5 -6.0 0.7 silver_rough       # Roughness: 0.8  (rough metal)
+sphere 3.0 0.5 -6.0 0.7 matte_white       # Lambert reference
+
+# THIRD ROW: Dielectric plastics progression (smooth → rough)
+# Educational focus: How dielectrics differ from metals in BRDF behavior
+sphere -3.0 -1.0 -6.0 0.7 plastic_green_smooth   # Roughness: 0.1 (glossy plastic)
+sphere -1.0 -1.0 -6.0 0.7 plastic_green_semi     # Roughness: 0.5 (semi-matte)
+sphere 1.0 -1.0 -6.0 0.7 plastic_green_rough     # Roughness: 0.9 (matte plastic)
+sphere 3.0 -1.0 -6.0 0.7 matte_blue              # Lambert reference
+
+# BOTTOM ROW: Specular parameter comparison (F0 effects)
+# Educational focus: How F0 affects dielectric reflection strength
+sphere -2.0 -2.5 -6.0 0.7 plastic_red_normal     # Standard F0: 0.04
+sphere 0.0 -2.5 -6.0 0.7 plastic_red_glossy      # Higher F0: 0.08
+sphere 2.0 -2.5 -6.0 0.7 matte_white            # Lambert reference
+
+# ================================================
+# EDUCATIONAL NOTES AND LEARNING OBJECTIVES
+# ================================================
+# This scene demonstrates the following Cook-Torrance microfacet theory concepts:
+#
+# 1. ROUGHNESS EFFECTS:
+#    - Low roughness (0.02): Sharp, mirror-like reflections (concentrated highlights)
+#    - Medium roughness (0.3-0.5): Semi-glossy surfaces (moderate highlight spread)  
+#    - High roughness (0.8-0.9): Diffuse-like behavior (broad highlight spread)
+#
+# 2. METALLIC vs DIELECTRIC BEHAVIOR:
+#    - Metallic=1.0 (conductors): High reflectance, colored F0 from base_color
+#    - Metallic=0.0 (dielectrics): Low F0 reflectance, transmissive behavior
+#    - F0 determines reflection strength at normal viewing angles
+#
+# 3. FRESNEL EFFECT DEMONSTRATION:
+#    - All materials show increased reflection at grazing angles
+#    - Metals maintain colored reflection across angles
+#    - Dielectrics transition from transmissive to reflective
+#
+# 4. ENERGY CONSERVATION:
+#    - All parameters clamped to physically valid ranges
+#    - No light amplification (energy conservation maintained)
+#    - Realistic material behavior across parameter space
+#
+# 5. COMPARISON WITH LAMBERT MODEL:
+#    - Lambert: Constant BRDF, viewing angle independent
+#    - Cook-Torrance: Variable BRDF with viewing angle dependency
+#    - Educational contrast between empirical and physically-based models
+#
+# RECOMMENDED LEARNING EXERCISES:
+# - Render scene with different viewing angles to observe Fresnel effects
+# - Compare specular highlights between different roughness values
+# - Observe how metallic materials differ from dielectric materials
+# - Validate energy conservation by checking that no materials amplify light
+# - Test parameter boundaries (roughness limits, metallic interpolation)
+#
+# TECHNICAL IMPLEMENTATION NOTES:
+# - All materials use physically plausible parameter ranges
+# - Roughness limited to [0.01, 1.0] to prevent numerical instability
+# - F0 values appropriate for material types (0.04 typical for dielectrics)
+# - Scene layout optimized for educational comparison and visual learning

docs/architecture/scene-data-format-specifications.md

@@ -2,7 +2,163 @@
 
 ## Educational Scene File Format (.scene)
 
-The scene file format uses YAML for educational clarity and supports progressive complexity from Epic 2 through Epic 4.
+The scene file format uses simple text format for educational clarity and supports progressive complexity from Epic 2 through Epic 4.
 
-**Epic 2 Scene Format Example:**
-```yaml
+## Multi-Material Scene Format (Epic 3+)
+
+### Format Overview
+The extended scene format supports both Lambert and Cook-Torrance materials in the same scene file, enabling comprehensive educational demonstrations of different BRDF models.
+
+### Material Definitions
+
+#### Lambert Material Format
+```
+material_lambert <name> <red> <green> <blue>
+```
+
+**Parameters:**
+- `name`: Unique material identifier (string, no spaces)
+- `red`, `green`, `blue`: Albedo color components [0.0, 1.0]
+
+**Example:**
+```
+material_lambert diffuse_red 0.8 0.3 0.3
+material_lambert matte_white 0.9 0.9 0.9
+```
+
+#### Cook-Torrance Material Format
+```
+material_cook_torrance <name> <base_r> <base_g> <base_b> <roughness> <metallic> <specular>
+```
+
+**Parameters:**
+- `name`: Unique material identifier (string, no spaces)
+- `base_r`, `base_g`, `base_b`: Base color components [0.0, 1.0]
+- `roughness`: Surface roughness [0.01, 1.0] (0.01=mirror, 1.0=diffuse)
+- `metallic`: Metallic parameter [0.0, 1.0] (0.0=dielectric, 1.0=conductor)
+- `specular`: Dielectric F0 reflectance [0.0, 1.0] (typical: 0.04)
+
+**Example:**
+```
+material_cook_torrance gold_mirror 1.0 0.8 0.3 0.02 1.0 0.04
+material_cook_torrance plastic_rough 0.2 0.8 0.4 0.9 0.0 0.04
+```
+
+### Primitive Definitions
+
+#### Sphere Format
+```
+sphere <center_x> <center_y> <center_z> <radius> <material_name>
+```
+
+**Parameters:**
+- `center_x`, `center_y`, `center_z`: Sphere center coordinates
+- `radius`: Sphere radius (positive value)
+- `material_name`: Reference to previously defined material
+
+**Example:**
+```
+sphere 0.0 0.0 -5.0 1.0 diffuse_red
+sphere 2.0 0.0 -5.0 1.0 gold_mirror
+```
+
+## Complete Scene File Example
+
+### Cook-Torrance Material Showcase
+```
+# Cook-Torrance Material Showcase Scene
+# Educational demonstration of microfacet theory with multiple material configurations
+# Demonstrates roughness, metallic, and specular parameter effects
+
+# Lambert materials for comparison
+material_lambert matte_white 0.9 0.9 0.9
+material_lambert matte_red 0.8 0.3 0.3
+material_lambert matte_blue 0.3 0.3 0.8
+
+# Cook-Torrance materials demonstrating parameter ranges
+material_cook_torrance gold_mirror 1.0 0.8 0.3 0.02 1.0 0.04
+material_cook_torrance gold_brushed 1.0 0.8 0.3 0.3 1.0 0.04
+material_cook_torrance gold_rough 1.0 0.8 0.3 0.8 1.0 0.04
+material_cook_torrance plastic_smooth 0.2 0.8 0.4 0.1 0.0 0.04
+material_cook_torrance plastic_rough 0.2 0.8 0.4 0.9 0.0 0.04
+
+# Scene layout: 3x3 grid demonstrating material progression
+# Top row: Metal progression (smooth to rough)
+sphere -2.0 1.0 -5.0 0.8 gold_mirror
+sphere 0.0 1.0 -5.0 0.8 gold_brushed  
+sphere 2.0 1.0 -5.0 0.8 gold_rough
+
+# Middle row: Dielectric Cook-Torrance materials
+sphere -1.0 0.0 -5.0 0.8 plastic_smooth
+sphere 1.0 0.0 -5.0 0.8 plastic_rough
+
+# Bottom row: Lambert reference materials for comparison
+sphere -1.0 -1.0 -5.0 0.8 matte_red
+sphere 0.0 -1.0 -5.0 0.8 matte_white
+sphere 1.0 -1.0 -5.0 0.8 matte_blue
+
+# Educational Notes:
+# - Gold spheres show roughness progression in metallic materials
+# - Plastic spheres demonstrate dielectric Cook-Torrance behavior  
+# - Lambert spheres provide educational reference for comparison
+# - Scene layout enables side-by-side visual comparison of material theory
+```
+
+## Backward Compatibility
+
+### Legacy Lambert-Only Format (Epic 2)
+The original format continues to work for backward compatibility:
+```
+material red_sphere 0.8 0.3 0.3
+sphere 0.0 0.0 -5.0 1.0 red_sphere
+```
+
+**Compatibility Rules:**
+1. Lines starting with `material ` (single space) are interpreted as Lambert materials
+2. Lines starting with `material_lambert ` are explicit Lambert materials  
+3. Lines starting with `material_cook_torrance ` are Cook-Torrance materials
+4. Mixed format files are supported - both legacy and new syntax in same file
+
+### Error Handling
+
+**Invalid Material References:**
+- Sphere referencing undefined material → Error with helpful message
+- Material name conflicts → Later definition overrides earlier one with warning
+
+**Invalid Parameters:**
+- Parameter out of range → Automatic clamping with educational console output
+- Insufficient parameters → Error with expected format example
+- Invalid number format → Error with line number and expected type
+
+**Educational Error Messages:**
+```
+Error: Sphere at line 15 references undefined material 'unknown_material'
+Available materials: matte_white, gold_mirror, plastic_rough
+
+Warning: Roughness 1.5 at line 8 exceeds valid range [0.01, 1.0], clamped to 1.0
+Educational note: Roughness > 1.0 would represent unphysical surface behavior
+
+Error: Expected 7 parameters for Cook-Torrance material at line 12, got 5
+Format: material_cook_torrance <name> <r> <g> <b> <roughness> <metallic> <specular>
+Example: material_cook_torrance gold 1.0 0.8 0.3 0.1 1.0 0.04
+```
+
+## Implementation Guidelines
+
+### Parser Requirements
+1. **Line-based parsing**: Each material/primitive definition on separate line
+2. **Comment support**: Lines starting with `#` are ignored
+3. **Whitespace tolerance**: Multiple spaces/tabs between parameters allowed
+4. **Case sensitivity**: Material names and keywords are case-sensitive
+5. **UTF-8 encoding**: Support for educational comments in multiple languages
+
+### Memory Management
+1. **Polymorphic storage**: `std::vector<std::unique_ptr<Material>>` for materials
+2. **Reference validation**: Ensure all material references resolve before geometry creation
+3. **Resource cleanup**: Automatic memory management through smart pointers
+
+### Educational Integration
+1. **Parsing feedback**: Console output showing materials loaded and validated
+2. **Parameter clamping**: Educational explanations when values are adjusted
+3. **Material statistics**: Summary of material types and parameter ranges loaded
+4. **Cross-reference validation**: Report which materials are used/unused