# Three.js Progressive Visualization Specification

## Core Challenge
Create **progressively sophisticated Three.js 3D visualizations** that demonstrate mastery of modern WebGL/WebGPU techniques through web-based learning. Each iteration fetches and learns from official Three.js resources, examples, and documentation to create increasingly advanced 3D experiences.

## Output Requirements

**File Naming**: `threejs_viz_[iteration_number].html`

**Content Structure**: Self-contained HTML file with Three.js visualization
```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Three.js - [Visualization Name]</title>
    <style>
        body {
            margin: 0;
            overflow: hidden;
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
        }
        canvas {
            display: block;
            width: 100vw;
            height: 100vh;
        }
        #info {
            position: absolute;
            top: 10px;
            left: 10px;
            color: white;
            background: rgba(0, 0, 0, 0.7);
            padding: 15px;
            border-radius: 8px;
            font-size: 14px;
            max-width: 400px;
            z-index: 100;
        }
        #info h2 {
            margin: 0 0 10px 0;
            font-size: 18px;
        }
        #info .web-source {
            margin-top: 10px;
            padding-top: 10px;
            border-top: 1px solid rgba(255,255,255,0.3);
            font-size: 12px;
            opacity: 0.8;
        }
    </style>
</head>
<body>
    <div id="info">
        <h2>[Visualization Title]</h2>
        <p><strong>Technique:</strong> [Main technique demonstrated]</p>
        <p><strong>Learning:</strong> [What was learned from web source]</p>
        <div class="web-source">
            <strong>Web Source:</strong><br>
            <a href="[URL]" target="_blank" style="color: #4fc3f7;">[URL]</a><br>
            <em>Applied: [Specific technique from source]</em>
        </div>
    </div>

    <script type="importmap">
    {
        "imports": {
            "three": "https://cdn.jsdelivr.net/npm/three@0.170.0/build/three.module.js",
            "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.170.0/examples/jsm/"
        }
    }
    </script>

    <script type="module">
        import * as THREE from 'three';
        // Import any needed addons
        // import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

        // Scene setup
        let camera, scene, renderer;
        let [objects, animations, etc];

        init();
        animate();

        function init() {
            // Camera setup
            camera = new THREE.PerspectiveCamera(
                75,
                window.innerWidth / window.innerHeight,
                0.1,
                1000
            );
            camera.position.z = 5;

            // Scene
            scene = new THREE.Scene();

            // Renderer (WebGL or WebGPU)
            renderer = new THREE.WebGLRenderer({ antialias: true });
            renderer.setPixelRatio(window.devicePixelRatio);
            renderer.setSize(window.innerWidth, window.innerHeight);
            document.body.appendChild(renderer.domElement);

            // Create visualization using learned technique
            createVisualization();

            // Handle resize
            window.addEventListener('resize', onWindowResize);
        }

        function createVisualization() {
            // Implementation of learned technique from web source
            // This is where the web learning is applied
        }

        function onWindowResize() {
            camera.aspect = window.innerWidth / window.innerHeight;
            camera.updateProjectionMatrix();
            renderer.setSize(window.innerWidth, window.innerHeight);
        }

        function animate() {
            requestAnimationFrame(animate);

            // Animation logic using learned techniques

            renderer.render(scene, camera);
        }
    </script>
</body>
</html>
```

## Progressive Learning Dimensions

### **Foundation Level (Iterations 1-5)**
Learn and apply basic Three.js concepts:
- **Scene Setup**: Camera, scene, renderer initialization
- **Basic Geometries**: BoxGeometry, SphereGeometry, PlaneGeometry
- **Materials**: MeshBasicMaterial, MeshStandardMaterial, MeshPhongMaterial
- **Lighting**: AmbientLight, DirectionalLight, PointLight
- **Basic Animation**: Rotation, position changes, simple movements

**Web Sources:** Official Three.js Getting Started, Basic Examples

### **Intermediate Level (Iterations 6-12)**
Build on fundamentals with more complex techniques:
- **Textures**: TextureLoader, UV mapping, normal maps
- **Controls**: OrbitControls, FlyControls, user interaction
- **Particle Systems**: Points, PointsMaterial, BufferGeometry
- **Groups & Hierarchies**: Object3D grouping, parent-child relationships
- **Advanced Geometry**: Custom geometries, geometry manipulation
- **Post-Processing**: Basic effects, bloom, blur

**Web Sources:** Three.js Examples, Intermediate Tutorials

### **Advanced Level (Iterations 13-18)**
Master complex 3D programming:
- **Custom Shaders**: ShaderMaterial, vertex & fragment shaders
- **GLSL Programming**: Uniforms, attributes, varyings
- **Advanced Lighting**: Shadow mapping, environment maps, IBL
- **Physics Integration**: Collision detection, realistic motion
- **Procedural Generation**: Noise functions, algorithmic geometry
- **Advanced Materials**: Custom materials, multi-pass rendering

**Web Sources:** Shader Examples, Advanced Three.js Techniques

### **Expert Level (Iterations 19+)**
Push boundaries with cutting-edge techniques:
- **WebGPU**: Modern GPU API, compute shaders
- **Ray Marching**: SDF rendering, volumetric effects
- **GPU Particles**: Millions of particles with compute shaders
- **Complex Shaders**: Water simulation, atmospheric scattering
- **Performance Optimization**: Instancing, LOD, frustum culling
- **Advanced Effects**: Ocean waves, realistic materials, weather systems

**Web Sources:** WebGPU Examples, Expert Shader Tutorials, Research Papers

## Inspiration from Ocean Examples

The provided ocean examples demonstrate several key techniques to learn:

**From webgl_shaders_ocean.html:**
- Water shader with normal maps
- Sky system with atmospheric scattering
- Environment mapping with PMREM
- Dynamic sun positioning
- Shader uniforms for real-time control
- GUI integration for parameter tweaking

**From webgpu_ocean.html:**
- WebGPU renderer setup
- Modern shader syntax
- WaterMesh and SkyMesh objects
- Inspector integration
- Advanced tone mapping

## Quality Standards

### **Technical Excellence**
- **Clean Code**: Well-structured, commented, readable
- **Modern APIs**: Use latest Three.js features and best practices
- **Performance**: 60fps minimum, optimized render loops
- **Responsive**: Works on different screen sizes
- **Browser Support**: Modern browsers with WebGL/WebGPU support

### **Web Learning Integration**
- **Source Attribution**: Clearly document the web source URL
- **Specific Application**: Identify exact technique learned and applied
- **Demonstrable Learning**: Code shows clear evidence of web-sourced knowledge
- **Progressive Building**: Later iterations reference earlier learnings
- **Unique Implementation**: Don't copy-paste; adapt and innovate

### **Visual Quality**
- **Aesthetic Appeal**: Beautiful, engaging visualizations
- **Smooth Animation**: No stuttering or jank
- **Proper Lighting**: Realistic or artistically intentional lighting
- **Color Harmony**: Thoughtful color palettes
- **Camera Work**: Interesting viewpoints and movement

### **Documentation**
- **Clear Info Panel**: Explains what the visualization demonstrates
- **Web Source Citation**: Links to source with specific technique noted
- **Learning Documentation**: What was learned and how it was applied
- **Inline Comments**: Code explains complex techniques

## Three.js-Specific Requirements

### **Import Strategy**
Use CDN-based imports for self-contained files:
```javascript
<script type="importmap">
{
    "imports": {
        "three": "https://cdn.jsdelivr.net/npm/three@0.170.0/build/three.module.js",
        "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.170.0/examples/jsm/"
    }
}
</script>
```

### **Common Addons to Explore**
- **Controls**: OrbitControls, TrackballControls, FlyControls
- **Loaders**: GLTFLoader, OBJLoader, TextureLoader
- **Post-Processing**: EffectComposer, RenderPass, UnrealBloomPass
- **Objects**: Water, Sky, Lensflare
- **Helpers**: AxesHelper, GridHelper, DirectionalLightHelper
- **Utils**: VertexNormalsHelper, BufferGeometryUtils

### **Shader Resources**
- GLSL syntax and built-in functions
- Vertex shader transformations
- Fragment shader effects
- Uniform passing and updating
- Texture sampling techniques

## Progressive Complexity Strategy

### **Iteration 1-5: Foundations**
- Single object with basic material and lighting
- Simple animations (rotation, scaling)
- Basic camera positioning
- One or two lights
- Solid colors or simple textures

### **Iteration 6-12: Expanding Skills**
- Multiple objects with different materials
- Particle systems
- User controls (OrbitControls)
- Advanced lighting setups
- Texture mapping and normal maps
- Simple post-processing

### **Iteration 13-18: Advanced Techniques**
- Custom shaders (vertex and fragment)
- Procedural geometry generation
- Complex animations and physics
- Multi-pass rendering
- Advanced materials (refraction, reflection)
- Dynamic environments

### **Iteration 19+: Expert Mastery**
- WebGPU implementations
- Compute shaders
- Advanced shader effects (water, fire, atmosphere)
- Massive scenes with optimization
- Cutting-edge techniques from research
- Complex simulations (fluids, physics)

## Web Research Integration

### **Research Process for Each Iteration**
1. **Fetch Assigned URL**: Use WebFetch to retrieve Three.js documentation or example
2. **Deep Analysis**: Study the code, identify key techniques
3. **Extract Learnings**: Note 1-3 specific techniques to apply
4. **Plan Application**: Design how to use the technique in visualization
5. **Implement**: Code the visualization using learned technique
6. **Document**: Clearly show what was learned and from where

### **Quality Web Sources**
- **Official Docs**: threejs.org/docs
- **Official Examples**: threejs.org/examples
- **Three.js Manual**: threejs.org/manual
- **GitHub Wiki**: github.com/mrdoob/three.js/wiki
- **Observable Notebooks**: observablehq.com/@mrdoob
- **Community Tutorials**: discoverthreejs.com, threejs-journey.com

### **Learning Evidence**
Each iteration must demonstrate:
- Clear understanding of the web source
- Proper implementation of learned technique
- Original application (not copy-paste)
- Comments explaining the technique
- Visual proof that it works

## Ultra-Thinking Directive

Before each Three.js visualization, deeply consider:

**Web Learning Strategy:**
- What specific Three.js technique does this URL teach?
- How can I extract the most valuable knowledge from this source?
- What code patterns or concepts are most important?
- How does this build on previous iterations' learnings?

**Technical Implementation:**
- What's the most effective way to apply this technique?
- How can I ensure smooth 60fps performance?
- What Three.js APIs are most appropriate?
- How should shaders or materials be structured?

**Visual Design:**
- What makes this visualization aesthetically compelling?
- How does lighting enhance the scene?
- What camera angle best showcases the technique?
- How can animation improve the experience?

**Progressive Building:**
- How does this iteration advance beyond previous ones?
- What new complexity is introduced?
- Can I combine techniques from earlier iterations?
- What's the next logical step in the learning path?

**Quality Assurance:**
- Does the code clearly demonstrate the learned technique?
- Is the web source properly attributed?
- Would someone learn from viewing this example?
- Is the implementation unique and creative?

## Success Criteria

A successful Three.js iteration:
- **Runs Perfectly**: No errors, smooth 60fps animation
- **Demonstrates Learning**: Clear application of web-sourced technique
- **Looks Beautiful**: Visually engaging and well-crafted
- **Is Self-Contained**: Single HTML file works standalone
- **Documents Sources**: Clear attribution and learning explanation
- **Shows Progression**: Builds on previous iterations appropriately
- **Teaches Others**: Code quality that others can learn from

Generate Three.js visualizations that showcase the power and beauty of modern 3D web graphics while demonstrating genuine progressive learning from web resources.
