@playcanvas/splat-transform 0.2.0 → 0.3.0

package/README.md

@@ -22,7 +22,7 @@ splat-transform input_a.ply input_b.ply output/meta.json
 The input and output files can optionally be transformed. For example:
 ```
 # load input.ply and translate it by (1, 0, 0) and write the result to output.ply
-splat-transform input.ply --t 1,0,0 output.ply
+splat-transform input.ply -t 1,0,0 output.ply
 
 # remove entries containing NaN and Inf and bands larger than 2
 splat-transform input.ply output.ply --filterNaN --filterBands 2
@@ -37,8 +37,3 @@ The full list of possible actions are as follows:
 -filterByValue -c name,comparator,value     Filter gaussians by a value. Specify the value name, comparator (lt, lte, gt, gte, eq, neq) and value
 -filterBands   -h 1                         Filter spherical harmonic band data. Value must be 0, 1, 2 or 3.
 ```
-
-## Note
-This very first version supports the following:
-- reading gaussian splat ply files containing only float32 data
-- writing PlayCanvas' compressed.ply format

package/dist/index.mjs

@@ -1881,7 +1881,7 @@ class Quat {
 		}
 }
 
-var version = "0.2.0";
+var version = "0.3.0";
 
 class Column {
     name;
@@ -2770,6 +2770,23 @@ const writeCompressedPly = async (fileHandle, dataTable) => {
     await fileHandle.write(shData);
 };
 
+const writeCsv = async (fileHandle, dataTable) => {
+    const len = dataTable.numRows;
+    // write header
+    await fileHandle.write(`${dataTable.columnNames.join(',')}\n`);
+    const columns = dataTable.columns.map(c => c.data);
+    // write rows
+    for (let i = 0; i < len; ++i) {
+        let row = '';
+        for (let c = 0; c < dataTable.columns.length; ++c) {
+            if (c)
+                row += ',';
+            row += columns[c][i];
+        }
+        await fileHandle.write(`${row}\n`);
+    }
+};
+
 const columnTypeToPlyType = (type) => {
     switch (type) {
         case 'float32': return 'float';
@@ -2846,18 +2863,11 @@ const calcMinMax = (dataTable, columnNames) => {
 const logTransform = (value) => {
     return Math.sign(value) * Math.log(Math.abs(value) + 1);
 };
-// calculate the output index of the gaussian given its index. chunks of
-// 256 gaussians are packed into 16x16 tiles on the output texture.
-const target = (index, width) => {
-    const chunkWidth = width / 16;
-    const chunkIndex = Math.floor(index / 256);
-    const chunkX = chunkIndex % chunkWidth;
-    const chunkY = Math.floor(chunkIndex / chunkWidth);
-    const x = chunkX * 16 + (index % 16);
-    const y = chunkY * 16 + Math.floor((index % 256) / 16);
-    return x + y * width;
+// no packing
+const identity = (index, width) => {
+    return index;
 };
-const writeSogs = async (outputFilename, dataTable) => {
+const writeSogs = async (fileHandle, dataTable, outputFilename) => {
     // generate an optimal ordering
     const sortIndices = generateOrdering(dataTable);
     const numRows = dataTable.numRows;
@@ -2871,6 +2881,8 @@ const writeSogs = async (outputFilename, dataTable) => {
             .webp({ lossless: true })
             .toFile(pathname);
     };
+    // the layout function determines how the data is packed into the output texture.
+    const layout = identity; // rectChunks;
     const row = {};
     // convert position/means
     const meansL = new Uint8Array(width * height * channels);
@@ -2883,7 +2895,7 @@ const writeSogs = async (outputFilename, dataTable) => {
         const x = 65535 * (logTransform(row.x) - meansMinMax[0][0]) / (meansMinMax[0][1] - meansMinMax[0][0]);
         const y = 65535 * (logTransform(row.y) - meansMinMax[1][0]) / (meansMinMax[1][1] - meansMinMax[1][0]);
         const z = 65535 * (logTransform(row.z) - meansMinMax[2][0]) / (meansMinMax[2][1] - meansMinMax[2][0]);
-        const ti = target(i, width);
+        const ti = layout(i);
         meansL[ti * 4] = x & 0xff;
         meansL[ti * 4 + 1] = y & 0xff;
         meansL[ti * 4 + 2] = z & 0xff;
@@ -2930,7 +2942,7 @@ const writeSogs = async (outputFilename, dataTable) => {
             [0, 1, 3],
             [0, 1, 2]
         ][maxComp];
-        const ti = target(i, width);
+        const ti = layout(i);
         quats[ti * 4] = 255 * (q[idx[0]] * 0.5 + 0.5);
         quats[ti * 4 + 1] = 255 * (q[idx[1]] * 0.5 + 0.5);
         quats[ti * 4 + 2] = 255 * (q[idx[2]] * 0.5 + 0.5);
@@ -2944,7 +2956,7 @@ const writeSogs = async (outputFilename, dataTable) => {
     const scaleMinMax = calcMinMax(dataTable, scaleNames);
     for (let i = 0; i < dataTable.numRows; ++i) {
         dataTable.getRow(sortIndices[i], row, scaleColumns);
-        const ti = target(i, width);
+        const ti = layout(i);
         scales[ti * 4] = 255 * (row.scale_0 - scaleMinMax[0][0]) / (scaleMinMax[0][1] - scaleMinMax[0][0]);
         scales[ti * 4 + 1] = 255 * (row.scale_1 - scaleMinMax[1][0]) / (scaleMinMax[1][1] - scaleMinMax[1][0]);
         scales[ti * 4 + 2] = 255 * (row.scale_2 - scaleMinMax[2][0]) / (scaleMinMax[2][1] - scaleMinMax[2][0]);
@@ -2958,7 +2970,7 @@ const writeSogs = async (outputFilename, dataTable) => {
     const sh0MinMax = calcMinMax(dataTable, sh0Names);
     for (let i = 0; i < dataTable.numRows; ++i) {
         dataTable.getRow(sortIndices[i], row, sh0Columns);
-        const ti = target(i, width);
+        const ti = layout(i);
         sh0[ti * 4] = 255 * (row.f_dc_0 - sh0MinMax[0][0]) / (sh0MinMax[0][1] - sh0MinMax[0][0]);
         sh0[ti * 4 + 1] = 255 * (row.f_dc_1 - sh0MinMax[1][0]) / (sh0MinMax[1][1] - sh0MinMax[1][0]);
         sh0[ti * 4 + 2] = 255 * (row.f_dc_2 - sh0MinMax[2][0]) / (sh0MinMax[2][1] - sh0MinMax[2][0]);
@@ -2998,9 +3010,7 @@ const writeSogs = async (outputFilename, dataTable) => {
             files: ['sh0.webp']
         }
     };
-    const outputFile = await open(outputFilename, 'w');
-    await outputFile.write((new TextEncoder()).encode(JSON.stringify(meta, null, 4)));
-    await outputFile.close();
+    await fileHandle.write((new TextEncoder()).encode(JSON.stringify(meta, null, 4)));
 };
 
 const readFile = async (filename) => {
@@ -3010,28 +3020,63 @@ const readFile = async (filename) => {
     await inputFile.close();
     return plyData;
 };
-const writeFile = async (filename, dataTable) => {
-    if (filename.endsWith('.json')) {
-        await writeSogs(filename, dataTable);
+const getOutputFormat = (filename) => {
+    const lowerFilename = filename.toLowerCase();
+    if (lowerFilename.endsWith('.csv')) {
+        return 'csv';
+    }
+    else if (lowerFilename.endsWith('.json')) {
+        return 'json';
     }
-    else if (filename.endsWith('.compressed.ply')) {
-        console.log(`writing '${filename}'...`);
-        const outputFile = await open(filename, 'w');
-        await writeCompressedPly(outputFile, dataTable);
-        await outputFile.close();
+    else if (lowerFilename.endsWith('.compressed.ply')) {
+        return 'compressed-ply';
+    }
+    else if (lowerFilename.endsWith('.ply')) {
+        return 'ply';
     }
     else {
-        console.log(`writing '${filename}'...`);
-        const outputFile = await open(filename, 'w');
-        await writePly(outputFile, {
-            comments: [],
-            elements: [{
-                    name: 'vertex',
-                    dataTable: dataTable
-                }]
-        });
-        await outputFile.close();
+        throw new Error(`Unsupported output file type: ${filename}`);
+    }
+};
+const writeFile = async (filename, dataTable, options) => {
+    const outputFormat = getOutputFormat(filename);
+    // open the output file
+    let outputFile;
+    try {
+        outputFile = await open(filename, options.overwrite ? 'w' : 'wx');
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            console.error(`File '${filename}' already exists. Use -w option to overwrite.`);
+            exit(1);
+        }
+        else {
+            throw err;
+        }
+    }
+    console.log(`writing '${filename}'...`);
+    // write the data
+    switch (outputFormat) {
+        case 'csv':
+            await writeCsv(outputFile, dataTable);
+            break;
+        case 'json':
+            await writeSogs(outputFile, dataTable, filename);
+            break;
+        case 'compressed-ply':
+            await writeCompressedPly(outputFile, dataTable);
+            break;
+        case 'ply':
+            await writePly(outputFile, {
+                comments: [],
+                elements: [{
+                        name: 'vertex',
+                        dataTable: dataTable
+                    }]
+            });
+            break;
     }
+    await outputFile.close();
 };
 // combine multiple tables into one
 // columns with matching name and type are combined
@@ -3098,12 +3143,17 @@ const parseArguments = () => {
         strict: true,
         allowPositionals: true,
         options: {
+            // global options
+            overwrite: { type: 'boolean', short: 'w' },
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
+            // file options
             translate: { type: 'string', short: 't', multiple: true },
             rotate: { type: 'string', short: 'r', multiple: true },
             scale: { type: 'string', short: 's', multiple: true },
             filterNaN: { type: 'boolean', short: 'n', multiple: true },
             filterByValue: { type: 'string', short: 'c', multiple: true },
-            filterBands: { type: 'string', short: 'h', multiple: true }
+            filterBands: { type: 'string', short: 'b', multiple: true },
         }
     });
     const parseNumber = (value) => {
@@ -3133,6 +3183,11 @@ const parseArguments = () => {
         }
     };
     const files = [];
+    const options = {
+        overwrite: v.overwrite || false,
+        help: v.help || false,
+        version: v.version || false
+    };
     for (const t of tokens) {
         if (t.kind === 'positional') {
             files.push({
@@ -3193,22 +3248,57 @@ const parseArguments = () => {
             }
         }
     }
-    return files;
+    return { files, options };
 };
-const usage = `Usage: splat-transform input.ply [actions] input.ply [actions] ... output.ply [actions]
-actions:
--translate     -t x,y,z                     Translate splats by (x, y, z)
--rotate        -r x,y,z                     Rotate splats by euler angles (x, y, z) (in degrees)
--scale         -s x                         Scale splats by x (uniform scaling)
--filterNaN     -n                           Remove gaussians containing any NaN or Inf value
--filterByValue -c name,comparator,value     Filter gaussians by a value. Specify the value name, comparator (lt, lte, gt, gte, eq, neq) and value
--filterBands   -h 1                         Filter spherical harmonic band data. Value must be 0, 1, 2 or 3.
+const usage = `
+Apply geometric transforms & filters to Gaussian-splat point clouds
+===================================================================
+
+USAGE
+  splat-transform [GLOBAL]  <input.ply> [ACTIONS]  ...  <output.{ply|compressed.ply|meta.json|csv}> [ACTIONS]
+
+  • Every time an *.ply* appears, it becomes the current working set; the following
+    ACTIONS are applied in the order listed.  
+  • The last file on the command line is treated as the output; anything after it is
+    interpreted as actions that modify the final result.
+
+SUPPORTED INPUTS
+    .ply
+
+SUPPORTED OUTPUTS
+    .ply   .compressed.ply   meta.json (SOGS)   .csv
+
+ACTIONS (can be repeated, in any order)
+    -t, --translate  x,y,z                  Translate splats by (x, y, z)
+    -r, --rotate     x,y,z                  Rotate splats by Euler angles (deg)
+    -s, --scale      x                      Uniformly scale splats by factor x
+    -n, --filterNaN                         Remove any Gaussian containing NaN/Inf
+    -c, --filterByValue name,cmp,value      Keep splats where  <name> <cmp> <value>
+                                            cmp ∈ {lt,lte,gt,gte,eq,neq}
+    -h, --filterBands  {0|1|2|3}            Strip spherical-harmonic bands > N
+
+GLOBAL OPTIONS
+    -w, --overwrite                         Overwrite output file if it already exists
+    -h, --help                              Show this help and exit
+    -v, --version                           Show version and exit
+
+EXAMPLES
+    # Simple scale-then-translate
+    splat-transform bunny.ply -s 0.5 -t 0,0,10 bunny_scaled.ply
+
+    # Chain two inputs and write compressed output, overwriting if necessary
+    splat-transform -w cloudA.ply -r 0,90,0 cloudB.ply -s 2 merged.compressed.ply
 `;
 const main = async () => {
     console.log(`splat-transform v${version}`);
     // read args
-    const files = parseArguments();
-    if (files.length < 2) {
+    const { files, options } = parseArguments();
+    // show version and exit
+    if (options.version) {
+        exit(0);
+    }
+    // invalid args or show help
+    if (files.length < 2 || options.help) {
         console.error(usage);
         exit(1);
     }
@@ -3236,7 +3326,7 @@ const main = async () => {
         // combine inputs into a single output dataTable
         const dataTable = process(combine(inputFiles.map(file => file.elements[0].dataTable)), outputArg.processActions);
         // write file
-        await writeFile(resolve(outputArg.filename), dataTable);
+        await writeFile(resolve(outputArg.filename), dataTable, options);
     }
     catch (err) {
         // handle errors