Initial commit

docs/loading-splats.md

@@ -0,0 +1,86 @@
+# Loading Gsplats
+
+Forge provides loaders for most popular Gsplat file formats, including `.ply` (original "gsplat" format, some compressed variants, and plain x/y/z/r/g/b point clouds) and `.spz` (Niantic open source compressed format), both auto-detected from the file contents.
+
+Forge can also load popular formats `.splat` (from `antimatter15/splat`) and `.ksplat` (from `mkkellogg/GaussianSplats3D`) if the file type can be inferred from the URL/path extension, or set explicitly using the `fileType` property when creating a `SplatMesh` or `PackedSplats`.
+
+## Loading auto-detectable formats `.ply` and `.spz`
+
+Adding an individual `SplatMesh` from an auto-detectable format is easy and can be done as simply as below:
+
+```javascript
+// Load and create SplatMesh in one go
+const splats = new SplatMesh({ url: "./butterfly.ply" });
+scene.add(splats);
+
+scene.add(new SplatMesh({ url: "plyBin/0123456789abcdef" }));
+scene.add(new SplatMesh({ url: "spzBin/fedcba9876543210" }));
+```
+
+### Load via `PackedSplats`
+
+Alternatively, you can load a `.ply` or `.spz` into a `PackedSplats`, which can then be used as an input source for multiple `SplatMesh` instances in the scene.
+
+```javascript
+const packedSplats = new PackedSplats({ url: "./clone.ply" });
+
+const splats1 = new SplatMesh({ packedSplats });
+scene.add(splats1);
+
+const splats2 = new SplatMesh({ packedSplats });
+scene.add(splats2);
+```
+
+### Load via `SplatLoader`
+
+Finally, you can make use of the `THREE.Loader` infrastructure via the `SplatLoader` class. A `Loader` has a synchronous and asynchronous interface. You can provide progress meters during downloads and invoke completion callbacks as follows:
+
+```javascript
+const loader = new SplatLoader();
+loader.loadAsync(url, (event) => {
+  if (event.type === "progress") {
+    const progress = event.lengthComputable
+      ? `${((event.loaded / event.total) * 100).toFixed(2)}%`
+      : `${event.loaded} bytes`;
+    console.log(`Background download progress: ${progress}`);
+  }
+})
+.then((packedSplats) => {
+  const splatMesh = new SplatMesh({ packedSplats });
+  // Re-orient from OpenCV to OpenGL coordinates
+  splatMesh.quaternion.set(1, 0, 0, 0);
+  splatMesh.position.set(0, 0, -1);
+  splatMesh.scale.setScalar(0.5);
+  scene.add(splatMesh);
+})
+.catch((error) => {
+  console.warn(error);
+});
+```
+
+## Loading additional formats `.splat` and `.ksplat`
+
+These formats are reliably auto-detected from the file contents, so we use two fall-back mechanism to enable support for these popular formats.
+
+First, the auto-detection fails on these files, which triggers file type inference via URL/path file extension. If the URL contains the `.splat` or `.ksplat` extensions (stripping out query parameters etc.), we set the corresponding file type.
+
+```javascript
+const splats = new SplatMesh({ url: "./butterfly.splats" });
+scene.add(splats);
+
+const ksplats = new SplatMesh({ url: "./butterfly.ksplats" });
+scene.add(ksplats);
+```
+If the URL contains a path with no obvious file extension, you can set the field `fileType` when constructing a `SplatMesh` or `PackedSplats`.
+
+```javascript
+scene.add(new SplatMesh({
+  url: "splatBin/0123456789abcdef",
+  fileType: SplatFileType.SPLAT,
+}));
+
+scene.add(new SplatMesh({
+  url: "ksplatBin/fedcba9876543210",
+  fileType: SplatFileType.KSPLAT,
+}));
+```