Merge pull request #252 from mkkellogg/dev

Release 0.4.2: General Updates

.gitignore

@@ -1,3 +1,4 @@
 dist
 build
 node_modules
+**/*.DS_Store

README.md

@@ -147,12 +147,13 @@ Parameters for `addSplatScene()`
 
 | Parameter | Purpose
 | --- | ---
+| `format` | Force the loader to assume the specified file format when loading a splat scene. This is useful when loading from a URL where there is no file extension. Valid values are defined in the `SceneFormat` enum: `Ply`, `Splat`, and `KSplat`.
 | `splatAlphaRemovalThreshold` | Tells `addSplatScene()` to ignore any splats with an alpha less than the specified value (valid range: 0 - 255). Defaults to `1`.
 | `showLoadingUI` | Displays a loading spinner and/or loading progress bar while the scene is loading.  Defaults to `true`.
 | `position` | Position of the scene, acts as an offset from its default position. Defaults to `[0, 0, 0]`.
 | `rotation` | Rotation of the scene represented as a quaternion, defaults to `[0, 0, 0, 1]` (identity quaternion).
 | `scale` | Scene's scale, defaults to `[1, 1, 1]`.
-| `streamView` | Stream the scene's splat data and allow the scene to be rendered and viewed as the splats are loaded. Option is only valid for `addSplatScene()`, and not for `addSplatScenes()`.
+| `progressiveLoad` | Progressively load the scene's splat data and allow the scene to be rendered and viewed as the splats are loaded. Option is only valid for `addSplatScene()`, and not for `addSplatScenes()`.
 
 <br>
 
@@ -263,17 +264,21 @@ const viewer = new GaussianSplats3D.Viewer({
     'useBuiltInControls': false,
     'ignoreDevicePixelRatio': false,
     'gpuAcceleratedSort': true,
-    'halfPrecisionCovariancesOnGPU': true,
+    `enableSIMDInSort`: true,
     'sharedMemoryForWorkers': true,
     'integerBasedSort': true,
+    'halfPrecisionCovariancesOnGPU': true,
     'dynamicScene': false,
     'webXRMode': GaussianSplats3D.WebXRMode.None,
     'renderMode': GaussianSplats3D.RenderMode.OnChange,
     'sceneRevealMode': GaussianSplats3D.SceneRevealMode.Instant,
     'antialiased': false,
     'focalAdjustment': 1.0,
     'logLevel': GaussianSplats3D.LogLevel.None,
-    'sphericalHarmonicsDegree': 0
+    'sphericalHarmonicsDegree': 0,
+    `enableOptionalEffects`: false,
+    `plyInMemoryCompressionLevel`: 2
+    `freeIntermediateSplatData`: false
 });
 viewer.addSplatScene('<path to .ply, .ksplat, or .splat file>')
 .then(() => {
@@ -293,14 +298,15 @@ Advanced `Viewer` parameters
 | Parameter | Purpose
 | --- | ---
 | `selfDrivenMode` | If `false`, tells the viewer that you will manually call its `update()` and `render()` methods. Defaults to `true`.
-| `useBuiltInControls` | Tells the viewer to use its own camera controls. Defaults to `true`.
 | `renderer` | Pass an instance of a Three.js `Renderer` to the viewer, otherwise it will create its own. Defaults to `undefined`.
 | `camera` | Pass an instance of a Three.js `Camera` to the viewer, otherwise it will create its own. Defaults to `undefined`.
+| `useBuiltInControls` | Tells the viewer to use its own camera controls. Defaults to `true`.
 | `ignoreDevicePixelRatio` | Tells the viewer to pretend the device pixel ratio is 1, which can boost performance on devices where it is larger, at a small cost to visual quality. Defaults to `false`.
 | `gpuAcceleratedSort` | Tells the viewer to use a partially GPU-accelerated approach to sorting splats. Currently this means pre-computation of splat distances from the camera is performed on the GPU. It is recommended that this only be set to `true` when `sharedMemoryForWorkers` is also `true`. Defaults to `false` on mobile devices, `true` otherwise.
-| `halfPrecisionCovariancesOnGPU` | Tells the viewer to use 16-bit floating point values when storing splat covariance data in textures, instead of 32-bit. Defaults to `false`.
+| `enableSIMDInSort` | Enable the usage of SIMD WebAssembly instructions for the splat sort. Default is `true`.
 | `sharedMemoryForWorkers` | Tells the viewer to use shared memory via a `SharedArrayBuffer` to transfer data to and from the sorting web worker. If set to `false`, it is recommended that `gpuAcceleratedSort` be set to `false` as well. Defaults to `true`.
 | `integerBasedSort` | Tells the sorting web worker to use the integer versions of relevant data to compute the distance of splats from the camera. Since integer arithmetic is faster than floating point, this reduces sort time. However it can result in integer overflows in larger scenes so it should only be used for small scenes. Defaults to `true`.
+| `halfPrecisionCovariancesOnGPU` | Tells the viewer to use 16-bit floating point values when storing splat covariance data in textures, instead of 32-bit. Defaults to `false`.
 | `dynamicScene` | Tells the viewer to not make any optimizations that depend on the scene being static. Additionally all splat data retrieved from the viewer's splat mesh will not have their respective scene transform applied to them by default.
 | `webXRMode` | Tells the viewer whether or not to enable built-in Web VR or Web AR. Valid values are defined in the `WebXRMode` enum: `None`, `VR`, and `AR`. Defaults to `None`.
 | `renderMode` | Controls when the viewer renders the scene. Valid values are defined in the `RenderMode` enum: `Always`, `OnChange`, and `Never`. Defaults to `Always`.
@@ -309,6 +315,9 @@ Advanced `Viewer` parameters
 | `focalAdjustment` | Hacky, non-scientific parameter for tweaking focal length related calculations. For scenes with very small gaussians & small details, increasing this value can help improve visual quality. Default value is 1.0.
 | `logLevel` | Verbosity of the console logging. Defaults to `GaussianSplats3D.LogLevel.None`.
 | `sphericalHarmonicsDegree` | Degree of spherical harmonics to utilize in rendering splats (assuming the data is present in the splat scene). Valid values are 0, 1, or 2. Default value is 0.
+| `enableOptionalEffects` | When true, allows for usage of extra properties and attributes during rendering for effects such as opacity adjustment. Default is `false` for performance reasons. These properties are separate from transform properties (scale, rotation, position) that are enabled by the `dynamicScene` parameter.
+| `plyInMemoryCompressionLevel` | Level to compress `.ply` files when loading them for direct rendering (not exporting to `.ksplat`). Valid values are the same as `.ksplat` compression levels (0, 1, or 2). Default is 2.
+| `freeIntermediateSplatData` | When true, the intermediate splat data that is the result of decompressing splat bufffer(s) and used to populate data textures will be freed. This will reduces memory usage, but if that data needs to be modified it will need to be re-populated from the splat buffer(s). Defaults to `false`.
 <br>
 
 ### Creating KSPLAT files

demo/bonsai.html

@@ -43,7 +43,7 @@
     });
     let path = 'assets/data/bonsai/bonsai' + (mode ? '_high' : '') + '.ksplat';
     viewer.addSplatScene(path, {
-      'streamView': true
+      'progressiveLoad': false
     })
     .then(() => {
         viewer.start();

demo/garden.html

@@ -43,7 +43,7 @@
     });
     let path = 'assets/data/garden/garden' + (mode ? '_high' : '') + '.ksplat';
     viewer.addSplatScene(path, {
-      'streamView': true
+      'progressiveLoad': true
     })
     .then(() => {
         viewer.start();

demo/stump.html

@@ -42,7 +42,7 @@
     });
     let path = 'assets/data/stump/stump' + (mode ? '_high' : '') + '.ksplat';
     viewer.addSplatScene(path, {
-      'streamView': true
+      'progressiveLoad': false
     })
     .then(() => {
         viewer.start();

demo/truck.html

@@ -42,7 +42,7 @@
     });
     let path = 'assets/data/truck/truck' + (mode ? '_high' : '') + '.ksplat';
     viewer.addSplatScene(path, {
-      'streamView': true
+      'progressiveLoad': false
     })
     .then(() => {
         viewer.start();

package.json

@@ -4,7 +4,7 @@
         "type": "git",
         "url": "https://github.com/mkkellogg/GaussianSplats3D"
     },
-    "version": "0.4.1",
+    "version": "0.4.2",
     "description": "Three.js-based 3D Gaussian splat viewer",
     "module": "build/gaussian-splats-3d.module.js",
     "main": "build/gaussian-splats-3d.umd.cjs",

src/AbortablePromise.js

@@ -13,13 +13,16 @@ export class AbortablePromise {
 
     constructor(promiseFunc, abortHandler) {
 
-        let promiseResolve;
-        let promiseReject;
+        let resolver;
+        let rejecter;
         this.promise = new Promise((resolve, reject) => {
-            promiseResolve = resolve.bind(this);
-            promiseReject = reject.bind(this);
+            resolver = resolve;
+            rejecter = reject;
         });
 
+        const promiseResolve = resolver.bind(this);
+        const promiseReject = rejecter.bind(this);
+
         const resolve = (...args) => {
             promiseResolve(...args);
         };

src/Constants.js

@@ -5,6 +5,7 @@ export class Constants {
     static BytesPerFloat = 4;
     static BytesPerInt = 4;
     static MaxScenes = 32;
-    static StreamingSectionSize = 524288;
+    static ProgressiveLoadSectionSize = 262144;
+    static ProgressiveLoadSectionDelayDuration = 15;
     static SphericalHarmonics8BitCompressionRange = 3;
 }

src/Util.js

@@ -60,8 +60,8 @@ export const fetchWithProgress = function(path, onProgress, saveChunks = true) {
     const signal = abortController.signal;
     let aborted = false;
     let rejectFunc = null;
-    const abortHandler = () => {
-        abortController.abort();
+    const abortHandler = (reason) => {
+        abortController.abort(reason);
         rejectFunc(new AbortedPromiseError('Fetch aborted.'));
         aborted = true;
     };
@@ -156,3 +156,64 @@ export const getSphericalHarmonicsComponentCountForDegree = (sphericalHarmonicsD
     }
     return 0;
 };
+
+export const nativePromiseWithExtractedComponents = () => {
+    let resolver;
+    let rejecter;
+    const promise = new Promise((resolve, reject) => {
+        resolver = resolve;
+        rejecter = reject;
+    });
+    return {
+        'promise': promise,
+        'resolve': resolver,
+        'reject': rejecter
+    };
+};
+
+export const abortablePromiseWithExtractedComponents = (abortHandler) => {
+    let resolver;
+    let rejecter;
+    if (!abortHandler) {
+        abortHandler = () => {};
+    }
+    const promise = new AbortablePromise((resolve, reject) => {
+        resolver = resolve;
+        rejecter = reject;
+    }, abortHandler);
+    return {
+        'promise': promise,
+        'resolve': resolver,
+        'reject': rejecter
+    };
+};
+
+class Semver {
+    constructor(major, minor, patch) {
+        this.major = major;
+        this.minor = minor;
+        this.patch = patch;
+    }
+
+    toString() {
+        return `${this.major}_${this.minor}_${this.patch}`;
+    }
+}
+
+export function isIOS() {
+    const ua = navigator.userAgent;
+    return ua.indexOf('iPhone') > 0 || ua.indexOf('iPad') > 0;
+}
+
+export function getIOSSemever() {
+    if (isIOS()) {
+        const extract = navigator.userAgent.match(/OS (\d+)_(\d+)_?(\d+)?/);
+        return new Semver(
+            parseInt(extract[1] || 0, 10),
+            parseInt(extract[2] || 0, 10),
+            parseInt(extract[3] || 0, 10)
+        );
+    } else {
+        return null; // or [0,0,0]
+    }
+}