Skip to content
Draft
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
2 changes: 2 additions & 0 deletions docs/scene-language.md
Original file line number Diff line number Diff line change
Expand Up @@ -239,6 +239,8 @@ This is base-pose placement, not a live joint or a physics constraint. Ordinary

All take `id` and optionally `at` and `dur`. These apply to 3D objects (`move`, `along`, `turn`, `scale`, `explode`, `reveal`) or to any object or mark (`style`, `highlight`). `style` and `highlight` on a group reach everything inside it.

A fully hidden parent hides its descendants, including children added after it was hidden. Hidden subtrees do not affect camera framing, contact shadows, label space or cut caps. Showing them includes them again. See [`visible-model-bounds.json`](../samples/scenes/visible-model-bounds.json).

| op | fields | |
|---|---|---|
| `move` | `to: [x,y,z]` | tween to an absolute position |
Expand Down
32 changes: 32 additions & 0 deletions samples/scenes/visible-model-bounds.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
{
"v": 1,
"steps": [
{
"say": "The visible solid should fill the stage, with a close contact shadow.",
"actions": [
{ "op": "panel", "x": 100, "y": 100, "w": 600, "h": 500 },
{ "op": "orbit", "az": 22, "el": 18, "dur": 0 },
{ "op": "add", "shape": "box", "id": "body", "size": [2, 1.5, 1.5], "color": "teal", "material": "plastic" },
{ "op": "pin", "id": "label", "on": "body", "text": "Visible solid" }
]
},
{
"say": "Hidden detail arrives under a hidden group. The visible solid, its framing and its shadow should remain unchanged, with no floating cut faces.",
"actions": [
{ "op": "add", "shape": "group", "id": "hidden" },
{ "op": "style", "id": "hidden", "opacity": 0, "dur": 0 },
{ "op": "add", "shape": "box", "id": "remote", "parent": "hidden", "size": [12, 10, 8], "pos": [20, 0, 0], "color": "orange" },
{ "op": "add", "shape": "part", "part": "header", "id": "pins", "parent": "hidden", "size": [8, 4, 6], "pos": [-20, 0, 0] },
{ "op": "cut", "id": "hidden", "axis": "z", "to": 0, "dur": 0 }
]
},
{
"say": "Showing the group now includes the extra pieces in the framing and restores their cut faces.",
"actions": [ { "op": "style", "id": "hidden", "opacity": 1, "dur": 0 } ]
},
{
"say": "Hiding it again returns to the original solid and contact shadow.",
"actions": [ { "op": "style", "id": "hidden", "opacity": 0, "dur": 0 } ]
}
]
}
6 changes: 4 additions & 2 deletions src/overlay/cutaway.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ import {
import type { Material, Object3D, StencilOp } from 'three';
import { hatched, sectionTone } from './materials.ts';
import type { Frame } from './timeline.ts';
import { isVisible, visibleBounds } from './visible-bounds.ts';

/** What the cutting needs to know of a drawn object: its three.js root, its meshes, and how it looks just now. */
export type CutPiece = {
Expand Down Expand Up @@ -63,7 +64,8 @@ export class Cutaway {
let radius = 10;
if (user > 0 || frame.objects.some((o) => o.cut)) {
this.box.makeEmpty();
for (const node of nodes.values()) if (node.obj.visible) this.box.expandByObject(node.obj);
const visible = new Box3();
for (const node of nodes.values()) this.box.union(visibleBounds(node.obj, visible));
if (!this.box.isEmpty()) radius = Math.max(1, this.box.getSize(new Vector3()).length());
}
if (user > 0 && !this.box.isEmpty()) {
Expand Down Expand Up @@ -130,7 +132,7 @@ export class Cutaway {
material.clipShadows = true;
material.side = DoubleSide;
if (p.lines) (p.lines.material as Material).clippingPlanes = planes;
const capped = p.closed && (material as { userData?: { base?: number } }).userData?.base === 1 && node.alpha >= 0.98 && node.obj.visible;
const capped = p.closed && (material as { userData?: { base?: number } }).userData?.base === 1 && node.alpha >= 0.98 && isVisible(mesh);
// One helper set for each plane that cuts this part; spare ones are put away.
while (state.helpers.length > planes.length) this.retire(state.helpers.pop()!);
for (let i = 0; i < planes.length; i++) {
Expand Down
35 changes: 16 additions & 19 deletions src/overlay/scene3d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ import type { Part } from './explode.ts';
import { PATCH_SEGMENTS } from '../scene/patch.ts';
import { patchGeometry, patchEdges } from './patch.ts';
import { Cutaway } from './cutaway.ts';
import { isVisible, visibleBounds } from './visible-bounds.ts';
import { anchorsOf } from '../scene/anchors.ts';
import { latheSectorEdges, latheSectorGeometry } from './lathe-sector.ts';
import { buildConnector, buildStream, updateAttached, updateConnectors, updateStreams } from './scene3d-flow.ts';
Expand Down Expand Up @@ -762,7 +763,7 @@ export class PanelScene {
const sprite = node.obj;
if (!(sprite instanceof Sprite)) continue;
sprite.center.set(0.5, 0.5);
if (!sprite.visible) continue;
if (!isVisible(sprite)) continue;
sprite.getWorldPosition(p);
const depth = -p.clone().applyMatrix4(this.camera.matrixWorldInverse).z;
if (depth <= 0) continue;
Expand Down Expand Up @@ -826,14 +827,14 @@ export class PanelScene {
private partSpheres(): PartHull[] {
const spheres: PartHull[] = [];
for (const node of this.nodes.values()) {
if (!node.obj.visible || node.obj instanceof Sprite || node.pieces.length === 0 || (node.path && !node.path.body) || node.stream) continue;
if (!isVisible(node.obj) || node.obj instanceof Sprite || node.pieces.length === 0 || (node.path && !node.path.body) || node.stream) continue;
for (const p of node.pieces) {
const mesh = p.object as Mesh;
const geo = mesh.geometry;
if (!geo) continue;
if (!geo || !isVisible(mesh)) continue;
if (mesh instanceof InstancedMesh) {
// The geometry is one instance; the piece is where all of them are.
const box = new Box3().setFromObject(mesh);
const box = visibleBounds(mesh, new Box3());
if (!box.isEmpty()) spheres.push({ sphere: box.getBoundingSphere(new Sphere()), corners: boxCorners(box, undefined) });
continue;
}
Expand All @@ -856,10 +857,10 @@ export class PanelScene {
const p = new Vector3();
const proj = this.camera.projectionMatrix.elements;
for (const node of this.nodes.values()) {
if (!node.obj.visible || node.obj instanceof Sprite || node.pieces.length === 0 || (node.path && !node.path.body) || node.stream) continue;
if (!isVisible(node.obj) || node.obj instanceof Sprite || node.pieces.length === 0 || (node.path && !node.path.body) || node.stream) continue;
for (const piece of node.pieces) {
const mesh = piece.object as Mesh;
box.setFromObject(mesh);
visibleBounds(mesh, box);
if (box.isEmpty()) continue;
let a0 = Infinity, b0 = Infinity, a1 = -Infinity, b1 = -Infinity;
for (const x of [box.min.x, box.max.x]) for (const y of [box.min.y, box.max.y]) for (const z of [box.min.z, box.max.z]) {
Expand Down Expand Up @@ -902,7 +903,7 @@ export class PanelScene {
let anywhere = false;
this.scene.traverseVisible((o) => {
if (!((o as Mesh).isMesh || (o as LineSegments).isLineSegments || (o as Sprite).isSprite)) return;
box.setFromObject(o);
visibleBounds(o, box);
if (box.isEmpty()) return;
for (const x of [box.min.x, box.max.x]) for (const y of [box.min.y, box.max.y]) for (const z of [box.min.z, box.max.z]) {
p.set(x, y, z);
Expand Down Expand Up @@ -956,8 +957,8 @@ export class PanelScene {
const box = new Box3();
const corner = new Vector3();
for (const node of this.nodes.values()) {
if (!node.obj.visible || node.obj instanceof Sprite || node.pieces.length === 0 || (node.path && !node.path.body) || node.stream) continue;
box.setFromObject(node.obj);
if (!isVisible(node.obj) || node.obj instanceof Sprite || node.pieces.length === 0 || (node.path && !node.path.body) || node.stream) continue;
visibleBounds(node.obj, box);
if (box.isEmpty()) continue;
for (const x of [box.min.x, box.max.x]) for (const y of [box.min.y, box.max.y]) for (const z of [box.min.z, box.max.z]) far = Math.max(far, corner.set(x, y, z).distanceTo(from));
}
Expand All @@ -971,8 +972,8 @@ export class PanelScene {
// How solid the model is, by its biggest part: a shadow under a see-through shell would grey the layers inside it.
let biggest = 0, solidity = 1, smallestRadius = Infinity;
for (const node of this.nodes.values()) {
if (!node.obj.visible || node.obj instanceof Sprite || node.pieces.length === 0 || (node.path && !node.path.body) || node.stream) continue;
const b = new Box3().setFromObject(node.obj);
if (!isVisible(node.obj) || node.obj instanceof Sprite || node.pieces.length === 0 || (node.path && !node.path.body) || node.stream) continue;
const b = visibleBounds(node.obj, new Box3());
if (!b.isEmpty()) {
this.box.union(b);
this.hasBox = true;
Expand Down Expand Up @@ -1038,10 +1039,6 @@ export class PanelScene {
return { x: 0, y: 0, visible: false };
};
if (!node) { hidden(); return undefined; }
const isVisible = (obj: Object3D): boolean => {
for (let p: Object3D | null = obj; p; p = p.parent) if (!p.visible) return false;
return true;
};
if (!isVisible(node.obj) || node.alpha <= 0.003) return hidden();
// Scene text is a camera-facing sprite drawn with depth testing disabled.
// Its origin is also used by the text-layout and clipping calculations.
Expand All @@ -1066,7 +1063,7 @@ export class PanelScene {
const explicit = named ?? point;
if (explicit) candidates.push(new Vector3(...explicit).applyMatrix4(node.obj.matrixWorld));
else {
const box = new Box3().setFromObject(node.obj);
const box = visibleBounds(node.obj, new Box3());
if (!box.isEmpty()) candidates.push(box.getCenter(new Vector3()));
if (node.path?.sampled.length) for (let i = 0; i < 12; i++) {
const p = node.path.sampled[Math.floor((node.path.sampled.length - 1) * i / 11)]!;
Expand Down Expand Up @@ -1189,12 +1186,12 @@ export class PanelScene {
const hulls: Pt[][] = [];
const corner = new Vector3();
for (const node of this.nodes.values()) {
if (!node.obj.visible || node.obj instanceof Sprite || node.path || node.stream) continue;
if (!isVisible(node.obj) || node.obj instanceof Sprite || node.path || node.stream) continue;
for (const piece of node.pieces) {
const o = piece.object;
if (!(o instanceof Mesh) || !o.visible) continue;
if (!(o instanceof Mesh) || !isVisible(o)) continue;
const box = new Box3();
if (o instanceof InstancedMesh) box.setFromObject(o);
if (o instanceof InstancedMesh) visibleBounds(o, box);
else {
const geo = o.geometry as BufferGeometry;
if (!geo.boundingBox) geo.computeBoundingBox();
Expand Down
32 changes: 32 additions & 0 deletions src/overlay/visible-bounds.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
// Three.js hides a whole subtree when any ancestor is invisible. Its generic
// Box3.setFromObject deliberately does not, so display bounds need this filter.
import { Box3, InstancedMesh, LineSegments, Mesh, Sprite } from 'three';
import type { Object3D } from 'three';

export function isVisible(object: Object3D): boolean {
for (let p: Object3D | null = object; p; p = p.parent) if (!p.visible) return false;
return true;
}

/** Like setFromObject, but excludes hidden descendants. Includes visible children
* of a mesh and every instance; never changes transforms, geometry or visibility. */
export function visibleBounds(object: Object3D, target: Box3): Box3 {
target.makeEmpty();
if (!isVisible(object)) return target;
const box = new Box3();
object.traverseVisible(o => {
if (!(o instanceof Mesh || o instanceof LineSegments || o instanceof Sprite)) return;
if (o instanceof InstancedMesh) {
if (!o.boundingBox) o.computeBoundingBox();
if (!o.boundingBox) return;
box.copy(o.boundingBox);
} else {
if (!o.geometry.boundingBox) o.geometry.computeBoundingBox();
if (!o.geometry.boundingBox) return;
box.copy(o.geometry.boundingBox);
}
o.updateWorldMatrix(true, false);
target.union(box.applyMatrix4(o.matrixWorld));
});
return target;
}
48 changes: 48 additions & 0 deletions test/overlay-visible-bounds-helper.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { Box3, BoxGeometry, Group, InstancedMesh, Matrix4, Mesh, MeshBasicMaterial, Sprite } from 'three';
import { visibleBounds } from '../src/overlay/visible-bounds.ts';

test('visible bounds preserve mesh children, instances and sprites under nested transforms', () => {
const root = new Group();
root.position.set(11, 12, 13);
root.scale.set(2, 3, 4);
root.rotation.set(0.1, 0.2, 0.3);
const parent = new Mesh(new BoxGeometry(1, 2, 3));
root.add(parent);
parent.rotation.set(0.2, 0.4, 0.6);
const child = new Mesh(new BoxGeometry(3, 4, 5));
child.position.set(100, 7, 8);
parent.add(child);
const instances = new InstancedMesh(new BoxGeometry(1, 1, 1), new MeshBasicMaterial(), 2);
instances.setMatrixAt(0, new Matrix4().makeTranslation(-70, 3, 4));
instances.setMatrixAt(1, new Matrix4().makeTranslation(45, 6, 8));
child.add(instances);
const sprite = new Sprite();
sprite.position.set(10, 20, 30);
root.add(sprite);
try {
root.updateMatrixWorld(true);
const expected = new Box3().setFromObject(root);
assert.deepEqual(visibleBounds(root, new Box3()), expected);
child.visible = false;
const hidden = visibleBounds(root, new Box3());
parent.remove(child);
root.updateMatrixWorld(true);
assert.deepEqual(hidden, new Box3().setFromObject(root));
parent.add(child);
child.visible = true;
assert.deepEqual(visibleBounds(root, new Box3()), expected);
root.visible = false;
assert.equal(visibleBounds(child, new Box3()).isEmpty(), true);
} finally {
parent.geometry.dispose();
child.geometry.dispose();
instances.geometry.dispose();
(parent.material as MeshBasicMaterial).dispose();
(child.material as MeshBasicMaterial).dispose();
instances.material.dispose();
instances.dispose();
sprite.material.dispose();
}
});
Loading
Loading