From bf10efcab070305ddaa763007dbee89408c37d31 Mon Sep 17 00:00:00 2001
From: Andreas Sundquist <asundqui@worldlabs.ai>
Date: Fri, 11 Jul 2025 17:09:38 -0700
Subject: [PATCH] Update SplatLoader to handle progress updates, both for main
 file and any extra files, aggregating totals. Misc. improvements to examples.
 (#112)

---
 examples/dynamic-lighting/index.html    |   1 +
 examples/editor/index.html              |   1 +
 examples/envmap/index.html              |   9 +-
 examples/hello-world/index.html         |   1 +
 examples/interactivity/index.html       |   1 +
 examples/multiple-splats/index.html     |  10 +-
 examples/multiple-viewpoints/index.html |   1 +
 examples/particle-simulation/index.html |   2 +
 examples/procedural-splats/index.html   |   1 +
 examples/raycasting/index.html          |   4 +-
 examples/sogs/index.html                |   6 +-
 examples/splat-texture/index.html       |   2 +-
 src/SplatLoader.ts                      | 216 +++++++++++++++---------
 13 files changed, 163 insertions(+), 92 deletions(-)

diff --git a/examples/dynamic-lighting/index.html b/examples/dynamic-lighting/index.html
index 8b4bf1d..27f9843 100644
--- a/examples/dynamic-lighting/index.html
+++ b/examples/dynamic-lighting/index.html
@@ -1,4 +1,5 @@
 <!DOCTYPE html>
+<html>
 
 <head>
   <meta charset="utf-8">
diff --git a/examples/editor/index.html b/examples/editor/index.html
index c1e2287..bf703f1 100644
--- a/examples/editor/index.html
+++ b/examples/editor/index.html
@@ -1,4 +1,5 @@
 <!DOCTYPE html>
+<html>
 
 <head>
   <meta charset="utf-8">
diff --git a/examples/envmap/index.html b/examples/envmap/index.html
index f3ff903..6fea9c5 100644
--- a/examples/envmap/index.html
+++ b/examples/envmap/index.html
@@ -1,4 +1,5 @@
 <!DOCTYPE html>
+<html>
 
 <head>
   <meta charset="utf-8">
@@ -39,7 +40,7 @@
   </script>
   <script type="module">
     import * as THREE from "three";
-    import { SplatMesh, SparkRenderer } from "@sparkjsdev/spark";
+    import { SplatMesh, SparkRenderer, PackedSplats } from "@sparkjsdev/spark";
     import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
     import { getAssetFileURL } from "/examples/js/get-asset-url.js";
 
@@ -55,13 +56,14 @@
     const spark = new SparkRenderer({ renderer });
 
     const splatURL = await getAssetFileURL("fireplace.spz");
-    const background = new SplatMesh({ url: splatURL });
+    const packedSplats = new PackedSplats({ url: splatURL });
+    const background = new SplatMesh({ packedSplats });
     background.quaternion.set(1, 0, 0, 0);
     background.position.set(0.5, 0, -1);
     background.scale.setScalar(0.5);
     scene.add(background);
 
-    const background2 = new SplatMesh({ url: splatURL });
+    const background2 = new SplatMesh({ packedSplats });
     background2.quaternion.set(1, 0, 0, 0);
     background2.rotation.y = Math.PI;
     background2.position.set(-0.5, 0, 0.0);
@@ -81,6 +83,7 @@
     scene.add(duck);
 
     let lastTime;
+    let renderedEnvMap = false;
     renderer.setAnimationLoop(function animate(time) {
       const deltaTime = time - (lastTime || time);
       lastTime = time;
diff --git a/examples/hello-world/index.html b/examples/hello-world/index.html
index 94eab44..d06c72f 100644
--- a/examples/hello-world/index.html
+++ b/examples/hello-world/index.html
@@ -1,4 +1,5 @@
 <!DOCTYPE html>
+<html>
 
 <head>
   <meta charset="utf-8">
diff --git a/examples/interactivity/index.html b/examples/interactivity/index.html
index e009ece..20a278b 100644
--- a/examples/interactivity/index.html
+++ b/examples/interactivity/index.html
@@ -1,4 +1,5 @@
 <!DOCTYPE html>
+<html>
 
 <head>
   <meta charset="utf-8">
diff --git a/examples/multiple-splats/index.html b/examples/multiple-splats/index.html
index 56cfb24..f9509d8 100644
--- a/examples/multiple-splats/index.html
+++ b/examples/multiple-splats/index.html
@@ -1,4 +1,5 @@
 <!DOCTYPE html>
+<html>
 
 <head>
   <meta charset="utf-8">
@@ -34,7 +35,7 @@
   </script>
   <script type="module">
     import * as THREE from "three";
-    import { SplatMesh } from "@sparkjsdev/spark";
+    import { SplatMesh, PackedSplats } from "@sparkjsdev/spark";
     import { EXRLoader } from "three/addons/loaders/EXRLoader.js";
     import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
     import { getAssetFileURL } from "/examples/js/get-asset-url.js";
@@ -49,16 +50,17 @@
     renderer.setClearColor(new THREE.Color(0xFFFFFF), 1);
     document.body.appendChild(renderer.domElement)
 
+    let splatURL = await getAssetFileURL("butterfly-ai.spz");
+    const butterflySplats = new PackedSplats({ url: splatURL });
     const butterflies = [];
     for (let i = 0; i < 6; i++) {
-      let splatURL = await getAssetFileURL("butterfly-ai.spz");
-      const splat = new SplatMesh({ url: splatURL });
+      const splat = new SplatMesh({ packedSplats: butterflySplats });
       splat.quaternion.set(1, 0, 0, 0);
       scene.add(splat);
       butterflies.push(splat);
     }
 
-    let splatURL = await getAssetFileURL("cat.spz");
+    splatURL = await getAssetFileURL("cat.spz");
     const cat = new SplatMesh({ url: splatURL });
     cat.quaternion.set(1, 0, 0, 0);
     cat.scale.setScalar(0.5);
diff --git a/examples/multiple-viewpoints/index.html b/examples/multiple-viewpoints/index.html
index c0c62b2..2456e63 100644
--- a/examples/multiple-viewpoints/index.html
+++ b/examples/multiple-viewpoints/index.html
@@ -1,4 +1,5 @@
 <!DOCTYPE html>
+<html>
 
 <head>
   <meta charset="utf-8">
diff --git a/examples/particle-simulation/index.html b/examples/particle-simulation/index.html
index f77f540..b97bf0e 100644
--- a/examples/particle-simulation/index.html
+++ b/examples/particle-simulation/index.html
@@ -1,4 +1,6 @@
 <!DOCTYPE html>
+<html>
+
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
diff --git a/examples/procedural-splats/index.html b/examples/procedural-splats/index.html
index 3b6aca8..7267993 100644
--- a/examples/procedural-splats/index.html
+++ b/examples/procedural-splats/index.html
@@ -1,4 +1,5 @@
 <!DOCTYPE html>
+<html>
 
 <head>
   <meta charset="utf-8">
diff --git a/examples/raycasting/index.html b/examples/raycasting/index.html
index 3c98628..ffcd212 100644
--- a/examples/raycasting/index.html
+++ b/examples/raycasting/index.html
@@ -1,4 +1,5 @@
 <!DOCTYPE html>
+<html>
 
 <head>
   <meta charset="utf-8">
@@ -47,8 +48,9 @@
     const NUM_ROBOTS = 5;
     const robots = [];
     const splatURL = await getAssetFileURL("robot-head.spz");
+    const packedSplats = new PackedSplats({ url: splatURL });
     for (let i = 0; i < NUM_ROBOTS; i++) {
-      const robot = new SplatMesh({ url: splatURL });
+      const robot = new SplatMesh({ packedSplats });
       robot.rotation.x = Math.PI;
       robot.scale.setScalar(0.2);
       robot.position.set(0, 0, i);
diff --git a/examples/sogs/index.html b/examples/sogs/index.html
index c3e7274..23e9d66 100644
--- a/examples/sogs/index.html
+++ b/examples/sogs/index.html
@@ -1,4 +1,5 @@
 <!DOCTYPE html>
+<html>
 
 <head>
   <meta charset="utf-8">
@@ -25,14 +26,15 @@
     import * as THREE from "three";
     import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
     import { Sky } from 'three/addons/objects/Sky.js';
-    import { SplatMesh, SparkRenderer } from "@sparkjsdev/spark";
+    import { SplatMesh } from "@sparkjsdev/spark";
     import { getAssetFileURL } from "/examples/js/get-asset-url.js";
 
     const scene = new THREE.Scene();
-    const camera = new THREE.PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.1, 1000);
+    const camera = new THREE.PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.01, 1000);
     camera.position.set(0, 1.5, -1.2);
 
     const renderer = new THREE.WebGLRenderer();
+    renderer.setPixelRatio(window.devicePixelRatio);
     renderer.setSize(window.innerWidth, window.innerHeight);
     document.body.appendChild(renderer.domElement);
 
diff --git a/examples/splat-texture/index.html b/examples/splat-texture/index.html
index e5b408b..9eee367 100644
--- a/examples/splat-texture/index.html
+++ b/examples/splat-texture/index.html
@@ -100,7 +100,7 @@
     const spark = new SparkRenderer({
         renderer,
         maxStdDev: 1.0,
-        focalDistance: 0,
+        focalDistance: 4.0,
     });
     const splatTexture = {
         enable: true,
diff --git a/src/SplatLoader.ts b/src/SplatLoader.ts
index 3442f61..d77bde7 100644
--- a/src/SplatLoader.ts
+++ b/src/SplatLoader.ts
@@ -32,87 +32,106 @@ export class SplatLoader extends Loader {
       (this.path ?? "") + (url ?? ""),
     );
 
-    // create request
-    const req = new Request(resolvedURL, {
-      headers: new Headers(this.requestHeader),
-      credentials: this.withCredentials ? "include" : "same-origin",
-    });
-
+    const headers = new Headers(this.requestHeader);
+    const credentials = this.withCredentials ? "include" : "same-origin";
+    const request = new Request(resolvedURL, { headers, credentials });
     let fileType = this.fileType;
 
-    fetch(req)
-      .then(async (response) => {
-        if (!response.ok) {
-          throw new Error(
-            `${response.status} "${response.statusText}" fetching URL: ${resolvedURL}`,
-          );
-        }
-        if (onLoad) {
-          const input = await response.arrayBuffer();
-          const extraFiles: Record<string, ArrayBuffer> = {};
-          const promises = [];
+    this.manager.itemStart(resolvedURL);
 
-          try {
-            const pcSogsJson = tryPcSogs(input);
-            if (this.fileType === SplatFileType.PCSOGS) {
-              if (pcSogsJson === undefined) {
-                throw new Error("Invalid PC SOGS file");
-              }
-            }
+    fetchWithProgress(request, onProgress)
+      .then(async (input) => {
+        const progresses = [
+          new ProgressEvent("progress", {
+            lengthComputable: true,
+            loaded: input.byteLength,
+            total: input.byteLength,
+          }),
+        ];
 
-            if (pcSogsJson !== undefined) {
-              fileType = SplatFileType.PCSOGS;
-              for (const key of ["means", "scales", "quats", "sh0", "shN"]) {
-                const prop = pcSogsJson[key as keyof PcSogsJson];
-                if (prop) {
-                  const files = prop.files;
-                  for (const file of files) {
-                    const fileUrl = new URL(file, resolvedURL).toString();
-                    this.manager.itemStart(fileUrl);
-                    const promise = this.loadExtra(fileUrl)
-                      .then((data) => {
-                        extraFiles[file] = data;
-                      })
-                      .catch((error) => {
-                        this.manager.itemError(fileUrl);
-                        throw error;
-                      })
-                      .finally(() => {
-                        this.manager.itemEnd(fileUrl);
-                      });
-                    promises.push(promise);
-                  }
-                }
-              }
-            }
-
-            await Promise.all(promises);
-            const decoded = await unpackSplats({
-              input,
-              extraFiles,
-              fileType,
-              pathOrUrl: resolvedURL,
+        function updateProgresses() {
+          if (onProgress) {
+            const lengthComputable = progresses.every((p) => {
+              // Either it's computable or no progress yet
+              return p.lengthComputable || (p.loaded === 0 && p.total === 0);
             });
+            const loaded = progresses.reduce((sum, p) => sum + p.loaded, 0);
+            const total = progresses.reduce((sum, p) => sum + p.total, 0);
+            onProgress(
+              new ProgressEvent("progress", {
+                lengthComputable,
+                loaded,
+                total,
+              }),
+            );
+          }
+        }
 
-            if (this.packedSplats) {
-              this.packedSplats.initialize(decoded);
-              onLoad(this.packedSplats);
-            } else {
-              onLoad(new PackedSplats(decoded));
+        const extraFiles: Record<string, ArrayBuffer> = {};
+        const promises = [];
+
+        const pcSogsJson = tryPcSogs(input);
+        if (fileType === SplatFileType.PCSOGS) {
+          if (pcSogsJson === undefined) {
+            throw new Error("Invalid PC SOGS file");
+          }
+        }
+        if (pcSogsJson !== undefined) {
+          fileType = SplatFileType.PCSOGS;
+          for (const key of ["means", "scales", "quats", "sh0", "shN"]) {
+            const prop = pcSogsJson[key as keyof PcSogsJson];
+            if (prop) {
+              for (const file of prop.files) {
+                const fileUrl = new URL(file, resolvedURL).toString();
+                const progressIndex = progresses.length;
+                progresses.push(new ProgressEvent("progress"));
+
+                this.manager.itemStart(fileUrl);
+                const request = new Request(fileUrl, { headers, credentials });
+                const promise = fetchWithProgress(request, (progress) => {
+                  progresses[progressIndex] = progress;
+                  updateProgresses();
+                })
+                  .then((data) => {
+                    extraFiles[file] = data;
+                  })
+                  .catch((error) => {
+                    this.manager.itemError(fileUrl);
+                    throw error;
+                  })
+                  .finally(() => {
+                    this.manager.itemEnd(fileUrl);
+                  });
+                promises.push(promise);
+              }
             }
-          } catch (error) {
-            onError?.(error);
+          }
+        }
+
+        await Promise.all(promises);
+        if (onLoad) {
+          const decoded = await unpackSplats({
+            input,
+            extraFiles,
+            fileType,
+            pathOrUrl: resolvedURL,
+          });
+
+          if (this.packedSplats) {
+            this.packedSplats.initialize(decoded);
+            onLoad(this.packedSplats);
+          } else {
+            onLoad(new PackedSplats(decoded));
           }
         }
       })
       .catch((error) => {
+        this.manager.itemError(resolvedURL);
         onError?.(error);
       })
       .finally(() => {
         this.manager.itemEnd(resolvedURL);
       });
-
-    this.manager.itemStart(resolvedURL);
   }
 
   async loadAsync(
@@ -131,22 +150,62 @@ export class SplatLoader extends Loader {
     });
   }
 
-  async loadExtra(url: string): Promise<ArrayBuffer> {
-    return new Promise((resolve, reject) => {
-      this.fileLoader.load(
-        url,
-        (response) => resolve(response as ArrayBuffer),
-        undefined,
-        (error) => reject(error),
-      );
-    });
-  }
-
   parse(packedSplats: PackedSplats): SplatMesh {
     return new SplatMesh({ packedSplats });
   }
 }
 
+async function fetchWithProgress(
+  request: Request,
+  onProgress?: (event: ProgressEvent) => void,
+) {
+  const response = await fetch(request);
+  if (!response.ok) {
+    throw new Error(
+      `${response.status} "${response.statusText}" fetching URL: ${request.url}`,
+    );
+  }
+  if (!response.body) {
+    throw new Error(`Response body is null for URL: ${request.url}`);
+  }
+
+  const reader = response.body.getReader();
+  const contentLength = Number.parseInt(
+    response.headers.get("Content-Length") || "0",
+  );
+  const total = Number.isNaN(contentLength) ? 0 : contentLength;
+  let loaded = 0;
+  const chunks: Uint8Array[] = [];
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    chunks.push(value);
+    loaded += value.length;
+
+    if (onProgress) {
+      onProgress(
+        new ProgressEvent("progress", {
+          lengthComputable: total !== 0,
+          loaded,
+          total,
+        }),
+      );
+    }
+  }
+
+  // Combine chunks into a single buffer
+  const bytes = new Uint8Array(loaded);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return bytes.buffer;
+}
+
 export enum SplatFileType {
   PLY = "ply",
   SPZ = "spz",
@@ -520,7 +579,6 @@ export class SplatData {
       }
 
       this.maxSplats = targetSplats;
-      // console.log("Reallocated capacity", this.maxSplats);
     }
   }
 
@@ -560,7 +618,6 @@ export class SplatData {
   setSh1(index: number, sh1: Float32Array) {
     if (!this.sh1) {
       this.sh1 = new Float32Array(this.maxSplats * 9);
-      // console.log("setSh1 creating sh1", this.sh1.length);
     }
     for (let j = 0; j < 9; ++j) {
       this.sh1[index * 9 + j] = sh1[j];
@@ -570,7 +627,6 @@ export class SplatData {
   setSh2(index: number, sh2: Float32Array) {
     if (!this.sh2) {
       this.sh2 = new Float32Array(this.maxSplats * 15);
-      // console.log("setSh2 creating sh2", this.sh2.length);
     }
     for (let j = 0; j < 15; ++j) {
       this.sh2[index * 15 + j] = sh2[j];
@@ -580,7 +636,6 @@ export class SplatData {
   setSh3(index: number, sh3: Float32Array) {
     if (!this.sh3) {
       this.sh3 = new Float32Array(this.maxSplats * 21);
-      // console.log("setSh3 creating sh3", this.sh3.length);
     }
     for (let j = 0; j < 21; ++j) {
       this.sh3[index * 21 + j] = sh3[j];
@@ -592,7 +647,6 @@ export async function transcodeSpz(
   input: TranscodeSpzInput,
 ): Promise<{ input: TranscodeSpzInput; fileBytes: Uint8Array }> {
   return await withWorker(async (worker) => {
-    // console.log("withWorker calling transcodeSpz", input);
     const result = (await worker.call("transcodeSpz", input)) as {
       input: TranscodeSpzInput;
       fileBytes: Uint8Array;