rayzee 8.8.1 → 9.0.0

package/README.md

@@ -22,9 +22,10 @@ A real-time WebGPU path tracing engine built on Three.js. Framework-agnostic —
   - [Configuring Assets (CDN URLs & cache namespace)](#configuring-assets-cdn-urls--cache-namespace)
   - [PathTracerApp](#pathtracerapp)
   - [engine.cameraManager](#enginecameramanager)
-  - [Camera Projection (360° Panorama)](#camera-projection-360-panorama)
+  - [Camera Projection (Orthographic, 360° Panorama)](#camera-projection-orthographic-360-panorama)
   - [engine.lightManager](#enginelightmanager)
   - [engine.animationManager](#engineanimationmanager)
+  - [engine.timeline](#enginetimeline)
   - [Materials](#materials)
   - [Colour Management](#colour-management)
   - [engine.environmentManager](#engineenvironmentmanager)
@@ -428,16 +429,19 @@ Key settings:
 | `maxSubsurfaceSteps` | `number` | 8 | Max random-walk steps for subsurface scattering (raised to 64 by `configureForMode('production')`) |
 | `enableAlphaShadows` | `boolean` | false | Alpha-tested shadow rays (enabled by `configureForMode('production')`) |
 | `enableDOF` | `boolean` | false | Enable depth of field |
-| `focusDistance` | `number` | 0.8 | DOF focus distance |
-| `aperture` | `number` | 5.6 | DOF aperture (f-stop) |
-| `focalLength` | `number` | 50 | DOF focal length (mm) |
+| `dofMode` | `string` | 'look' | `'look'`: the blur is set by `dofBlur`, the same at any scene scale; `'physical'`: a real lens set by `aperture`, `focalLength` and `unitsPerMetre`. The `physical` render profile defaults to `'physical'` |
+| `dofBlur` | `number` | 0.05 | Look mode: how far a distant background blurs, as a fraction of the image height |
+| `focusDistance` | `number` | 0.8 | DOF focus distance in scene units — depth along the view axis (the focal plane is flat) |
+| `aperture` | `number` | 5.6 | Physical mode: f-stop |
+| `focalLength` | `number` | 50 | Physical mode: focal length (mm) |
+| `unitsPerMetre` | `number` | 1 | Physical mode: scene units per real metre, for files whose units are not metres. It carries over between model loads — reset it when the new file's units differ |
 | `transparentBackground` | `boolean` | false | Transparent canvas background |
 | `interactionModeEnabled` | `boolean` | true | Render at lower resolution while the camera moves, keeping the full bounce budget ("Fast Navigation" in the app) |
 | `interactionRenderScale` | `number` | 0.5 | Per-axis render scale while the camera moves (0.5 = a quarter of the pixels); `1` turns the drop off. Ignored while OIDN is the live denoiser |
 | `renderMode` | `number` | 0 | Internal preview(0)/production(1) flag driving accumulation & ASVGF behavior — normally set via `configureForMode()`, not written directly |
 | `visMode` | `number` | 0 | Debug visualization mode (0 = off) |
 | `environmentMode` | `string` | 'hdri' | Sky mode: `'hdri'` \| `'procedural'` \| `'gradient'` \| `'color'` — not routed through `engine.settings`; use `engine.environmentManager.setMode()` instead |
-| `cameraProjection` | `string` | 'perspective' | `'perspective'` \| `'equirectangular'` — see [Camera Projection](#camera-projection-360-panorama) |
+| `cameraProjection` | `string` | 'perspective' | `'perspective'` \| `'orthographic'` \| `'equirectangular'` — see [Camera Projection](#camera-projection-orthographic-360-panorama) |
 | `panoramaLonRange` | `[number, number]` | `[-180, 180]` | Panorama longitude sweep, degrees, left→right |
 | `panoramaLatRange` | `[number, number]` | `[-90, 90]` | Panorama latitude sweep, degrees, bottom→top |
 | `panoramaLevelHorizon` | `boolean` | true | Yaw-only panorama basis, so orbit pitch/roll can't tilt the horizon |
@@ -467,21 +471,45 @@ To pause rendering for image-viewing UI, set `engine.pauseRendering = true` and
 Camera switching, auto-focus, DOF, and direct Three.js access.
 
 ```js
-engine.cameraManager.active                  // The active PerspectiveCamera
+engine.cameraManager.active                  // The active camera: a PerspectiveCamera that can turn orthographic
 engine.cameraManager.controls                // The OrbitControls instance
 engine.cameraManager.switchCamera(index)      // Switch between scene cameras
 engine.cameraManager.getNames()              // List available cameras
 engine.cameraManager.focusOn(center)         // Focus orbit camera on a world-space point
 engine.cameraManager.setAutoFocusMode(mode)  // 'auto' | 'manual'
 engine.cameraManager.setAFScreenPoint(x, y)  // Set normalized AF screen point (0-1)
+engine.cameraManager.setNavigationMode(mode) // 'orbit' | 'walk'
+engine.cameraManager.walkControls.speed      // Walk speed, scene units per second
+engine.cameraManager.orthoHeight             // Orthographic view height, scene units, wheel zoom included
+engine.cameraManager.setOrthoHeight(height)  // Set it
 ```
 
-### Camera Projection (360° Panorama)
+**Walk mode** is first-person navigation: drag to look, W A S D or the arrow keys to walk level, E and Q to
+rise and sink, Shift faster, Alt slower. A new model resets `speed` so the walk crosses it in about eight
+seconds. Keys are ignored while focus is in a text field, list or menu, and when a focused control has
+already used the key. The mode obeys `controls.enabled`, so anything that locks the orbit camera locks walking
+too. Switching back to `'orbit'` circles the surface at the centre of the view.
 
-Two camera models live behind the `cameraProjection` setting. Both branches are compiled into the same kernel, so switching writes a uniform and resets accumulation — it never recompiles WGSL.
+### Camera Projection (Orthographic, 360° Panorama)
+
+Three camera models live behind the `cameraProjection` setting. All are compiled into the same kernel, so switching writes a uniform and resets accumulation — it never recompiles WGSL.
+
+#### Orthographic
+
+```js
+engine.settings.set('cameraProjection', 'orthographic');
+engine.cameraManager.setOrthoHeight(12);   // the view's height in scene units
+engine.addEventListener(EngineEvents.ORTHO_HEIGHT_UPDATED, ({ height }) => {}); // the wheel changed it
+```
+
+Rays are parallel and start on the camera's image plane, so nothing behind the camera is seen and nothing shrinks with distance. Switching keeps what the view shows at the orbit target: turning orthographic sizes the view from the orbit distance and field of view, and turning back moves the camera to match. The wheel then zooms by changing the view's size rather than moving the camera. A new model is framed the same way.
+
+`engine.cameraManager.active` stays the same object — it switches its own projection and reports `isOrthographicCamera` — so picking, the transform gizmo and the overlays follow without anything being re-pointed. Imported orthographic cameras (glTF, and pbrt's `Camera "orthographic"`) switch the projection to orthographic at their own size, and a camera left orthographic comes back so; any other camera switches it back to perspective. Every denoiser, auto-focus and depth of field keep working. An environment at infinity is seen from a single direction, so the background is one colour.
+
+#### 360° Panorama
 
 ```js
-engine.settings.set('cameraProjection', 'equirectangular');  // 'perspective' (default) | 'equirectangular'
+engine.settings.set('cameraProjection', 'equirectangular');
 
 // Optional: crop the sweep. Degrees, [min, max].
 engine.settings.set('panoramaLonRange', [-90, 90]);   // VR180
@@ -496,9 +524,9 @@ Depth of field still works: the lens plane is built from each ray's own frame, n
 Two features are incompatible with a non-frustum camera and the engine switches them off for you when panorama is enabled:
 
 - **ASVGF** falls back to the `edgeaware` denoiser — ASVGF's motion vectors unproject through the projection matrix, which is meaningless when every pixel is its own direction.
-- **Auto-focus** switches to `'manual'` — it raycasts via `Raycaster.setFromCamera`, which only understands a frustum.
+- **Auto-focus** pauses and focus holds its last distance — it raycasts via `Raycaster.setFromCamera`, which only understands a frustum. It resumes when you leave the panorama.
 
-Read the outcome back rather than duplicating the rule (`engine.denoisingManager.denoiserStrategy`, `engine.cameraManager.autoFocusMode`). Neither is restored automatically when you switch back to `'perspective'`.
+Read the denoiser outcome back rather than duplicating the rule (`engine.denoisingManager.denoiserStrategy`); it is not restored automatically when you leave the panorama.
 
 ### engine.lightManager
 
@@ -529,6 +557,34 @@ engine.animationManager.setLoop(true)        // Enable/disable looping
 engine.animationManager.clips                // Get available animation clips
 ```
 
+### engine.timeline
+
+Authored animation: keyframed tracks on one time axis, in seconds. The camera's is the first track; the timeline is where lights and objects will join it. A model's own clips stay with `engine.animationManager`, and saved cameras (`engine.addCamera()`) stay cameras — a keyframe is not a camera.
+
+```js
+const camera = engine.timeline.camera          // the camera's track
+const key = camera.addKey()                    // key the current view, 2 s after the last key
+camera.addKey(5)                               // …or at a time
+camera.updateKey(key.id)                       // give a key the current view
+camera.setTime(key.id, 3.5)                    // retime it; keys stay in time order
+camera.remove(key.id)
+camera.keys                                    // [{ id, time, position, target, fov, orthoHeight }]
+
+engine.timeline.duration                       // seconds to the last key of any track
+engine.timeline.animates                       // a track has two keys or more
+engine.timeline.seek(2.5)                      // put the scene where the timeline has it at 2.5 s
+await engine.timeline.play()                   // run it in the viewport, controls locked
+engine.timeline.stop()                         // or stop early
+
+// Keys changed ({ track: 'camera' }) or playback started or stopped ({ track: undefined })
+engine.addEventListener(EngineEvents.TIMELINE_CHANGED, ({ track }) => {})
+
+// A video of the move through a still scene; pass clipIndex too to move the camera during a clip
+await new VideoRenderManager(engine).renderAnimation({ timeline: engine.timeline, fps: 30, onFrame });
+```
+
+Between keys the camera glides along a smooth curve through their positions while looking along another through their targets, so a subject every key looks at stays in frame. It leaves the first key and reaches the last at rest, runs straight through the keys between, and holds still outside them. FOV, or an orthographic view's height, blends too, in the projection in use. The curves are three.js keyframe tracks (`InterpolateSmooth`). With auto-focus on, focus is measured again on every video frame, and the view is put back when the render ends. A new model clears the keys, as it clears saved cameras.
+
 ### Materials
 
 Material property updates and texture transforms — accessed as direct methods on the engine.
@@ -941,7 +997,8 @@ engine.addEventListener(EngineEvents.RENDER_COMPLETE, (e) => {
 | `TRANSFORM_MODE_CHANGED` | Gizmo mode changed |
 | `SELECT_MODE_CHANGED` | Selection mode toggled |
 | `SETTING_CHANGED` | A render setting is modified |
-| `AUTO_FOCUS_UPDATED` | Auto-focus recalculated |
+| `AUTO_FOCUS_UPDATED` | Auto-focus recalculated — `worldDistance` in scene units, `distance` divided by the model's size |
+| `ORTHO_HEIGHT_UPDATED` | An orthographic view's height changed — `height` in scene units |
 | `AUTO_EXPOSURE_UPDATED` | Auto-exposure recalculated |
 | `AF_POINT_PLACED` | Focus point placed on screen |
 | `ANIMATION_STARTED` / `ANIMATION_PAUSED` / `ANIMATION_STOPPED` / `ANIMATION_FINISHED` | Animation lifecycle |
@@ -1024,6 +1081,8 @@ import {
   AnimationManager,
   TransformManager,
   VideoRenderManager,
+  TimelineManager,
+  CameraTrack,
   InteractionManager,
   RenderPipeline,
   RenderStage,

package/dist/{NeuralSuperRes-Dc6jRYke.js → NeuralSuperRes-CQLCLpcC.js}

@@ -21,6 +21,7 @@ var i = {
 	OBJECT_TRANSFORM_END: "engine:objectTransformEnd",
 	TRANSFORM_MODE_CHANGED: "engine:transformModeChanged",
 	AUTO_FOCUS_UPDATED: "engine:autoFocusUpdated",
+	ORTHO_HEIGHT_UPDATED: "engine:orthoHeightUpdated",
 	AUTO_EXPOSURE_UPDATED: "engine:autoExposureUpdated",
 	AF_POINT_PLACED: "engine:afPointPlaced",
 	SETTING_CHANGED: "engine:settingChanged",
@@ -28,6 +29,7 @@ var i = {
 	ANIMATION_PAUSED: "engine:animationPaused",
 	ANIMATION_STOPPED: "engine:animationStopped",
 	ANIMATION_FINISHED: "engine:animationFinished",
+	TIMELINE_CHANGED: "engine:timelineChanged",
 	VIDEO_RENDER_PROGRESS: "engine:videoRenderProgress",
 	VIDEO_RENDER_COMPLETE: "engine:videoRenderComplete",
 	DISPOSE: "engine:dispose",