repository·main·Indexed 25 days ago
https://github.com/mkkellogg/gaussiansplats3dA high-performance Three.js-based 3D Gaussian Splatting library for the web. It provides tools to load, parse, and visualize Gaussian Splat data in formats including PLY, SPZ, and KSPLAT. The library includes a DropInViewer for easy Three.js integration, specialized loaders, and the SplatBuffer class for managing compressed splat data and binary layouts.
build, you can provide an array of sceneOptions objects to customize individual scenes within the mesh. Each object in the array corresponds to a SplatBuffer in the same index.When instantiating DropInViewer, you can pass an options object to configure the underlying Viewer:
selfDrivenMode (boolean): Defaults to false.useBuiltInControls (boolean): Defaults to false.rootElement (HTMLElement): The DOM element for the viewer.dropInMode (boolean): Defaults to true.camera (THREE.Camera): The Three.js camera to use.renderer (THREE.WebGLRenderer): The Three.js renderer to use.Iterate through all leaf nodes in the SplatTree by providing a callback function. This is useful for performing operations on every leaf node in the spatial structure.
Parameters:
visitFunc: A callback function that is executed for each leaf node found in the tree.Use generateFromUncompressedSplatArrays to create a compressed or uncompressed SplatBuffer from raw splat data. This is the primary method for encoding splat data into the project's binary format.
Parameters:
splatArrays: An array of UncompressedSplatArray objects containing the raw splat data.minimumAlpha: A threshold to filter out splats with opacity below this value.compressionLevel: The desired compression level (e.g., 0 for uncompressed, 1 or higher for compressed formats).sceneCenter: A THREE.Vector3 representing the center of the scene.blockSize: The size of the spatial blocks used for bucketing.bucketSize: The maximum number of splats per bucket.options: (Optional) An array of configuration objects corresponding to each splatArray to override blockSizeFactor or bucketSizeFactor.const splatBuffer = SplatBuffer.generateFromUncompressedSplatArrays(
splatArrays,
minimumAlpha,
compressionLevel,
sceneCenter,
blockSize,
bucketSize,
options
);The viewer can be run in a 'self-driven' mode where it manages its own animation loop (via requestAnimationFrame or WebXR).
start(): Starts the animation loop. Note that this will throw an error if the viewer is not already configured for self-driven mode.stop(): Stops the animation loop.The package provides several loaders for different Gaussian Splatting file formats. Use the appropriate loader based on your source file type:
PlyLoader: For standard .ply files.SpzLoader: For .spz compressed files.SplatLoader: For .splat files.KSplatLoader: For .ksplat files.PlayCanvasCompressedPlyParser: Specifically for compressed PLY files used in PlayCanvas.Use calculateComponentStorage(compressionLevel, sphericalHarmonicsDegree) to determine the byte size and component counts for different parts of a splat (center, scale, rotation, color, and spherical harmonics) based on the compression level and SH degree.
const {
bytesPerCenter,
bytesPerScale,
bytesPerRotation,
bytesPerColor,
sphericalHarmonicsComponentsPerSplat,
bytesPerSplat
} = SplatBuffer.calculateComponentStorage(compressionLevel, sphericalHarmonicsDegree);The Viewer provides methods to dynamically adjust rendering parameters during runtime:
setRenderMode(renderMode): Changes the rendering frequency (e.g., RenderMode.Always or RenderMode.OnChange).setActiveSphericalHarmonicsDegrees(degrees): Updates the degree of spherical harmonics used in the shader (0-2).onSplatMeshChanged(callback): Registers a callback that triggers whenever the underlying SplatMesh is updated or changed.Assigns a THREE.WebGLRenderer to the SplatMesh. This is required for texture updates and GPU-based distance computations.
/**
* Set the Three.js renderer used by this splat mesh
* @param {THREE.WebGLRenderer} renderer Instance of THREE.WebGLRenderer
*/
setRenderer(renderer) {
// ... implementation
}countLeaves() to return the total number of leaf nodes currently present in the SplatTree.DropInViewer class is a wrapper for a Viewer instance that extends THREE.Group. This allows you to add a Gaussian splat viewer directly into an existing Three.js scene as if it were a standard Mesh or Object3D. It manages its own internal Viewer and handles the synchronization of splat meshes within the Three.js scene graph.The DropInViewer provides methods to manipulate loaded scenes:
getSplatScene(sceneIndex): Returns the SplatScene at the specified index.removeSplatScene(index, showLoadingUI = true): Removes the scene at the specified index.removeSplatScenes(indexes, showLoadingUI = true): Removes multiple scenes by their indices.getSceneCount(): Returns the number of currently loaded scenes.setActiveSphericalHarmonicsDegrees(activeSphericalHarmonicsDegrees): Sets the active spherical harmonics degrees.dispose(): Asynchronously disposes of the viewer and its resources.