@heliguy-xyz/splat-viewer 1.0.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-01-XX
+
+### Added
+
+#### Multi-Model Support
+- Add multiple models to the same scene with `addModel()`
+- Remove models individually with `removeModel()`
+- Query all loaded models with `getModels()`
+- Get per-model statistics with `getModelStats()`
+- Get scene-wide statistics with `getSceneStats()`
+- Events: `model-added`, `model-removed`, `scene-cleared`
+
+#### Transform System
+- Apply 4x4 transformation matrices to models
+- Set/get position, rotation, and scale independently
+- Reset transforms to identity
+- Event: `model-transform-changed`
+
+#### Fly Camera Mode
+- Switch between orbit and fly camera modes with `setCameraMode()`
+- First-person WASD + mouse-look navigation with pointer lock
+- Configurable movement speed, sensitivity, and key bindings
+- Speed modifiers (Shift for fast, Ctrl for slow)
+- Height constraints and collision detection options
+- Events: `camera-mode-changed`, `fly-camera-move`, `fly-camera-look`
+
+#### Scene Configuration
+- Set and animate camera FOV with `setCameraFOV()` and `animateCameraFOV()`
+- Set and animate background color with `setBackgroundColor()` and `animateBackgroundColor()`
+- Support for multiple color formats (hex, RGB, RGBA, named colors)
+- Events: `camera-fov-changed`, `background-color-changed`
+
+#### TypeScript Support
+- Full type definitions for all public APIs
+- Export types for models, transforms, camera, and scene config
+- IntrinsicElements declaration support for React/JSX
+
+#### Documentation
+- Comprehensive integration guide for frontend developers
+- API quick reference
+- Migration guide
+- React/Next.js integration examples
+
+### Changed
+- Package name changed to `@heliguy/web-viewer` (scoped package)
+- Made package public for npm publishing
+- Updated README with npm installation instructions
+- Enhanced event system with more granular events
+
+### Fixed
+- Improved type safety across all APIs
+- Better error handling for model operations
+- Consistent event emission patterns
+
+## [0.1.0] - 2024-XX-XX
+
+### Added
+- Initial release
+- Basic 3D Gaussian Splat viewer web component
+- Support for .splat, .ply, .ply.compressed, and .sog formats
+- PlayCanvas-based rendering engine
+- Orbit camera controls
+- Navigation cube for camera orientation
+- Performance monitoring
+- Loading states and error handling
+- Self-contained bundle with zero external dependencies
+
+[1.0.0]: https://github.com/Heliguy-com/3d-web-viewer/releases/tag/v1.0.0
+[0.1.0]: https://github.com/Heliguy-com/3d-web-viewer/releases/tag/v0.1.0

package/README.md

@@ -0,0 +1,343 @@
+# Heliguy Web 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.
+
+## 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
+- 📡 **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)
+
+```bash
+npm install @heliguy/web-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
+
+#### Vanilla 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>
+</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
+
+```tsx
+import { useEffect, useRef } from 'react'
+import '@heliguy/web-viewer'
+
+function App() {
+  const viewerRef = useRef<any>(null)
+
+  useEffect(() => {
+    const viewer = viewerRef.current
+    if (!viewer) return
+
+    const handleReady = () => {
+      viewer.load('/models/scene.splat')
+    }
+
+    viewer.addEventListener('ready', handleReady)
+    return () => viewer.removeEventListener('ready', handleReady)
+  }, [])
+
+  return (
+    <splat-viewer
+      ref={viewerRef}
+      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
+      },
+      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)
+
+#### 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)
+
+### 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:
+
+- Complete PlayCanvas engine (v2.11.8)
+- Web component implementation
+- File format loaders
+- Performance monitoring
+- Interactive controls
+
+**Benefits:**
+
+- Zero external dependencies
+- Version consistency guaranteed
+- Easy embedding in any web application
+- Offline functionality
+
+## Development
+
+```bash
+# Start development server
+npm run web-component:serve
+
+# Build for production
+npm run web-component:build
+
+# Clean build artifacts
+npm run web-component:clean
+```
+
+## Deployment
+
+### Netlify
+
+- Publish directory: `dist`
+- Build command: `npm run build`
+- Node version: 18 (configured in `netlify.toml`)
+
+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`.
+
+## License
+
+MIT License - see LICENSE file for details.

package/dist/web-component/CameraModeManager.d.ts

@@ -0,0 +1,22 @@
+import type { CameraMode, FlyCameraConfig, FlyCameraState, OrbitCameraScript, PlayCanvasApplication, PlayCanvasEntity } from './types';
+type EmitFn = (eventType: string, detail?: any) => void;
+export declare class CameraModeManager {
+    private app;
+    private camera;
+    private orbit;
+    private fly;
+    private mode;
+    private emit;
+    constructor(app: PlayCanvasApplication, camera: PlayCanvasEntity, orbit: OrbitCameraScript | null, fly: any | null, emit: EmitFn, initialMode?: CameraMode);
+    getMode(): CameraMode;
+    setMode(nextMode: CameraMode): void;
+    setFlyConfig(config: Partial<FlyCameraConfig>): void;
+    getFlyConfig(): FlyCameraConfig | null;
+    getFlyState(): FlyCameraState | null;
+    private activateOrbitMode;
+    private deactivateOrbitMode;
+    private activateFlyMode;
+    private deactivateFlyMode;
+}
+export {};
+//# sourceMappingURL=CameraModeManager.d.ts.map

package/dist/web-component/CameraModeManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CameraModeManager.d.ts","sourceRoot":"","sources":["../../src/web-component/CameraModeManager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,SAAS,CAAA;AAEhB,KAAK,MAAM,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,KAAK,IAAI,CAAA;AAEvD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,GAAG,CAAuB;IAClC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,IAAI,CAAY;IACxB,OAAO,CAAC,IAAI,CAAQ;gBAGlB,GAAG,EAAE,qBAAqB,EAC1B,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,iBAAiB,GAAG,IAAI,EAC/B,GAAG,EAAE,GAAG,GAAG,IAAI,EACf,IAAI,EAAE,MAAM,EACZ,WAAW,GAAE,UAAkC;IAmB1C,OAAO,IAAI,UAAU;IAIrB,OAAO,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI;IA0BnC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI;IAMpD,YAAY,IAAI,eAAe,GAAG,IAAI;IAmBtC,WAAW,IAAI,cAAc,GAAG,IAAI;IAe3C,OAAO,CAAC,iBAAiB;IA+BzB,OAAO,CAAC,mBAAmB;IA4B3B,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,iBAAiB;CAI1B"}

package/dist/web-component/FlyCameraScript.d.ts

@@ -0,0 +1,2 @@
+export declare function registerFlyCameraScript(): void;
+//# sourceMappingURL=FlyCameraScript.d.ts.map

package/dist/web-component/FlyCameraScript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlyCameraScript.d.ts","sourceRoot":"","sources":["../../src/web-component/FlyCameraScript.ts"],"names":[],"mappings":"AAsEA,wBAAgB,uBAAuB,IAAI,IAAI,CA0X9C"}

package/dist/web-component/ModelManager.d.ts

@@ -0,0 +1,96 @@
+/**
+ * ModelManager - Manages multiple 3D models in a single scene
+ *
+ * This class provides functionality to:
+ * - Add/remove models with unique IDs
+ * - Track model metadata and statistics
+ * - Extract model information (splat count, bounding box, memory usage)
+ * - Provide aggregate scene statistics
+ */
+import type { AddModelOptions, ModelInfo, ModelMetadata, PlayCanvasApplication, SceneMetadata, TransformData } from './types';
+export declare class ModelManager {
+    private models;
+    private app;
+    private _eventEmitter;
+    constructor(app: PlayCanvasApplication, eventEmitter?: (eventType: string, detail: any) => void);
+    /**
+     * Generate a unique model ID
+     */
+    private generateModelId;
+    /**
+     * Extract a human-readable model name from the source
+     */
+    private extractModelName;
+    /**
+     * Extract metadata from a loaded model
+     */
+    private extractMetadata;
+    /**
+     * Extract splat count from entity/asset
+     */
+    private extractSplatCount;
+    /**
+     * Calculate bounding box for an entity
+     */
+    private calculateBoundingBox;
+    /**
+     * Estimate GPU memory usage based on splat count
+     * Formula: ~64 bytes per splat (approximate)
+     */
+    private estimateMemoryUsage;
+    /**
+     * Get current transform data from an entity
+     */
+    private getEntityTransform;
+    /**
+     * Add a model to the scene
+     * @param source URL, File, or Blob containing the model data
+     * @param options Configuration options for the model
+     * @returns Promise resolving to model information
+     */
+    addModel(source: string | File | Blob, options?: AddModelOptions): Promise<ModelInfo>;
+    /**
+     * Remove a specific model from the scene
+     * @param modelId ID of the model to remove
+     */
+    removeModel(modelId: string): void;
+    /**
+     * Get information about all loaded models
+     * @returns Array of model information objects
+     */
+    getModels(): ModelInfo[];
+    /**
+     * Get information about a specific model
+     * @param modelId ID of the model
+     * @returns Model information or undefined if not found
+     */
+    getModelById(modelId: string): ModelInfo | undefined;
+    /**
+     * Get statistics for a specific model
+     * @param modelId ID of the model
+     * @returns Model metadata and statistics
+     */
+    getModelStats(modelId: string): ModelMetadata;
+    /**
+     * Get statistics for all models
+     * @returns Map of model IDs to metadata
+     */
+    getAllModelStats(): Record<string, ModelMetadata>;
+    /**
+     * Get aggregate scene statistics
+     * @returns Scene-wide metadata
+     */
+    getSceneStats(): SceneMetadata;
+    /**
+     * Clear all models from the scene
+     */
+    clear(): void;
+    /**
+     * Update transform for a model
+     * @param modelId ID of the model
+     * @param transform New transform data
+     */
+    updateModelTransform(modelId: string, transform: TransformData): void;
+}
+export default ModelManager;
+//# sourceMappingURL=ModelManager.d.ts.map

package/dist/web-component/ModelManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModelManager.d.ts","sourceRoot":"","sources":["../../src/web-component/ModelManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EACV,eAAe,EAGf,SAAS,EACT,aAAa,EACb,qBAAqB,EAGrB,aAAa,EACb,aAAa,EAEd,MAAM,SAAS,CAAA;AAUhB,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAA4C;IAC1D,OAAO,CAAC,GAAG,CAAuB;IAClC,OAAO,CAAC,aAAa,CAAwD;gBAG3E,GAAG,EAAE,qBAAqB,EAC1B,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,IAAI;IAMzD;;OAEG;IACH,OAAO,CAAC,eAAe;IASvB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;OAEG;IACH,OAAO,CAAC,eAAe;IA2DvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAmD5B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;;;;OAKG;IACU,QAAQ,CACnB,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,EAC5B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,SAAS,CAAC;IAiKrB;;;OAGG;IACI,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAgCzC;;;OAGG;IACI,SAAS,IAAI,SAAS,EAAE;IAW/B;;;;OAIG;IACI,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAgB3D;;;;OAIG;IACI,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa;IAUpD;;;OAGG;IACI,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAUxD;;;OAGG;IACI,aAAa,IAAI,aAAa;IA4DrC;;OAEG;IACI,KAAK,IAAI,IAAI;IAapB;;;;OAIG;IACI,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,GAAG,IAAI;CAW7E;AAED,eAAe,YAAY,CAAA"}