abstract-3d 3.1.2 → 4.0.0-beta.10

package/src/renderers/three/geometry/geometry.test.ts

@@ -0,0 +1,121 @@
+import { type BufferGeometry, Vector3 } from "three";
+import { describe, expect, it } from "vitest";
+import type { Mesh } from "../../../abstract-3d.js";
+import { box, circleCurve, cone, cylinder, plane, polygon, roundHole, shape, sphere, tube, vec2, vec3, vec3Zero } from "../../../abstract-3d.js";
+import { createSolidGeometry, getSolidShape, keepGeometries } from "./geometry.js";
+
+const m = { normal: "rgb(0,0,0)" };
+const local = (mesh: Mesh, x: number, y: number, z: number): ReadonlyArray<number> =>
+  new Vector3(x, y, z)
+    .applyMatrix4(getSolidShape(mesh.geometry)!.local)
+    .toArray()
+    .map((v) => Math.round(v * 1000) / 1000 + 0);
+const key = (mesh: Mesh): string => getSolidShape(mesh.geometry)!.key;
+const bounds = (mesh: Mesh): ReadonlyArray<number> => {
+  const geometry = createSolidGeometry(mesh.geometry);
+  geometry.computeBoundingBox();
+  return [...geometry.boundingBox!.min.toArray(), ...geometry.boundingBox!.max.toArray()].map((v) => Math.round(v * 1000) / 1000 + 0);
+};
+
+/** The radius and joined sides' bits, the same for every vertex */
+const bevel = (mesh: Mesh): ReadonlyArray<number> => {
+  const attribute = createSolidGeometry(mesh.geometry).getAttribute("bevel");
+  const pairs = new Set(Array.from({ length: attribute.count }, (_, i) => `${attribute.getX(i)} ${attribute.getY(i)}`));
+  return [...pairs].flatMap((pair) => pair.split(" ").map(Number));
+};
+
+describe("getSolidShape", () => {
+  it("shares unit geometries between primitives of any size, scaled by the local matrix", () => {
+    expect(key(box(vec3(1, 2, 3), m))).toBe(key(box(vec3(4, 5, 6), m)));
+    expect(local(box(vec3(2, 4, 6), m, vec3(10, 0, 0)), 0.5, 0.5, 0.5)).toEqual([11, 2, 3]);
+    expect(local(plane(vec3Zero, vec2(2, 4), m), 0.5, 0.5, 0)).toEqual([1, 2, 0]);
+    expect(local(sphere(3, m, vec3(1, 0, 0)), 1, 0, 0)).toEqual([4, 0, 0]);
+    expect(local(cone(vec3Zero, 2, 10, m), 1, 0.5, 0)).toEqual([2, 5, 0]);
+  });
+
+  it("scales cylinders by their largest radius, with a geometry per radius ratio", () => {
+    expect(key(cylinder(vec3Zero, 1, 2, m))).toBe(key(cylinder(vec3Zero, 5, 7, m)));
+    expect(key(cylinder(vec3Zero, 1, 2, m))).not.toBe(key(cylinder(vec3Zero, 1, 2, m, vec3Zero, false, [], 0, Math.PI * 2, 2)));
+    expect(local(cylinder(vec3Zero, 1, 10, m, vec3Zero, false, [], 0, Math.PI * 2, 4), 1, 0.5, 0)).toEqual([4, 5, 0]);
+  });
+
+  it("shares geometries between identical shapes", () => {
+    const triangle = polygon([vec3(0, 0, 0), vec3(1, 0, 0), vec3(1, 1, 0)], m);
+    expect(key(triangle)).toBe(key(polygon([vec3(0, 0, 0), vec3(1, 0, 0), vec3(1, 1, 0)], m)));
+  });
+
+  it("ignores zero holes", () => {
+    expect(key(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [roundHole(vec2(0, 0), 0)]))).toBe(key(box(vec3(2, 2, 2), m)));
+  });
+
+  it("extrudes primitives with holes into their own geometry, centered", () => {
+    const holed = box(vec3(10, 10, 2), m, vec3(1, 0, 0), vec3Zero, [roundHole(vec2(0, 0), 2)]);
+    expect(key(holed)).not.toBe(key(box(vec3(10, 10, 2), m)));
+    expect(local(holed, 0, 0, 0)).toEqual([1, 0, 0]);
+    expect(bounds(holed)).toEqual([-5, -5, -1, 5, 5, 1]);
+    expect(bounds(cylinder(vec3Zero, 2, 10, m, vec3Zero, false, [roundHole(vec2(0, 0), 1)]))).toEqual([-2, -5, -2, 2, 5, 2]);
+  });
+});
+
+describe("createSolidGeometry", () => {
+  it("closes partial cylinders with walls", () => {
+    const whole = createSolidGeometry(cylinder(vec3Zero, 1, 1, m).geometry);
+    const half = createSolidGeometry(cylinder(vec3Zero, 1, 1, m, vec3Zero, false, [], 0, Math.PI).geometry);
+    expect(half.getAttribute("position").count).toBeGreaterThan(whole.getAttribute("position").count / 2);
+  });
+
+  it("draws 4-point polygons as a quad and other polygons as a triangle list", () => {
+    expect(createSolidGeometry(polygon([vec3(0, 0, 0), vec3(1, 0, 0), vec3(1, 1, 0), vec3(0, 1, 0)], m).geometry).index!.count).toBe(6);
+    expect(createSolidGeometry(polygon([vec3(0, 0, 0), vec3(1, 0, 0), vec3(1, 1, 0)], m).geometry).index!.count).toBe(3);
+  });
+
+  it("gives every geometry an index, normals and uvs, so they can share a batch", () => {
+    const meshes = [
+      box(vec3(1, 1, 1), m),
+      box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [roundHole(vec2(0, 0), 0.1)]),
+      polygon([vec3(0, 0, 0), vec3(1, 0, 0), vec3(1, 1, 0)], m),
+      cylinder(vec3Zero, 1, 1, m, vec3Zero, false, [], 0, Math.PI),
+      shape([vec2(0, 0), vec2(1, 0), vec2(0, 1)], vec3Zero, m, 1),
+      tube(circleCurve(10, 0, Math.PI), 1, m),
+    ];
+    meshes.forEach((mesh) => {
+      const geometry = createSolidGeometry(mesh.geometry);
+      expect(geometry.index!.count).toBeGreaterThan(0);
+      expect(Object.keys(geometry.attributes).sort()).toEqual(["bevel", "normal", "position", "uv"]);
+    });
+  });
+
+  it("gives boxes with a radius it as the radius their edges are shaded rounded by, with a geometry per radius", () => {
+    expect(bevel(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [], 4))).toEqual([4, 2 ** 12 - 1]);
+    expect(key(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [], 4))).toBe(key(box(vec3(9, 9, 9), m, vec3Zero, vec3Zero, [], 4)));
+    expect(key(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [], 4))).not.toBe(key(box(vec3(1, 1, 1), m)));
+  });
+
+  it("rounds all edges of boxes with a radius, or only their rounded edges, a bit each in the order of boxEdges, with a geometry per edges", () => {
+    expect(bevel(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [], 4, ["BottomBack", "FrontRight", "TopRight"]))).toEqual([4, 1 + 2 ** 7 + 2 ** 11]);
+    expect(bevel(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [], 4, []))).toEqual([4, 0]);
+    expect(key(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [], 4, ["TopFront"]))).not.toBe(key(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [], 4)));
+  });
+
+  it("keeps boxes without a radius, with holes, and other shapes sharp", () => {
+    expect(bevel(box(vec3(1, 1, 1), m))).toEqual([0, 0]);
+    expect(bevel(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [], undefined, ["TopFront"]))).toEqual([0, 0]);
+    expect(bevel(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [roundHole(vec2(0, 0), 0.1)], 4))).toEqual([0, 0]);
+    expect(bevel(sphere(1, m))).toEqual([0, 0]);
+  });
+});
+
+describe("keepGeometries", () => {
+  it("disposes the geometries a build no longer uses", () => {
+    const [kept, unused] = [createSolidGeometry(box(vec3(1, 1, 1), m).geometry), createSolidGeometry(sphere(1, m).geometry)];
+    const cache = new Map<string, BufferGeometry>([
+      ["Box", kept],
+      ["Sphere", unused],
+    ]);
+    const disposed: Array<string> = [];
+    unused.addEventListener("dispose", () => disposed.push("Sphere"));
+    keepGeometries(cache, new Set(["Box"]));
+    expect(disposed).toEqual(["Sphere"]);
+    expect([...cache.keys()]).toEqual(["Box"]);
+  });
+});

package/src/renderers/three/geometry/geometry.ts

@@ -0,0 +1,189 @@
+import {
+  BoxGeometry,
+  BufferGeometry,
+  CatmullRomCurve3,
+  ConeGeometry,
+  CylinderGeometry,
+  ExtrudeGeometry,
+  Float32BufferAttribute,
+  type Matrix4,
+  PlaneGeometry,
+  Shape,
+  SphereGeometry,
+  TubeGeometry,
+  Vector2,
+  Vector3,
+} from "three";
+import { mergeGeometries } from "three/addons/utils/BufferGeometryUtils.js";
+import type { Hole, Mesh } from "../../../abstract-3d.js";
+import { boxEdges, isZero, vec3, vec3Zero } from "../../../abstract-3d.js";
+import { addHoles, CircleCurve, CYLINDER_SEGMENTS, cylinderCutPositions, holeIsZero } from "../../shared/three-geometry.js";
+import { transform } from "../compile/compile.js";
+
+/**
+ * Solid geometries by key, so identical shapes share one geometry; primitives are unit geometries scaled by their local matrix. The shapes, holes and
+ * radius-ratio cylinders are the r3f renderer's react-mesh.tsx
+ */
+
+export type SolidShape = {
+  readonly key: string;
+  /** Position, rotation and, for unit geometries, scale, relative to the item's matrix */
+  readonly local: Matrix4;
+};
+
+/**
+ * The shape of a solid geometry, undefined for text and lines; images are unit planes. Shapes with their own geometry are keyed by JSON of what
+ * identifies them: cheap next to the geometry creation that sharing skips (measured: unique keys built systemair3 2–4 times slower)
+ */
+export function getSolidShape(g: Mesh["geometry"]): SolidShape | undefined {
+  switch (g.type) {
+    case "Box":
+    case "Plane": {
+      const size = g.type === "Box" ? g.size : vec3(g.size.x, g.size.y, 1);
+      return g.holes?.some((h) => !holeIsZero(h))
+        ? { key: JSON.stringify([g.type, g.size, g.holes]), local: transform(g.pos, g.rot) }
+        : {
+            key: g.type === "Box" && g.radius ? `Box ${g.radius} ${g.roundedEdges?.join() ?? ""}` : g.type,
+            local: transform(g.pos, g.rot, undefined, size),
+          };
+    }
+    case "Image":
+      return { key: "Plane", local: transform(g.pos, g.rot, undefined, vec3(g.size.x, g.size.y, 1)) };
+    case "Sphere":
+      return { key: g.type, local: transform(g.pos, vec3Zero, undefined, vec3(g.radius, g.radius, g.radius)) };
+    case "Cone":
+      return { key: g.type, local: transform(g.pos, g.rot, undefined, vec3(g.radius, g.length, g.radius)) };
+    case "Cylinder": {
+      const { radius, radiusEnd = radius, open = false, angleStart = 0, angleLength = Math.PI * 2 } = g;
+      if (radiusEnd === radius && isZero(Math.PI * 2 - angleLength) && g.holes?.some((h) => !holeIsZero(h))) {
+        return { key: JSON.stringify([g.type, radius, g.length, g.holes]), local: transform(g.pos, g.rot) };
+      }
+      // Unit geometry scaled by the largest radius, so only the radius ratio needs its own geometry
+      const max = Math.max(radius, radiusEnd) || 1;
+      return {
+        key: `${g.type} ${radiusEnd / max} ${radius / max} ${open} ${angleStart} ${angleLength}`,
+        local: transform(g.pos, g.rot, undefined, vec3(max, g.length, max)),
+      };
+    }
+    case "Shape":
+      return { key: JSON.stringify([g.type, g.points, g.thickness, g.holes]), local: transform(g.pos, g.rot) };
+    case "Polygon":
+      return { key: JSON.stringify([g.type, g.points]), local: transform(g.pos, g.rot) };
+    case "Tube":
+      return { key: JSON.stringify([g.type, g.curve, g.radius]), local: transform(g.pos, g.rot) };
+    default:
+      return undefined;
+  }
+}
+
+/** The geometry of a solid shape, indexed, with exactly position, normal and uv attributes and no groups, as a BatchedMesh needs */
+export function createSolidGeometry(g: Mesh["geometry"]): BufferGeometry {
+  const geometry = createGeometry(g);
+  const count = geometry.getAttribute("position").count;
+  if (!geometry.index) {
+    geometry.setIndex(Array.from({ length: count }, (_, i) => i));
+  }
+  if (!geometry.hasAttribute("normal")) {
+    geometry.computeVertexNormals();
+  }
+  if (!geometry.hasAttribute("uv")) {
+    geometry.setAttribute("uv", new Float32BufferAttribute(new Float32Array(count * 2), 2));
+  }
+  // The radius a unit box's edges are shaded as rounded by, 0 for sharp, and a bit per rounded edge, in the order of `boxEdges`; every geometry has
+  // it, as a batch's geometries share their attributes
+  const bevel =
+    geometry instanceof BoxGeometry && g.type === "Box" && g.radius
+      ? [g.radius, boxEdges.reduce((edges, edge, i) => ((g.roundedEdges?.includes(edge) ?? true) ? edges + 2 ** i : edges), 0)]
+      : [0, 0];
+  geometry.setAttribute("bevel", new Float32BufferAttribute(Array.from({ length: count }, () => bevel).flat(), 2));
+  Object.keys(geometry.attributes).forEach((name) => {
+    if (name !== "position" && name !== "normal" && name !== "uv" && name !== "bevel") {
+      geometry.deleteAttribute(name);
+    }
+  });
+  geometry.clearGroups();
+  return geometry;
+}
+
+function createGeometry(g: Mesh["geometry"]): BufferGeometry {
+  switch (g.type) {
+    case "Box":
+    case "Plane": {
+      if (!g.holes?.some((h) => !holeIsZero(h))) {
+        return g.type === "Box" ? new BoxGeometry() : new PlaneGeometry();
+      }
+      const [x, y] = [g.size.x / 2, g.size.y / 2];
+      return extrude(
+        new Shape([new Vector2(-x, -y), new Vector2(-x, y), new Vector2(x, y), new Vector2(x, -y)]),
+        g.holes,
+        g.type === "Box" ? g.size.z : 0
+      );
+    }
+    case "Image":
+      return new PlaneGeometry();
+    case "Sphere":
+      return new SphereGeometry(1, 12, 12);
+    case "Cone":
+      return new ConeGeometry(1, 1, 16, 1);
+    case "Cylinder": {
+      const { radius, radiusEnd = radius, open = false, angleStart = 0, angleLength = Math.PI * 2 } = g;
+      const whole = isZero(Math.PI * 2 - angleLength);
+      if (radiusEnd === radius && whole && g.holes?.some((h) => !holeIsZero(h))) {
+        return extrude(new Shape().moveTo(0, radius).absellipse(0, 0, radius, radius, 0, Math.PI * 2, true), g.holes, g.length).rotateX(Math.PI / 2);
+      }
+      const max = Math.max(radius, radiusEnd) || 1;
+      const [top, bottom] = [radiusEnd / max, radius / max];
+      const mantle = new CylinderGeometry(top, bottom, 1, CYLINDER_SEGMENTS, 1, open && whole, angleStart, angleLength);
+      if (whole) {
+        return mantle;
+      }
+      // The walls closing the cut, merged with the mantle, both unindexed
+      const positions = cylinderCutPositions(top, bottom, 1, angleStart, angleLength);
+      const walls = new BufferGeometry().setAttribute("position", new Float32BufferAttribute(positions, 3));
+      walls.setAttribute("uv", new Float32BufferAttribute(new Float32Array((positions.length / 3) * 2), 2));
+      walls.computeVertexNormals();
+      return mergeGeometries([mantle.toNonIndexed(), walls]);
+    }
+    case "Shape":
+      return extrude(new Shape(g.points.map((p) => new Vector2(p.x, p.y))), g.holes, g.thickness);
+    case "Polygon": {
+      // A quad for 4 points, else a list of triangles, as the points are given
+      const geometry = new BufferGeometry().setAttribute(
+        "position",
+        new Float32BufferAttribute(
+          g.points.flatMap((p) => [p.x, p.y, p.z]),
+          3
+        )
+      );
+      geometry.setIndex(g.points.length === 4 ? [0, 1, 2, 2, 3, 0] : Array.from({ length: Math.floor(g.points.length / 3) * 3 }, (_, i) => i));
+      geometry.computeVertexNormals();
+      return geometry;
+    }
+    case "Tube":
+      return new TubeGeometry(
+        g.curve.type === "SplineCurve" ? new CatmullRomCurve3(g.curve.points.map((p) => new Vector3(p.x, p.y, p.z))) : new CircleCurve(g.curve),
+        9,
+        g.radius,
+        9,
+        false
+      );
+    default:
+      return new BufferGeometry();
+  }
+}
+
+/** Extruded along z and centered on it */
+function extrude(shape: Shape, holes: ReadonlyArray<Hole> | undefined, depth: number): BufferGeometry {
+  addHoles(holes, shape);
+  return new ExtrudeGeometry(shape, { depth, bevelEnabled: false }).translate(0, 0, -depth / 2);
+}
+
+/** Disposes the cached geometries whose keys aren't in `keys` */
+export function keepGeometries(cache: Map<string, BufferGeometry>, keys: ReadonlySet<string>): void {
+  cache.forEach((geometry, key) => {
+    if (!keys.has(key)) {
+      geometry.dispose();
+      cache.delete(key);
+    }
+  });
+}

package/src/renderers/three/index.ts

@@ -0,0 +1,15 @@
+export { createViewer, updateViewer, disposeViewer, invalidate } from "./viewer/viewer.js";
+export type { Viewer } from "./viewer/viewer.js";
+export type { ViewerOptions, Popover, SceneEvent } from "./viewer/options.js";
+export type { MountedOverlay, MountOverlays } from "./viewer/overlays.js";
+export { compileScene } from "./compile/compile.js";
+export type { CompiledScene } from "./compile/compile.js";
+export { buildScene, disposeScene } from "./build/build.js";
+export type { BuildOptions, BuiltScene } from "./build/build.js";
+export { createGlyphAtlas } from "./text/text.js";
+export { ERROR_IMG_KEY } from "./appearance/appearance.js";
+export type { MaterialState } from "./appearance/appearance.js";
+export type { CameraOptions, BufferZones } from "./camera/camera.js";
+export type { ControlsOptions } from "./camera/controls.js";
+export type { ControlsHelper, ViewcubeOptions, AxesOptions, GizmoAlignment } from "./camera/gizmo.js";
+export type { Quality, Tier } from "./quality/quality.js";

package/src/renderers/three/quality/quality.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import type { Quality, TierGovernor } from "./quality.js";
+import { getPixelRatio, recordFrame } from "./quality.js";
+
+const governor = (quality: Quality): TierGovernor => ({ quality, tier: quality === "auto" ? "high" : quality, sum: 0, count: 0 });
+const record = (g: TierGovernor, intervals: ReadonlyArray<number>): ReadonlyArray<boolean> => intervals.map((ms) => recordFrame(g, ms));
+
+describe("recordFrame", () => {
+  it("keeps a fixed quality", () => {
+    const g = governor("high");
+    record(g, Array<number>(100).fill(100));
+    expect(g.tier).toBe("high");
+  });
+
+  it("drops auto to low for good when moving frames are slow", () => {
+    const g = governor("auto");
+    expect(record(g, Array<number>(30).fill(40)).filter(Boolean)).toHaveLength(1);
+    record(g, Array<number>(100).fill(5));
+    expect(g.tier).toBe("low");
+  });
+
+  it("keeps auto at high at 60 frames per second, ignoring the pauses between moves", () => {
+    const g = governor("auto");
+    record(
+      g,
+      Array.from({ length: 100 }, (_, i) => (i % 10 === 0 ? 2000 : 16.7))
+    );
+    expect(g.tier).toBe("high");
+  });
+});
+
+describe("getPixelRatio", () => {
+  it("caps the screen's pixel ratio by the tier, and high is the screen's own, as the r3f renderer's", () => {
+    expect([getPixelRatio("low", 3), getPixelRatio("medium", 3), getPixelRatio("high", 3)]).toEqual([1, 1.5, 3]);
+    expect(getPixelRatio("high", 1)).toBe(1);
+  });
+});

package/src/renderers/three/quality/quality.ts

@@ -0,0 +1,36 @@
+/**
+ * Quality tiers by resolution, the cheapest lever on a weak GPU: low renders a pixel per CSS pixel, medium up to 1.5, and high, the default, the
+ * screen's own pixel ratio as the r3f renderer. `auto` starts high and drops to low for good once moving frames are slow, as model viewers lower
+ * their resolution under load
+ */
+
+export type Tier = "low" | "medium" | "high";
+export type Quality = Tier | "auto";
+
+/** `auto` starts at high, and drops to low for good once moving frames average slower than 40 per second */
+export type TierGovernor = { readonly quality: Quality; tier: Tier; sum: number; count: number };
+
+const pixelRatioCaps: Record<Tier, number> = { low: 1, medium: 1.5, high: Infinity };
+const windowSize = 30;
+const slowFrameMs = 25;
+/** Longer intervals are pauses between moves, not slow frames */
+const pauseMs = 250;
+
+/** Records the time between two frames while the camera moves; true when that dropped the tier */
+export function recordFrame(governor: TierGovernor, intervalMs: number): boolean {
+  if (governor.quality !== "auto" || governor.tier === "low" || intervalMs > pauseMs) {
+    return false;
+  }
+  governor.sum += intervalMs;
+  governor.count += 1;
+  if (governor.count < windowSize) {
+    return false;
+  }
+  const slow = governor.sum / governor.count > slowFrameMs;
+  Object.assign(governor, { sum: 0, count: 0 }, slow ? { tier: "low" } : {});
+  return slow;
+}
+
+export function getPixelRatio(tier: Tier, devicePixelRatio: number): number {
+  return Math.min(devicePixelRatio, pixelRatioCaps[tier]);
+}

package/src/renderers/three/shadow/key-light.ts

@@ -0,0 +1,43 @@
+import { DirectionalLight, Group, Sphere, Vector3 } from "three";
+import type { BuiltScene } from "../build/build.js";
+import { getShadowCasters } from "./shadow.js";
+
+/**
+ * A key light from the upper left front, on top of the studio's soft light, that casts the solids' shadows on themselves, e.g. under a roof or behind
+ * a profile. Its shadow map is rendered once per build, as the scene doesn't move, so a frame only samples it; the casters are the ground shadow's
+ */
+
+const direction = new Vector3(-1, 2, 1.2).normalize();
+const intensity = 1.6;
+const mapSize = 2048;
+/** Of the key light kept out of its shadows, so faces under an overhang, e.g. a recessed base frame, aren't black */
+const shadowIntensity = 0.6;
+
+/** The light and its target, to add to the scene, with or without shadows; undefined for a scene without solids */
+export function createKeyLight(built: BuiltScene, shadows: boolean): Group | undefined {
+  const { bounds } = getShadowCasters(built);
+  if (bounds.isEmpty()) {
+    return undefined;
+  }
+  const { center, radius } = bounds.getBoundingSphere(new Sphere());
+  const light = new DirectionalLight(0xffffff, intensity);
+  light.position.copy(center).addScaledVector(direction, radius * 2);
+  light.target.position.copy(center);
+  light.castShadow = shadows;
+  // The shadow camera just encloses the scene, so the map's texels are as small as they can be
+  Object.assign(light.shadow.camera, { left: -radius, right: radius, top: radius, bottom: -radius, near: radius, far: radius * 3 });
+  light.shadow.camera.updateProjectionMatrix();
+  light.shadow.mapSize.set(mapSize, mapSize);
+  // Offsets along the normal by three texels, against shadow acne on the lit faces
+  Object.assign(light.shadow, { bias: -0.0005, normalBias: (radius * 6) / mapSize, radius: 3, intensity: shadowIntensity });
+  return new Group().add(light, light.target);
+}
+
+export function disposeKeyLight(key: Group): void {
+  key.removeFromParent();
+  key.children.forEach((child) => {
+    if (child instanceof DirectionalLight) {
+      child.shadow.dispose();
+    }
+  });
+}

package/src/renderers/three/shadow/shadow.ts

@@ -0,0 +1,170 @@
+import {
+  type BatchedMesh,
+  Box3,
+  CanvasTexture,
+  HalfFloatType,
+  type Scene,
+  Mesh,
+  MeshBasicMaterial,
+  MeshDepthMaterial,
+  OrthographicCamera,
+  PlaneGeometry,
+  ShaderMaterial,
+  UniformsUtils,
+  Vector3,
+  type WebGLRenderer,
+  WebGLRenderTarget,
+} from "three";
+import { FullScreenQuad } from "three/addons/postprocessing/Pass.js";
+import { HorizontalBlurShader } from "three/addons/shaders/HorizontalBlurShader.js";
+import { VerticalBlurShader } from "three/addons/shaders/VerticalBlurShader.js";
+import type { BuiltScene } from "../build/build.js";
+
+/**
+ * A soft shadow on the ground the scene stands on, rendered once per build: the solids seen from below by their depth, darker the closer to the
+ * ground, blurred into a texture on a plane, so a frame costs one textured quad. three.js's webgl_shadow_contact example, rendered once as drei's
+ * ContactShadows with `frames={1}`
+ */
+
+export type GroundShadow = {
+  readonly mesh: Mesh<PlaneGeometry, MeshBasicMaterial>;
+  readonly floor: Mesh<PlaneGeometry, MeshBasicMaterial>;
+  readonly target: WebGLRenderTarget;
+};
+
+/** The layer the solids are drawn on for the shadow, so text, lines, images and dimensions don't cast one */
+const shadowLayer = 1;
+/** Of the texture's longer side */
+const resolution = 512;
+/** The blur's reach, of the solids' height */
+const softness = 0.22;
+const opacity = 1;
+/** A pool of light on the floor the shadow lies in, so it shows on a dark background, which a shadow alone can't darken; on white it's invisible */
+const floorLight = 0.06;
+/** The pool's reach beyond the solids, of their height */
+const floorReach = 1;
+
+/** The batches of solids that cast shadows, with their bounds: opaque ones whose material doesn't turn it off, not text, lines, images or dimensions */
+export function getShadowCasters(built: BuiltScene): { readonly casters: ReadonlyArray<BatchedMesh>; readonly bounds: Box3 } {
+  const casters: Array<BatchedMesh> = [];
+  const bounds = new Box3();
+  built.parts.forEach((part) => {
+    if (part.kind === "solid" && part.object.castShadow && part.object.parent !== built.dimensions && part.object.boundingBox) {
+      casters.push(part.object);
+      bounds.union(part.object.boundingBox);
+    }
+  });
+  return { casters, bounds };
+}
+
+/** Undefined for a scene without solids; renders with `renderer`, and leaves its render target as it was */
+export function createGroundShadow(renderer: WebGLRenderer, scene: Scene, built: BuiltScene): GroundShadow | undefined {
+  const { casters, bounds } = getShadowCasters(built);
+  if (bounds.isEmpty()) {
+    return undefined;
+  }
+  casters.forEach((caster) => caster.layers.enable(shadowLayer));
+  const size = bounds.getSize(new Vector3());
+  // The plane reaches past the solids by twice the blur's reach on every side
+  const reach = softness * size.y;
+  const [width, depth] = [size.x + reach * 4, size.z + reach * 4];
+  const center = new Vector3((bounds.min.x + bounds.max.x) / 2, bounds.min.y, (bounds.min.z + bounds.max.z) / 2);
+  const [texelsX, texelsZ] =
+    width > depth ? [resolution, Math.ceil((resolution * depth) / width)] : [Math.ceil((resolution * width) / depth), resolution];
+  // Half float, so the blur's soft falloff isn't rounded into steps
+  const halfFloat = { type: HalfFloatType };
+  const [target, blurred] = [new WebGLRenderTarget(texelsX, texelsZ, halfFloat), new WebGLRenderTarget(texelsX, texelsZ, halfFloat)];
+
+  // Looks up from the ground, seeing as far as the solids are high
+  const camera = new OrthographicCamera(-width / 2, width / 2, depth / 2, -depth / 2, 0, size.y);
+  camera.position.copy(center);
+  camera.rotation.x = Math.PI / 2;
+  camera.layers.set(shadowLayer);
+  camera.updateMatrixWorld();
+  // Depth tested, so at each point the surface closest to the ground darkens it, not the last one drawn
+  const darkness = new MeshDepthMaterial();
+  darkness.onBeforeCompile = (shader) => {
+    shader.fragmentShader = shader.fragmentShader.replace(
+      "gl_FragColor = vec4( vec3( 1.0 - fragCoordZ ), opacity );",
+      "gl_FragColor = vec4( vec3( 0.0 ), sqrt( 1.0 - fragCoordZ ) );"
+    );
+  };
+  const previous = renderer.getRenderTarget();
+  Object.assign(scene, { overrideMaterial: darkness });
+  renderer.setRenderTarget(target);
+  renderer.render(scene, camera);
+  Object.assign(scene, { overrideMaterial: null });
+
+  const horizontal = new ShaderMaterial({ ...HorizontalBlurShader, uniforms: UniformsUtils.clone(HorizontalBlurShader.uniforms) });
+  const vertical = new ShaderMaterial({ ...VerticalBlurShader, uniforms: UniformsUtils.clone(VerticalBlurShader.uniforms) });
+  const quad = new FullScreenQuad(horizontal);
+  // The blur shaders reach 4 steps; three passes of shrinking steps blend into one smooth falloff
+  const step = (reach * texelsX) / width / 4;
+  [step, step / 2, step / 4].forEach((amount) => {
+    Object.assign(horizontal.uniforms, { tDiffuse: { value: target.texture }, h: { value: amount / texelsX } });
+    quad.material = horizontal;
+    renderer.setRenderTarget(blurred);
+    quad.render(renderer);
+    Object.assign(vertical.uniforms, { tDiffuse: { value: blurred.texture }, v: { value: amount / texelsZ } });
+    quad.material = vertical;
+    renderer.setRenderTarget(target);
+    quad.render(renderer);
+  });
+  renderer.setRenderTarget(previous);
+  [blurred, darkness, horizontal, vertical, quad].forEach((d) => d.dispose());
+
+  // The plane faces down as the camera looked up, so its texture lines up, and is mirrored to face up
+  const mesh = new Mesh(
+    new PlaneGeometry(width, depth).rotateX(Math.PI / 2),
+    ditherAlpha(new MeshBasicMaterial({ map: target.texture, transparent: true, depthWrite: false, opacity }), 2)
+  );
+  mesh.position.copy(center);
+  mesh.scale.y = -1;
+  // The floor's pool of light first, then the shadow in it, both before other transparent objects
+  const floor = new Mesh(
+    new PlaneGeometry(size.x + size.y * floorReach * 2, size.z + size.y * floorReach * 2).rotateX(-Math.PI / 2),
+    ditherAlpha(new MeshBasicMaterial({ alphaMap: createPool(), transparent: true, depthWrite: false, opacity: floorLight }), 1)
+  );
+  floor.position.copy(center);
+  Object.assign(floor, { renderOrder: -2 });
+  Object.assign(mesh, { renderOrder: -1 });
+  scene.add(floor, mesh);
+  return { mesh, floor, target };
+}
+
+/** A radial falloff from the center to the edges, as a spotlight's pool on the floor */
+function createPool(): CanvasTexture {
+  const canvas = Object.assign(document.createElement("canvas"), { width: 128, height: 128 });
+  const ctx = canvas.getContext("2d")!;
+  const gradient = ctx.createRadialGradient(64, 64, 0, 64, 64, 64);
+  gradient.addColorStop(0, "#fff");
+  gradient.addColorStop(0.3, "#999");
+  gradient.addColorStop(0.7, "#222");
+  gradient.addColorStop(1, "#000");
+  Object.assign(ctx, { fillStyle: gradient }).fillRect(0, 0, 128, 128);
+  return new CanvasTexture(canvas);
+}
+
+export function disposeGroundShadow(shadow: GroundShadow): void {
+  [shadow.mesh, shadow.floor].forEach((mesh) => {
+    mesh.removeFromParent();
+    mesh.geometry.dispose();
+    mesh.material.alphaMap?.dispose();
+    mesh.material.dispose();
+  });
+  shadow.target.dispose();
+}
+
+/**
+ * Jitters the alpha by about `levels` of the screen's 256 per pixel, so a faint gradient blended over the background doesn't show the 8-bit steps of
+ * the blend; three's `dithering` jitters the color, which these blends' steps don't come from
+ */
+function ditherAlpha(material: MeshBasicMaterial, levels: number): MeshBasicMaterial {
+  material.onBeforeCompile = (shader) => {
+    shader.fragmentShader = shader.fragmentShader.replace(
+      "#include <dithering_fragment>",
+      `gl_FragColor.a = clamp( gl_FragColor.a + ( rand( gl_FragCoord.xy ) - 0.5 ) * ${(levels / 255).toFixed(5)}, 0.0, 1.0 );`
+    );
+  };
+  return material;
+}