storysplat-viewer 2.9.17 → 2.9.18

package/README.md

@@ -24,6 +24,11 @@ A powerful npm package for embedding and interacting with 3D Gaussian Splatting
 - [Audio Emitters](#audio-emitters)
 - [HTML Meshes](#html-meshes)
 - [Voxel Collision](#voxel-collision)
+- [Mirror Planes](#mirror-planes)
+- [Measurements](#measurements)
+- [Post-Processing](#post-processing)
+- [Custom Menu Links](#custom-menu-links)
+- [Entity Animations](#entity-animations)
 - [React Integration](#react-integration)
 - [Native App Integration](#native-app-integration)
 - [Analytics & Tracking](#analytics--tracking)
@@ -1055,6 +1060,193 @@ The voxel collision system requires two co-located files:
 
 Both primitive collision meshes and voxel collision coexist — primitives are checked first, then the octree.
 
+## Mirror Planes
+
+Mirror planes add reflective surfaces to scenes, useful for replacing broken mirrors in Gaussian Splat scans with real-time reflections.
+
+### Scene Data
+
+```json
+{
+  "mirrors": [
+    {
+      "id": "mirror-1",
+      "position": { "x": 0, "y": 1.5, "z": -3 },
+      "rotation": { "x": 0, "y": 0, "z": 0 },
+      "scale": { "x": 2, "y": 2, "z": 1 },
+      "resolution": 0.5,
+      "intensity": 0.8,
+      "tint": "#ffffff"
+    }
+  ]
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `position` | `Vector3` | World position of the mirror |
+| `rotation` | `Vector3` | Euler rotation in radians |
+| `scale` | `Vector3` | Dimensions of the mirror plane |
+| `resolution` | `number` | Reflection quality (0.25–1.0, lower = better performance) |
+| `intensity` | `number` | Reflection strength (0 = invisible, 1 = full) |
+| `tint` | `string` | Hex color overlay applied to reflections |
+
+Up to 3 mirrors are supported per scene.
+
+## Measurements
+
+The measurement system allows viewers to measure real-world distances in 3D scenes using a calibrated scale.
+
+### Scene Data
+
+```json
+{
+  "measurement": {
+    "enabled": true,
+    "scaleRatio": 0.0254,
+    "unit": "meters",
+    "color": "#00ff00",
+    "measurements": [
+      {
+        "id": "m1",
+        "start": { "x": 0, "y": 0, "z": 0 },
+        "end": { "x": 1, "y": 0, "z": 0 },
+        "label": "Wall width"
+      }
+    ]
+  }
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether measurement mode is available |
+| `scaleRatio` | `number` | Scene units to real-world units multiplier |
+| `unit` | `string` | Display unit: `"meters"`, `"centimeters"`, `"feet"`, or `"inches"` |
+| `color` | `string` | Hex color for measurement visualization |
+| `measurements` | `array` | Pre-defined measurements with start/end points and labels |
+
+## Post-Processing
+
+Post-processing applies real-time color grading adjustments in the viewer.
+
+### Scene Data
+
+```json
+{
+  "postProcessing": {
+    "colorEnhance": {
+      "enabled": true,
+      "shadows": 0.5,
+      "highlights": -0.3,
+      "vibrance": 0.2,
+      "midtones": 0.1,
+      "dehaze": 0.15
+    }
+  }
+}
+```
+
+| Property | Type | Range | Description |
+|----------|------|-------|-------------|
+| `enabled` | `boolean` | — | Master toggle for color enhancement |
+| `shadows` | `number` | -3 to +3 | Brighten or darken dark areas |
+| `highlights` | `number` | -3 to +3 | Adjust bright areas |
+| `vibrance` | `number` | -1 to +1 | Increase or decrease color saturation |
+| `midtones` | `number` | -1 to +1 | Adjust mid-range tones |
+| `dehaze` | `number` | -1 to +1 | Remove or add atmospheric haze |
+
+## Custom Menu Links
+
+Add external links to the viewer's navigation menu alongside portals.
+
+### Scene Data
+
+```json
+{
+  "menuLinks": [
+    {
+      "id": "link-1",
+      "label": "Book Now",
+      "url": "https://example.com/book",
+      "icon": "calendar",
+      "menuPath": "Resources",
+      "openInNewTab": true
+    }
+  ]
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `label` | `string` | Display text for the link |
+| `url` | `string` | Target URL (http/https) |
+| `icon` | `string` | Icon type: `"link"`, `"map"`, `"calendar"`, `"phone"`, `"cart"`, `"globe"`, `"download"` |
+| `menuPath` | `string` | Folder path for menu organization (e.g., `"Resources/Help"`) |
+| `openInNewTab` | `boolean` | Whether to open in a new browser tab (default: `true`) |
+
+Menu links share the folder system with portals, so links and portals can be organized in the same folder hierarchy.
+
+## Entity Animations
+
+Keyframe-based animation system for any scene entity (hotspots, portals, lights, particles, meshes, mirrors).
+
+### Scene Data
+
+```json
+{
+  "entityAnimations": [
+    {
+      "entityId": "hotspot-1",
+      "entityType": "hotspot",
+      "timelineMode": "independent",
+      "duration": 3,
+      "playbackMode": "loop",
+      "autoplay": true,
+      "delay": 0,
+      "tracks": [
+        {
+          "property": "position.y",
+          "keyframes": [
+            { "time": 0, "value": 1, "easing": "ease-in-out" },
+            { "time": 1, "value": 2, "easing": "ease-in-out" },
+            { "time": 2, "value": 1, "easing": "linear" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Timeline Modes
+
+| Mode | Description |
+|------|-------------|
+| `independent` | Time-based playback with configurable duration, delay, and loop mode |
+| `scroll` | Animation driven by camera tour scroll progress (0–100%) |
+
+### Playback Modes (independent only)
+
+| Mode | Description |
+|------|-------------|
+| `once` | Play once and stop |
+| `loop` | Restart from beginning when complete |
+| `pingpong` | Reverse direction at each end |
+
+### Easing Functions
+
+`linear`, `ease-in`, `ease-out`, `ease-in-out`
+
+### Animatable Properties
+
+| Category | Properties |
+|----------|------------|
+| Position | `position.x`, `position.y`, `position.z` |
+| Rotation | `rotation.x`, `rotation.y`, `rotation.z` |
+| Scale | `scale.x`, `scale.y`, `scale.z` |
+| Particles | `rate`, `lifetime`, `speed`, `scale`, `gravity`, `opacity`, `rotationSpeed` |
+
 ## React Integration
 
 ```jsx