Uniform decimation by default again; the adaptive path moves to --decimate-adaptive

README.md

@@ -118,10 +118,10 @@ Actions execute in the order specified and can be repeated. Any action may appea
                                           opacity, scale_*, f_dc_* use transformed values
                                           (linear opacity 0-1, linear scale, linear color 0-1).
                                           Append _raw for raw PLY values (e.g. opacity_raw).
--d, --decimate         <n|n%>           Simplify, allocating removal by local error (adaptive)
-                                          Use n% for a percentage. --decimate-uniform removes at a uniform
-                                          rate instead (the pre-3.2 algorithm): lower memory, and better on
-                                          uniformly-sized Gaussians.
+-d, --decimate         <n|n%>           Simplify at a uniform rate everywhere
+                                          Use n% for a percentage. --decimate-adaptive allocates removal
+                                          by local error instead: much better on mixed-scale content such
+                                          as skies, at higher memory cost.
                                           Memory-bounded and streaming: scales to scenes of 100M+
                                           Gaussians. Must be the final action, and the output must
                                           be .ply (write a decimated PLY first, then convert in a

src/cli/index.ts

@@ -16,7 +16,7 @@ import {
     DataTable,
     dataTableToChunkSource,
     decimateSource,
-    decimateSourceUniform,
+    decimateSourceAdaptive,
     fmtBytes,
     fmtCount,
     fmtTime,
@@ -127,12 +127,12 @@ const resolveInput = (arg: string): ResolvedInput => {
 // never dispatched as a data operation).
 type CliAction = ProcessAction | { kind: 'lod'; value: number };
 
-// `--decimate` and `--decimate-uniform` both produce a decimate action, so
+// `--decimate` and `--decimate-adaptive` both produce a decimate action, so
 // which decimator to run rides on the action itself rather than on global
 // options — that way it always describes the action actually executed, with no
 // dependence on flag ordering or on the "exactly one decimate action" check.
 // The extra field is stripped before actions reach the library.
-type CliDecimate = Extract<ProcessAction, { kind: 'decimate' }> & { uniform: boolean };
+type CliDecimate = Extract<ProcessAction, { kind: 'decimate' }> & { adaptive: boolean };
 
 // Strip the CLI-only lod tags, narrowing back to dispatchable actions.
 const stripLodTags = (actions: CliAction[]): ProcessAction[] => {
@@ -199,7 +199,7 @@ const cliOptionsConfig = {
     'filter-box': { type: 'string', short: 'B', multiple: true },
     'filter-sphere': { type: 'string', short: 'S', multiple: true },
     'decimate': { type: 'string', short: 'd', multiple: true },
-    'decimate-uniform': { type: 'string', multiple: true },
+    'decimate-adaptive': { type: 'string', multiple: true },
     'filter-cluster': { type: 'string', short: 'C', multiple: true },
     'filter-floaters': { type: 'string', short: 'F', multiple: true },
     params: { type: 'string', short: 'p', multiple: true },
@@ -704,7 +704,7 @@ const parseArguments = async () => {
                     });
                     break;
                 case 'decimate':
-                case 'decimate-uniform': {
+                case 'decimate-adaptive': {
                     const value = t.value.trim();
                     let count: number | null = null;
                     let percent: number | null = null;
@@ -727,7 +727,7 @@ const parseArguments = async () => {
                         kind: 'decimate',
                         count,
                         percent,
-                        uniform: t.name === 'decimate-uniform'
+                        adaptive: t.name === 'decimate-adaptive'
                     };
                     current.processActions.push(decimate);
                     break;
@@ -806,12 +806,12 @@ ACTIONS (executed in order; can be repeated)
     -S, --filter-sphere    <x,y,z,radius>   Remove Gaussians outside sphere
     -V, --filter-value     <name,cmp,value> Keep Gaussians where <name> <cmp> <value>;
                                               cmp ∈ {lt,lte,gt,gte,eq,neq}
-    -d, --decimate         <n|n%>           Simplify, allocating removal by local error (adaptive; default).
-                                              Much better on mixed-scale content such as skies.
-        --decimate-uniform <n|n%>           Simplify at a uniform rate everywhere (the pre-3.2 algorithm).
+    -d, --decimate         <n|n%>           Simplify at a uniform rate everywhere (default).
                                               Lower memory, and better at depth on uniformly-sized
                                               Gaussians: uniform texture, single objects, snow.
-                                              Must be the final action, and the output must be .ply
+        --decimate-adaptive <n|n%>          Simplify, allocating removal by local error (adaptive).
+                                              Much better on mixed-scale content such as skies.
+                                              Either must be the final action, with a .ply output
         --scratch-dir      <path>           Directory for decimation spill files (deep targets on huge
                                               scenes). Default: the output file's directory
     -F, --filter-floaters  [size,op,min]    Remove Gaussians not contributing to any solid voxel. Default: 0.05,0.1,0.004
@@ -1279,8 +1279,8 @@ const main = async () => {
                     scratchDir: options.scratchDir ?? dirname(outputFilename),
                     remove: (path: string) => unlink(path)
                 };
-                combined = decimateAction.uniform ?
-                    await decimateSourceUniform(combined, pool, {
+                combined = decimateAction.adaptive ?
+                    await decimateSourceAdaptive(combined, pool, {
                         targetCount: keepCount,
                         createDevice: deviceCreator,
                         memoryBudgetBytes: options.memoryBudgetBytes,

src/lib/decimate-uniform/README.md

@@ -1,8 +1,8 @@
 # decimate-uniform — the pre-3.2 decimator
 
-The decimator that shipped up to 3.1.x, reached through `--decimate-uniform` /
-`decimateSourceUniform()`. `src/lib/decimate/` holds the adaptive one
-(`--decimate` / `decimateSource()`).
+The decimator that shipped up to 3.1.x and the default again, reached through
+`--decimate` / `decimateSource()`. `src/lib/decimate/` holds the adaptive one
+(`--decimate-adaptive` / `decimateSourceAdaptive()`).
 
 The names describe how each allocates removal, not a ranking. Both are
 supported and neither is a fallback for the other: they win on different
@@ -65,8 +65,8 @@ to be deliberate rather than incidental. Before landing one:
 
 - Re-run the whole-scene comparison if you expect output to be unchanged. That
   is what `tools/decimate-parity.mjs` is for — it chains halvings through a
-  reference binary's `--decimate` and this tree's `--decimate-uniform`, compares
-  byte for byte, reports PSNR for both, and exits non-zero on any mismatch:
+  reference binary's `--decimate` and this tree's `--decimate`, compares byte
+  for byte, reports PSNR for both, and exits non-zero on any mismatch:
 
   ```bash
   node tools/decimate-parity.mjs sky --ref splat-transform
@@ -85,7 +85,7 @@ to be deliberate rather than incidental. Before landing one:
 
 ## If it is ever retired
 
-Nothing in `src/lib/decimate/` refers to this directory, so: `rm -rf` it, drop
-`decimateSourceUniform` from `src/lib/index.ts`, drop `--decimate-uniform`
-from the CLI, and delete `test/decimate-uniform-parity.test.mjs` and
+Nothing in `src/lib/decimate/` refers to this directory, so: `rm -rf` it, point
+`decimateSource` in `src/lib/index.ts` and `--decimate` in the CLI back at the
+adaptive path, and delete `test/decimate-uniform-parity.test.mjs` and
 `tools/decimate-parity.mjs`.

src/lib/decimate-uniform/gpu-knn.ts

@@ -18,7 +18,7 @@ import {
 import { type FlatKdTree } from '../spatial/kd-tree';
 
 /**
- * Block-local GPU KNN for `--decimate-uniform`.
+ * Block-local GPU KNN for `--decimate`.
  *
  * Separate from the quality path's `gpu/gpu-knn.ts` because the two have
  * incompatible models: this one takes a max size and accepts a DIFFERENT tree

src/lib/decimate-uniform/index.ts

@@ -1,8 +1,4 @@
-// The pre-3.2 decimator — see README.md. Its `decimateSource` is exported
-// under the `Uniform` name so the two paths can coexist without renaming
-// anything inside this directory.
-export {
-    decimateSource as decimateSourceUniform,
-    type DecimateOptions as DecimateUniformOptions,
-    type DecimateSpill as DecimateUniformSpill
-} from './decimate-source';
+// The pre-3.2 decimator, reached through `--decimate` / `decimateSource()` —
+// see README.md. The adaptive path (`--decimate-adaptive`) is exported under
+// the `Adaptive` name from ../decimate/.
+export { decimateSource, type DecimateOptions, type DecimateSpill } from './decimate-source';

src/lib/decimate/decimate-source.ts

@@ -318,7 +318,7 @@ const decimateSource = async (
                 if (!device) {
                     throw new Error(
                         `multi-block adaptive decimation requires WebGPU (${fmtCount(N)} splats, ` +
-                    `${fmtCount(blockSize)}-splat cores); provide a device, or use --decimate-uniform`
+                    `${fmtCount(blockSize)}-splat cores); provide a device, or use --decimate`
                     );
                 }
                 if (!opts.spill) {

src/lib/decimate/index.ts

@@ -1,3 +1,11 @@
-export { decimateSource, type DecimateOptions, type DecimateSpill } from './decimate-source';
+// The adaptive decimator (`--decimate-adaptive`). Its `decimateSource` is
+// exported under the `Adaptive` name so the two paths can coexist without
+// renaming anything inside this directory; `decimateSource` is the pre-3.2
+// path in ../decimate-uniform/.
+export {
+    decimateSource as decimateSourceAdaptive,
+    type DecimateOptions as DecimateAdaptiveOptions,
+    type DecimateSpill as DecimateAdaptiveSpill
+} from './decimate-source';
 export { mergeGroup, createMergeScratch, splatMass, makeGaussianSamples, type SplatView, type MergedOut, type MergeScratch } from './moment-match';
 export { kdPartition, coherenceRuns, type BlockRange, type ResidentPositions } from './partition';

src/lib/decimate/priority.ts

@@ -35,7 +35,7 @@ type CandidateArrays = {
 /**
  * Colour components the pass gathers per row. The field-L2 cost reads only
  * DC, so at SH band 3 this is 16× less colour RAM and copy traffic per block
- * than gathering every band. (`--decimate-uniform` scores full SH and has its
+ * than gathering every band. (`--decimate` scores full SH and has its
  * own pass — see lib/decimate-uniform/priority.ts.)
  */
 const COLOR_COMPONENTS = 3;

src/lib/index.ts

@@ -43,14 +43,14 @@ export type {
     Decimate
 } from './process';
 
-// Chunk-native decimation
-export { decimateSource } from './decimate';
-export type { DecimateOptions, DecimateSpill } from './decimate';
-
-// The frozen pre-3.2 decimator (--decimate-uniform); see
-// lib/decimate-uniform/README.md
-export { decimateSourceUniform } from './decimate-uniform';
-export type { DecimateUniformOptions, DecimateUniformSpill } from './decimate-uniform';
+// Chunk-native decimation (--decimate): the frozen pre-3.2 decimator, which
+// removes at a uniform rate everywhere; see lib/decimate-uniform/README.md
+export { decimateSource } from './decimate-uniform';
+export type { DecimateOptions, DecimateSpill } from './decimate-uniform';
+
+// The adaptive decimator (--decimate-adaptive), allocating removal by local error
+export { decimateSourceAdaptive } from './decimate';
+export type { DecimateAdaptiveOptions, DecimateAdaptiveSpill } from './decimate';
 
 // Statistics
 export { computeStats } from './stats';

src/lib/process.ts

@@ -3,7 +3,7 @@ import { Vec3 } from 'playcanvas';
 import { createChunkDataPool } from './chunk';
 import { dataTableToChunkSource, materializeToDataTable } from './compat/data-table';
 import { Column, DataTable, sortMortonOrder, convertToSpace, getSHBands } from './data-table';
-import { decimateSource } from './decimate';
+import { decimateSource } from './decimate-uniform';
 import { computeSourceStats } from './ops';
 import { type InputFormat } from './read';
 import { formatSourceInfo, formatSourceStats } from './source-info';
@@ -158,6 +158,9 @@ type MortonOrder = {
  * Instead of discarding low-visibility splats, this iteratively merges nearby
  * similar splats into single approximating Gaussians using Mass-Preserving
  * Moment Matching (MPMM), preserving scene structure and appearance.
+ *
+ * Removal is allocated at a uniform rate everywhere; for the adaptive variant
+ * call `decimateSourceAdaptive()` directly.
  */
 type Decimate = {
     /** Action type identifier. */

src/lib/workers/tasks.ts

@@ -103,7 +103,7 @@ const taskHandlers = {
     },
 
     // Build + flatten a KD-tree over interleaved LOCAL positions (the
-    // `--decimate-uniform` GPU path: node splat ids stay local and the
+    // `--decimate` GPU path: node splat ids stay local and the
     // flattened arrays upload straight into that path's GpuKnn). Serves
     // decimate-uniform/ — see its README before changing either handler.
     flattenKdTree: (args: { positions: Float32Array }): TaskOutput<FlatKdTree> => {
@@ -125,7 +125,7 @@ const taskHandlers = {
         };
     },
 
-    // `--decimate-uniform` CPU-fallback block KNN: exact k-NN of the owned
+    // `--decimate` CPU-fallback block KNN: exact k-NN of the owned
     // prefix within the local point set, as local indices. Frozen.
     knnBlock: (args: { positions: Float32Array, ownedCount: number, k: number }): TaskOutput<Uint32Array> => {
         const result = knnQueryBlock(args.positions, args.ownedCount, args.k);

test/cli.test.mjs

@@ -185,17 +185,17 @@ describe('CLI decimate (terminal PLY restriction)', () => {
         assert.strictEqual(written, Math.round(inputCount / 2), `50% of ${inputCount}`);
     });
 
-    it('--decimate-uniform runs the pre-3.2 algorithm', async () => {
+    it('--decimate-adaptive runs the adaptive algorithm', async () => {
         const { mkdtemp, readFile: readFileFs, rm } = await import('node:fs/promises');
         const { tmpdir } = await import('node:os');
         const { join } = await import('node:path');
-        const dir = await mkdtemp(join(tmpdir(), 'st-decimate-uniform-cli-'));
+        const dir = await mkdtemp(join(tmpdir(), 'st-decimate-adaptive-cli-'));
         const balancedPath = join(dir, 'balanced.ply');
 
         const balanced = await runCli([
             '--gpu', 'cpu',
             'test/fixtures/splat/minimal.splat',
-            '--decimate-uniform', '50%',
+            '--decimate-adaptive', '50%',
             balancedPath
         ]);
         assert.strictEqual(balanced.code, 0, `balanced CLI failed:\n${balanced.stderr}\n${balanced.stdout}`);

test/decimate-multiblock.test.mjs

@@ -3,7 +3,7 @@ import { after, before, describe, it } from 'node:test';
 
 import { makeSyntheticSource } from './helpers/synthetic-source.mjs';
 
-import { decimateSource } from '../src/lib/decimate/index.js';
+import { decimateSourceAdaptive } from '../src/lib/decimate/index.js';
 import { MemoryReadSource } from '../src/lib/io/read/memory-file-system.js';
 import { MemoryFileSystem } from '../src/lib/io/write/memory-file-system.js';
 
@@ -22,11 +22,11 @@ after(() => {
     device?.destroy?.();
 });
 
-describe('decimateSource multi-block adaptive path', () => {
+describe('decimateSourceAdaptive multi-block adaptive path', () => {
     it('fails clearly when the memory budget requires multiple blocks without WebGPU', async () => {
         const { source, pool } = await makeSyntheticSource(65540, 0, 123, { chunkSize: 1024 });
         await assert.rejects(
-            decimateSource(source, pool, { targetCount: 65000, memoryBudgetBytes: 1 }),
+            decimateSourceAdaptive(source, pool, { targetCount: 65000, memoryBudgetBytes: 1 }),
             /multi-block adaptive decimation requires WebGPU/
         );
     });
@@ -55,7 +55,7 @@ describe('decimateSource multi-block adaptive path', () => {
             }
         };
 
-        const out = await decimateSource(source, pool, {
+        const out = await decimateSourceAdaptive(source, pool, {
             targetCount,
             createDevice: async () => device,
             memoryBudgetBytes: 1,