@speridlabs/visus 0.1.0 → 0.3.0

package/README.md

@@ -1,155 +1,123 @@
-# Visus - Gaussian Splatting for Three.js
+# Visus
 
-Visus is a high-performance WebGL library designed to seamlessly integrate real-time 3D Gaussian Splatting (3DGS) rendering into [Three.js](https://threejs.org/) applications. It focuses on speed and optimization to deliver smooth rendering experiences directly within your existing Three.js scenes.
+![Visus Demo](./public/demo.png)
 
-## Installation
+**High‑performance Gaussian Splatting** (3DGS) for [Three.js](https://threejs.org/) and React‑Three‑Fiber.
+Drop in a `SplatMesh` or `<Splat>` component, feed it a `.ply`, and render millions of splats with correct transparency and minimal overhead.
+
+---
+
+## 🚀 Installation
 
 ```bash
-# Using npm
-npm install visus
+# npm
+npm install @speridlabs/visus three
 
-# Using yarn
-yarn add visus
+# yarn
+yarn add @speridlabs/visus three
+
+# pnpm
+pnpm add @speridlabs/visus three
 
-# Using pnpm
-pnpm add visus
 ```
 
-## Key Features
+> Visus treats Three.js as a peer dependency—make sure it's installed alongside.
+
+---
 
-- **Three.js Integration:** Designed as a `THREE.Mesh`-like object (`SplatMesh`) for easy addition to Three.js scenes.
-- **Customizable Material:** Offers options for controlling rendering appearance.
-- **Optimized Performance:** Leverages several techniques for speed:
-    - **GPU Sorting:** Performs view-dependent sorting in a Web Worker to avoid blocking the main thread, ensuring correct transparency.
-    - **Instanced Rendering:** Draws multiple splats per draw call using GPU instancing.
-    - **Efficient Texture Packing:** Packs rotation and scale data tightly into GPU textures.
-    - **Optimized Shaders:** Includes early discards and efficient math operations in GLSL shaders.
+## 🔑 Key Features
 
-## Basic Usage
+* **Mesh‑like API**: `new SplatMesh(data, options)` behaves like a `THREE.Mesh`.
+* **React wrapper**: `<Splat plyUrl="..." splatOptions={{…}} />` for R3F apps.
+* **Web Worker sorting**: non‑blocking depth sort for correct transparency.
+* **GPU instancing**: draw hundreds of splats in a single call.
+* **Packed textures**: compact quaternion & scale storage.
+* **Shader culling**: early discards, premultiplied alpha.
 
-```typescript
-// main.ts
+---
+
+## 🎯 Quickstart
+
+### Plain Three.js
+
+```js
 import * as THREE from 'three';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
-import { PlyLoader, SplatMesh, SplatData } from 'visus'; // Import from visus
-
-// 1. Basic Three.js Scene Setup
-const scene = new THREE.Scene();
-const camera = new THREE.PerspectiveCamera(
-    75,
-    window.innerWidth / window.innerHeight,
-    0.1,
-    1000,
-);
+import { PlyLoader, SplatMesh } from '@speridlabs/visus';
+
+const scene    = new THREE.Scene();
+const camera   = new THREE.PerspectiveCamera(75, window.innerWidth/window.innerHeight, 0.1, 100);
 camera.position.set(0, 1, 3);
 
 const renderer = new THREE.WebGLRenderer({ antialias: true });
 renderer.setSize(window.innerWidth, window.innerHeight);
-renderer.setAnimationLoop(animate);
 document.body.appendChild(renderer.domElement);
 
 const controls = new OrbitControls(camera, renderer.domElement);
-controls.enableDamping = true;
-
-// 2. Load the Splat File
-// IMPORTANT: Place your PLY file (e.g., sample.ply) in your project's `public/` directory
-// or serve it from a location accessible by the browser.
-const loader = new PlyLoader();
-const plyUrl = '/sample.ply'; // Adjust path as needed
-
-async function loadAndDisplaySplat() {
-    try {
-        console.log(`Loading splat from ${plyUrl}...`);
-        const splatData: SplatData = await loader.loadAsync(plyUrl);
-        console.log(`Loaded ${splatData.numSplats} splats.`);
-
-        // 3. Create the SplatMesh
-        // autoSort: true enables automatic sorting based on camera view (recommended)
-        const splatMesh = new SplatMesh(splatData, { autoSort: true });
-
-        // Optional: Apply transformations if needed (e.g., correct orientation)
-        // splatMesh.rotation.set(0, 0, Math.PI);
-
-        // 4. Add to Scene
-        scene.add(splatMesh);
-        console.log('SplatMesh added to scene.');
-
-        // Optional: Focus camera on the splat
-        if (splatMesh.geometry.boundingBox) {
-            const center = new THREE.Vector3();
-            splatMesh.geometry.boundingBox.getCenter(center);
-            controls.target.copy(center);
-
-            const sphere = new THREE.Sphere();
-            splatMesh.geometry.boundingBox.getBoundingSphere(sphere);
-            camera.position
-                .copy(center)
-                .add(new THREE.Vector3(0, 0, sphere.radius * 2));
-            camera.lookAt(center);
-            controls.update();
-        }
-    } catch (error) {
-        console.error('Error loading splat:', error);
-        // Display error to user
-    }
-}
-
-loadAndDisplaySplat(); // Start loading
 
-// 5. Animation Loop
-function animate() {
-    controls.update(); // Required if damping is enabled
-    renderer.render(scene, camera);
-}
+(async () => {
+  const data = await new PlyLoader().loadAsync('/sample.ply');
+  const mesh = new SplatMesh(data, { autoSort: true });
+  scene.add(mesh);
+})();
 
-// Handle window resize
-window.addEventListener('resize', () => {
-    camera.aspect = window.innerWidth / window.innerHeight;
-    camera.updateProjectionMatrix();
-    renderer.setSize(window.innerWidth, window.innerHeight);
+renderer.setAnimationLoop(() => {
+  controls.update();
+  renderer.render(scene, camera);
 });
 ```
 
-_(See `examples/main.ts` for a more complete example setup)_
+### React‑Three‑Fiber (R3F)
+
+```tsx
+import React from 'react';
+import { Canvas } from '@react-three/fiber';
+import { Splat } from '@speridlabs/visus/react';
+
+export default function App() {
+  return (
+    <Canvas camera={{ position: [0, 1, 3] }}>
+      <ambientLight />
+      <Splat plyUrl="/sample.ply" splatOptions={{ autoSort: true }} />
+    </Canvas>
+  );
+}
+```
 
-## API Overview
+---
 
-- **`PlyLoader`**: Loads `.ply` files containing Gaussian Splat data. Use `loadAsync` for Promise-based loading.
-- **`SplatData`**: Internal representation holding the raw data (positions, rotations, scales, colors, opacities) for all splats.
-- **`SplatMesh`**: The main renderable object. Add this to your `THREE.Scene`. It manages the geometry, material, and sorting. Takes `SplatData` and optional `SplatMeshOptions` in its constructor.
-    - `options.autoSort` (default `true`): Automatically triggers sorting based on camera movement.
-- **`SplatMaterial`**: The `THREE.ShaderMaterial` used internally by `SplatMesh`. Handles the actual splat rendering logic. Can be customized via `SplatMaterialOptions`.
-- **`SplatSorter`**: Manages the Web Worker responsible for view-dependent sorting. Generally used internally by `SplatMesh`.
-- **`TextureManager`**: Handles packing splat data into GPU textures. Used internally.
+## 📦 API Overview
 
-## Performance Optimizations
+| Export         | Description                                                    |
+| -------------- | -------------------------------------------------------------- |
+| `PlyLoader`    | `.loadAsync(url): Promise<SplatData>`                          |
+| `SplatData`    | Raw buffers of positions, rotations, scales, colors, opacities |
+| `SplatMesh`    | `new SplatMesh(data, options?)` → a `THREE.Mesh`               |
+| `SplatOptions` | `{ autoSort?: boolean; /* … */ }`                              |
+| `Splat`        | React component wrapping `SplatMesh`                           |
+| `VERSION`      | Library version string                                         |
 
-Visus employs several techniques documented in `Optimizations.md` to achieve real-time performance:
+---
 
-- **GPU Sorting via Web Worker:** Sorts splats by depth off the main thread using a distance-based counting sort, preventing stutter and ensuring correct alpha blending.
-- **Instanced Rendering:** Renders many splats (typically 128) in a single draw call, reducing CPU overhead.
-- **Packed Data Textures:** Stores rotation and scale data efficiently in textures, minimizing GPU memory bandwidth. Rotation quaternions are packed, reconstructing the `w` component in the shader. Scale is stored logarithmically.
-- **Shader Optimizations:** Uses early checks in vertex and fragment shaders to discard splats/fragments that won't be visible (behind near plane, too small, fully transparent, outside ellipse), reducing GPU workload.
-- **Premultiplied Alpha Blending:** Uses standard premultiplied alpha for correct transparency compositing.
+## 🔧 Performance Highlights
 
-## Future Development / Roadmap
+* **Off‑thread sorting** via Web Worker
+* **Instanced draw calls** for minimal CPU overhead
+* **Packed data textures** reduce memory bandwidth
+* **Shader‑level early exit** for invisible splats
 
-Based on the analysis in `Optimizations.md`, potential future enhancements include:
+---
 
-- Support for Spherical Harmonics (SH) for view-dependent color effects.
-- Implementing spatial data reordering (e.g., Morton order) before GPU upload for improved cache coherency.
-- Exploring more advanced texture compression or lower-precision formats (like half-floats or uint8) for attributes like color and scale to further reduce GPU memory usage.
-- Adding streamed loading capabilities to handle very large `.ply` files more efficiently in terms of RAM.
-- Investigating multi-chunk based sorting optimizations for better key distribution with non-uniform datasets.
-- Adding optional dithering techniques as an alternative to alpha blending.
-- Implementing more sophisticated culling methods.
+## 🤝 Contributing
 
-## Contributing
+1. Fork & clone
+2. `pnpm install`
+3. `pnpm lint && pnpm build`
+4. Open a PR!
 
-Contributions are welcome! If you find a bug or have a feature request, please open an issue on the GitHub repository.
+---
 
-For pull requests, please ensure your code adheres to the project's linting (`pnpm lint`) and formatting (`pnpm format`) standards.
+## 📄 License
 
-## License
+Apache 2.0 © Sperid Labs
 
-Visus is licensed under the [Apache License 2.0](LICENSE).

package/dist/main.d.ts

@@ -0,0 +1,320 @@
+import * as THREE from 'three';
+
+/**
+ * Simplified bounding box class that tracks min/max points
+ */
+export declare class BoundingBox {
+    min: THREE.Vector3;
+    max: THREE.Vector3;
+    center: THREE.Vector3;
+    /** Half extents (size/2) */
+    halfExtents: THREE.Vector3;
+    /**
+     * Reset the bounding box to its initial state
+     */
+    reset(): void;
+    /**
+     * Expand the bounding box to include the given point
+     * @param point Point to include in the bounding box
+     */
+    expandByPoint(point: THREE.Vector3): void;
+    /**
+     * Expand this bounding box to include another bounding box
+     * @param box Bounding box to include
+     */
+    expandByBox(box: BoundingBox): void;
+    /**
+     * Update the center and half extents based on min/max
+     */
+    private updateDerived;
+    /**
+     * Check if this box contains a point
+     * @param point Point to check
+     * @returns True if the point is inside the box
+     */
+    containsPoint(point: THREE.Vector3): boolean;
+    /**
+     * Create a Three.js Box3 from this bounding box
+     * @returns THREE.Box3 representation
+     */
+    toBox3(): THREE.Box3;
+    /**
+     * Create a clone of this bounding box
+     * @returns New bounding box with the same values
+     */
+    clone(): BoundingBox;
+}
+
+/**
+ * Class for loading PLY files with Gaussian Splat data
+ */
+export declare class PlyLoader extends THREE.Loader {
+    /**
+     * Load a PLY file with Gaussian Splat data
+     * @param url URL of the PLY file
+     * @param onLoad Optional callback when loading is complete
+     * @param onProgress Optional progress callback
+     * @param onError Optional error callback
+     */
+    load(url: string, onLoad?: (data: SplatData) => void, onProgress?: (event: ProgressEvent) => void, onError?: (event: ErrorEvent) => void): void;
+    /**
+     * Load a PLY file asynchronously and return a Promise
+     * @param url URL of the PLY file
+     * @param onProgress Optional progress callback
+     * @returns A Promise that resolves with the parsed SplatData
+     */
+    loadAsync(url: string, onProgress?: (event: ProgressEvent) => void): Promise<SplatData>;
+    /**
+     * Parse PLY buffer data into SplatData
+     * @param buffer ArrayBuffer containing PLY data
+     * @returns Parsed SplatData
+     */
+    parse(buffer: ArrayBuffer): SplatData;
+}
+
+export declare class SplatData {
+    numSplats: number;
+    positions: Float32Array;
+    rotations: Float32Array;
+    scales: Float32Array;
+    colors: Float32Array;
+    opacities: Float32Array;
+    centers: Float32Array;
+    boundingBox: BoundingBox;
+    constructor(numSplats?: number);
+    private allocateBuffers;
+    /**
+     * Set data for a specific splat
+     * @param index Splat index
+     * @param position Position vector
+     * @param rotation Quaternion
+     * @param scale Scale vector (expects LOG SCALE)
+     * @param color Color
+     * @param opacity Opacity value
+     */
+    setSplat(index: number, position: THREE.Vector3, rotation: THREE.Quaternion, scale: THREE.Vector3, color: THREE.Color, opacity: number): void;
+    /**
+     * Get a splat's data
+     * @param index Splat index
+     * @returns Object containing splat data (linear scale)
+     */
+    getSplat(index: number): {
+        position: THREE.Vector3;
+        rotation: THREE.Quaternion;
+        scale: THREE.Vector3;
+        color: THREE.Color;
+        opacity: number;
+    };
+    /**
+     * Calculate the bounding box for all splats
+     * NOTE: Currently it only uses positions, not the actual splat bounds
+     */
+    calculateBoundingBox(): BoundingBox;
+    /**
+     * Create a Three.js BufferGeometry from this splat data
+     * This is for visualization/debugging purposes only, not for rendering
+     */
+    createDebugGeometry(): THREE.BufferGeometry;
+}
+
+export declare class SplatMaterial extends THREE.ShaderMaterial {
+    constructor(options?: SplatMaterialOptions);
+    /**
+     * Update the viewport size
+     * @param width Viewport width
+     * @param height Viewport height
+     */
+    updateViewport(width: number, height: number): void;
+    /**
+     * Set transform texture A (positions)
+     * @param texture Texture containing positions
+     */
+    setTransformA(texture: THREE.Texture): void;
+    /**
+     * Set transform texture B (rotation, scale)
+     * @param texture Texture containing rotation and scale data
+     */
+    setTransformB(texture: THREE.Texture): void;
+    /**
+     * Set color texture
+     * @param texture Texture containing colors
+     */
+    setColorTexture(texture: THREE.Texture): void;
+    /**
+     * Set order texture
+     * @param texture Texture containing sort order
+     */
+    setOrderTexture(texture: THREE.Texture): void;
+    /**
+     * Set number of splats to render
+     * @param count Number of splats
+     */
+    setNumSplats(count: number): void;
+}
+
+export declare interface SplatMaterialOptions {
+    alphaTest?: number;
+    alphaHash?: boolean;
+    toneMapped?: boolean;
+}
+
+/**
+ * A mesh that renders Gaussian splats
+ * Not a real MESH, but a custom geometry with instancing
+ */
+export declare class SplatMesh extends THREE.Mesh {
+    sorter: SplatSorter;
+    splatData: SplatData;
+    options: SplatMeshOptions;
+    textureManager: TextureManager;
+    material: SplatMaterial;
+    geometry: THREE.InstancedBufferGeometry;
+    private lastCameraPositionLocal;
+    private lastCameraDirectionLocal;
+    private invModelMatrix;
+    /** Number of splats combined into a single instanced draw call. */
+    private static INSTANCE_SIZE;
+    /**
+     * Create a new SplatMesh for rendering Gaussian splats
+     * @param splatData The splat data to render
+     * @param options Rendering options
+     */
+    constructor(splatData: SplatData, options?: SplatMeshOptions);
+    /**
+     * Creates the instanced geometry for rendering splats.
+     * @param totalSplats Total number of splats in the data.
+     * @param instanceSize Number of splats per instance.
+     * @returns InstancedBufferGeometry
+     */
+    private static createInstancedGeometry;
+    /**
+     * Create chunks data (bounding box min/max) for the sorter.
+     * @returns Float32Array containing chunk data [minX, minY, minZ, maxX, maxY, maxZ] or null.
+     */
+    private createChunks;
+    /**
+     * Update the viewport size
+     * @param width Viewport width
+     * @param height Viewport height
+     */
+    updateViewport(width: number, height: number): void;
+    /**
+     * Sorts splats based on camera position and direction.
+     * @param camera The camera to sort against.
+     */
+    sort(camera: THREE.Camera): void;
+    /**
+     * THREE.js hook called before rendering the object.
+     * Used here to trigger sorting and update viewport.
+     * @param renderer The renderer
+     * @param scene The scene
+     * @param camera The camera
+     */
+    onBeforeRender(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera): void;
+    /**
+     * Dispose of resources
+     */
+    dispose(): void;
+}
+
+export declare interface SplatMeshOptions extends SplatMaterialOptions {
+    autoSort?: boolean;
+}
+
+/**
+ * Manages sorting of splats based on camera view using a Web Worker.
+ */
+export declare class SplatSorter extends THREE.EventDispatcher<{
+    updated: SplatSortUpdateEvent;
+}> {
+    private worker;
+    private centers;
+    private orderTexture;
+    /** Bounding box data for optimization */
+    private chunks;
+    private lastCameraPosition;
+    private lastCameraDirection;
+    constructor();
+    /**
+     * Handles messages received from the sorting worker.
+     * @param event The message event from the worker.
+     */
+    private onWorkerMessage;
+    /**
+     * Initializes the sorter with necessary data and textures.
+     * @param orderTexture The THREE.DataTexture (R32UI) to store the sorted splat indices.
+     * @param centers A Float32Array containing the center position (x, y, z) for each splat.
+     * @param chunks Optional: A Float32Array containing bounding box chunk data [minX, minY, minZ, maxX, maxY, maxZ, ...] for optimization.
+     */
+    init(orderTexture: THREE.DataTexture, centers: Float32Array, chunks?: Float32Array): void;
+    /**
+     * Applies an optional mapping to filter or reorder splats before sorting.
+     * The sorter will only consider splats whose original indices are present in the mapping.
+     * @param mapping A Uint32Array where each element is the *original* index of a splat to include, or null to reset mapping.
+     */
+    setMapping(mapping: Uint32Array | null): void;
+    /**
+     * Updates the camera parameters used for sorting.
+     * @param position The camera's position in the sorter's local coordinate space.
+     * @param direction The camera's forward direction in the sorter's local coordinate space.
+     */
+    setCamera(position: THREE.Vector3, direction: THREE.Vector3): void;
+    /**
+     * Terminates the Web Worker and cleans up resources.
+     */
+    dispose(): void;
+    /**
+     * Creates the self-contained code for the sorting Web Worker.
+     * @returns A string containing the JavaScript code for the worker.
+     */
+    private createWorkerCode;
+}
+
+/** Event dispatched when the sort is updated */
+declare interface SplatSortUpdateEvent extends THREE.Event {
+    type: 'updated';
+    count: number;
+}
+
+export declare class TextureManager {
+    transformA: THREE.DataTexture;
+    transformB: THREE.DataTexture;
+    colorTexture: THREE.DataTexture;
+    orderTexture: THREE.DataTexture;
+    textureWidth: number;
+    textureHeight: number;
+    /**
+     * Create a new TextureManager for a set of splats
+     * @param splatData The splat data to manage textures for
+     */
+    constructor(splatData: SplatData);
+    /**
+     * Create the transform A texture (positions and quaternion w component)
+     * @param splatData The splat data
+     * @returns DataTexture containing position data
+     */
+    private createTransformATexture;
+    /**
+     * Create the transform B texture (scale and rotation xyz)
+     * @param splatData The splat data
+     * @returns DataTexture containing scale and rotation data
+     */
+    private createTransformBTexture;
+    /**
+     * Create the color texture (RGB and opacity)
+     * @param splatData The splat data
+     * @returns DataTexture containing color data
+     */
+    private createColorTexture;
+    /**
+     * Create the order texture for sorting
+     * @param numSplats Number of splats
+     * @returns DataTexture for storing order indices
+     */
+    private createOrderTexture;
+    dispose(): void;
+}
+
+export declare const VERSION = "0.2.0";
+
+export { }