beckhoff-xts-viewer-3d 4.4.0 → 4.6.0

package/README.md

@@ -70,9 +70,11 @@ reflections, ACES tone mapping and anisotropic textures are on by default.
   - [Read selection + errors](#4-read-selection--errors)
   - [Detect mover collisions](#5-detect-mover-collisions)
   - [Capture screenshots](#6-capture-screenshots)
-  - [Mark zones with Areas](#7-mark-zones-with-areas)
-  - [Stator heatmap](#8-stator-heatmap)
-  - [Track direction + zero offset](#9-track-direction--zero-offset)
+  - [Live 2D plan view (orthographic top-down)](#7-live-2d-plan-view-orthographic-top-down)
+  - [Fly the camera to an object (focusOn)](#8-fly-the-camera-to-an-object-focuson)
+  - [Mark zones with Areas](#9-mark-zones-with-areas)
+  - [Stator heatmap](#10-stator-heatmap)
+  - [Track direction + zero offset](#11-track-direction--zero-offset)
 - [Realism + performance](#realism--performance)
 - [Troubleshooting](#troubleshooting)
 - [Documentation](#documentation)
@@ -135,7 +137,14 @@ reflections, ACES tone mapping and anisotropic textures are on by default.
 - **Custom assets** — static, mover-bound, all-movers; opacity + scale
   per-instance, never leaks back into the source GLB.
 - **CAD ViewCube** — opt-in, snap to standard orthogonal views.
-- **Imperative ref API** — `zoomToFit` / `setCamera` / `getCamera` /
+- **Live 2D plan view** — `projection="orthographic"` flips the live canvas to
+  a flat top-down view, pixel-consistent with the `'top-down'` screenshot, with
+  no WebGL-context remount and rotation auto-locked.
+- **Animated focus** — `viewerRef.current.focusOn({ kind: 'station' | 'area' |
+  'mover' | 'module' | 'scene', ... })` flies the camera so the whole target
+  fits the frame, in both 3D and 2D.
+- **Imperative ref API** — `zoomToFit` / `frameTopDown` / `focusOn` /
+  `setCamera` / `getCamera` /
   `getMoverWorldTransform` / `getBoundingBox` / `exportModel` /
   `exportScreenshot` / `setMoverPosition(s)` (Record or
   `MoverPositionEntry[]` indexed by `MoverConfig.index`) / `getMoverPosition` /
@@ -371,7 +380,63 @@ viewer.current!.exportScreenshot({
 Renders go to an offscreen WebGLRenderTarget — the live canvas keeps
 running at full speed, no `preserveDrawingBuffer` perf cost.
 
-### 7. Mark zones with Areas
+### 7. Live 2D plan view (orthographic top-down)
+
+Set `projection="orthographic"` to switch the **live** canvas into a flat 2D
+plan view — straight down +Z, world +Y up — that is pixel-consistent with
+`exportScreenshot({ mode: 'top-down' })`. Switching at runtime does **not**
+recreate the WebGL context, so toggling between 3D and 2D is instant.
+
+```tsx
+const [is2D, setIs2D] = useState(false);
+
+<XtsViewer3D
+  config={config}
+  projection={is2D ? 'orthographic' : 'perspective'}
+  // shadows add nothing to a flat plan — drop them in 2D
+  display={is2D ? { ...display, shadows: false } : display}
+/>
+```
+
+In orthographic top-down, **rotation is auto-disabled** (a 2D plan has no
+meaningful orbit); pan and zoom stay on. Set `lock={{ rotate: false }}` to
+opt rotation back in. The frustum re-fits automatically on container resize
+and whenever the scene's bounding box changes. From the ref, `frameTopDown()`
+re-fits on demand and `zoomToFit()` adjusts the ortho frustum (instead of
+dollying) when the live camera is orthographic.
+
+### 8. Fly the camera to an object (focusOn)
+
+`viewerRef.current.focusOn(target, opts)` animates the camera so a **station,
+area, mover, module** — or the whole `scene` — fits the frame. In perspective
+the current view angle is preserved (the camera only dollies + re-centres); in
+orthographic top-down the frustum re-frames and the camera pans straight over
+the target. Works in both 2D and 3D.
+
+```tsx
+// Frame a station, 700 ms ease-in-out (defaults)
+viewerRef.current?.focusOn({ kind: 'station', stationId: 3 });
+
+// Frame a mover, faster
+viewerRef.current?.focusOn(
+  { kind: 'mover', ref: { processingUnitObjectId: 0, moverIndex: 2 } },
+  { durationMs: 500 },
+);
+
+// Frame an area / a module / the whole scene
+viewerRef.current?.focusOn({ kind: 'area', areaId: 1 });
+viewerRef.current?.focusOn({
+  kind: 'module',
+  ref: { processingUnitObjectId: 0, partObjectId: 10, moduleIndex: 4 },
+});
+viewerRef.current?.focusOn({ kind: 'scene' }, { durationMs: 0 }); // 0 = jump
+```
+
+`FocusOptions`: `durationMs` (default `700`, `0` jumps), `paddingFactor`
+(default `1.2` perspective / `1.1` ortho), `easing` (`'easeInOutCubic'` |
+`'linear'`). A new `focusOn` call supersedes any in-flight animation.
+
+### 9. Mark zones with Areas
 
 Areas are stop-position-free range overlays — like Stations, but with no
 markers. Use them for cleanroom / safety-area / manual-access
@@ -404,7 +469,7 @@ zones that don't drive any mover behaviour:
 />;
 ```
 
-### 8. Stator heatmap
+### 10. Stator heatmap
 
 Coloured tube along each part's centerline, vertex colours interpolated
 across consumer-supplied `(positionMm, value)` samples — perfect for
@@ -427,7 +492,7 @@ const heatmap: StatorHeatmap = {
 />;
 ```
 
-### 9. Track direction + zero offset
+### 11. Track direction + zero offset
 
 When the host machine uses a different sign convention or zero point
 than the GLB chain, set a `positionFrame` on the XPU. Movers, stations,