@speridlabs/visus 0.1.0

package/README.md

@@ -0,0 +1,155 @@
+# Visus - Gaussian Splatting for Three.js
+
+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.
+
+## Installation
+
+```bash
+# Using npm
+npm install visus
+
+# Using yarn
+yarn add visus
+
+# Using pnpm
+pnpm add visus
+```
+
+## Key Features
+
+- **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.
+
+## Basic Usage
+
+```typescript
+// main.ts
+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,
+);
+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);
+}
+
+// Handle window resize
+window.addEventListener('resize', () => {
+    camera.aspect = window.innerWidth / window.innerHeight;
+    camera.updateProjectionMatrix();
+    renderer.setSize(window.innerWidth, window.innerHeight);
+});
+```
+
+_(See `examples/main.ts` for a more complete example setup)_
+
+## 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.
+
+## Performance Optimizations
+
+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.
+
+## Future Development / Roadmap
+
+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
+
+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
+
+Visus is licensed under the [Apache License 2.0](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * visus - Gaussian Splat Rendering for Three.js
+ */
+export { SplatData } from './core/data';
+export { SplatSorter } from './core/sorter';
+export { SplatMesh, type SplatMeshOptions } from './core/mesh';
+export { PlyLoader } from './loaders/ply';
+export { SplatMaterial, type SplatMaterialOptions } from './materials';
+export { BoundingBox } from './utils/bounding';
+export { TextureManager } from './materials/texture';
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/main.es.js

@@ -0,0 +1,12 @@
+import { B as r, P as s, S as o, c as S, b as l, a as p, T as n } from "./ply-CQ9dyX1o.mjs";
+const a = "0.1.0";
+export {
+  r as BoundingBox,
+  s as PlyLoader,
+  o as SplatData,
+  S as SplatMaterial,
+  l as SplatMesh,
+  p as SplatSorter,
+  n as TextureManager,
+  a as VERSION
+};