@playcanvas/splat-transform 0.2.1 → 0.4.0

package/dist/index.mjs

@@ -1881,7 +1881,7 @@ class Quat {
 		}
 }
 
-var version = "0.2.1";
+var version = "0.3.0";
 
 class Column {
     name;
@@ -2445,6 +2445,407 @@ const readPly = async (fileHandle) => {
     };
 };
 
+const readSplat = async (fileHandle) => {
+    // Get file size to determine number of splats
+    const fileStats = await fileHandle.stat();
+    const fileSize = fileStats.size;
+    // Each splat is 32 bytes
+    const BYTES_PER_SPLAT = 32;
+    if (fileSize % BYTES_PER_SPLAT !== 0) {
+        throw new Error('Invalid .splat file: file size is not a multiple of 32 bytes');
+    }
+    const numSplats = fileSize / BYTES_PER_SPLAT;
+    if (numSplats === 0) {
+        throw new Error('Invalid .splat file: file is empty');
+    }
+    // Create columns for the standard Gaussian splat data
+    const columns = [
+        // Position
+        new Column('x', new Float32Array(numSplats)),
+        new Column('y', new Float32Array(numSplats)),
+        new Column('z', new Float32Array(numSplats)),
+        // Scale (stored as linear in .splat, convert to log for internal use)
+        new Column('scale_0', new Float32Array(numSplats)),
+        new Column('scale_1', new Float32Array(numSplats)),
+        new Column('scale_2', new Float32Array(numSplats)),
+        // Color/opacity
+        new Column('f_dc_0', new Float32Array(numSplats)), // Red
+        new Column('f_dc_1', new Float32Array(numSplats)), // Green
+        new Column('f_dc_2', new Float32Array(numSplats)), // Blue
+        new Column('opacity', new Float32Array(numSplats)),
+        // Rotation quaternion
+        new Column('rot_0', new Float32Array(numSplats)),
+        new Column('rot_1', new Float32Array(numSplats)),
+        new Column('rot_2', new Float32Array(numSplats)),
+        new Column('rot_3', new Float32Array(numSplats))
+    ];
+    // Read data in chunks
+    const chunkSize = 1024;
+    const numChunks = Math.ceil(numSplats / chunkSize);
+    const chunkData = Buffer$1.alloc(chunkSize * BYTES_PER_SPLAT);
+    for (let c = 0; c < numChunks; ++c) {
+        const numRows = Math.min(chunkSize, numSplats - c * chunkSize);
+        const bytesToRead = numRows * BYTES_PER_SPLAT;
+        const { bytesRead } = await fileHandle.read(chunkData, 0, bytesToRead);
+        if (bytesRead !== bytesToRead) {
+            throw new Error('Failed to read expected amount of data from .splat file');
+        }
+        // Parse each splat in the chunk
+        for (let r = 0; r < numRows; ++r) {
+            const splatIndex = c * chunkSize + r;
+            const offset = r * BYTES_PER_SPLAT;
+            // Read position (3 × float32)
+            const x = chunkData.readFloatLE(offset + 0);
+            const y = chunkData.readFloatLE(offset + 4);
+            const z = chunkData.readFloatLE(offset + 8);
+            // Read scale (3 × float32)
+            const scaleX = chunkData.readFloatLE(offset + 12);
+            const scaleY = chunkData.readFloatLE(offset + 16);
+            const scaleZ = chunkData.readFloatLE(offset + 20);
+            // Read color and opacity (4 × uint8)
+            const red = chunkData.readUInt8(offset + 24);
+            const green = chunkData.readUInt8(offset + 25);
+            const blue = chunkData.readUInt8(offset + 26);
+            const opacity = chunkData.readUInt8(offset + 27);
+            // Read rotation quaternion (4 × uint8)
+            const rot0 = chunkData.readUInt8(offset + 28);
+            const rot1 = chunkData.readUInt8(offset + 29);
+            const rot2 = chunkData.readUInt8(offset + 30);
+            const rot3 = chunkData.readUInt8(offset + 31);
+            // Store position
+            columns[0].data[splatIndex] = x;
+            columns[1].data[splatIndex] = y;
+            columns[2].data[splatIndex] = z;
+            // Store scale (convert from linear in .splat to log scale for internal use)
+            columns[3].data[splatIndex] = Math.log(scaleX);
+            columns[4].data[splatIndex] = Math.log(scaleY);
+            columns[5].data[splatIndex] = Math.log(scaleZ);
+            // Store color (convert from uint8 back to spherical harmonics)
+            const SH_C0 = 0.28209479177387814;
+            columns[6].data[splatIndex] = (red / 255.0 - 0.5) / SH_C0;
+            columns[7].data[splatIndex] = (green / 255.0 - 0.5) / SH_C0;
+            columns[8].data[splatIndex] = (blue / 255.0 - 0.5) / SH_C0;
+            // Store opacity (convert from uint8 to float and apply inverse sigmoid)
+            const epsilon = 1e-6;
+            const normalizedOpacity = Math.max(epsilon, Math.min(1.0 - epsilon, opacity / 255.0));
+            columns[9].data[splatIndex] = Math.log(normalizedOpacity / (1.0 - normalizedOpacity));
+            // Store rotation quaternion (convert from uint8 [0,255] to float [-1,1] and normalize)
+            const rot0Norm = (rot0 / 255.0) * 2.0 - 1.0;
+            const rot1Norm = (rot1 / 255.0) * 2.0 - 1.0;
+            const rot2Norm = (rot2 / 255.0) * 2.0 - 1.0;
+            const rot3Norm = (rot3 / 255.0) * 2.0 - 1.0;
+            // Normalize quaternion
+            const length = Math.sqrt(rot0Norm * rot0Norm + rot1Norm * rot1Norm + rot2Norm * rot2Norm + rot3Norm * rot3Norm);
+            if (length > 0) {
+                columns[10].data[splatIndex] = rot0Norm / length;
+                columns[11].data[splatIndex] = rot1Norm / length;
+                columns[12].data[splatIndex] = rot2Norm / length;
+                columns[13].data[splatIndex] = rot3Norm / length;
+            }
+            else {
+                // Default to identity quaternion if invalid
+                columns[10].data[splatIndex] = 0.0;
+                columns[11].data[splatIndex] = 0.0;
+                columns[12].data[splatIndex] = 0.0;
+                columns[13].data[splatIndex] = 1.0;
+            }
+        }
+    }
+    return {
+        comments: [],
+        elements: [{
+                name: 'vertex',
+                dataTable: new DataTable(columns)
+            }]
+    };
+};
+
+// Half-precision floating point decoder
+function decodeFloat16(encoded) {
+    const signBit = (encoded >> 15) & 1;
+    const exponent = (encoded >> 10) & 0x1f;
+    const mantissa = encoded & 0x3ff;
+    if (exponent === 0) {
+        if (mantissa === 0) {
+            return signBit ? -0 : 0.0;
+        }
+        // Denormalized number
+        let m = mantissa;
+        let exp = -14;
+        while (!(m & 0x400)) {
+            m <<= 1;
+            exp--;
+        }
+        m &= 0x3ff;
+        const finalExp = exp + 127;
+        const finalMantissa = m << 13;
+        const bits = (signBit << 31) | (finalExp << 23) | finalMantissa;
+        return new Float32Array(new Uint32Array([bits]).buffer)[0];
+    }
+    if (exponent === 0x1f) {
+        return mantissa === 0 ? (signBit ? -Infinity : Infinity) : NaN;
+    }
+    const finalExp = exponent - 15 + 127;
+    const finalMantissa = mantissa << 13;
+    const bits = (signBit << 31) | (finalExp << 23) | finalMantissa;
+    return new Float32Array(new Uint32Array([bits]).buffer)[0];
+}
+const COMPRESSION_MODES = [
+    {
+        centerBytes: 12,
+        scaleBytes: 12,
+        rotationBytes: 16,
+        colorBytes: 4,
+        harmonicsBytes: 4,
+        scaleStartByte: 12,
+        rotationStartByte: 24,
+        colorStartByte: 40,
+        harmonicsStartByte: 44,
+        scaleQuantRange: 1
+    },
+    {
+        centerBytes: 6,
+        scaleBytes: 6,
+        rotationBytes: 8,
+        colorBytes: 4,
+        harmonicsBytes: 2,
+        scaleStartByte: 6,
+        rotationStartByte: 12,
+        colorStartByte: 20,
+        harmonicsStartByte: 24,
+        scaleQuantRange: 32767
+    },
+    {
+        centerBytes: 6,
+        scaleBytes: 6,
+        rotationBytes: 8,
+        colorBytes: 4,
+        harmonicsBytes: 1,
+        scaleStartByte: 6,
+        rotationStartByte: 12,
+        colorStartByte: 20,
+        harmonicsStartByte: 24,
+        scaleQuantRange: 32767
+    }
+];
+const HARMONICS_COMPONENT_COUNT = [0, 9, 24, 45];
+const readKsplat = async (fileHandle) => {
+    const stats = await fileHandle.stat();
+    const totalSize = stats.size;
+    // Load complete file
+    const fileBuffer = Buffer$1.alloc(totalSize);
+    await fileHandle.read(fileBuffer, 0, totalSize, 0);
+    const MAIN_HEADER_SIZE = 4096;
+    const SECTION_HEADER_SIZE = 1024;
+    if (totalSize < MAIN_HEADER_SIZE) {
+        throw new Error('File too small to be valid .ksplat format');
+    }
+    // Parse main header
+    const mainHeader = new DataView(fileBuffer.buffer, fileBuffer.byteOffset, MAIN_HEADER_SIZE);
+    const majorVersion = mainHeader.getUint8(0);
+    const minorVersion = mainHeader.getUint8(1);
+    if (majorVersion !== 0 || minorVersion < 1) {
+        throw new Error(`Unsupported version ${majorVersion}.${minorVersion}`);
+    }
+    const maxSections = mainHeader.getUint32(4, true);
+    const numSplats = mainHeader.getUint32(16, true);
+    const compressionMode = mainHeader.getUint16(20, true);
+    if (compressionMode > 2) {
+        throw new Error(`Invalid compression mode: ${compressionMode}`);
+    }
+    const minHarmonicsValue = mainHeader.getFloat32(36, true) ?? -1.5;
+    const maxHarmonicsValue = mainHeader.getFloat32(40, true) ?? 1.5;
+    if (numSplats === 0) {
+        throw new Error('Invalid .ksplat file: file is empty');
+    }
+    // First pass: scan all sections to find maximum harmonics degree
+    let maxHarmonicsDegree = 0;
+    for (let sectionIdx = 0; sectionIdx < maxSections; sectionIdx++) {
+        const sectionHeaderOffset = MAIN_HEADER_SIZE + sectionIdx * SECTION_HEADER_SIZE;
+        const sectionHeader = new DataView(fileBuffer.buffer, fileBuffer.byteOffset + sectionHeaderOffset, SECTION_HEADER_SIZE);
+        const sectionSplatCount = sectionHeader.getUint32(0, true);
+        if (sectionSplatCount === 0)
+            continue; // Skip empty sections
+        const harmonicsDegree = sectionHeader.getUint16(40, true);
+        maxHarmonicsDegree = Math.max(maxHarmonicsDegree, harmonicsDegree);
+    }
+    // Initialize data storage with base columns
+    const columns = [
+        new Column('x', new Float32Array(numSplats)),
+        new Column('y', new Float32Array(numSplats)),
+        new Column('z', new Float32Array(numSplats)),
+        new Column('scale_0', new Float32Array(numSplats)),
+        new Column('scale_1', new Float32Array(numSplats)),
+        new Column('scale_2', new Float32Array(numSplats)),
+        new Column('f_dc_0', new Float32Array(numSplats)),
+        new Column('f_dc_1', new Float32Array(numSplats)),
+        new Column('f_dc_2', new Float32Array(numSplats)),
+        new Column('opacity', new Float32Array(numSplats)),
+        new Column('rot_0', new Float32Array(numSplats)),
+        new Column('rot_1', new Float32Array(numSplats)),
+        new Column('rot_2', new Float32Array(numSplats)),
+        new Column('rot_3', new Float32Array(numSplats))
+    ];
+    // Add spherical harmonics columns based on maximum degree found
+    const maxHarmonicsComponentCount = HARMONICS_COMPONENT_COUNT[maxHarmonicsDegree];
+    for (let i = 0; i < maxHarmonicsComponentCount; i++) {
+        columns.push(new Column(`f_rest_${i}`, new Float32Array(numSplats)));
+    }
+    const { centerBytes, scaleBytes, rotationBytes, colorBytes, harmonicsBytes, scaleStartByte, rotationStartByte, colorStartByte, harmonicsStartByte, scaleQuantRange } = COMPRESSION_MODES[compressionMode];
+    let currentSectionDataOffset = MAIN_HEADER_SIZE + maxSections * SECTION_HEADER_SIZE;
+    let splatIndex = 0;
+    // Process each section
+    for (let sectionIdx = 0; sectionIdx < maxSections; sectionIdx++) {
+        const sectionHeaderOffset = MAIN_HEADER_SIZE + sectionIdx * SECTION_HEADER_SIZE;
+        const sectionHeader = new DataView(fileBuffer.buffer, fileBuffer.byteOffset + sectionHeaderOffset, SECTION_HEADER_SIZE);
+        const sectionSplatCount = sectionHeader.getUint32(0, true);
+        const maxSectionSplats = sectionHeader.getUint32(4, true);
+        const bucketCapacity = sectionHeader.getUint32(8, true);
+        const bucketCount = sectionHeader.getUint32(12, true);
+        const spatialBlockSize = sectionHeader.getFloat32(16, true);
+        const bucketStorageSize = sectionHeader.getUint16(20, true);
+        const quantizationRange = sectionHeader.getUint32(24, true) || scaleQuantRange;
+        const fullBuckets = sectionHeader.getUint32(32, true);
+        const partialBuckets = sectionHeader.getUint32(36, true);
+        const harmonicsDegree = sectionHeader.getUint16(40, true);
+        // Calculate layout
+        const fullBucketSplats = fullBuckets * bucketCapacity;
+        const partialBucketMetaSize = partialBuckets * 4;
+        const totalBucketStorageSize = bucketStorageSize * bucketCount + partialBucketMetaSize;
+        const harmonicsComponentCount = HARMONICS_COMPONENT_COUNT[harmonicsDegree];
+        const bytesPerSplat = centerBytes + scaleBytes + rotationBytes +
+            colorBytes + harmonicsComponentCount * harmonicsBytes;
+        const sectionDataSize = bytesPerSplat * maxSectionSplats;
+        // Calculate decompression parameters
+        const positionScale = spatialBlockSize / 2.0 / quantizationRange;
+        // Get bucket centers
+        const bucketCentersOffset = currentSectionDataOffset + partialBucketMetaSize;
+        const bucketCenters = new Float32Array(fileBuffer.buffer, fileBuffer.byteOffset + bucketCentersOffset, bucketCount * 3);
+        // Get partial bucket sizes
+        const partialBucketSizes = new Uint32Array(fileBuffer.buffer, fileBuffer.byteOffset + currentSectionDataOffset, partialBuckets);
+        // Get splat data
+        const splatDataOffset = currentSectionDataOffset + totalBucketStorageSize;
+        const splatData = new DataView(fileBuffer.buffer, fileBuffer.byteOffset + splatDataOffset, sectionDataSize);
+        // Harmonic value decoder
+        const decodeHarmonics = (offset, component) => {
+            switch (compressionMode) {
+                case 0:
+                    return splatData.getFloat32(offset + harmonicsStartByte + component * 4, true);
+                case 1:
+                    return decodeFloat16(splatData.getUint16(offset + harmonicsStartByte + component * 2, true));
+                case 2: {
+                    const normalized = splatData.getUint8(offset + harmonicsStartByte + component) / 255;
+                    return minHarmonicsValue + normalized * (maxHarmonicsValue - minHarmonicsValue);
+                }
+                default:
+                    return 0;
+            }
+        };
+        // Track partial bucket processing
+        let currentPartialBucket = fullBuckets;
+        let currentPartialBase = fullBucketSplats;
+        // Process splats in this section
+        for (let splatIdx = 0; splatIdx < sectionSplatCount; splatIdx++) {
+            const splatByteOffset = splatIdx * bytesPerSplat;
+            // Determine which bucket this splat belongs to
+            let bucketIdx;
+            if (splatIdx < fullBucketSplats) {
+                bucketIdx = Math.floor(splatIdx / bucketCapacity);
+            }
+            else {
+                const currentBucketSize = partialBucketSizes[currentPartialBucket - fullBuckets];
+                if (splatIdx >= currentPartialBase + currentBucketSize) {
+                    currentPartialBucket++;
+                    currentPartialBase += currentBucketSize;
+                }
+                bucketIdx = currentPartialBucket;
+            }
+            // Decode position
+            let x, y, z;
+            if (compressionMode === 0) {
+                x = splatData.getFloat32(splatByteOffset, true);
+                y = splatData.getFloat32(splatByteOffset + 4, true);
+                z = splatData.getFloat32(splatByteOffset + 8, true);
+            }
+            else {
+                x = (splatData.getUint16(splatByteOffset, true) - quantizationRange) * positionScale + bucketCenters[bucketIdx * 3];
+                y = (splatData.getUint16(splatByteOffset + 2, true) - quantizationRange) * positionScale + bucketCenters[bucketIdx * 3 + 1];
+                z = (splatData.getUint16(splatByteOffset + 4, true) - quantizationRange) * positionScale + bucketCenters[bucketIdx * 3 + 2];
+            }
+            // Decode scales
+            let scaleX, scaleY, scaleZ;
+            if (compressionMode === 0) {
+                scaleX = splatData.getFloat32(splatByteOffset + scaleStartByte, true);
+                scaleY = splatData.getFloat32(splatByteOffset + scaleStartByte + 4, true);
+                scaleZ = splatData.getFloat32(splatByteOffset + scaleStartByte + 8, true);
+            }
+            else {
+                scaleX = decodeFloat16(splatData.getUint16(splatByteOffset + scaleStartByte, true));
+                scaleY = decodeFloat16(splatData.getUint16(splatByteOffset + scaleStartByte + 2, true));
+                scaleZ = decodeFloat16(splatData.getUint16(splatByteOffset + scaleStartByte + 4, true));
+            }
+            // Decode rotation quaternion
+            let rot0, rot1, rot2, rot3;
+            if (compressionMode === 0) {
+                rot0 = splatData.getFloat32(splatByteOffset + rotationStartByte, true);
+                rot1 = splatData.getFloat32(splatByteOffset + rotationStartByte + 4, true);
+                rot2 = splatData.getFloat32(splatByteOffset + rotationStartByte + 8, true);
+                rot3 = splatData.getFloat32(splatByteOffset + rotationStartByte + 12, true);
+            }
+            else {
+                rot0 = decodeFloat16(splatData.getUint16(splatByteOffset + rotationStartByte, true));
+                rot1 = decodeFloat16(splatData.getUint16(splatByteOffset + rotationStartByte + 2, true));
+                rot2 = decodeFloat16(splatData.getUint16(splatByteOffset + rotationStartByte + 4, true));
+                rot3 = decodeFloat16(splatData.getUint16(splatByteOffset + rotationStartByte + 6, true));
+            }
+            // Decode color and opacity
+            const red = splatData.getUint8(splatByteOffset + colorStartByte);
+            const green = splatData.getUint8(splatByteOffset + colorStartByte + 1);
+            const blue = splatData.getUint8(splatByteOffset + colorStartByte + 2);
+            const opacity = splatData.getUint8(splatByteOffset + colorStartByte + 3);
+            // Store position
+            columns[0].data[splatIndex] = x;
+            columns[1].data[splatIndex] = y;
+            columns[2].data[splatIndex] = z;
+            // Store scale (convert from linear in .ksplat to log scale for internal use)
+            columns[3].data[splatIndex] = Math.log(scaleX);
+            columns[4].data[splatIndex] = Math.log(scaleY);
+            columns[5].data[splatIndex] = Math.log(scaleZ);
+            // Store color (convert from uint8 back to spherical harmonics)
+            const SH_C0 = 0.28209479177387814;
+            columns[6].data[splatIndex] = (red / 255.0 - 0.5) / SH_C0;
+            columns[7].data[splatIndex] = (green / 255.0 - 0.5) / SH_C0;
+            columns[8].data[splatIndex] = (blue / 255.0 - 0.5) / SH_C0;
+            // Store opacity (convert from uint8 to float and apply inverse sigmoid)
+            const epsilon = 1e-6;
+            const normalizedOpacity = Math.max(epsilon, Math.min(1.0 - epsilon, opacity / 255.0));
+            columns[9].data[splatIndex] = Math.log(normalizedOpacity / (1.0 - normalizedOpacity));
+            // Store quaternion
+            columns[10].data[splatIndex] = rot0;
+            columns[11].data[splatIndex] = rot1;
+            columns[12].data[splatIndex] = rot2;
+            columns[13].data[splatIndex] = rot3;
+            // Store spherical harmonics
+            for (let i = 0; i < harmonicsComponentCount; i++) {
+                columns[14 + i].data[splatIndex] = decodeHarmonics(splatByteOffset, i);
+            }
+            splatIndex++;
+        }
+        currentSectionDataOffset += sectionDataSize + totalBucketStorageSize;
+    }
+    if (splatIndex !== numSplats) {
+        throw new Error(`Splat count mismatch: expected ${numSplats}, processed ${splatIndex}`);
+    }
+    const resultTable = new DataTable(columns);
+    return {
+        comments: [],
+        elements: [{
+                name: 'vertex',
+                dataTable: resultTable
+            }]
+    };
+};
+
 const sigmoid = (v) => 1 / (1 + Math.exp(-v));
 
 const q = new Quat();
@@ -2770,6 +3171,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 +3264,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 +3282,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 +3296,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 +3343,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 +3357,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 +3371,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,40 +3411,85 @@ 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) => {
     console.log(`reading '${filename}'...`);
     const inputFile = await open(filename, 'r');
-    const plyData = await readPly(inputFile);
+    const lowerFilename = filename.toLowerCase();
+    let fileData;
+    if (lowerFilename.endsWith('.ksplat')) {
+        fileData = await readKsplat(inputFile);
+    }
+    else if (lowerFilename.endsWith('.splat')) {
+        fileData = await readSplat(inputFile);
+    }
+    else if (lowerFilename.endsWith('.ply')) {
+        fileData = await readPly(inputFile);
+    }
+    else {
+        await inputFile.close();
+        throw new Error(`Unsupported input file type: ${filename}`);
+    }
     await inputFile.close();
-    return plyData;
+    return fileData;
 };
-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 (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('.json')) {
+        return 'json';
     }
-    else {
-        console.log(`writing '${filename}'...`);
-        const outputFile = await open(filename, 'w');
-        await writePly(outputFile, {
-            comments: [],
-            elements: [{
-                    name: 'vertex',
-                    dataTable: dataTable
-                }]
-        });
-        await outputFile.close();
+    else if (lowerFilename.endsWith('.compressed.ply')) {
+        return 'compressed-ply';
+    }
+    else if (lowerFilename.endsWith('.ply')) {
+        return 'ply';
+    }
+    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 +3556,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 +3596,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 +3661,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|splat|ksplat}> [ACTIONS]  ...  <output.{ply|compressed.ply|meta.json|csv}> [ACTIONS]
+
+  • Every time an input file 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   .splat   .ksplat
+
+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 +3739,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