3D Experiments & Animation

Problem Statement

The Programmatic 3D Rendering Gap

Creating 3D animated videos traditionally requires either a 3D artist wielding Blender or Maya, or complex game engine programming. For data visualizations, product demos, and scientific simulations, neither extreme is ideal — the artist pipeline is labor-intensive and hard to version-control, while game engines are overkill for linear narrative content.

The sweet spot is programmatic 3D: write code, get animation. Three.js brings WebGL rendering to the browser with a rich scene graph; Theatre.js adds a professional animation timeline with keyframes, sequencing, and easing curves; HyperFrames bridges the gap between real-time rendering and offline video output by capturing individual frames and assembling them into a playable file.

The exploration question: can a Three.js scene be driven entirely by a Theatre.js timeline and rendered losslessly to video through HyperFrames? The answer scales from a solar-system tour to a forest-census data visualization — two radically different scenes sharing the same pipeline architecture.

Approach & Architecture

Three.js → Theatre.js → HyperFrames → Video

The pipeline is a linear frame-processing chain. Three.js constructs the 3D scene graph — meshes, lights, cameras, and materials for solar-system bodies or forest-census point clouds. Theatre.js drives every animated property through a declarative timeline: keyframes on position, rotation, scale, and material uniforms with configurable easing. HyperFrames captures each frame from the WebGL canvas at a target resolution and framerate, then assembles the sequence into an MP4 video file. GSAP supplements Theatre.js for simpler timeline orchestration where full keyframe editing is unnecessary.

const scene = new THREE.Scene();
 const camera = new THREE.PerspectiveCamera(45, 1920/1080, 0.1, 1000);
 const sphere = new THREE.Mesh(
   new THREE.SphereGeometry(1, 32, 32),
   new THREE.MeshStandardMaterial({ color: 0xfbbf24 })
 );
 scene.add(sphere);
 
 const timeline = new Theatre.Timeline("solar-system");
 timeline.add(sphere.position, { x: 0, y: 0, z: -10 }); // keyframe 0
 timeline.add(sphere.position, { x: 5, y: 0, z: -10 }); // keyframe 1
 timeline.play();

Linear pipeline: Three.js scene graph → Theatre.js keyframe timeline → HyperFrames frame capture → MP4 video output. Animated elements show planet orbit motion, timeline playhead advancing, and frames being captured sequentially.

Component Interaction Diagram

Three.js ↔ Theatre.js ↔ HyperFrames Renderer

Sequence Diagram

Frame Render → Capture → Assemble

Technology Stack

3D, Animation & Rendering

3D Engine

Three.js (WebGL) Scene Graph Camera System PBR Materials

Animation System

Theatre.js Keyframe Timeline Easing Curves Sequencing

Rendering Pipeline

HyperFrames Frame Capture Video Assembly Lossless Output

Supplementary

GSAP Timeline Control WebGL Canvas

Architecture Decisions

Key Design Records

ADR-001

Three.js over Unity

Lighter weight, browser-native, Theatre.js has first-class Three.js support. Unity would require a standalone build target, a heavier runtime, and a fundamentally different development loop. Three.js runs in the same browser context as Theatre.js and HyperFrames, enabling instant iteration without compile steps. The WebGL renderer is sufficient for the visual complexity of solar-system tours and forest-census point clouds.

ADR-002

HyperFrames over Puppeteer Screenshot

Purpose-built for high-fidelity frame capture at target resolutions. Puppeteer's page.screenshot is designed for single captures and PDF generation — not sequencing thousands of frames into a coherent video. HyperFrames handles frame pacing, resolution consistency, and video assembly automatically. Its programmatic scene assembly API also enables dynamic scene composition per frame, which Puppeteer would require manual orchestration to achieve.

ADR-003

GSAP over native requestAnimationFrame — battle-tested timeline control, cross-browser consistency, easing functions built-in

Battle-tested, cross-browser, rich easing library. Native requestAnimationFrame requires manual delta-time tracking, custom easing implementations, and per-animation state management. GSAP provides a declarative timeline API with built-in easing curves (Power, Elastic, Back, Bounce), automatic cross-browser normalization of transform origins and property prefixes, and a scrubbable timeline that simplifies debugging complex multi-object animations. For Theatre.js supplemental animation work where full keyframe editing is unnecessary, GSAP reduces animation code by ~70% compared to raw rAF loops. The library is 28KB gzipped — acceptable for a development-focused pipeline where the output is video, not page load performance.

Session Timeline

Development Journey

Session 1

Solar System Animation via HyperFrames

870 messages · Core pipeline

Building and rendering a Three.js solar system to video — sun with emissive glow, orbiting planets with orbital paths, camera flythrough driven by Theatre.js timeline, and frame capture via HyperFrames. Proved the core pipeline works end-to-end.

Session 2

Forest Census 3D Scene

169 messages · Integration

Integrating HyperFrames + Theatre.js with the threejs-forest-census visualization. Tree canopies rendered as Three.js point clouds, with Theatre.js driving camera orbit and canopy opacity animations. GSAP timeline testing for supplementary controls.

Session 3

Explore threejs-forest-census Codebase

13 messages · Discovery

Deep-dive into the threejs-forest-census repository — understanding the data format (tree positions, canopy radii, species classification), the Three.js geometry generation pipeline, and how to retrofit Theatre.js timelines onto existing animation loops.

Session 4

Explore Theatre.js Repo

8 messages · Research

Evaluating Theatre.js internals — how the studio panel serializes timelines, the Three.js extension object API, and the sequence-to-video export pathway. Identified the @theatrejs/studio and @theatrejs/r3f packages as key integration points.

Outcome & Impact

Results & Industry Alignment

5

Sessions Completed

6

Key Decisions

1,067

Messages

Working pipeline: Three.js → Theatre.js → HyperFrames → video — proven across two distinct scene types (solar system, forest census)
Industry alignment: Runway ML / Gen-3 AI-assisted 3D — programmatic 3D animation shares the same goal of reducing manual artist labour through procedural generation and timeline-driven output
Industry alignment: Theatre.js programmatic animation mirrors the direction of real-time animation tools like Rive and Lottie — declarative timelines driving native rendering engines
Solar system tour and forest census visualization both rendered to video through the same pipeline architecture