Implementation PC SOGS file format loading via meta.json root file. Added webp dependency for accurate decoding. Updated viewer and editor to accept new file type. (#73)

asundqui · web-flow · commit 36c3c61d0bbf · 2025-06-30T08:57:51.000-07:00
diff --git a/examples/editor/index.html b/examples/editor/index.html
@@ -68,7 +68,7 @@
     import * as THREE from "three";
     import { OrbitControls } from "three/addons/controls/OrbitControls.js";
     import { GUI } from "lil-gui";
-    import { constructGrid, SparkControls, SparkRenderer, SplatMesh, textSplats, dyno, transcodeSpz } from "@sparkjsdev/spark";
+    import { constructGrid, SparkControls, SparkRenderer, SplatMesh, textSplats, dyno, transcodeSpz, isPcSogs } from "@sparkjsdev/spark";
     import { getAssetFileURL } from "/examples/js/get-asset-url.js";
 
     const scene = new THREE.Scene();
@@ -154,7 +154,7 @@
             loadFiles(urls);
             guiOptions.loadFromText = ""; // Clear after loading
           } else {
-            alert("No valid URLs found in text. URLs must start with http:// or https:// and end with .ply, .spz, .splat, or .ksplat");
+            alert("No valid URLs found in text. URLs must start with http:// or https:// and end with .ply, .spz, .splat, .ksplat, or .json");
           }
         }
       },
@@ -357,6 +357,7 @@
         try {
           let fileBytes;
           let fileName;
+          let url = null;
 
           // Check if splatFile is a URL string or a File object
           if (typeof splatFile === "string") {
@@ -365,6 +366,10 @@
             fileBytes = new Uint8Array(await fetchWithProgress(splatFile));
             // Extract filename from URL
             fileName = splatFile.split("/").pop().split("?")[0] || "downloaded-file";
+
+            if (isPcSogs(fileBytes)) {
+              url = splatFile;
+            }
           } else {
             // It's a File object
             fileBytes = new Uint8Array(await splatFile.arrayBuffer());
@@ -375,14 +380,18 @@
             writeOptions.filename = fileName.split(".")[0];
           }
 
-          const splatMesh = new SplatMesh({ fileBytes: fileBytes.slice(), fileName });
+          const init = url ? { url } : { fileBytes: fileBytes.slice(), fileName };
+          const splatMesh = new SplatMesh(init);
           const translate = guiOptions.loadOffset * index
           splatMesh.position.set(translate, 0.5 * translate, 0.1 * translate);
           splatMesh.enableWorldToView = true;
           splatMesh.worldModifier = makeWorldModifier(splatMesh);
           await splatMesh.initialized;
 
-          inputs.push({ fileBytes, pathOrUrl: fileName, object: splatMesh });
+          if (!url) {
+            // PC SOGS transcode not supported yet
+            inputs.push({ fileBytes, pathOrUrl: fileName, object: splatMesh });
+          }
           frame.add(splatMesh);
           console.log(`Loaded ${fileName} with ${splatMesh.numSplats} splats`);
 
@@ -659,7 +668,7 @@
 
     // Parse URLs from text (handles single URLs, multiple lines, mixed content)
     function parseURLsFromText(text) {
-      const supportedExtensions = [".ply", ".spz", ".splat", ".ksplat"];
+      const supportedExtensions = [".ply", ".spz", ".splat", ".ksplat", ".json"];
       const urls = [];
 
       // Split by lines, commas, and semicolons
diff --git a/examples/viewer/index.html b/examples/viewer/index.html
@@ -263,15 +263,17 @@
       loadSplatFile(event.target.files[0]);
     };
 
-    var loadedSplat;
     async function loadSplatFile(splatFile) {
-      const reader = new FileReader();
       fileBytes = new Uint8Array(await splatFile.arrayBuffer());
       fileName = splatFile.name;
+      setSplatFile({ fileBytes: fileBytes.slice(), fileName });
+    }
 
+    var loadedSplat;
+    function setSplatFile(init) {
       if (loadedSplat) { scene.remove(loadedSplat); }
 
-      loadedSplat = new SplatMesh({ fileBytes: fileBytes.slice(), fileName });
+      loadedSplat = new SplatMesh(init);
       loadedSplat.quaternion.set(1, 0, 0, 0);
       scene.add(loadedSplat);
 
@@ -289,12 +291,7 @@
       fileName = splatURL.split("/").pop().split("?")[0];
       document.querySelector('.container').classList.add('hidden');
       document.querySelector('.canvas-container').classList.remove('invisible');
-      fetch(splatURL)
-        .then(res => res.blob())
-        .then(blob => {
-          loadSplatFile(blob);
-        })
-        .catch(err => console.error('Download failed:', err));
+      setSplatFile({ url: splatURL });
     }
 
     const urlFormEl = document.querySelector('.url-form');
diff --git a/package.json b/package.json
@@ -58,6 +58,7 @@
     "spark-internal-rs": "file:rust/spark-internal-rs/pkg"
   },
   "dependencies": {
+    "@jsquash/webp": "^1.5.0",
     "fflate": "^0.8.2"
   },
   "keywords": ["3d", "three.js", "gsplats", "3dgs", "gaussian", "splats"]
diff --git a/src/PackedSplats.ts b/src/PackedSplats.ts
@@ -1,7 +1,7 @@
 import * as THREE from "three";
 
 import type { GsplatGenerator } from "./SplatGenerator";
-import { type SplatFileType, unpackSplats } from "./SplatLoader";
+import { type SplatFileType, SplatLoader, unpackSplats } from "./SplatLoader";
 import { SPLAT_TEX_HEIGHT, SPLAT_TEX_WIDTH } from "./defines";
 import {
   DynoProgram,
@@ -120,27 +120,20 @@ export class PackedSplats {
   }
 
   async asyncInitialize(options: PackedSplatsOptions) {
-    let { url, fileBytes, construct } = options;
+    const { url, fileBytes, construct } = options;
     if (url) {
-      fileBytes = await fetch(url).then(async (response) => {
-        if (!response.ok) {
-          throw new Error(
-            `${response.status} "${response.statusText}" fetching URL: ${url}`,
-          );
-        }
-        const arrayBuffer = await response.arrayBuffer();
-        return arrayBuffer;
-      });
-    }
-
-    if (fileBytes) {
+      const loader = new SplatLoader();
+      loader.packedSplats = this;
+      await loader.loadAsync(url);
+    } else if (fileBytes) {
       const unpacked = await unpackSplats({
         input: fileBytes,
         fileType: options.fileType,
         pathOrUrl: options.fileName ?? url,
       });
       this.initialize(unpacked);
     }
+
     if (construct) {
       const maybePromise = construct(this);
       // If construct returns a promise, wait for it to complete
diff --git a/src/SplatLoader.ts b/src/SplatLoader.ts
@@ -14,6 +14,7 @@ import { decompressPartialGzip, getTextureSize } from "./utils";
 export class SplatLoader extends Loader {
   fileLoader: FileLoader;
   fileType?: SplatFileType;
+  packedSplats?: PackedSplats;
 
   constructor(manager?: LoadingManager) {
     super(manager);
@@ -37,12 +38,61 @@ export class SplatLoader extends Loader {
       async (response) => {
         if (onLoad) {
           const input = response as ArrayBuffer;
-          const decoded = await unpackSplats({
-            input,
-            fileType: this.fileType,
-            pathOrUrl: url,
-          });
-          onLoad(new PackedSplats(decoded));
+          const extraFiles: Record<string, ArrayBuffer> = {};
+          const promises = [];
+          let fileType = this.fileType;
+
+          try {
+            const pcSogsJson = tryPcSogs(input);
+            if (this.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) {
+                  const files = prop.files;
+                  for (const file of files) {
+                    const fileUrl = new URL(file, url).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: url,
+            });
+
+            if (this.packedSplats) {
+              this.packedSplats.initialize(decoded);
+              onLoad(this.packedSplats);
+            } else {
+              onLoad(new PackedSplats(decoded));
+            }
+          } catch (error) {
+            onError?.(error);
+          }
         }
       },
       onProgress,
@@ -66,6 +116,17 @@ 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 });
   }
@@ -76,6 +137,7 @@ export enum SplatFileType {
   SPZ = "spz",
   SPLAT = "splat",
   KSPLAT = "ksplat",
+  PCSOGS = "pcsogs",
 }
 
 export function getSplatFileType(
@@ -133,12 +195,96 @@ export function getSplatFileTypeFromPath(
   return undefined;
 }
 
+export type PcSogsJson = {
+  means: {
+    shape: number[];
+    dtype: string;
+    mins: number[];
+    maxs: number[];
+    files: string[];
+  };
+  scales: {
+    shape: number[];
+    dtype: string;
+    mins: number[];
+    maxs: number[];
+    files: string[];
+  };
+  quats: { shape: number[]; dtype: string; encoding?: string; files: string[] };
+  sh0: {
+    shape: number[];
+    dtype: string;
+    mins: number[];
+    maxs: number[];
+    files: string[];
+  };
+  shN: {
+    shape: number[];
+    dtype: string;
+    mins: number;
+    maxs: number;
+    quantization: number;
+    files: string[];
+  };
+};
+
+export function isPcSogs(input: ArrayBuffer | Uint8Array | string): boolean {
+  // Returns true if the input seems to be a valid PC SOGS file
+  return tryPcSogs(input) !== undefined;
+}
+
+export function tryPcSogs(
+  input: ArrayBuffer | Uint8Array | string,
+): PcSogsJson | undefined {
+  // Try to parse input as SOGS JSON and see if it's valid
+  try {
+    let text: string;
+    if (typeof input === "string") {
+      text = input;
+    } else {
+      const fileBytes =
+        input instanceof ArrayBuffer ? new Uint8Array(input) : input;
+      if (fileBytes.length > 65536) {
+        // Should be only a few KB, definitely not a SOGS JSON file
+        return undefined;
+      }
+      text = new TextDecoder().decode(fileBytes);
+    }
+
+    const json = JSON.parse(text);
+    if (!json || typeof json !== "object" || Array.isArray(json)) {
+      return undefined;
+    }
+    for (const key of ["means", "scales", "quats", "sh0"]) {
+      if (
+        !json[key] ||
+        typeof json[key] !== "object" ||
+        Array.isArray(json[key])
+      ) {
+        return undefined;
+      }
+      if (!json[key].shape || !json[key].files) {
+        return undefined;
+      }
+      if (key !== "quats" && (!json[key].mins || !json[key].maxs)) {
+        return undefined;
+      }
+    }
+    // This is probably a PC SOGS file
+    return json as PcSogsJson;
+  } catch {
+    return undefined;
+  }
+}
+
 export async function unpackSplats({
   input,
+  extraFiles,
   fileType,
   pathOrUrl,
 }: {
   input: Uint8Array | ArrayBuffer;
+  extraFiles?: Record<string, ArrayBuffer>;
   fileType?: SplatFileType;
   pathOrUrl?: string;
 }): Promise<{
@@ -201,7 +347,7 @@ export async function unpackSplats({
         return { packedArray, numSplats };
       });
     }
-    case SplatFileType.KSPLAT:
+    case SplatFileType.KSPLAT: {
       return await withWorker(async (worker) => {
         const { packedArray, numSplats, extra } = (await worker.call(
           "decodeKsplat",
@@ -213,6 +359,20 @@ export async function unpackSplats({
         };
         return { packedArray, numSplats, extra };
       });
+    }
+    case SplatFileType.PCSOGS: {
+      return await withWorker(async (worker) => {
+        const { packedArray, numSplats, extra } = (await worker.call(
+          "decodePcSogs",
+          { fileBytes, extraFiles },
+        )) as {
+          packedArray: Uint32Array;
+          numSplats: number;
+          extra: Record<string, unknown>;
+        };
+        return { packedArray, numSplats, extra };
+      });
+    }
     default: {
       throw new Error(`Unknown splat file type: ${splatFileType}`);
     }
diff --git a/src/index.ts b/src/index.ts
@@ -8,6 +8,7 @@ export {
   unpackSplats,
   SplatFileType,
   getSplatFileType,
+  isPcSogs,
 } from "./SplatLoader";
 export { PlyReader } from "./ply";
 export { SpzReader, SpzWriter, transcodeSpz } from "./spz";
diff --git a/src/pcsogs.ts b/src/pcsogs.ts
diff --git a/src/utils.ts b/src/utils.ts
diff --git a/src/worker.ts b/src/worker.ts
