@speridlabs/visus 0.2.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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@speridlabs/visus",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "A web package for threejs that enables real time rendering of optimized 3DGS (Gaussian Splatting)",
     "types": "dist/main.d.ts",
     "main": "dist/main.umd.js",