3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Drop splat PLY positions past float32 and name the 64 KiB header limit (#2379)
Nguyen Xuan Andf9510e00eb6
diff --git a/changes/2379.md b/changes/2379.mdnew file mode 100644index 00000000..2173f535--- /dev/null+++ b/changes/2379.md@@ -0,0 +1 @@+- Splat PLY loading drops a splat whose position is past the float32 range instead of loading an infinite position, and a PLY header over 64 KiB is refused with a message that names the limit instead of "Not a PLY file" (#2379, #2380).diff --git a/docs/gaussian-splats.md b/docs/gaussian-splats.mdindex ed55af55..2177be1b 100644--- a/docs/gaussian-splats.md+++ b/docs/gaussian-splats.md@@ -27,7 +27,7 @@ The second is SPZ, Niantic's format and the output of World Labs Atlas and Marblconst data = await parseGaussianSplatSpz(await (await fetch('/world.spz')).arrayBuffer());```-A file over `maximumBytes` (default 512 MiB, for SPZ also its inflated size), or one whose header names more than `maximumCount` splats (default 2,000,000, never above 4,000,000), throws a `RangeError` before any splat is read. A file that is not a PLY (or an SPZ: bad gzip, bad magic, unsupported version), is ASCII, lacks a property or is truncated throws an `Error` that names the problem. `createGaussianSplats` applies the count limit again. A PLY may declare fixed-size elements (such as `camera`) before `vertex`, which are skipped; a list element before `vertex` is refused with a message to put the vertex element first. CRLF header lines are accepted. A PLY splat with any non-finite field (NaN or infinite position, colour, opacity or rotation, or a scale that overflows, a log-scale above about 88) is dropped, and the result carries `skipped: { count, fields }` with the number dropped (0 for a clean file, and for SPZ) and the names of the offending fields; the parse throws only when no splat is usable. `createGaussianSplats` throws a `RangeError` naming the splat when its covariance overflows 32-bit floats. `maximumCount` must be a positive number; the 4,000,000 hard limit always applies.+A file over `maximumBytes` (default 512 MiB, for SPZ also its inflated size), or one whose header names more than `maximumCount` splats (default 2,000,000, never above 4,000,000), throws a `RangeError` before any splat is read. A file that is not a PLY (or an SPZ: bad gzip, bad magic, unsupported version), is ASCII, lacks a property or is truncated throws an `Error` that names the problem. `createGaussianSplats` applies the count limit again. A PLY may declare fixed-size elements (such as `camera`) before `vertex`, which are skipped; a list element before `vertex` is refused with a message to put the vertex element first. CRLF header lines are accepted. The PLY header may be at most 64 KiB; a longer one is refused with a message that names the limit. A PLY splat with any non-finite field (NaN or infinite position, colour, opacity or rotation, a position past the float32 range of about 3.4e38, or a scale that overflows, a log-scale above about 88) is dropped, and the result carries `skipped: { count, fields }` with the number dropped (0 for a clean file, and for SPZ) and the names of the offending fields; the parse throws only when no splat is usable. `createGaussianSplats` throws a `RangeError` naming the splat when its covariance overflows 32-bit floats. `maximumCount` must be a positive number; the 4,000,000 hard limit always applies.## Z-up files and hard opaque discsdiff --git a/src/gaussian-splat-ply.js b/src/gaussian-splat-ply.jsindex c0203c3c..3fe9e662 100644--- a/src/gaussian-splat-ply.js+++ b/src/gaussian-splat-ply.js@@ -41,6 +41,9 @@ function readHeaderText(bytes) {const searchLimit = Math.min(bytes.length, MAXIMUM_HEADER_BYTES);const text = new TextDecoder('latin1').decode(bytes.subarray(0, searchLimit));const endMatch = HEADER_END_PATTERN.exec(text);+ if (text.startsWith('ply') && !endMatch && bytes.length > MAXIMUM_HEADER_BYTES) {+ throw new Error(`Gaussian splat PLY header is longer than ${MAXIMUM_HEADER_BYTES} bytes (64 KiB) or has no "end_header" line. Remove comment lines or re-export the file.`);+ }if (!text.startsWith('ply') || !endMatch) {throw new Error('Not a PLY file: the header must start with "ply" and end with "end_header"');}@@ -226,7 +229,9 @@ function createSplatReader({ view, vertexCount, layout, stride, upAxis }) {let valid = true;for (let field = 0; field < fields.length; field++) {const value = fields[field].read(view, row + fields[field].offset);- values[field] = field >= 7 && field <= 9 ? Math.fround(Math.exp(value)) : value;+ // Positions are stored as float32, so a value past that range counts as non-finite here, as an overflowing scale does.+ const isPosition = field < 3;+ values[field] = field >= 7 && field <= 9 ? Math.fround(Math.exp(value)) : isPosition ? Math.fround(value) : value;if (!Number.isFinite(values[field])) {badFieldNames.add(FIELD_NAMES[field]);valid = false;diff --git a/tests/gaussian-splat-ply-bounds.test.js b/tests/gaussian-splat-ply-bounds.test.jsnew file mode 100644index 00000000..fd877a3e--- /dev/null+++ b/tests/gaussian-splat-ply-bounds.test.js@@ -0,0 +1,47 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { parseGaussianSplatPly, parseGaussianSplatPlyAsync } from '../src/gaussian-splat-ply.js';++const PROPERTY_NAMES = ['x', 'y', 'z', 'f_dc_0', 'f_dc_1', 'f_dc_2', 'opacity', 'scale_0', 'scale_1', 'scale_2', 'rot_0', 'rot_1', 'rot_2', 'rot_3'];+const IDENTITY_VALUES = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0];++// One splat per row of 14 values, written as 64 bit doubles so a value can pass the finite check and still overflow float32.+function buildDoublePly(rows, headerComment = '') {+ const commentLines = headerComment ? [headerComment] : [];+ const header = ['ply', 'format binary_little_endian 1.0', ...commentLines, `element vertex ${rows.length}`, ...PROPERTY_NAMES.map(name => `property double ${name}`), 'end_header', ''].join('\n');+ const headerBytes = new TextEncoder().encode(header);+ const file = new Uint8Array(headerBytes.length + rows.length * PROPERTY_NAMES.length * 8);+ file.set(headerBytes, 0);+ const view = new DataView(file.buffer);+ rows.forEach((row, rowIndex) => {+ row.forEach((value, column) => view.setFloat64(headerBytes.length + (rowIndex * PROPERTY_NAMES.length + column) * 8, value, true));+ });+ return file;+}++function rowAt(x, y, z) {+ return [x, y, z, ...IDENTITY_VALUES.slice(3)];+}++test('a position past the float32 range is dropped and named, not loaded as infinity', async () => {+ const file = buildDoublePly([rowAt(1, 2, 3), rowAt(1e300, 0, 0), rowAt(0, -1e300, 0), rowAt(4, 5, 6)]);+ for (const data of [parseGaussianSplatPly(file), await parseGaussianSplatPlyAsync(file)]) {+ assert.equal(data.count, 2);+ assert.deepEqual(Array.from(data.positions), [1, 2, 3, 4, 5, 6]);+ assert.deepEqual(data.bounds, { minimum: [1, 2, 3], maximum: [4, 5, 6] });+ assert.deepEqual(data.skipped, { count: 2, fields: ['x', 'y'] });+ }+});++test('a PLY whose only position overflows float32 throws and names the field', () => {+ assert.throws(() => parseGaussianSplatPly(buildDoublePly([rowAt(0, 0, 1e300)])), /no usable splat.*z/);+});++test('a PLY header longer than 64 KiB names the header limit instead of calling the file not a PLY', () => {+ const file = buildDoublePly([rowAt(0, 0, 0)], `comment ${'a'.repeat(70_000)}`);+ assert.throws(() => parseGaussianSplatPly(file), /header is longer than 65536 bytes/);+});++test('a file that is not a PLY still says so, even when it is large', () => {+ assert.throws(() => parseGaussianSplatPly(new Uint8Array(100_000).fill(65)), /Not a PLY file/);+});