abstract-3d 3.1.2 → 4.0.0-beta.10

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

@@ -0,0 +1,126 @@
+import { Matrix4, Vector3 } from "three";
+import { assert, 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 type { CompiledScene, Item } from "./compile.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 | undefined, x: number, y: number, z: number): ReadonlyArray<number> => {
+  assert(m);
+  return new Vector3(x, y, z)
+    .applyMatrix4(m)
+    .toArray()
+    .map((v) => Math.round(v * 1000) / 1000 + 0);
+};
+const getItem = (compiled: CompiledScene, index: number): Item => {
+  const item = compiled.items.at(index);
+  assert(item);
+  return item;
+};
+// Destructured, as the build's and lint's compiler options disagree on reading an index signature by dot or bracket
+const groupId = (g: Group): string => {
+  const { id = "" }: Record<string, string | undefined> = g.data ?? {};
+  return id;
+};
+
+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.at(0)?.matrix, 0, 0, 0)).toEqual([100, 0, 0]);
+    expect(apply(compiled.items.at(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.at(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.at(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.at(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" })]), groupId);
+    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.at(0)?.speed).toEqual(vec3(0, 0, Math.PI));
+    expect(compiled.items.at(0)?.animation).toBe(0);
+    const world = (seconds: number): ReadonlyArray<number> => apply(getItemMatrix(compiled, getItem(compiled, 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, getItem(compiled, 0), 0.5, new Matrix4()), 0, 0, 0)).toEqual([0, 1, 0]);
+    expect(apply(getItemMatrix(compiled, getItem(compiled, 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.at(0)?.target ?? -1]).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[getItem(compiled, 0).target]).toEqual({ kind: "relation", relation });
+    const outline = getItem(compiled, 1).mesh.geometry;
+    expect(outline.type === "Box" && outline.size).toEqual(vec3(10.125, 10.125, 10.125));
+    expect(apply(compiled.items.at(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.at(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));
+}