Skip to content

3D engine that AI agents drive

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.md
new file mode 100644
index 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.md
index 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 Marbl
const 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 discs
diff --git a/src/gaussian-splat-ply.js b/src/gaussian-splat-ply.js
index 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.js
new file mode 100644
index 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/);
+});