abstract-3d 3.1.1 → 4.0.0-beta.0

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

@@ -0,0 +1,113 @@
+import { Matrix4, Vector3 } from "three";
+import { describe, expect, it } from "vitest";
+import type { Group, Scene } from "../../../abstract-3d.js";
+import { alignedDimension, box, group, line, sphere, text, vec3, vec3Zero } from "../../../abstract-3d.js";
+import { compileScene, getItemMatrix } from "./compile.js";
+
+const red = { normal: "rgb(255, 0, 0)" };
+const scene = (groups: ReadonlyArray<Group>, rest: Partial<Scene> = {}): Scene => ({ size_deprecated: vec3(1, 1, 1), groups, ...rest });
+const apply = (m: Matrix4, x: number, y: number, z: number): ReadonlyArray<number> =>
+  new Vector3(x, y, z)
+    .applyMatrix4(m)
+    .toArray()
+    .map((v) => Math.round(v * 1000) / 1000 + 0);
+
+describe("compileScene", () => {
+  it("flattens nested groups into items with world matrices", () => {
+    const inner = group([sphere(1, red)], vec3(0, 10, 0));
+    const compiled = compileScene(scene([group([box(vec3(1, 1, 1), red)], vec3(100, 0, 0), vec3Zero, [inner])]));
+    expect(compiled.items.map((i) => i.role)).toEqual(["solid", "solid"]);
+    expect(apply(compiled.items[0].matrix, 0, 0, 0)).toEqual([100, 0, 0]);
+    expect(apply(compiled.items[1].matrix, 0, 0, 0)).toEqual([100, 10, 0]);
+  });
+
+  it("applies group rotation before the group's position", () => {
+    const compiled = compileScene(scene([group([box(vec3(1, 1, 1), red)], vec3(5, 0, 0), vec3(0, 0, Math.PI / 2))]));
+    expect(apply(compiled.items[0].matrix, 1, 0, 0)).toEqual([5, 1, 0]);
+  });
+
+  it("rotates the scene by its deprecated rotation, then moves it by minus its deprecated center", () => {
+    const g = group([box(vec3(1, 1, 1), red)], vec3(10, 0, 0));
+    const centered = compileScene(scene([g], { center_deprecated: vec3(10, 0, 0) }));
+    expect(apply(centered.items[0].matrix, 0, 0, 0)).toEqual([0, 0, 0]);
+    const rotated = compileScene(scene([g], { center_deprecated: vec3(-10, 0, 0), rotation_deprecated: vec3(0, Math.PI, 0) }));
+    expect(apply(rotated.items[0].matrix, 1, 0, 0)).toEqual([-1, 0, 0]);
+  });
+
+  it("gives every item of a top-level group that group's target, and the data of the group it's in", () => {
+    const inner = group([sphere(1, red)], vec3Zero, vec3Zero, [], { part: "motor" });
+    const fan = group([box(vec3(1, 1, 1), red)], vec3Zero, vec3Zero, [inner], { id: "fan" });
+    const compiled = compileScene(scene([fan, group([box(vec3(1, 1, 1), red)], vec3Zero, vec3Zero, [], { id: "coil" })]), (g) => g.data?.id ?? "");
+    expect(compiled.targets).toEqual([
+      { kind: "group", id: "fan", root: 0, rootData: { id: "fan" } },
+      { kind: "group", id: "coil", root: 1, rootData: { id: "coil" } },
+    ]);
+    expect(compiled.items.map((i) => [i.target, i.data])).toEqual([
+      [0, { id: "fan" }],
+      [0, { part: "motor" }],
+      [1, { id: "coil" }],
+    ]);
+  });
+
+  it("gives groups an empty id without createGroupId", () => {
+    const compiled = compileScene(scene([group([box(vec3(1, 1, 1), red)])]));
+    expect(compiled.targets[0]).toMatchObject({ kind: "group", id: "" });
+  });
+
+  it("assigns roles by geometry type", () => {
+    const g = group([box(vec3(1, 1, 1), red), text(vec3Zero, "A", 10, red), line(vec3Zero, vec3(1, 0, 0), 1, red)]);
+    expect(compileScene(scene([g])).items.map((i) => i.role)).toEqual(["solid", "text", "line"]);
+  });
+
+  it("makes items of animated groups relative to an animation that rotates the group", () => {
+    const fan = group(
+      [box(vec3(1, 1, 1), red)],
+      vec3(0, 5, 0),
+      vec3Zero,
+      [],
+      {},
+      { transform: { rot: vec3(0, 0, Math.PI), trans: vec3Zero }, duration: 1000 }
+    );
+    const compiled = compileScene(scene([group([], vec3(10, 0, 0), vec3Zero, [fan])]));
+    expect(compiled.animations).toHaveLength(1);
+    expect(compiled.animations[0].speed).toEqual(vec3(0, 0, Math.PI));
+    expect(compiled.items[0].animation).toBe(0);
+    const world = (seconds: number): ReadonlyArray<number> => apply(getItemMatrix(compiled, compiled.items[0], seconds, new Matrix4()), 1, 0, 0);
+    expect(world(0)).toEqual([11, 5, 0]);
+    expect(world(0.5)).toEqual([10, 6, 0]);
+  });
+
+  it("chains nested animations", () => {
+    const spin = { transform: { rot: vec3(0, 0, Math.PI), trans: vec3Zero }, duration: 1000 };
+    const inner = group([box(vec3(1, 1, 1), red)], vec3(1, 0, 0), vec3Zero, [], {}, spin);
+    const compiled = compileScene(scene([group([], vec3Zero, vec3Zero, [inner], {}, spin)]));
+    expect(compiled.animations.map((a) => a.parent)).toEqual([undefined, 0]);
+    expect(apply(getItemMatrix(compiled, compiled.items[0], 0.5, new Matrix4()), 0, 0, 0)).toEqual([0, 1, 0]);
+    expect(apply(getItemMatrix(compiled, compiled.items[0], 0.5, new Matrix4()), 1, 0, 0)).toEqual([-1, 1, 0]);
+  });
+
+  it("converts aligned dimensions to dimension items with a target per dimension", () => {
+    const dimension = alignedDimension(vec3Zero, vec3(1000, 0, 0), vec3(0, -100, 0), "1000", ["front"], undefined, "fan");
+    const compiled = compileScene(scene([], { dimensions_deprecated: { dimensions: [dimension], material: red } }));
+    const items = compiled.items.filter((i) => i.style === "dimension");
+    expect(items.length).toBeGreaterThan(0);
+    expect(new Set(items.map((i) => i.role))).toEqual(new Set(["line", "text", "solid"]));
+    expect(compiled.targets[items[0].target]).toEqual({ kind: "dimension", id: "fan" });
+  });
+
+  it("adds relation shapes, with an outline around their boxes", () => {
+    const relation = { id: "r1", pos: vec3Zero, groups: [group([box(vec3(10, 10, 10), red), sphere(1, red)], vec3(5, 0, 0))] };
+    const compiled = compileScene(scene([], { relations: [relation] }));
+    expect(compiled.items.map((i) => i.style)).toEqual(["relation", "outline", "relation"]);
+    expect(compiled.targets[compiled.items[0].target]).toEqual({ kind: "relation", relation });
+    const outline = compiled.items[1].mesh.geometry;
+    expect(outline.type === "Box" && outline.size).toEqual(vec3(10.125, 10.125, 10.125));
+    expect(apply(compiled.items[0].matrix, 0, 0, 0)).toEqual([5, 0, 0]);
+  });
+
+  it("keeps the world matrix of each top-level group for its tooltips", () => {
+    const compiled = compileScene(scene([group([], vec3(3, 0, 0))], { center_deprecated: vec3(1, 0, 0) }));
+    expect(apply(compiled.roots[0], 0, 0, 0)).toEqual([2, 0, 0]);
+    expect(apply(compiled.matrix, 0, 0, 0)).toEqual([-1, 0, 0]);
+  });
+});

package/src/renderers/three/compile/compile.ts

@@ -0,0 +1,151 @@
+import { Euler, Matrix4, Quaternion, Vector3 } from "three";
+import type { Group, Mesh, Relation, Scene, Vec3 } from "../../../abstract-3d.js";
+import { dimensionConvertToTypeMesh, vec3, vec3Scale, vec3Zero } from "../../../abstract-3d.js";
+
+/**
+ * Scene → flat items with world matrices, with no GPU objects, so everything here is testable in Node; groups transform as the r3f renderer's
+ * react-group.tsx
+ */
+
+/** How the item's geometry is drawn */
+export type Role = "solid" | "text" | "line" | "image";
+/** What the item belongs to, which decides its material and whether it's shown */
+export type Style = "group" | "dimension" | "relation" | "outline";
+
+/** What a pointer event on an item is about, and what hover and selection apply to */
+export type Target =
+  | { readonly kind: "group"; readonly id: string; readonly root: number; readonly rootData: Record<string, string> | undefined }
+  | { readonly kind: "dimension"; readonly id: string | undefined }
+  | { readonly kind: "relation"; readonly relation: Relation };
+
+export type Item = {
+  readonly mesh: Mesh;
+  readonly role: Role;
+  readonly style: Style;
+  /** World matrix, or for an animated item its matrix relative to its animation's group */
+  readonly matrix: Matrix4;
+  readonly target: number;
+  /** The data of the group the mesh is in */
+  readonly data: Record<string, string> | undefined;
+  readonly animation: number | undefined;
+};
+
+export type Animation = {
+  readonly parent: number | undefined;
+  /** The matrix of the group's parent, in world space or relative to the parent animation's group */
+  readonly base: Matrix4;
+  readonly pos: Vec3;
+  readonly rot: Vec3;
+  /** Radians per second around x, y and z */
+  readonly speed: Vec3;
+};
+
+export type CompiledScene = {
+  readonly items: ReadonlyArray<Item>;
+  readonly targets: ReadonlyArray<Target>;
+  readonly animations: ReadonlyArray<Animation>;
+  /** World matrix of the scene's root, from its deprecated center and rotation */
+  readonly matrix: Matrix4;
+  /** World matrix of each top-level group */
+  readonly roots: ReadonlyArray<Matrix4>;
+};
+
+type Output = { readonly items: Array<Item>; readonly animations: Array<Animation> };
+type ItemBase = Pick<Item, "style" | "target" | "data" | "animation">;
+
+const outlineScale = 1.0125;
+
+/** Targets are the top-level groups, then the dimensions, then the relations */
+export function compileScene(scene: Scene, createGroupId?: (g: Group) => string): CompiledScene {
+  const out: Output = { items: [], animations: [] };
+  const center = scene.center_deprecated ?? vec3Zero;
+  const matrix = new Matrix4().makeTranslation(-center.x, -center.y, -center.z).multiply(transform(vec3Zero, scene.rotation_deprecated));
+  const dimensions = scene.dimensions_deprecated?.dimensions ?? [];
+  const relations = scene.relations ?? [];
+  const targets: ReadonlyArray<Target> = [
+    ...scene.groups.map((g, root): Target => ({ kind: "group", id: createGroupId?.(g) ?? "", root, rootData: g.data })),
+    ...dimensions.map((d): Target => ({ kind: "dimension", id: d.id })),
+    ...relations.map((relation): Target => ({ kind: "relation", relation })),
+  ];
+  scene.groups.forEach((g, i) => addGroup(out, g, matrix, undefined, "group", i));
+  dimensions.forEach((dimension, i) => {
+    const mesh = dimensionConvertToTypeMesh(dimension, scene.rotation_deprecated ?? vec3Zero, scene.dimensions_deprecated?.material);
+    const base = { style: "dimension", target: scene.groups.length + i, data: undefined, animation: undefined } as const;
+    addMeshes(out, mesh.meshes, matrix.clone().multiply(transform(mesh.pos, mesh.rot)), base);
+  });
+  relations.forEach((relation, i) =>
+    relation.groups?.forEach((g) => addGroup(out, g, matrix, undefined, "relation", scene.groups.length + dimensions.length + i))
+  );
+  return { ...out, targets, matrix, roots: scene.groups.map((g) => matrix.clone().multiply(transform(g.pos, g.rot))) };
+}
+
+function addGroup(out: Output, g: Group, parent: Matrix4, parentAnimation: number | undefined, style: "group" | "relation", target: number): void {
+  const animation = g.animation ? out.animations.push(createAnimation(g, parent, parentAnimation)) - 1 : parentAnimation;
+  // An animated group's items are relative to it, so its animation can move them
+  const matrix = g.animation ? new Matrix4() : parent.clone().multiply(transform(g.pos, g.rot));
+  addMeshes(out, g.meshes ?? [], matrix, { style, target, data: g.data, animation });
+  g.groups?.forEach((child) => addGroup(out, child, matrix, animation, style, target));
+}
+
+function addMeshes(out: Output, meshes: ReadonlyArray<Mesh>, matrix: Matrix4, base: ItemBase): void {
+  meshes.forEach((mesh) => {
+    out.items.push({ ...base, mesh, role: getRole(mesh), matrix });
+    if (base.style === "relation" && mesh.geometry.type === "Box") {
+      const outline = { ...mesh, geometry: { ...mesh.geometry, size: vec3Scale(mesh.geometry.size, outlineScale) } };
+      out.items.push({ ...base, style: "outline", mesh: outline, role: "solid", matrix });
+    }
+  });
+}
+
+/** The item's world matrix at `seconds` into its animations, written to `out` */
+export function getItemMatrix(compiled: CompiledScene, item: Item, seconds: number, out: Matrix4): Matrix4 {
+  return item.animation === undefined
+    ? out.copy(item.matrix)
+    : getAnimationMatrix(compiled.animations, item.animation, seconds, out).multiply(item.matrix);
+}
+
+function getAnimationMatrix(animations: ReadonlyArray<Animation>, index: number, seconds: number, out: Matrix4): Matrix4 {
+  const a = animations[index]!;
+  const rot = vec3(a.rot.x + a.speed.x * seconds, a.rot.y + a.speed.y * seconds, a.rot.z + a.speed.z * seconds);
+  out.copy(a.base).multiply(transform(a.pos, rot, scratch));
+  return a.parent === undefined ? out : out.premultiply(getAnimationMatrix(animations, a.parent, seconds, new Matrix4()));
+}
+
+/** The r3f renderer turned an animated group by its rotation per duration in milliseconds */
+function createAnimation(g: Group, parent: Matrix4, parentAnimation: number | undefined): Animation {
+  const { rot } = g.animation!.transform;
+  const perSecond = 1000 / g.animation!.duration;
+  return {
+    parent: parentAnimation,
+    base: parent.clone(),
+    pos: g.pos,
+    rot: g.rot ?? vec3Zero,
+    speed: vec3(rot.x * perSecond, rot.y * perSecond, rot.z * perSecond),
+  };
+}
+
+function getRole(mesh: Mesh): Role {
+  switch (mesh.geometry.type) {
+    case "Text":
+      return "text";
+    case "Line":
+    case "CulledLine":
+      return "line";
+    case "Image":
+      return "image";
+    default:
+      return "solid";
+  }
+}
+
+const scratch = new Matrix4();
+const euler = new Euler();
+const quaternion = new Quaternion();
+const position = new Vector3();
+const scale = new Vector3();
+
+/** Translation, then XYZ Euler rotation, then scale, as on a three.js Object3D */
+export function transform(pos: Vec3, rot: Vec3 | undefined, out = new Matrix4(), size?: Vec3): Matrix4 {
+  quaternion.setFromEuler(euler.set(rot?.x ?? 0, rot?.y ?? 0, rot?.z ?? 0));
+  return out.compose(position.set(pos.x, pos.y, pos.z), quaternion, scale.set(size?.x ?? 1, size?.y ?? 1, size?.z ?? 1));
+}

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

@@ -0,0 +1,95 @@
+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);
+};
+
+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(["normal", "position", "uv"]);
+    });
+  });
+});
+
+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,179 @@
+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 { 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, 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));
+  }
+  Object.keys(geometry.attributes).forEach((name) => {
+    if (name !== "position" && name !== "normal" && name !== "uv") {
+      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,30 @@
+import { describe, expect, it } from "vitest";
+import type { Quality, TierGovernor } from "./quality.js";
+import { recordFrame } from "./quality.js";
+
+const governor = (quality: Quality): TierGovernor => ({ quality, tier: quality === "auto" ? "medium" : 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 medium 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("medium");
+  });
+});