npm - @heliguy-xyz/splat-viewer - Versions diffs - 1.0.0-rc.26 → 1.0.0-rc.28 - Mend

@heliguy-xyz/splat-viewer 1.0.0-rc.26 → 1.0.0-rc.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/README.md CHANGED Viewed

@@ -1,382 +1,98 @@
-# Heliguy Web Viewer
+# @heliguy-xyz/splat-viewer
-A self-contained 3D Gaussian Splat viewer web component built with PlayCanvas for high-performance
-rendering of point cloud data. Framework-agnostic and embeddable in any web application with zero
-external dependencies.
+A standalone 3D Gaussian Splat viewer web component with multi-model support, transform system, fly camera, and scene configuration. Framework-agnostic and works with vanilla JavaScript, React, Vue, Angular, and any other framework.
-## Features
-- 🎯 **Gaussian Splat Rendering**: Native support for `.splat` files using PlayCanvas
-- 📊 **PLY Support**: Traditional point cloud rendering for `.ply` and `.ply.compressed` formats
-- 📦 **SOG Support**: Native support for `.sog` (Spatially Ordered Gaussians) files
-- 🎮 **Interactive Controls**: Smooth camera navigation and manipulation
-- 🧭 **Navigation Cube**: Interactive 3D cube for quick camera orientation control
-- 📈 **Performance Monitoring**: Real-time rendering statistics
-- ⚡ **High Performance**: WebGL2-powered rendering with PlayCanvas engine
-- 📱 **Responsive Design**: Full-screen immersive viewing experience
-- 🔧 **Self-Contained**: Single file with bundled PlayCanvas engine (2MB)
-- 🎨 **Built-in Loading**: Professional loading spinner with orange/black theme
-- 🚀 **Zero Dependencies**: No external scripts required
-### Enhanced Features (v1.0.0)
-- 🎭 **Multi-Model Support**: Load and manage multiple models in the same scene
-- 🔄 **Transform System**: Programmatically position, rotate, and scale models
-- 🎥 **Fly Camera Mode**: First-person WASD + mouse-look navigation with configurable controls
-- 🎨 **Scene Configuration**: Adjust FOV and background color with smooth animations
-- 👁️ **Preview Mode**: Disable camera controls for product previews with programmatic rotation
-- 📡 **Comprehensive Events**: React to model lifecycle, transforms, camera changes, and more
-- 📘 **TypeScript Support**: Full type definitions for all APIs
-## Quick Start
-### Installation
-#### Via npm (Recommended)
+## Installation
 ```bash
-npm install @heliguy/web-viewer
+npm install @heliguy-xyz/splat-viewer
 ```
-#### Via CDN
-```html
-<!-- UMD Bundle -->
-<script src="https://unpkg.com/@heliguy/web-viewer@1.0.0/dist/web-component/splat-viewer.min.js"></script>
-<!-- ESM Bundle -->
-<script type="module">
-  import '@heliguy/web-viewer/esm'
-</script>
-```
-### Prerequisites
-- Modern browser with WebGL2 support
-- Node.js ≥18.0.0 (for development only)
-### Usage
+## Quick Start
-#### Vanilla HTML
+### Vanilla JavaScript / HTML
 ```html
 <!DOCTYPE html>
 <html>
-  <head>
-    <title>3D Splat Viewer</title>
-  </head>
-  <body>
-    <splat-viewer
-      id="viewer"
-      width="100%"
-      height="600px"
-      auto-focus
-      enable-navigation-cube
-    ></splat-viewer>
-    <!-- Import from npm package -->
-    <script src="node_modules/@heliguy/web-viewer/dist/web-component/splat-viewer.min.js"></script>
-    <script>
-      const viewer = document.getElementById('viewer')
-      viewer.addEventListener('ready', () => {
-        viewer.load('path/to/model.splat')
-      })
-    </script>
-  </body>
+<head>
+  <script type="module" src="node_modules/@heliguy-xyz/splat-viewer/dist/splat-viewer.esm.js"></script>
+</head>
+<body>
+  <splat-viewer
+    src="path/to/model.splat"
+    width="800"
+    height="600"
+    auto-focus
+  ></splat-viewer>
+</body>
 </html>
 ```
-#### Embed via iframe
-Use the provided `viewer.html` page that reads query parameters and configures the web component.
-Host `viewer.html` alongside `dist/web-component/splat-viewer.min.js`.
-Supported query params:
-- `src` (required): URL to your model (encode it!)
-- `width` (optional): CSS width (e.g. `100%`, `800px`)
-- `height` (optional): CSS height (e.g. `100vh`, `600px`)
-- `autoFocus` (optional): `true` | `false` (default: `true`)
-- `stats` (optional): `true` | `false`
-Example:
-```html
-<iframe
-  src="https://your-domain.com/viewer.html?src=https%3A%2F%2Fcdn.yourdomain.com%2Fmodels%2FRyhope.ply&width=100%25&height=100vh&autoFocus=true"
-  width="100%"
-  height="600"
-  style="border:0; background:#000"
-  allowfullscreen
-></iframe>
-```
-Notes:
-- Ensure CORS allows the viewer origin to fetch the model (`Access-Control-Allow-Origin`).
-- Prefer hosting `viewer.html`, the bundle, and models on the same domain to avoid CORS.
-- URL-encode the `src` value.
-#### React / Next.js
+### React
 ```tsx
-import { useEffect, useRef } from 'react'
-import '@heliguy/web-viewer'
+import '@heliguy-xyz/splat-viewer';
+import { useRef, useEffect } from 'react';
 function App() {
-  const viewerRef = useRef<any>(null)
+  const viewerRef = useRef(null);
   useEffect(() => {
-    const viewer = viewerRef.current
-    if (!viewer) return
+    const viewer = viewerRef.current;
+    if (!viewer) return;
-    const handleReady = () => {
-      viewer.load('/models/scene.splat')
-    }
-    viewer.addEventListener('ready', handleReady)
-    return () => viewer.removeEventListener('ready', handleReady)
-  }, [])
+    viewer.addEventListener('loaded', (e) => {
+      console.log('Model loaded:', e.detail);
+    });
+  }, []);
   return (
     <splat-viewer
       ref={viewerRef}
+      src="/model.splat"
       width="100%"
       height="600px"
       auto-focus
     />
-  )
-}
-```
-**TypeScript:** Add to your `global.d.ts`:
-```typescript
-declare namespace JSX {
-  interface IntrinsicElements {
-    'splat-viewer': React.DetailedHTMLProps<
-      React.HTMLAttributes<HTMLElement> & {
-        ref?: React.Ref<any>
-        src?: string
-        width?: string
-        height?: string
-        'auto-focus'?: boolean
-        'enable-stats'?: boolean
-        'preview-mode'?: boolean
-      },
-      HTMLElement
-    >
-  }
+  );
 }
 ```
-#### Vue 3
-```vue
-<template>
-  <splat-viewer
-    ref="viewerRef"
-    width="100%"
-    height="600px"
-    auto-focus
-  />
-</template>
-<script setup>
-import { ref, onMounted } from 'vue'
-import '@heliguy/web-viewer'
-const viewerRef = ref(null)
-onMounted(() => {
-  const viewer = viewerRef.value
-  const handleReady = () => {
-    viewer.load('/models/scene.splat')
-  }
-  viewer.addEventListener('ready', handleReady)
-})
-</script>
-```
-## Commands
-| Command                       | Description                        |
-| ----------------------------- | ---------------------------------- |
-| `npm run web-component:serve` | Start development server           |
-| `npm run web-component:build` | Build self-contained web component |
-| `npm run web-component:clean` | Clean build artifacts              |
-| `npm run lint`                | Check code quality with ESLint     |
-| `npm run lint:fix`            | Fix linting issues automatically   |
-| `npm run format`              | Format code with Prettier          |
-| `npm run format:check`        | Check code formatting              |
-## Web Component API
-### Attributes
-#### Basic Configuration
-- `src` - Model file path or URL
-- `width` - Canvas width (default: "100%")
-- `height` - Canvas height (default: "400px")
-- `auto-focus` - Auto-focus on load (default: true)
-- `enable-stats` - Show performance stats (default: false)
-- `max-splats` - Maximum splat count (default: 2000000)
-- `preview-mode` - Disable camera controls for preview use (default: false)
-#### Camera Controls
-- `orbit-sensitivity` - Mouse orbit sensitivity (default: 0.3)
-- `pan-sensitivity` - Mouse pan sensitivity (default: 0.5)
-- `zoom-sensitivity` - Mouse zoom sensitivity (default: 0.1)
-- `min-distance` - Minimum camera distance (default: 1)
-- `max-distance` - Maximum camera distance (default: 100)
-#### Navigation Cube
-- `enable-navigation-cube` - Show interactive navigation cube (default: false)
-- `navigation-cube-size` - Cube size in pixels (default: 120)
-- `navigation-cube-transition` - Camera transition duration in ms (default: 800)
-### Preview Mode
-Preview mode disables all camera controls (mouse/touch interactions) while maintaining programmatic rotation capabilities. This is ideal for:
-- Product configurators with UI-controlled rotation
-- Model previews with custom control interfaces
-- Embedded viewers where you want to control all interactions
-**Usage:**
-```html
-<splat-viewer src="model.splat" preview-mode></splat-viewer>
-```
-**Features in Preview Mode:**
-- ✅ Camera controls are completely disabled
-- ✅ Model is automatically centered and framed on load
-- ✅ Programmatic rotation via `setModelRotation()` API still works
-- ✅ All other APIs remain functional (visibility, transforms, etc.)
-**Example with Rotation Controls:**
-```javascript
-const viewer = document.getElementById('viewer');
-viewer.addEventListener('loaded', () => {
-  const models = viewer.getModels();
-  const modelId = models[0].id;
-  // Programmatically set rotation
-  viewer.setModelRotation(modelId, { x: 0, y: 45, z: 0 });
-});
-```
-See `examples/preview-mode.html` for a complete working example.
-### Events
-#### Core Events
-- `ready` - Component initialized
-- `loading-start` - Model loading started
-- `loading-progress` - Model loading progress update
-- `loaded` - Model loaded successfully
-- `error` - Loading error occurred
-- `stats-update` - Performance statistics update
-- `camera-change` - Camera position/target changed
-- `interaction-start` / `interaction-end` - User interaction with orbit controls
-#### Multi-Model Events (v1.0.0)
-- `model-added` - Model added to scene
-- `model-removed` - Model removed from scene
-- `scene-cleared` - All models cleared
-#### Transform Events (v1.0.0)
-- `model-transform-changed` - Model transform updated
-#### Camera Events (v1.0.0)
-- `camera-mode-changed` - Camera mode switched (orbit/fly)
-- `fly-camera-move` - Fly camera position changed
-- `fly-camera-look` - Fly camera rotation changed
-#### Scene Config Events (v1.0.0)
-- `camera-fov-changed` - Camera FOV changed
-- `background-color-changed` - Background color changed
-## Project Structure
-```
-src/
-├── web-component/        # Main web component implementation
-│   ├── SplatViewerElement.ts    # Web component class
-│   ├── SplatViewerCore.ts       # Core rendering engine
-│   ├── NavigationCubeController.ts  # Navigation cube controller
-│   ├── OrbitCameraScript.ts     # Camera controls
-│   ├── navigation-cube/     # Navigation cube modules
-│   │   ├── CubeRenderer.ts           # 3D cube visual rendering
-│   │   ├── ControlPointManager.ts    # Control point UI elements
-│   │   └── CameraTransitionController.ts  # Camera animations
-│   ├── types/           # TypeScript definitions
-│   ├── loader/          # File loading system (.ply, .sog, .splat)
-│   └── utils/           # Utility functions
-├── build/               # Build configuration
-├── dist/web-component/  # Built self-contained web component
-│   └── splat-viewer.min.js  # Single 2MB file with PlayCanvas
-├── test-web-component.html  # Basic test page
-└── test-navigation-cube.html  # Navigation cube test page
-assets/                  # 3D model assets for testing
-docs/                    # Documentation
-```
-## Supported File Formats
-- **.sog** - Spatially Ordered Gaussians (PlayCanvas native support)
-- **.splat** - Gaussian Splat files (PlayCanvas native support)
-- **.ply** - Point cloud files (standard format)
-- **.ply.compressed** - Compressed PLY files (gzip/deflate)
-## Self-Contained Bundle
-The web component is distributed as a single 2MB file (`splat-viewer.min.js`) that includes:
+## Features
-- Complete PlayCanvas engine (v2.11.8)
-- Web component implementation
-- File format loaders
-- Performance monitoring
-- Interactive controls
+- 🎨 **Multi-Model Support** - Load and manage multiple models in one scene
+- 🎥 **Dual Camera Modes** - Orbit and fly camera controls
+- 🔧 **Transform System** - Position, rotate, and scale models programmatically
+- 📦 **Multiple Formats** - Support for PLY, SPLAT, and SOG files
+- ⚡ **High Performance** - Optimized rendering with PlayCanvas
+- 🎯 **Selection Tools** - Box and sphere selection for splats
+- 🎨 **Scene Configuration** - Background, grid, FOV, and more
+- 📱 **Responsive** - Works on desktop, tablet, and mobile
-**Benefits:**
+## API
-- Zero external dependencies
-- Version consistency guaranteed
-- Easy embedding in any web application
-- Offline functionality
+See the full [API documentation](https://github.com/Heliguy-com/3d-web-viewer/tree/main/packages/core/docs) for detailed information.
 ## Development
+This package is part of the `@heliguy-xyz/splat-viewer` monorepo.
 ```bash
-# Start development server
-npm run web-component:serve
+# Build
+npm run build
-# Build for production
-npm run web-component:build
+# Development server
+npm run dev
-# Clean build artifacts
-npm run web-component:clean
+# Type check
+npm run type-check
 ```
-## Deployment
-### Netlify
-- Publish directory: `dist`
-- Build command: `npm run build`
-- Node version: 18 (configured in `netlify.toml`)
+## License
-The build emits `dist/index.html` from `viewer.html` using a small zero-dependency Node script
-(`build/copy-viewer-to-index.mjs`). Rollup uses an ESM config at `build/rollup.config.mjs`.
+MIT © Heliguy
-## License
+## Related Packages
-MIT License - see LICENSE file for details.
+- [@heliguy-xyz/splat-viewer-react-ui](https://www.npmjs.com/package/@heliguy-xyz/splat-viewer-react-ui) - Full-featured React UI component

package/dist/web-component/splat-viewer.esm.js CHANGED Viewed

@@ -139557,11 +139557,15 @@ function parseJsonSafely(jsonString) {
 }
 /**
  * Convert a string to a boolean value
+ * For HTML boolean attributes, an empty string means the attribute is present (true)
  */
 function parseBoolean(value) {
     if (typeof value === 'boolean')
         return value;
     if (typeof value === 'string') {
+        // Empty string means attribute is present without value (should be true for boolean attributes)
+        if (value === '')
+            return true;
         return value.toLowerCase() === 'true' || value === '1';
     }
     return false;
@@ -140452,6 +140456,10 @@ function registerOrbitCameraScript() {
         this.isPanning = false;
         // Allow host to temporarily disable camera input (e.g., while dragging gizmos)
         this._inputEnabled = true;
+        // Granular control over specific input types
+        this._orbitEnabled = true;
+        this._panEnabled = true;
+        this._zoomEnabled = true;
         // Setup context menu prevention
         this.setupContextMenuPrevention();
         // Use PlayCanvas mouse events for reliable input handling
@@ -140489,6 +140497,19 @@ function registerOrbitCameraScript() {
             this.isPanning = false;
         }
     };
+    OrbitCamera.prototype.setInputControls = function (options) {
+        if (options.orbit !== undefined)
+            this._orbitEnabled = !!options.orbit;
+        if (options.pan !== undefined)
+            this._panEnabled = !!options.pan;
+        if (options.zoom !== undefined)
+            this._zoomEnabled = !!options.zoom;
+        // Clear any in-progress interactions if being disabled
+        if (this._orbitEnabled === false)
+            this.isOrbiting = false;
+        if (this._panEnabled === false)
+            this.isPanning = false;
+    };
     OrbitCamera.prototype.update = function (dt) {
         // Update navigation cube if enabled
         if (this.navigationCube &&
@@ -140505,12 +140526,13 @@ function registerOrbitCameraScript() {
             typeof this.navigationCube.cancelTransition === 'function') {
             this.navigationCube.cancelTransition('manual-interaction');
         }
-        if (event.button === MOUSEBUTTON_LEFT) {
+        if (event.button === MOUSEBUTTON_LEFT && this._orbitEnabled !== false) {
             this.isOrbiting = true;
             this.emitInteractionEvent?.('interaction-start', 'rotate');
         }
-        else if (event.button === MOUSEBUTTON_RIGHT ||
-            event.button === MOUSEBUTTON_MIDDLE) {
+        else if ((event.button === MOUSEBUTTON_RIGHT ||
+            event.button === MOUSEBUTTON_MIDDLE) &&
+            this._panEnabled !== false) {
             this.isPanning = true;
             this.emitInteractionEvent?.('interaction-start', 'pan');
         }
@@ -140558,7 +140580,7 @@ function registerOrbitCameraScript() {
         }
     };
     OrbitCamera.prototype.onMouseWheel = function (event) {
-        if (this._inputEnabled === false)
+        if (this._inputEnabled === false || this._zoomEnabled === false)
             return;
         // Cancel any ongoing navigation cube transition when manual zoom interaction starts
         if (this.navigationCube &&
@@ -142694,6 +142716,10 @@ class Splat extends Element$1 {
         this.entity.setEulerAngles(orientation);
         this.entity.addComponent('gsplat', { asset });
         const instance = this.entity.gsplat.instance;
+        // Check if the gsplat component initialized properly
+        if (!instance || !instance.meshInstance) {
+            throw new Error('Failed to initialize gsplat component. The file may not contain valid Gaussian Splatting data.');
+        }
         // use custom render order distance calculation for splats
         instance.meshInstance.calculateSortDistance = (meshInstance, pos, dir) => {
             const bound = this.localBound;
@@ -143802,6 +143828,10 @@ class PointerController {
         };
         // Allow temporarily disabling camera controls (e.g. while dragging gizmos).
         let enabled = true;
+        // Granular control over specific input types
+        let orbitEnabled = true;
+        let panEnabled = true;
+        let zoomEnabled = true;
         const resetState = () => {
             pressedButton = -1;
             touches = [];
@@ -143908,13 +143938,13 @@ class PointerController {
                     (event.shiftKey || event.ctrlKey ? 'orbit' :
                         (event.altKey || event.metaKey ? 'zoom' : null)) :
                     null;
-                if (mod === 'orbit' || (mod === null && pressedButton === 0)) {
+                if ((mod === 'orbit' || (mod === null && pressedButton === 0)) && orbitEnabled) {
                     orbit(dx, dy);
                 }
-                else if (mod === 'zoom' || (mod === null && pressedButton === 1)) {
+                else if ((mod === 'zoom' || (mod === null && pressedButton === 1)) && zoomEnabled) {
                     zoom(dy * -0.02);
                 }
-                else if (mod === 'pan' || (mod === null && pressedButton === 2)) {
+                else if ((mod === 'pan' || (mod === null && pressedButton === 2)) && panEnabled) {
                     pan(x, y, dx, dy);
                 }
             }
@@ -143925,7 +143955,9 @@ class PointerController {
                     const dy = event.offsetY - touch.y;
                     touch.x = event.offsetX;
                     touch.y = event.offsetY;
-                    orbit(dx, dy);
+                    if (orbitEnabled) {
+                        orbit(dx, dy);
+                    }
                 }
                 else if (touches.length === 2) {
                     const touch = touches[touches.map(t => t.id).indexOf(event.pointerId)];
@@ -143934,8 +143966,12 @@ class PointerController {
                     const mx = (touches[0].x + touches[1].x) * 0.5;
                     const my = (touches[0].y + touches[1].y) * 0.5;
                     const ml = dist(touches[0].x, touches[0].y, touches[1].x, touches[1].y);
-                    pan(mx, my, (mx - midx), (my - midy));
-                    zoom((ml - midlen) * 0.01);
+                    if (panEnabled) {
+                        pan(mx, my, (mx - midx), (my - midy));
+                    }
+                    if (zoomEnabled) {
+                        zoom((ml - midlen) * 0.01);
+                    }
                     midx = mx;
                     midy = my;
                     midlen = ml;
@@ -143953,16 +143989,20 @@ class PointerController {
                 return;
             const { deltaX, deltaY } = event;
             if (isMouseEvent(deltaX, deltaY)) {
-                zoom(deltaY * -2e-3);
+                if (zoomEnabled)
+                    zoom(deltaY * -2e-3);
             }
             else if (event.ctrlKey || event.metaKey) {
-                zoom(deltaY * -0.02);
+                if (zoomEnabled)
+                    zoom(deltaY * -0.02);
             }
             else if (event.shiftKey) {
-                pan(event.offsetX, event.offsetY, deltaX, deltaY);
+                if (panEnabled)
+                    pan(event.offsetX, event.offsetY, deltaX, deltaY);
             }
             else {
-                orbit(deltaX, deltaY);
+                if (orbitEnabled)
+                    orbit(deltaX, deltaY);
             }
             event.preventDefault();
         };
@@ -144030,6 +144070,14 @@ class PointerController {
                 resetState();
             }
         };
+        this.setInputControls = (options) => {
+            if (options.orbit !== undefined)
+                orbitEnabled = !!options.orbit;
+            if (options.pan !== undefined)
+                panEnabled = !!options.pan;
+            if (options.zoom !== undefined)
+                zoomEnabled = !!options.zoom;
+        };
     }
 }
@@ -147334,6 +147382,26 @@ class SupersplatAdapter {
             console.warn('SupersplatAdapter: Failed to toggle camera controls', e);
         }
     }
+    /**
+     * Configure granular control over specific camera input types.
+     * Allows enabling/disabling orbit, pan, and zoom independently.
+     */
+    setCameraInputControls(options) {
+        const controller = this.scene?.camera?.controller;
+        if (!controller)
+            return;
+        try {
+            if (typeof controller.setInputControls === 'function') {
+                controller.setInputControls(options);
+            }
+            else {
+                console.warn('SupersplatAdapter: Camera controller does not support setInputControls');
+            }
+        }
+        catch (e) {
+            console.warn('SupersplatAdapter: Failed to set camera input controls', e);
+        }
+    }
     /**
      * Enable/disable supersplat-core camera auto-update (orbit tweens).
      * When enabled, the camera entity transform may be driven by an external controller (fly mode).
@@ -147792,9 +147860,9 @@ class SplatViewerCore {
         this._supersplatReady = this._supersplat.init();
         this._supersplatReady
             ?.then(() => {
-            // Disable camera controls in preview mode
+            // In preview mode, enable zoom only (disable orbit and pan)
             if (this.previewMode && this._supersplat) {
-                this._supersplat.setCameraControlsEnabled?.(false);
+                this._supersplat.setCameraInputControls?.({ orbit: false, pan: false, zoom: true });
             }
             // Only set up fly camera if not in preview mode
             if (!this.previewMode) {
@@ -150007,11 +150075,12 @@ class SplatViewerCore {
                 detail: { type: interactionType },
             });
         };
-        // Disable camera controls in preview mode
+        // In preview mode, enable zoom only (disable orbit and pan)
         if (this.previewMode && this._orbit) {
             const orbitAny = this._orbit;
-            if (typeof orbitAny.setEnabled === 'function') {
-                orbitAny.setEnabled(false);
+            if (typeof orbitAny.setInputControls === 'function') {
+                // Enable zoom, disable orbit and pan
+                orbitAny.setInputControls({ orbit: false, pan: false, zoom: true });
             }
         }
         this.entities.camera.setPosition(0, 0, 10);