@playcanvas/splat-transform 1.4.1 → 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

@@ -11702,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.
@@ -14295,7 +14351,7 @@ class CompressedChunk {
     }
 }
 
-var version = "1.4.1";
+var version = "1.5.0";
 
 const generatedByString = `Generated by splat-transform ${version}`;
 const chunkProps = [
@@ -16253,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;
@@ -16530,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 },
@@ -16731,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;
+                }
             }
         }
     }
@@ -16763,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