@playcanvas/splat-transform 1.4.0 → 1.5.0

package/README.md

@@ -77,6 +77,8 @@ Actions can be repeated and applied in any order:
 -S, --filter-sphere    <x,y,z,radius>   Remove Gaussians outside sphere (center, radius)
 -V, --filter-value     <name,cmp,value> Keep splats where <name> <cmp> <value>
                                           cmp ∈ {lt,lte,gt,gte,eq,neq}
+-F, --filter-visibility <n|n%>          Keep the n most visible splats (by opacity * volume)
+                                          Use n% to keep a percentage of splats
 -p, --params           <key=val,...>    Pass parameters to .mjs generator script
 -l, --lod              <n>              Specify the level of detail of this model, n >= 0.
 -m, --summary                           Print per-column statistics to stdout
@@ -170,6 +172,12 @@ splat-transform input.ply -V opacity,gt,0.5 output.ply
 
 # Strip spherical harmonic bands higher than 2
 splat-transform input.ply --filter-harmonics 2 output.ply
+
+# Keep only the 50000 most visible splats
+splat-transform input.ply --filter-visibility 50000 output.ply
+
+# Keep the top 25% most visible splats
+splat-transform input.ply -F 25% output.ply
 ```
 
 ### Advanced Usage
@@ -275,6 +283,7 @@ import {
 | `processDataTable` | Apply a sequence of processing actions |
 | `computeSummary` | Generate statistical summary of data |
 | `sortMortonOrder` | Sort indices by Morton code for spatial locality |
+| `sortByVisibility` | Sort indices by visibility score for filtering |
 
 ### File System Abstractions
 
@@ -351,6 +360,7 @@ type ProcessAction =
     | { kind: 'filterBands'; value: 0|1|2|3 }
     | { kind: 'filterBox'; min: Vec3; max: Vec3 }
     | { kind: 'filterSphere'; center: Vec3; radius: number }
+    | { kind: 'filterVisibility'; count: number | null; percent: number | null }
     | { kind: 'lod'; value: number }
     | { kind: 'summary' }
     | { kind: 'mortonOrder' };

package/dist/cli.mjs

@@ -11029,42 +11029,38 @@ class DataTable {
      * After calling, row `i` will contain the data that was previously at row `indices[i]`.
      *
      * This is a memory-efficient alternative to `permuteRows` that modifies the table
-     * in-place rather than creating a copy.
+     * in-place rather than creating a copy. It reuses ArrayBuffers between columns to
+     * minimize memory allocations.
      *
      * @param indices - Array of indices defining the permutation. Must have the same
      * length as the number of rows, and must be a valid permutation
      * (each index 0 to n-1 appears exactly once).
      */
     permuteRowsInPlace(indices) {
-        const n = this.numRows;
-        const numCols = this.columns.length;
-        const visited = new Uint8Array(n);
-        const temps = new Array(numCols);
-        for (let i = 0; i < n; i++) {
-            if (visited[i] || indices[i] === i)
-                continue;
-            // Save values at position i
-            for (let c = 0; c < numCols; c++) {
-                temps[c] = this.columns[c].data[i];
+        // Cache for reusing ArrayBuffers by size
+        const cache = new Map();
+        const getBuffer = (size) => {
+            const cached = cache.get(size);
+            if (cached) {
+                cache.delete(size);
+                return cached;
             }
-            // Walk the cycle
-            let j = i;
-            while (true) {
-                const next = indices[j];
-                visited[j] = 1;
-                if (next === i) {
-                    // End of cycle - place saved values
-                    for (let c = 0; c < numCols; c++) {
-                        this.columns[c].data[j] = temps[c];
-                    }
-                    break;
-                }
-                // Move values from next to j
-                for (let c = 0; c < numCols; c++) {
-                    this.columns[c].data[j] = this.columns[c].data[next];
-                }
-                j = next;
+            return new ArrayBuffer(size);
+        };
+        const returnBuffer = (buffer) => {
+            cache.set(buffer.byteLength, buffer);
+        };
+        const n = this.numRows;
+        for (const column of this.columns) {
+            const src = column.data;
+            const constructor = src.constructor;
+            const dst = new constructor(getBuffer(src.byteLength));
+            // Sequential writes are cache-friendly
+            for (let i = 0; i < n; i++) {
+                dst[i] = src[indices[i]];
             }
+            returnBuffer(src.buffer);
+            column.data = dst;
         }
     }
 }
@@ -11706,6 +11702,62 @@ const sortMortonOrder = (dataTable, indices) => {
     generate(indices);
 };
 
+/**
+ * Sorts the provided indices by visibility score (descending order).
+ *
+ * Visibility is computed as: linear_opacity * volume
+ * where:
+ * - linear_opacity = sigmoid(opacity) = 1 / (1 + exp(-opacity))
+ * - volume = exp(scale_0) * exp(scale_1) * exp(scale_2)
+ *
+ * After calling this function, indices[0] will contain the index of the most
+ * visible splat, indices[1] the second most visible, and so on.
+ *
+ * @param dataTable - The DataTable containing splat data.
+ * @param indices - Array of indices to sort in-place.
+ */
+const sortByVisibility = (dataTable, indices) => {
+    const opacityCol = dataTable.getColumnByName('opacity');
+    const scale0Col = dataTable.getColumnByName('scale_0');
+    const scale1Col = dataTable.getColumnByName('scale_1');
+    const scale2Col = dataTable.getColumnByName('scale_2');
+    if (!opacityCol || !scale0Col || !scale1Col || !scale2Col) {
+        logger.debug('missing required columns for visibility sorting (opacity, scale_0, scale_1, scale_2)');
+        return;
+    }
+    if (indices.length === 0) {
+        return;
+    }
+    const opacity = opacityCol.data;
+    const scale0 = scale0Col.data;
+    const scale1 = scale1Col.data;
+    const scale2 = scale2Col.data;
+    // Compute visibility scores for each splat
+    const scores = new Float32Array(indices.length);
+    for (let i = 0; i < indices.length; i++) {
+        const ri = indices[i];
+        // Convert logit opacity to linear using sigmoid
+        const logitOpacity = opacity[ri];
+        const linearOpacity = 1 / (1 + Math.exp(-logitOpacity));
+        // Convert log scales to linear and compute volume
+        // volume = exp(scale_0) * exp(scale_1) * exp(scale_2) = exp(scale_0 + scale_1 + scale_2)
+        const volume = Math.exp(scale0[ri] + scale1[ri] + scale2[ri]);
+        // Visibility score is opacity * volume
+        scores[i] = linearOpacity * volume;
+    }
+    // Sort indices by score (descending - most visible first)
+    const order = new Uint32Array(indices.length);
+    for (let i = 0; i < order.length; i++) {
+        order[i] = i;
+    }
+    order.sort((a, b) => scores[b] - scores[a]);
+    // Apply the sorted order to indices
+    const tmpIndices = indices.slice();
+    for (let i = 0; i < indices.length; i++) {
+        indices[i] = tmpIndices[order[i]];
+    }
+};
+
 /**
  * Abstract base class for streaming data from a source.
  * Uses a pull-based model where the consumer provides the buffer.
@@ -14299,7 +14351,7 @@ class CompressedChunk {
     }
 }
 
-var version = "1.4.0";
+var version = "1.5.0";
 
 const generatedByString = `Generated by splat-transform ${version}`;
 const chunkProps = [
@@ -16257,6 +16309,24 @@ const processDataTable = (dataTable, processActions) => {
                 result.permuteRowsInPlace(indices);
                 break;
             }
+            case 'filterVisibility': {
+                const indices = new Uint32Array(result.numRows);
+                for (let i = 0; i < indices.length; i++) {
+                    indices[i] = i;
+                }
+                sortByVisibility(result, indices);
+                // Determine how many to keep
+                let keepCount;
+                if (processAction.count !== null) {
+                    keepCount = Math.min(processAction.count, result.numRows);
+                }
+                else {
+                    keepCount = Math.round(result.numRows * (processAction.percent ?? 100) / 100);
+                }
+                keepCount = Math.max(0, keepCount);
+                result = result.permuteRows(indices.subarray(0, keepCount));
+                break;
+            }
         }
     }
     return result;
@@ -16534,6 +16604,7 @@ const parseArguments = async () => {
             'filter-harmonics': { type: 'string', short: 'H', multiple: true },
             'filter-box': { type: 'string', short: 'B', multiple: true },
             'filter-sphere': { type: 'string', short: 'S', multiple: true },
+            'filter-visibility': { type: 'string', short: 'F', multiple: true },
             params: { type: 'string', short: 'p', multiple: true },
             lod: { type: 'string', short: 'l', multiple: true },
             summary: { type: 'boolean', short: 'm', multiple: true },
@@ -16735,6 +16806,31 @@ const parseArguments = async () => {
                         kind: 'mortonOrder'
                     });
                     break;
+                case 'filter-visibility': {
+                    const value = t.value.trim();
+                    let count = null;
+                    let percent = null;
+                    if (value.endsWith('%')) {
+                        // Percentage mode
+                        percent = parseNumber(value.slice(0, -1));
+                        if (percent < 0 || percent > 100) {
+                            throw new Error(`Invalid filter-visibility percentage: ${value}. Must be between 0% and 100%.`);
+                        }
+                    }
+                    else {
+                        // Count mode
+                        count = parseInteger(value);
+                        if (count < 0) {
+                            throw new Error(`Invalid filter-visibility count: ${value}. Must be a non-negative integer.`);
+                        }
+                    }
+                    current.processActions.push({
+                        kind: 'filterVisibility',
+                        count,
+                        percent
+                    });
+                    break;
+                }
             }
         }
     }
@@ -16767,6 +16863,8 @@ ACTIONS (can be repeated, in any order)
     -S, --filter-sphere    <x,y,z,radius>   Remove Gaussians outside sphere (center, radius)
     -V, --filter-value     <name,cmp,value> Keep Gaussians where <name> <cmp> <value>
                                               cmp ∈ {lt,lte,gt,gte,eq,neq}
+    -F, --filter-visibility <n|n%>          Keep the n most visible Gaussians (by opacity * volume)
+                                              Use n% to keep a percentage of Gaussians
     -p, --params           <key=val,...>    Pass parameters to .mjs generator script
     -l, --lod              <n>              Specify the level of detail, n >= 0
     -m, --summary                           Print per-column statistics to stdout