@woosh/meep-engine 3.1.0 → 3.3.0

package/src/engine/graphics3/preview/make_model_preview_scene.js

@@ -1,154 +1,154 @@
-import { assert } from "../../../core/assert.js";
-import Quaternion from "../../../core/geom/Quaternion.js";
-import Vector3 from "../../../core/geom/Vector3.js";
-import { PerspectiveCamera } from "../../../shade/renderer/camera/PerspectiveCamera.js";
-import { DirectionalLight } from "../../../shade/renderer/light/model/DirectionalLight.js";
-import { Mesh } from "../../../shade/renderer/scene/Mesh.js";
-import { Node3D } from "../../../shade/renderer/scene/Node3D.js";
-import { Scene } from "../../../shade/renderer/scene/Scene.js";
-
-/**
- * Vertical field of view a preview is drawn with, radians. Narrow enough that a model does not bend
- * at its edges and wide enough that it is not an orthographic projection in disguise.
- *
- * @type {number}
- */
-export const MODEL_PREVIEW_FOV = 45 * Math.PI / 180;
-
-/**
- * The lights a preview is lit by: a direction to point each one in, and its strength.
- *
- * A key from over the viewer's shoulder, a weaker one straight down the view axis so the side
- * facing us is not read off the key alone, and a dim one from behind and below so a silhouette does
- * not close up into black.
- *
- * **There is no ambient term.** Shade takes ambient from the environment map, and a preview scene
- * has none: an icon of a model is a picture of the model, not of a place it would stand in.
- *
- * @type {{direction: number[], intensity: number}[]}
- */
-const LIGHTS = [
-    { direction: [1, -1, 1], intensity: 3 },
-    { direction: [0, 0, 1], intensity: 1.5 },
-    { direction: [-0.5, 1, -0.5], intensity: 0.6 }
-];
-
-const scratch_rotation = new Quaternion();
-const scratch_direction = new Vector3();
-const scratch_target = new Vector3(0, 0, 0);
-
-/**
- * @param {number[]} direction
- * @param {number} intensity
- * @returns {DirectionalLight}
- */
-function makeLight(direction, intensity) {
-    const light = new DirectionalLight();
-
-    // a preview is one object over nothing; a shadow has nothing to fall on and costs an atlas
-    light.casts_shadow = false;
-    light.intensity = intensity;
-
-    scratch_direction.set(direction[0], direction[1], direction[2]).normalize();
-
-    scratch_rotation.fromUnitVectors(Vector3.forward, scratch_direction);
-    scratch_rotation.normalize();
-
-    light.transform_local.setRotation(
-        scratch_rotation.x,
-        scratch_rotation.y,
-        scratch_rotation.z,
-        scratch_rotation.w
-    );
-
-    light.updateMatrices();
-
-    return light;
-}
-
-/**
- * A scene holding one model and the light to see it by, and a camera framed on it.
- *
- * **The bundle is read, never moved.** A loaded model is shared — the asset manager hands the same
- * `SceneBundle` to everything that places it — so a preview that scaled the bundle's own roots to
- * fit an icon would scale every copy of that model in the world. What goes into the preview scene
- * is a fresh `Mesh` per drawing node, over the *same* geometry and the *same* material, placed at
- * the node's own global transform under a root carrying the framing.
- *
- * **A skinned mesh does not come across**, the same boundary `shade_node_to_entity_composition`
- * draws: its vertices are deformed against a skeleton the renderer poses, and a preview scene has
- * registered no skin. A model that is nothing but skinned meshes therefore previews as an empty
- * frame, which is what `false` says.
- *
- * @param {SceneBundle} bundle
- * @param {ModelPreviewFraming} framing as `model_preview_framing` answered for this bundle
- * @param {number} aspect_ratio width over height of the picture
- * @returns {{scene: Scene, camera: PerspectiveCamera, drawn: number}} `drawn` is how many meshes
- * the preview holds; zero means there is nothing to look at
- */
-export function make_model_preview_scene(bundle, framing, aspect_ratio) {
-    assert.defined(bundle, 'bundle');
-    assert.defined(framing, 'framing');
-    assert.greaterThan(aspect_ratio, 0, 'aspect_ratio');
-
-    const scene = new Scene();
-
-    const root = new Node3D();
-
-    const scale = framing.scale;
-    const offset = framing.offset;
-
-    root.transform_local.setScale(scale, scale, scale);
-    root.transform_local.setTranslation(offset.x, offset.y, offset.z);
-
-    let drawn = 0;
-
-    const scenes = bundle.scenes;
-
-    for (let i = 0; i < scenes.length; i++) {
-        scenes[i].updateMatrices();
-
-        scenes[i].traverse(node => {
-            if (node.isMesh !== true || node.isSkinnedMesh === true) {
-                return;
-            }
-
-            const copy = Mesh.from(node.geometry, node.material);
-
-            copy.name = node.name;
-            copy.transform_local.copy(node.transform_global);
-
-            root.addChild(copy);
-
-            drawn++;
-        });
-    }
-
-    root.updateMatrices();
-
-    scene.add(root);
-
-    for (let i = 0; i < LIGHTS.length; i++) {
-        scene.add(makeLight(LIGHTS[i].direction, LIGHTS[i].intensity));
-    }
-
-    const camera = new PerspectiveCamera();
-
-    camera.fov = MODEL_PREVIEW_FOV;
-    camera.aspect = aspect_ratio;
-    camera.near = 0.01;
-    camera.far = framing.camera_distance * 4 + 4;
-
-    /*
-     Which side the camera stands on is the renderer's convention, and this is where it is applied:
-     Shade's own samples put a camera at negative Z looking back at the origin, so that is where a
-     preview's camera stands.
-    */
-    camera.transform.position.set(0, 0, -framing.camera_distance);
-
-    camera.transform.lookAt(scratch_target);
-
-    camera.update_matrices();
-
-    return { scene, camera, drawn };
-}
+import { assert } from "../../../core/assert.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { PerspectiveCamera } from "../../../shade/renderer/camera/PerspectiveCamera.js";
+import { DirectionalLight } from "../../../shade/renderer/light/model/DirectionalLight.js";
+import { Mesh } from "../../../shade/renderer/scene/Mesh.js";
+import { Node3D } from "../../../shade/renderer/scene/Node3D.js";
+import { Scene } from "../../../shade/renderer/scene/Scene.js";
+
+/**
+ * Vertical field of view a preview is drawn with, radians. Narrow enough that a model does not bend
+ * at its edges and wide enough that it is not an orthographic projection in disguise.
+ *
+ * @type {number}
+ */
+export const MODEL_PREVIEW_FOV = 45 * Math.PI / 180;
+
+/**
+ * The lights a preview is lit by: a direction to point each one in, and its strength.
+ *
+ * A key from over the viewer's shoulder, a weaker one straight down the view axis so the side
+ * facing us is not read off the key alone, and a dim one from behind and below so a silhouette does
+ * not close up into black.
+ *
+ * **There is no ambient term.** Shade takes ambient from the environment map, and a preview scene
+ * has none: an icon of a model is a picture of the model, not of a place it would stand in.
+ *
+ * @type {{direction: number[], intensity: number}[]}
+ */
+const LIGHTS = [
+    { direction: [1, -1, 1], intensity: 3 },
+    { direction: [0, 0, 1], intensity: 1.5 },
+    { direction: [-0.5, 1, -0.5], intensity: 0.6 }
+];
+
+const scratch_rotation = new Quaternion();
+const scratch_direction = new Vector3();
+const scratch_target = new Vector3(0, 0, 0);
+
+/**
+ * @param {number[]} direction
+ * @param {number} intensity
+ * @returns {DirectionalLight}
+ */
+function makeLight(direction, intensity) {
+    const light = new DirectionalLight();
+
+    // a preview is one object over nothing; a shadow has nothing to fall on and costs an atlas
+    light.casts_shadow = false;
+    light.intensity = intensity;
+
+    scratch_direction.set(direction[0], direction[1], direction[2]).normalize();
+
+    scratch_rotation.fromUnitVectors(Vector3.forward, scratch_direction);
+    scratch_rotation.normalize();
+
+    light.transform_local.setRotation(
+        scratch_rotation.x,
+        scratch_rotation.y,
+        scratch_rotation.z,
+        scratch_rotation.w
+    );
+
+    light.updateMatrices();
+
+    return light;
+}
+
+/**
+ * A scene holding one model and the light to see it by, and a camera framed on it.
+ *
+ * **The bundle is read, never moved.** A loaded model is shared — the asset manager hands the same
+ * `SceneBundle` to everything that places it — so a preview that scaled the bundle's own roots to
+ * fit an icon would scale every copy of that model in the world. What goes into the preview scene
+ * is a fresh `Mesh` per drawing node, over the *same* geometry and the *same* material, placed at
+ * the node's own global transform under a root carrying the framing.
+ *
+ * **A skinned mesh does not come across**, the same boundary `shade_node_to_entity_composition`
+ * draws: its vertices are deformed against a skeleton the renderer poses, and a preview scene has
+ * registered no skin. A model that is nothing but skinned meshes therefore previews as an empty
+ * frame, which is what `false` says.
+ *
+ * @param {SceneBundle} bundle
+ * @param {ModelPreviewFraming} framing as `model_preview_framing` answered for this bundle
+ * @param {number} aspect_ratio width over height of the picture
+ * @returns {{scene: Scene, camera: PerspectiveCamera, drawn: number}} `drawn` is how many meshes
+ * the preview holds; zero means there is nothing to look at
+ */
+export function make_model_preview_scene(bundle, framing, aspect_ratio) {
+    assert.defined(bundle, 'bundle');
+    assert.defined(framing, 'framing');
+    assert.greaterThan(aspect_ratio, 0, 'aspect_ratio');
+
+    const scene = new Scene();
+
+    const root = new Node3D();
+
+    const scale = framing.scale;
+    const offset = framing.offset;
+
+    root.transform_local.setScale(scale, scale, scale);
+    root.transform_local.setTranslation(offset.x, offset.y, offset.z);
+
+    let drawn = 0;
+
+    const scenes = bundle.scenes;
+
+    for (let i = 0; i < scenes.length; i++) {
+        scenes[i].updateMatrices();
+
+        scenes[i].traverse(node => {
+            if (node.isMesh !== true || node.isSkinnedMesh === true) {
+                return;
+            }
+
+            const copy = Mesh.from(node.geometry, node.material);
+
+            copy.name = node.name;
+            copy.transform_local.copy(node.transform_global);
+
+            root.addChild(copy);
+
+            drawn++;
+        });
+    }
+
+    root.updateMatrices();
+
+    scene.add(root);
+
+    for (let i = 0; i < LIGHTS.length; i++) {
+        scene.add(makeLight(LIGHTS[i].direction, LIGHTS[i].intensity));
+    }
+
+    const camera = new PerspectiveCamera();
+
+    camera.fov = MODEL_PREVIEW_FOV;
+    camera.aspect = aspect_ratio;
+    camera.near = 0.01;
+    camera.far = framing.camera_distance * 4 + 4;
+
+    /*
+     Which side the camera stands on is the renderer's convention, and this is where it is applied:
+     Shade's own samples put a camera at negative Z looking back at the origin, so that is where a
+     preview's camera stands.
+    */
+    camera.transform.position.set(0, 0, -framing.camera_distance);
+
+    camera.transform.lookAt(scratch_target);
+
+    camera.update_matrices();
+
+    return { scene, camera, drawn };
+}

package/src/engine/graphics3/preview/make_model_thumbnail.js

@@ -1,48 +1,48 @@
-import { assert } from "../../../core/assert.js";
-import { AABB3 } from "../../../core/geom/3d/aabb/AABB3.js";
-import { shade_bundle_bounds } from "../shade_bundle_bounds.js";
-import { make_model_preview_scene, MODEL_PREVIEW_FOV } from "./make_model_preview_scene.js";
-import { model_preview_framing } from "./model_preview_framing.js";
-import { ModelPreviewFraming } from "./ModelPreviewFraming.js";
-
-/**
- * A picture of a loaded model, framed on itself.
- *
- * The four steps are each somebody's: where the model is (`shade_bundle_bounds`), how to frame it
- * (`model_preview_framing`), what a scene of one model looks like (`make_model_preview_scene`), and
- * how a frame becomes pixels (`GraphicsEngine3.render_to_sampler`). This is only the order.
- *
- * **A model with nothing to draw has no picture, and that is data rather than a fault**: a glTF of
- * empties, or one whose every mesh is skinned — a preview scene registers no skin, so a skinned
- * mesh is not in it. The answer then is `null`, and a caller showing icons shows none for that
- * asset rather than a blank square that reads as a broken renderer.
- *
- * @param {GraphicsEngine3} graphics
- * @param {SceneBundle} bundle
- * @param {number} width texels
- * @param {number} height texels
- * @param {number} [margin] fraction of the frame's height left clear around the model
- * @returns {Promise<Sampler2D|null>}
- */
-export async function make_model_thumbnail(graphics, bundle, width, height, margin = 0) {
-    assert.defined(graphics, 'graphics');
-    assert.defined(bundle, 'bundle');
-
-    // held locally rather than in module scratch: a caller may have several thumbnails in flight,
-    // and what each of them is framing must not be what the last one was
-    const bounds = new AABB3();
-
-    if (!shade_bundle_bounds(bounds, bundle)) {
-        return null;
-    }
-
-    const framing = model_preview_framing(new ModelPreviewFraming(), bounds, MODEL_PREVIEW_FOV, margin);
-
-    const { scene, camera, drawn } = make_model_preview_scene(bundle, framing, width / height);
-
-    if (drawn === 0) {
-        return null;
-    }
-
-    return graphics.render_to_sampler(scene, camera, width, height);
-}
+import { assert } from "../../../core/assert.js";
+import { AABB3 } from "../../../core/geom/3d/aabb/AABB3.js";
+import { shade_bundle_bounds } from "../shade_bundle_bounds.js";
+import { make_model_preview_scene, MODEL_PREVIEW_FOV } from "./make_model_preview_scene.js";
+import { model_preview_framing } from "./model_preview_framing.js";
+import { ModelPreviewFraming } from "./ModelPreviewFraming.js";
+
+/**
+ * A picture of a loaded model, framed on itself.
+ *
+ * The four steps are each somebody's: where the model is (`shade_bundle_bounds`), how to frame it
+ * (`model_preview_framing`), what a scene of one model looks like (`make_model_preview_scene`), and
+ * how a frame becomes pixels (`GraphicsEngine3.render_to_sampler`). This is only the order.
+ *
+ * **A model with nothing to draw has no picture, and that is data rather than a fault**: a glTF of
+ * empties, or one whose every mesh is skinned — a preview scene registers no skin, so a skinned
+ * mesh is not in it. The answer then is `null`, and a caller showing icons shows none for that
+ * asset rather than a blank square that reads as a broken renderer.
+ *
+ * @param {GraphicsEngine3} graphics
+ * @param {SceneBundle} bundle
+ * @param {number} width texels
+ * @param {number} height texels
+ * @param {number} [margin] fraction of the frame's height left clear around the model
+ * @returns {Promise<Sampler2D|null>}
+ */
+export async function make_model_thumbnail(graphics, bundle, width, height, margin = 0) {
+    assert.defined(graphics, 'graphics');
+    assert.defined(bundle, 'bundle');
+
+    // held locally rather than in module scratch: a caller may have several thumbnails in flight,
+    // and what each of them is framing must not be what the last one was
+    const bounds = new AABB3();
+
+    if (!shade_bundle_bounds(bounds, bundle)) {
+        return null;
+    }
+
+    const framing = model_preview_framing(new ModelPreviewFraming(), bounds, MODEL_PREVIEW_FOV, margin);
+
+    const { scene, camera, drawn } = make_model_preview_scene(bundle, framing, width / height);
+
+    if (drawn === 0) {
+        return null;
+    }
+
+    return graphics.render_to_sampler(scene, camera, width, height);
+}

package/src/engine/graphics3/preview/model_preview_framing.js

@@ -1,70 +1,70 @@
-import { assert } from "../../../core/assert.js";
-import {
-    camera_compute_distance_to_fit_length
-} from "../../graphics/camera/camera_compute_distance_to_fit_length.js";
-
-/**
- * Frame a model for a thumbnail: scale it into a unit box, centre it on the origin, and stand the
- * camera far enough back along the view axis to see the whole of it.
- *
- * **The scale is uniform and it is the tightest of the three axes**, so a model of any proportion
- * lands inside the same unit box and every icon in a library is drawn at the same apparent size —
- * which is the point of a thumbnail grid. A model's own units mean nothing here.
- *
- * **The distance is measured from the front face of the centred box**, not from wherever the
- * model's author left its origin. The three path this replaces measured from the un-centred box, so
- * a model whose geometry sat off to one side of its own origin was framed from the wrong depth.
- *
- * `margin` is how much of the frame is left empty around the model, as a fraction of the frame's
- * height on each side: `0` fills it edge to edge, `0.25` leaves a quarter of the frame's height
- * clear above and below. **It replaces the focus rectangle the three path took**, whose two halves
- * disagreed with each other — a smaller rectangle moved the camera *closer*, making the model
- * bigger, while its offset moved the model *away* from the part of the frame the rectangle named.
- * Every call site it ever had passed either the whole frame or a symmetric margin, which is the one
- * thing it did coherently and the only thing left here.
- *
- * **Which side the camera stands on is not answered here.** What comes back is a distance along the
- * view axis; whether that axis runs from `+Z` or `-Z` is the renderer's convention, and the scene
- * builder applies it.
- *
- * @param {ModelPreviewFraming} result
- * @param {AABB3} bounds the model's bounding box, in the model's own space
- * @param {number} fov vertical field of view, radians
- * @param {number} [margin] fraction of the frame's height left clear on each side
- * @returns {ModelPreviewFraming} `result`
- */
-export function model_preview_framing(result, bounds, fov, margin = 0) {
-    assert.defined(result, 'result');
-    assert.defined(bounds, 'bounds');
-    assert.isNumber(margin, 'margin');
-    assert.greaterThanOrEqual(margin, 0, 'margin');
-
-    const size_x = bounds.x1 - bounds.x0;
-    const size_y = bounds.y1 - bounds.y0;
-    const size_z = bounds.z1 - bounds.z0;
-
-    assert.greaterThan(size_x, 0, 'bounds width');
-    assert.greaterThan(size_y, 0, 'bounds height');
-    assert.greaterThan(size_z, 0, 'bounds depth');
-
-    const scale = Math.min(1 / size_x, 1 / size_y, 1 / size_z);
-
-    result.scale = scale;
-
-    result.offset.set(
-        -(bounds.x0 + bounds.x1) * 0.5 * scale,
-        -(bounds.y0 + bounds.y1) * 0.5 * scale,
-        -(bounds.z0 + bounds.z1) * 0.5 * scale
-    );
-
-    // the near face of the centred box, which is what the camera has to clear before it starts
-    // measuring the distance that fits the frame
-    const half_depth = size_z * scale * 0.5;
-
-    // the model is one unit tall by construction, so the frame has to show that plus the margins
-    const frame_height = 1 + margin * 2;
-
-    result.camera_distance = half_depth + camera_compute_distance_to_fit_length(frame_height, fov);
-
-    return result;
-}
+import { assert } from "../../../core/assert.js";
+import {
+    camera_compute_distance_to_fit_length
+} from "../../graphics/camera/camera_compute_distance_to_fit_length.js";
+
+/**
+ * Frame a model for a thumbnail: scale it into a unit box, centre it on the origin, and stand the
+ * camera far enough back along the view axis to see the whole of it.
+ *
+ * **The scale is uniform and it is the tightest of the three axes**, so a model of any proportion
+ * lands inside the same unit box and every icon in a library is drawn at the same apparent size —
+ * which is the point of a thumbnail grid. A model's own units mean nothing here.
+ *
+ * **The distance is measured from the front face of the centred box**, not from wherever the
+ * model's author left its origin. The three path this replaces measured from the un-centred box, so
+ * a model whose geometry sat off to one side of its own origin was framed from the wrong depth.
+ *
+ * `margin` is how much of the frame is left empty around the model, as a fraction of the frame's
+ * height on each side: `0` fills it edge to edge, `0.25` leaves a quarter of the frame's height
+ * clear above and below. **It replaces the focus rectangle the three path took**, whose two halves
+ * disagreed with each other — a smaller rectangle moved the camera *closer*, making the model
+ * bigger, while its offset moved the model *away* from the part of the frame the rectangle named.
+ * Every call site it ever had passed either the whole frame or a symmetric margin, which is the one
+ * thing it did coherently and the only thing left here.
+ *
+ * **Which side the camera stands on is not answered here.** What comes back is a distance along the
+ * view axis; whether that axis runs from `+Z` or `-Z` is the renderer's convention, and the scene
+ * builder applies it.
+ *
+ * @param {ModelPreviewFraming} result
+ * @param {AABB3} bounds the model's bounding box, in the model's own space
+ * @param {number} fov vertical field of view, radians
+ * @param {number} [margin] fraction of the frame's height left clear on each side
+ * @returns {ModelPreviewFraming} `result`
+ */
+export function model_preview_framing(result, bounds, fov, margin = 0) {
+    assert.defined(result, 'result');
+    assert.defined(bounds, 'bounds');
+    assert.isNumber(margin, 'margin');
+    assert.greaterThanOrEqual(margin, 0, 'margin');
+
+    const size_x = bounds.x1 - bounds.x0;
+    const size_y = bounds.y1 - bounds.y0;
+    const size_z = bounds.z1 - bounds.z0;
+
+    assert.greaterThan(size_x, 0, 'bounds width');
+    assert.greaterThan(size_y, 0, 'bounds height');
+    assert.greaterThan(size_z, 0, 'bounds depth');
+
+    const scale = Math.min(1 / size_x, 1 / size_y, 1 / size_z);
+
+    result.scale = scale;
+
+    result.offset.set(
+        -(bounds.x0 + bounds.x1) * 0.5 * scale,
+        -(bounds.y0 + bounds.y1) * 0.5 * scale,
+        -(bounds.z0 + bounds.z1) * 0.5 * scale
+    );
+
+    // the near face of the centred box, which is what the camera has to clear before it starts
+    // measuring the distance that fits the frame
+    const half_depth = size_z * scale * 0.5;
+
+    // the model is one unit tall by construction, so the frame has to show that plus the margins
+    const frame_height = 1 + margin * 2;
+
+    result.camera_distance = half_depth + camera_compute_distance_to_fit_length(frame_height, fov);
+
+    return result;
+}

package/src/engine/graphics3/shade_bundle_bounds.js

@@ -1,55 +1,55 @@
-import { assert } from "../../core/assert.js";
-import { aabb3_array_combine } from "../../core/geom/3d/aabb/aabb3_array_combine.js";
-
-/**
- * The box a loaded model occupies, in the model's own space.
- *
- * **Matrices are refreshed here.** A `Mesh`'s `bounding_box` is its geometry's box projected
- * through its global transform, and a bundle handed straight off a loader has never had
- * {@link Node3D.updateMatrices} run on it — so asking for the bounds without refreshing them reads
- * whatever the loader left, which for a node under a transformed parent is the wrong box.
- *
- * A bundle with no geometry in it — a file that is all empties, or a scene that is only lights —
- * has no bounds, and that is what `false` says. `result` is untouched then.
- *
- * @param {AABB3} result
- * @param {SceneBundle} bundle
- * @returns {boolean} whether the bundle had any geometry to bound
- */
-export function shade_bundle_bounds(result, bundle) {
-    assert.defined(result, 'result');
-    assert.defined(bundle, 'bundle');
-
-    let found = false;
-
-    /**
-     * @param {Mesh} node
-     */
-    function combine(node) {
-        if (node.isMesh !== true) {
-            // a grouping node carries no geometry, so it has no bounds of its own
-            return;
-        }
-
-        const bounds = node.bounding_box;
-
-        if (found) {
-            aabb3_array_combine(result, 0, result, 0, bounds, 0);
-        } else {
-            result.setBounds(bounds[0], bounds[1], bounds[2], bounds[3], bounds[4], bounds[5]);
-
-            found = true;
-        }
-    }
-
-    const scenes = bundle.scenes;
-
-    for (let i = 0; i < scenes.length; i++) {
-        const root = scenes[i];
-
-        root.updateMatrices();
-        root.traverse(combine);
-    }
-
-    return found;
-}
+import { assert } from "../../core/assert.js";
+import { aabb3_array_combine } from "../../core/geom/3d/aabb/aabb3_array_combine.js";
+
+/**
+ * The box a loaded model occupies, in the model's own space.
+ *
+ * **Matrices are refreshed here.** A `Mesh`'s `bounding_box` is its geometry's box projected
+ * through its global transform, and a bundle handed straight off a loader has never had
+ * {@link Node3D.updateMatrices} run on it — so asking for the bounds without refreshing them reads
+ * whatever the loader left, which for a node under a transformed parent is the wrong box.
+ *
+ * A bundle with no geometry in it — a file that is all empties, or a scene that is only lights —
+ * has no bounds, and that is what `false` says. `result` is untouched then.
+ *
+ * @param {AABB3} result
+ * @param {SceneBundle} bundle
+ * @returns {boolean} whether the bundle had any geometry to bound
+ */
+export function shade_bundle_bounds(result, bundle) {
+    assert.defined(result, 'result');
+    assert.defined(bundle, 'bundle');
+
+    let found = false;
+
+    /**
+     * @param {Mesh} node
+     */
+    function combine(node) {
+        if (node.isMesh !== true) {
+            // a grouping node carries no geometry, so it has no bounds of its own
+            return;
+        }
+
+        const bounds = node.bounding_box;
+
+        if (found) {
+            aabb3_array_combine(result, 0, result, 0, bounds, 0);
+        } else {
+            result.setBounds(bounds[0], bounds[1], bounds[2], bounds[3], bounds[4], bounds[5]);
+
+            found = true;
+        }
+    }
+
+    const scenes = bundle.scenes;
+
+    for (let i = 0; i < scenes.length; i++) {
+        const root = scenes[i];
+
+        root.updateMatrices();
+        root.traverse(combine);
+    }
+
+    return found;
+}