Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ API between minor releases.
drawable geometry, and set the model title when WebGL 2 is unavailable.
- Keep close geometry visible and pickable in kilometre-scale models. Orthographic wheel zoom changes the
magnification around the cursor while keeping the camera at the same depth.
- Speed up picking in large instanced models by skipping the trailing instances outside the pick tile.

## [0.3.1] - 2026-11-13

Expand Down
24 changes: 24 additions & 0 deletions docs/viewer-performance-baseline.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,3 +112,27 @@ readback and target computation. Every measured hover snapped to a vertex.

Set `PERF_MODELS` to the Synthetic-400k HTML exported with the current bundle and run the same harness. Read
`pickMs` and `pickP95Ms` alongside `measureSnap.medianMs`, `measureSnap.p95Ms` and `measureSnap.kinds`.

## Instance bounds in the picking pass

Set `PERF_PICK_BOUNDS_ONLY=1` and point `PERF_MODELS` at the current Synthetic-400k and Schependomlaan exports.
Run on both GPU modes as above. The harness alternates full-cell and bounded draws on each pixel, flushes the pick
cache and requires equal hit IDs and coordinates. It repeats an 81-pixel grid and up to 48 known hit pixels three
times each with the same fitted camera. `pickBounds` in the reports includes hit counts and median submitted triangles.
Export Synthetic-1M the same way with `--elements 1000000` to reproduce the million-element workload.

| Workload | GPU | Samples | Full cells p50 / p95, ms | Instance bounds p50 / p95, ms |
| --- | --- | --- | ---: | ---: |
| Synthetic-400k | Radeon | Grid, 3 hits of 243 | 8.8 / 11.3 | 1.9 / 4.4 |
| Synthetic-400k | Radeon | 144 hits | 8.7 / 10.4 | 2.0 / 3.0 |
| Synthetic-400k | RTX 4080 | Grid, 3 hits of 243 | 2.0 / 2.7 | 1.9 / 2.7 |
| Synthetic-400k | RTX 4080 | 144 hits | 1.8 / 2.3 | 1.6 / 2.1 |
| Synthetic-1M | Radeon | Grid, 6 hits of 243 | 21.9 / 25.8 | 5.2 / 8.2 |
| Synthetic-1M | Radeon | 144 hits | 20.0 / 25.7 | 5.5 / 7.5 |
| Schependomlaan | Radeon | 144 hits | 0.5 / 0.6 | 0.5 / 0.7 |
| Schependomlaan | RTX 4080 | 144 hits | 0.2 / 0.3 | 0.2 / 0.3 |

The median triangle count for Synthetic-400k hits fell from 4,046,612 to 62,948. On Synthetic-1M, with 96 million
triangles in the model, it fell from 10,339,788 to 159,872. All sample pairs matched.
Schependomlaan draws only merged chunks, so both runs submitted 247,472 triangles. This change applies to picking.
Adaptive orbit continues to use its existing detail cut. [Instancing and picking issue](https://github.com/IOExtend/IOViewer/issues/12)
358 changes: 179 additions & 179 deletions src/IOViewer/Viewer/dist/viewer.js

Large diffs are not rendered by default.

68 changes: 61 additions & 7 deletions src/IOViewer/Viewer/src/engine/modelScene.js
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ const PER_CELL = 1024; // instances per remainder cell
const CELL_EXTENT = 0.1;
const MAX_CELLS = 8192; // remainder draws at most
const INSTANCED_COST = 1.4; // an instanced triangle against a merged one (measured 1.58 / 1.16 ns per triangle)
const PICK_ROUNDING = 2 ** -20; // conservative float32 error for the shader's short matrix products

// True when the linear part of instance i (12 floats per instance, columns first) has a negative determinant.
export function isMirrored(matrices, i) {
Expand Down Expand Up @@ -52,6 +53,17 @@ const finiteBox = (boxes, i) => {
return true;
};

// The positive support vertex tests the whole box against each plane of the pick tile.
function outsidePickBox(planes, boxes, i, padding) {
for (let k = 0; k < 24; k += 4) {
const x = planes[k], y = planes[k + 1], z = planes[k + 2], d = planes[k + 3];
const farthest = x * boxes[i + (x >= 0 ? 3 : 0)] + y * boxes[i + (y >= 0 ? 4 : 1)]
+ z * boxes[i + (z >= 0 ? 5 : 2)] + d;
if (farthest < -(padding + PICK_ROUNDING * Math.abs(d))) return true;
}
return false;
}

// Each row of an affine transform reaches its extrema at the sum of its per-axis extrema.
function writeInstanceBox(matrices, i, { min, max }, boxes) {
const offset = i * 12;
Expand Down Expand Up @@ -117,6 +129,8 @@ export class ModelScene {
this._mode = 'materials';
this._opacity = 1;
this._picking = false;
this._pickBounds = true;
this._pickFrustum = null;
this._textures = new Map();
this._elementOf = data.view(instances.element).slice(); // own copy: the BIN block is released after load
this._bucketOf = new Uint32Array(count);
Expand Down Expand Up @@ -295,8 +309,13 @@ export class ModelScene {
}

// Runs fn with `material` on every chunk's triangles (and triangles shown in wireframe mode), e.g. for picking.
withMaterial(material, fn) {
withMaterial(material, fn, pickCamera = null) {
this._picking = true;
if (pickCamera && this._pickBounds && this._units.length > this._chunkCount) {
this._pickFrustum = frustumPlanes(pickCamera, this._planes);
const { x, y, z } = pickCamera.position;
this._pickViewPadding = PICK_ROUNDING * (Math.abs(x) + Math.abs(y) + Math.abs(z));
}
for (const unit of this._units) {
unit.mesh.material = material;
this._showUnit(unit);
Expand All @@ -305,10 +324,15 @@ export class ModelScene {
return fn();
} finally {
this._picking = false;
this._pickFrustum = null;
for (const unit of this._units) {
unit.mesh.material = unit.bucket.material;
this._showUnit(unit);
}
for (const unit of this._cut) {
unit.mesh.visible = false;
if (unit.lines) unit.lines.visible = false;
}
}
}

Expand Down Expand Up @@ -634,7 +658,17 @@ export class ModelScene {
const i0 = members[0];
const s = source(geometryOf[i0]);
let data = shared.get(shape);
if (!data) shared.set(shape, (data = this._shape(s, mirrored[i0] === 1, shape.textured)));
if (!data) {
const authored = meta.geometries[geometryOf[i0]].bbox;
data = this._shape(s, mirrored[i0] === 1, shape.textured);
const maxAbs = (values) => Math.max(...values.map(Math.abs));
const extent = Math.max(maxAbs(s.min), maxAbs(s.max));
data.pickExtent = extent;
// META bounds describe the authored positions. The decoded ones can extend beyond them.
data.pickPadding = Math.max(0, ...s.min.map((v, a) => authored.min[a] - v), ...s.max.map((v, a) => v - authored.max[a]))
+ (s.q ? PICK_ROUNDING * (maxAbs(s.q.o) + 65535 * Math.abs(s.q.s)) : 0);
shared.set(shape, data);
}
for (let j = 0; j < members.length; j++) {
const i = members[j];
const slot = slotBase + j;
Expand Down Expand Up @@ -702,6 +736,7 @@ export class ModelScene {
geometry.boundingSphere = sphere; // set, so three never computes one from the positions
const mesh = new THREE.InstancedMesh(geometry, bucket.material, 0);
const m = new Float32Array(n * 16); // three's column-major 4 x 4 from the 3 x 4 columns
let pickPadding = 0;
for (let j = 0; j < n; j++) {
const e = members[j] * 12;
for (let c = 0; c < 4; c++) {
Expand All @@ -710,14 +745,19 @@ export class ModelScene {
m[j * 16 + c * 4 + 2] = matrices[e + c * 3 + 2];
}
m[j * 16 + 15] = 1;
for (let a = e; a < e + 3; a++) {
const scale = Math.abs(matrices[a]) + Math.abs(matrices[a + 3]) + Math.abs(matrices[a + 6]);
const magnitude = scale * data.pickExtent + Math.abs(matrices[a + 9]);
pickPadding = Math.max(pickPadding, scale * data.pickPadding + PICK_ROUNDING * magnitude);
}
}
mesh.instanceMatrix = attr(m, 16, false, THREE.InstancedBufferAttribute);
mesh.count = n;
mesh.boundingSphere = sphere;
this._instancedBytes += n * (64 + 4);
const unit = {
bucket, mesh, lines: null, slotBase, n, sphere: s, shown: 0, first: 0, last: -1, end: 0, dirty: false,
cell: true, triangles: data.triangles, lastFrame: -Infinity,
cell: true, triangles: data.triangles, lastFrame: -Infinity, pickPadding: Math.sqrt(3) * pickPadding,
};
mesh.onBeforeRender = (renderer, scene, camera) => this._range(unit, renderer, camera, mesh);
mesh.visible = false;
Expand Down Expand Up @@ -808,7 +848,19 @@ export class ModelScene {
_range(unit, renderer, camera, object) {
if (unit.dirty) this._span(unit);
let end = unit.last + 1;
if (this._minPixels > 0 && end > unit.first) {
if (this._picking) {
if (unit.cell && this._pickFrustum) {
const alpha = this._state.image.data;
const padding = unit.pickPadding + this._pickViewPadding;
// WebGL2 has no base instance. Keep the original draw order and slot IDs, but drop the suffix
// after the last shown instance whose box can intersect the narrow pick tile.
while (end > 0) {
const slot = unit.slotBase + end - 1;
if (alpha[slot * 4 + 3] && !outsidePickBox(this._pickFrustum, this._boxes, this._slotInstance[slot] * 6, padding)) break;
end--;
}
}
} else if (this._minPixels > 0 && end > unit.first) {
const frame = renderer.info.render.frame;
if (frame !== this._frameViewAt) {
viewMetrics(camera, this._viewHeight, this._frameView);
Expand All @@ -825,9 +877,11 @@ export class ModelScene {
const [start, count] = drawSpan(unit.starts, unit.first, end);
object.geometry.setDrawRange(start * wire, count * wire);
}
unit.end = end;
unit.lastFrame = renderer.info.render.frame;
if (this._cutFrame === null && this._minPixels > 0) this._cutFrame = unit.lastFrame;
if (!this._picking) {
unit.end = end;
unit.lastFrame = renderer.info.render.frame;
if (this._cutFrame === null && this._minPixels > 0) this._cutFrame = unit.lastFrame;
}
}

// First and last shown slot of the unit (from the alpha bytes).
Expand Down
2 changes: 1 addition & 1 deletion src/IOViewer/Viewer/src/engine/picking.js
Original file line number Diff line number Diff line change
Expand Up @@ -245,7 +245,7 @@ export class Picker {
try {
renderer.setRenderTarget(target);
renderer.setClearColor(0x000000, 0);
this.scene.withMaterial(material, () => renderer.render(this.scene.root, camera));
this.scene.withMaterial(material, () => renderer.render(this.scene.root, camera), camera);
renderer.readRenderTargetPixels(target, 0, 0, target.width, target.height, pixels);
} finally {
renderer.setRenderTarget(previous.target);
Expand Down
75 changes: 73 additions & 2 deletions src/IOViewer/Viewer/test/perf/orbit.perf.js
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
// PERF_OUT: where JSON results go (default <os temp>/ioviewer-perf); PERF_LABEL names the run (e.g. baseline);
// PERF_PROFILE=1 also writes a CPU profile of each model's whole run; PERF_GPU: see playwright.perf.config.js.
// PERF_STARTUP_ONLY=1 stops after the first rendered frame and writes only the startup measurements.
// PERF_PICK_BOUNDS_ONLY=1 compares full-cell and bounded picking with the same fixed camera and pixels.
// After all runs, one table across them is printed and written with every result to <PERF_OUT>/ladder-<label>.{md,json}.
import { test } from '@playwright/test';
import { execFileSync } from 'node:child_process';
Expand All @@ -23,6 +24,7 @@ const MODELS = list(process.env.PERF_MODELS ?? (LADDER.length ? '' : path.join(O
const VARIANTS = list(process.env.PERF_VARIANTS);
const LABEL = process.env.PERF_LABEL ?? 'run';
const STARTUP_ONLY = process.env.PERF_STARTUP_ONLY === '1';
const PICK_BOUNDS_ONLY = process.env.PERF_PICK_BOUNDS_ONLY === '1';
const ORBIT_MS = 5000;
const REPO = fileURLToPath(new URL('../../../../../', import.meta.url));
const LIBRARY = path.join(REPO, 'src', 'IOViewer');
Expand Down Expand Up @@ -75,6 +77,62 @@ function quantile(values, q) {
return sorted.length ? sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))] : NaN;
}

async function comparePickBounds(page) {
const groups = await page.evaluate(() => {
const { scene, picker, camera } = window.__ioviewer;
if (typeof scene._pickBounds !== 'boolean') throw new Error('Export the model with the current viewer bundle.');
const query = (enabled, [x, y]) => {
scene._pickBounds = enabled;
picker._last = null;
const start = performance.now();
const hit = picker.pick(x, y);
return { hit, time: performance.now() - start, triangles: picker.renderer.info.render.triangles };
};
const grid = Array.from({ length: 81 }, (_, i) => [innerWidth / 2 + (i % 9 - 4) * 37, innerHeight / 2 + (Math.floor(i / 9) - 4) * 29]);
const targets = [];
const seen = new Set();
const point = camera.position.clone();
const boxes = scene._boxes;
for (let i = 0, step = Math.max(1, Math.ceil(scene.instanceCount / 512)); i < scene.instanceCount && targets.length < 48; i += step) {
const k = i * 6;
point.set((boxes[k] + boxes[k + 3]) / 2, (boxes[k + 1] + boxes[k + 4]) / 2, (boxes[k + 2] + boxes[k + 5]) / 2).project(camera);
const x = Math.floor((point.x + 1) * innerWidth / 2), y = Math.floor((1 - point.y) * innerHeight / 2);
if (!(point.z >= -1 && point.z <= 1 && x >= 0 && y >= 0 && x < innerWidth && y < innerHeight)) continue;
const key = y * innerWidth + x;
if (seen.has(key)) continue;
seen.add(key);
if (query(false, [x, y]).hit) targets.push([x, y]);
}
for (const pixel of grid.slice(0, 9)) for (const mode of [false, true]) query(mode, pixel);
const measure = (pixels) => {
const full = [], bounded = [];
let hits = 0;
for (let i = 0; i < 3 * pixels.length; i++) {
const pixel = pixels[i % pixels.length];
const a = query(i % 2 !== 0, pixel), b = query(i % 2 === 0, pixel);
const [before, after] = i % 2 ? [b, a] : [a, b];
if (before.hit?.element !== after.hit?.element || (before.hit && !before.hit.point.equals(after.hit.point)))
throw new Error(`Picking with bounds changed the hit at pixel ${pixel.join(', ')}`);
if (before.hit) hits++;
full.push(before);
bounded.push(after);
}
return { samples: full.length, hits, full, bounded };
};
const result = { grid: measure(grid), hits: measure(targets) };
scene._pickBounds = true;
picker._last = null;
return result;
});
const summarize = (records) => ({
p50Ms: median(records.map((r) => r.time)), p95Ms: quantile(records.map((r) => r.time), 0.95),
medianTriangles: median(records.map((r) => r.triangles)),
});
return Object.fromEntries(Object.entries(groups).map(([name, { samples, hits, full, bounded }]) => [
name, { samples, hits, full: summarize(full), bounded: summarize(bounded) },
]));
}

// Programmatic orbit about the vertical axis through the target (~46°/s) for `ms`; returns per frame the interval, the
// share of the instances in view that the previous render drew, and its detail threshold (px, 0 = full).
// fullDetail lifts the motion-detail budget, so every frame draws everything in view.
Expand Down Expand Up @@ -308,12 +366,18 @@ for (const run of RUNS) {
writeFileSync(path.join(OUT, `profile-${LABEL}-${name}.cpuprofile`), JSON.stringify(profile));
}
save(result);
if (!STARTUP_ONLY) console.log(table(result));
if (result.pickBounds) console.log(JSON.stringify({ model: result.model, renderer: result.renderer, ...result.pickBounds }));
else if (!STARTUP_ONLY) console.log(table(result));
};
if (STARTUP_ONLY) {
await finish();
return;
}
if (PICK_BOUNDS_ONLY) {
result.pickBounds = await comparePickBounds(page);
await finish();
return;
}
await installTimer(page);
if (run.variant === 'sections') await page.evaluate(() => window.__ioviewer.sections.setMode('box')); // box = the shown model
if (run.variant === 'textures') await page.evaluate(() => window.__ioviewer.scene.setDisplayMode('textures'));
Expand Down Expand Up @@ -445,7 +509,14 @@ test.afterAll(() => {
['startup blocking ms (over 50 ms)', (r) => n(r.startup.blockingMs)],
['sampled peak startup JS heap MiB', (r) => n(r.startup.sampledHeapPeakMiB, 0)],
];
const rows = STARTUP_ONLY ? startupRows : [
const rows = STARTUP_ONLY ? startupRows : PICK_BOUNDS_ONLY ? [
...['grid', 'hits'].flatMap((group) => ['full', 'bounded'].map((mode) => [
`${group} ${mode} pick ms, p50 / p95`, (r) => {
const sample = r.pickBounds[group][mode];
return `${n(sample.p50Ms)} / ${n(sample.p95Ms)}`;
},
])),
] : [
...startupRows,
['full-detail still frame ms, median (max of 10)', (r) => still(r.stillFrame)],
['draw calls (still frame)', (r) => String(r.stillFrame?.calls ?? '—')],
Expand Down
46 changes: 46 additions & 0 deletions src/IOViewer/Viewer/test/unit/modelScene.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -392,6 +392,44 @@ test('cell wireframe: three\'s wireframe over the cell\'s geometry and matrices;
assert.deepEqual([m.opacity, m.transparent, m.depthWrite, m.clipIntersection, m.clippingPlanes.length], [0.5, true, false, true, 1]);
});

test('a pick draws only through the last cell slot intersecting its tile, in original order', () => {
const scene = model([{ x: 0 }, { x: 4 }, { x: 8 }, { x: 12 }], { options: { ...INSTANCED, cellExtent: 1 } });
const { mesh } = scene.instance(0);
const pick = new THREE.MeshBasicMaterial();
const c = new THREE.OrthographicCamera(-0.1, 0.1, 0.1, -0.1, 0.1, 20);
const drawCount = (x) => {
c.position.set(x, 0, 5);
c.updateMatrixWorld();
return scene.withMaterial(pick, () => {
mesh.onBeforeRender(renderer, null, c, mesh.geometry, pick);
return mesh.count;
}, c);
};
assert.equal(drawCount(0), 1);
assert.equal(drawCount(4), 2);
assert.equal(drawCount(3), 0);
scene.setVisible([1], false);
assert.equal(drawCount(4), 0);
assert.equal(drawCount(8), 3);
mesh.onBeforeRender(renderer, null, c, mesh.geometry, mesh.material);
assert.equal(mesh.count, 4);
});

test('the pick tile includes encoded geometry extending beyond the authored bounds', () => {
const geometry = quantizedCube();
geometry.bbox.max[0] = 0.5 - GRID / 4;
const scene = model([{ x: 0 }], { geometries: [geometry], options: INSTANCED });
const { mesh } = scene.instance(0);
const pick = new THREE.MeshBasicMaterial();
const c = new THREE.OrthographicCamera(-GRID / 32, GRID / 32, 0.1, -0.1, 0.1, 20);
c.position.set(0.5 - GRID / 8, 0, 5);
c.updateMatrixWorld();
scene.withMaterial(pick, () => {
mesh.onBeforeRender(renderer, null, c, mesh.geometry, pick);
assert.equal(mesh.count, 1);
}, c);
});

test('over the cap, cells are bounded in extent: one shape spread along 190 m takes several cells', () => {
const scene = model(Array.from({ length: 20 }, (_, i) => ({ x: i * 10 })), { options: { mergedCap: 0, minRepeats: 1 } });
const { cells, instancedInstances } = scene.memory();
Expand All @@ -414,6 +452,14 @@ test('a unit the detail cut leaves empty is hidden for that frame, counted in vi
assert.deepEqual([big.visible, small.visible], [true, false]);
big.onBeforeRender({ info: { render: { frame: 7 } } }, null, c, big.geometry, big.material, null);
assert.deepEqual(scene.drawStats(), { drawn: 12, inView: 24, draws: 1 });
const pick = new THREE.MeshBasicMaterial();
scene.withMaterial(pick, () => {
assert.ok(small.visible);
small.onBeforeRender({ info: { render: { frame: 8 } } }, null, c, small.geometry, pick);
assert.equal(small.geometry.drawRange.count, 36);
}, c);
assert.equal(small.visible, false);
assert.deepEqual(scene.drawStats(), { drawn: 12, inView: 24, draws: 1 });
scene.setDetail(0);
assert.deepEqual([big.visible, small.visible], [true, true]);
// Without a fresh detailThreshold (a still frame) nothing is hidden.
Expand Down
Loading