abstract-3d 3.1.1 → 4.0.0-beta.0

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

@@ -0,0 +1,141 @@
+import { BatchedMesh, InstancedMesh, Matrix4, PerspectiveCamera, Raycaster, Vector2, Vector3, Vector4 } from "three";
+import { describe, expect, it } from "vitest";
+import type { Group, Scene } from "../../../abstract-3d.js";
+import { alignedDimension, box, culledLine, group, sphere, text, vec3, vec3Zero } from "../../../abstract-3d.js";
+import type { PaintState, StructureState } from "../appearance/appearance.js";
+import type { CompiledScene } from "../compile/compile.js";
+import { compileScene } from "../compile/compile.js";
+import type { GlyphBitmap } from "../text/text.js";
+import { createGlyphAtlas, SDF_BUFFER } from "../text/text.js";
+import type { BuiltScene } from "./build.js";
+import { animateScene, buildScene, cullScene, disposeScene, getPickables, getPickedItem, paintScene } from "./build.js";
+
+const red = { normal: "rgb(255, 0, 0)" };
+const blue = { normal: "rgb(0, 0, 255)", opacity: 0.5 };
+const rasterize = (): GlyphBitmap => {
+  const [width, height] = [20 + 2 * SDF_BUFFER, 40 + 2 * SDF_BUFFER];
+  return {
+    data: new Uint8ClampedArray(width * height),
+    width,
+    height,
+    glyphWidth: 20,
+    glyphHeight: 40,
+    glyphLeft: 0,
+    glyphTop: 30,
+    glyphAdvance: 24,
+  };
+};
+const idle: StructureState = { relationsActive: false };
+const scene = (groups: ReadonlyArray<Group>, rest: Partial<Scene> = {}): Scene => ({ size_deprecated: vec3(1, 1, 1), groups, ...rest });
+const part = (id: string, x: number, material = red): Group => group([box(vec3(10, 10, 10), material)], vec3(x, 0, 0), vec3Zero, [], { id });
+const build = (s: Scene, structure = idle, activeRelations?: ReadonlyArray<string>): BuiltScene =>
+  buildScene(
+    compileScene(s, (g) => g.data?.id ?? ""),
+    { structure, activeRelations, geometries: new Map(), atlas: createGlyphAtlas(rasterize, 256) }
+  );
+const relation = (id: string): NonNullable<Scene["relations"]>[number] => ({ id, pos: vec3Zero, groups: [group([box(vec3(1, 1, 1), red)])] });
+const batches = (built: BuiltScene): ReadonlyArray<BatchedMesh> => built.root.children.filter((o): o is BatchedMesh => o instanceof BatchedMesh);
+
+/** The id of the group under the screen center for a camera at `x` looking down -z */
+function pickId(built: BuiltScene, x: number): string | undefined {
+  const camera = new PerspectiveCamera(45, 1, 1, 1000);
+  camera.position.set(x, 0, 100);
+  camera.updateMatrixWorld();
+  built.root.updateMatrixWorld();
+  const raycaster = new Raycaster();
+  raycaster.setFromCamera(new Vector2(0, 0), camera);
+  const hits = raycaster.intersectObjects(getPickables(built), false);
+  const item = hits.length > 0 ? getPickedItem(built, hits[0]) : undefined;
+  const { compiled }: { readonly compiled: CompiledScene } = built;
+  const target = item === undefined ? undefined : compiled.targets[compiled.items[item].target];
+  return target?.kind === "group" || target?.kind === "dimension" ? target.id : undefined;
+}
+
+describe("buildScene", () => {
+  it("draws solids of one material class in one batch, whatever their geometry", () => {
+    const built = build(scene([part("a", 0), part("b", 20), group([sphere(5, red)], vec3(40, 0, 0)), part("c", 60, blue)]));
+    expect(batches(built).map((b) => b.instanceCount)).toEqual([3, 1]);
+    expect(built.parts).toHaveLength(2);
+  });
+
+  it("picks the group under the pointer", () => {
+    const built = build(scene([part("a", 0), part("b", 20)]));
+    expect([pickId(built, 0), pickId(built, 20), pickId(built, 100)]).toEqual(["a", "b", undefined]);
+  });
+
+  it("picks text by its glyphs", () => {
+    const built = build(scene([group([text(vec3Zero, "AB", 10, red)], vec3Zero, vec3Zero, [], { id: "label" })]));
+    expect(built.root.children.some((o) => o instanceof InstancedMesh)).toBe(true);
+    expect(pickId(built, 0)).toBe("label");
+  });
+
+  it("repaints the hovered and selected targets", () => {
+    const built = build(scene([part("a", 0), part("b", 20)]));
+    const [batch] = batches(built);
+    const color = (instance: number): ReadonlyArray<number> =>
+      batch
+        .getColorAt(instance, new Vector4())
+        .toArray()
+        .map((v) => Math.round(v * 100) / 100);
+    const before = color(1);
+    const state: PaintState = { ...idle, dimensionsClickable: true, hoveredTarget: 1 };
+    paintScene(built, state);
+    expect(color(1)).not.toEqual(before);
+    expect(color(0)).toEqual([1, 0, 0, 1]);
+    paintScene(built, { ...state, hoveredTarget: undefined, selectedIds: { a: true } });
+    expect(color(1)).toEqual(before);
+    expect(color(0)).not.toEqual([1, 0, 0, 1]);
+  });
+
+  it("keeps dimensions in their own group, and doesn't pick hidden ones", () => {
+    // Its text is centered half a text height of 44 above the line, here at the origin
+    const dimension = alignedDimension(vec3(-500, 78, 0), vec3(500, 78, 0), vec3(0, -22, 0), "1000", ["front"], undefined, "dim");
+    const built = build(scene([], { dimensions_deprecated: { dimensions: [dimension], material: red } }));
+    expect(built.dimensions.children.length).toBeGreaterThan(0);
+    expect(pickId(built, 0)).toBe("dim");
+    built.dimensions.visible = false;
+    expect(pickId(built, 0)).toBeUndefined();
+  });
+
+  it("builds the active relations only", () => {
+    const s = scene([], { relations: [relation("r1"), relation("r2")] });
+    expect(build(s).parts).toHaveLength(0);
+    // A relation's box and its outline
+    expect(batches(build(s, { relationsActive: true }, ["r1"])).map((b) => b.instanceCount)).toEqual([1, 1]);
+  });
+
+  it("fades and moves disabled groups to a transparent batch", () => {
+    const built = build(scene([part("a", 0), part("b", 20)]), { relationsActive: true, activeComponents: { b: "Accept" } });
+    expect(batches(built).map((b) => [b.instanceCount, b.material.transparent])).toEqual([
+      [1, true],
+      [1, false],
+    ]);
+  });
+
+  it("animates the instances of animated groups", () => {
+    const spin = { transform: { rot: vec3(0, 0, Math.PI), trans: vec3Zero }, duration: 1000 };
+    const built = build(scene([group([box(vec3(1, 1, 1), red)], vec3(5, 0, 0), vec3Zero, [], {}, spin)]));
+    expect(built.animatedItems).toHaveLength(1);
+    animateScene(built, 0.5);
+    const position = new Vector3(1, 0, 0).applyMatrix4(batches(built)[0].getMatrixAt(0, new Matrix4()));
+    expect(position.toArray().map((v) => Math.round(v * 1000) / 1000 + 0)).toEqual([5, 1, 0]);
+  });
+
+  it("hides culled lines that face away from the camera", () => {
+    const built = build(scene([group([culledLine(vec3(0, 0, 0), vec3(10, 0, 0), vec3(0, 0, 1), 1, red)])]));
+    const line = built.parts.find((p) => p.kind === "line")!;
+    const endX = (): number => (line.object.geometry.getAttribute("instanceEnd") as unknown as { readonly getX: (i: number) => number }).getX(0);
+    cullScene(built, new Vector3(0, 0, -100));
+    expect(endX()).toBe(0);
+    cullScene(built, new Vector3(0, 0, 100));
+    expect(endX()).toBe(10);
+  });
+
+  it("disposes its batches and materials", () => {
+    const built = build(scene([part("a", 0)]));
+    const disposed: Array<string> = [];
+    batches(built)[0].material.addEventListener("dispose", () => disposed.push("material"));
+    disposeScene(built);
+    expect(disposed).toEqual(["material"]);
+  });
+});

package/src/renderers/three/build/build.ts

@@ -0,0 +1,270 @@
+import {
+  type BufferGeometry,
+  Group,
+  type Intersection,
+  Matrix4,
+  type Mesh,
+  type MeshBasicMaterial,
+  type Object3D,
+  type Texture,
+  type Vector3,
+  Vector4,
+} from "three";
+import type { PaintState, StructureState, TargetState } from "../appearance/appearance.js";
+import { getHighlight, getItemColor, getMaterialClass, getTargetStates } from "../appearance/appearance.js";
+import type { CompiledScene } from "../compile/compile.js";
+import { getItemMatrix, transform } from "../compile/compile.js";
+import { createSolidGeometry, getSolidShape, keepGeometries } from "../geometry/geometry.js";
+import type { GlyphAtlas } from "../text/text.js";
+import type { TextureCache } from "./materials.js";
+import { createClassMaterial, createImageMaterial, getImageUrl, loadTexture } from "./materials.js";
+import type { Part } from "./parts.js";
+import {
+  createImagePart,
+  createLinePart,
+  createSolidPart,
+  createTextPart,
+  cullLines,
+  disposePart,
+  flushPart,
+  getHitSlot,
+  paintSlot,
+  placeSlot,
+} from "./parts.js";
+
+/** Compiled items → parts, with a slot per item, and painting, animating, culling, picking and disposing them */
+
+export type BuildOptions = {
+  readonly structure: StructureState;
+  readonly activeRelations?: ReadonlyArray<string>;
+  /** Geometries by shape key, shared between builds */
+  readonly geometries: Map<string, BufferGeometry>;
+  readonly atlas: GlyphAtlas;
+  /** Without it images aren't shown */
+  readonly textures?: TextureCache;
+  readonly materialStateImages?: Record<string, string>;
+  readonly useAlphaTest?: boolean;
+  readonly onTextureLoaded?: () => void;
+};
+
+export type BuiltScene = {
+  readonly compiled: CompiledScene;
+  readonly targetStates: ReadonlyArray<TargetState>;
+  readonly root: Group;
+  /** Holds the dimensions, shown or hidden by its `visible` */
+  readonly dimensions: Group;
+  readonly parts: ReadonlyArray<Part>;
+  /** Each compiled item's part and slot, -1 for items not built */
+  readonly partOfItem: Int32Array;
+  readonly slotOfItem: Int32Array;
+  readonly itemsOfPart: ReadonlyArray<ReadonlyArray<number>>;
+  readonly itemsOfTarget: ReadonlyArray<ReadonlyArray<number>>;
+  readonly animatedItems: ReadonlyArray<number>;
+  /** Each target's painted highlight, -1 before the first paint */
+  readonly highlights: Int8Array;
+  readonly partOfObject: ReadonlyMap<Object3D, number>;
+  readonly state: { disposed: boolean };
+};
+
+export function buildScene(compiled: CompiledScene, options: BuildOptions): BuiltScene {
+  const targetStates = getTargetStates(compiled.targets, options.structure);
+  const active = new Set(options.activeRelations);
+  const groups = new Map<string, Array<number>>();
+  const itemsOfTarget = compiled.targets.map((): Array<number> => []);
+  const animatedItems: Array<number> = [];
+  compiled.items.forEach((item, i) => {
+    const target = compiled.targets[item.target]!;
+    if (target.kind === "relation" && !active.has(target.relation.id)) {
+      return;
+    }
+    // Items of the same part key are drawn by one part
+    const g = item.mesh.geometry;
+    const container = item.style === "dimension" ? "dimension" : "scene";
+    const key =
+      item.role === "solid"
+        ? `${container} solid ${JSON.stringify(getMaterialClass(item, targetStates[item.target]!))}`
+        : item.role === "line"
+          ? `${container} line ${g.type === "Line" || g.type === "CulledLine" ? g.thickness : 0}`
+          : item.role === "text"
+            ? `${container} text`
+            : `image ${i}`;
+    const group = groups.get(key);
+    if (group) {
+      group.push(i);
+    } else {
+      groups.set(key, [i]);
+    }
+    itemsOfTarget[item.target]!.push(i);
+    if (item.animation !== undefined) {
+      animatedItems.push(i);
+    }
+  });
+
+  const [root, dimensions] = [new Group(), new Group()];
+  root.add(dimensions);
+  const usedShapes = new Set<string>();
+  const itemsOfPart = [...groups.values()];
+  const partOfItem = new Int32Array(compiled.items.length).fill(-1);
+  const slotOfItem = new Int32Array(compiled.items.length).fill(-1);
+  const state = { disposed: false };
+  const parts = itemsOfPart.map((indices, p) => {
+    indices.forEach((i, slot) => {
+      partOfItem[i] = p;
+      slotOfItem[i] = slot;
+    });
+    const part = createPart(compiled, indices, targetStates, options, usedShapes, state);
+    (compiled.items[indices[0]!]!.style === "dimension" ? dimensions : root).add(part.object);
+    return part;
+  });
+  keepGeometries(options.geometries, usedShapes);
+
+  const built: BuiltScene = {
+    compiled,
+    targetStates,
+    root,
+    dimensions,
+    parts,
+    partOfItem,
+    slotOfItem,
+    itemsOfPart,
+    itemsOfTarget,
+    animatedItems,
+    highlights: new Int8Array(compiled.targets.length).fill(-1),
+    partOfObject: new Map(parts.map((part, p) => [part.object, p])),
+    state,
+  };
+  compiled.items.forEach((item, i) => {
+    if (partOfItem[i]! >= 0) {
+      placeSlot(parts[partOfItem[i]!]!, slotOfItem[i]!, getItemMatrix(compiled, item, 0, world));
+    }
+  });
+  paintScene(built, { ...options.structure, dimensionsClickable: false });
+  parts.forEach((part) => flushPart(part, true));
+  return built;
+}
+
+/** Repaints the targets whose highlight changed */
+export function paintScene(built: BuiltScene, state: PaintState): void {
+  const { compiled, parts, highlights } = built;
+  const touched = new Set<Part>();
+  compiled.targets.forEach((target, t) => {
+    const highlight = getHighlight(target, t, state);
+    if (highlight !== highlights[t]) {
+      highlights[t] = highlight;
+      built.itemsOfTarget[t]!.forEach((i) => {
+        const part = parts[built.partOfItem[i]!]!;
+        paintSlot(part, built.slotOfItem[i]!, getItemColor(compiled.items[i]!, built.targetStates[t]!, highlight, color));
+        touched.add(part);
+      });
+    }
+  });
+  touched.forEach((part) => flushPart(part, false));
+}
+
+/** Moves the animated items to `seconds` into their animations */
+export function animateScene(built: BuiltScene, seconds: number): void {
+  const touched = new Set<Part>();
+  built.animatedItems.forEach((i) => {
+    const part = built.parts[built.partOfItem[i]!]!;
+    placeSlot(part, built.slotOfItem[i]!, getItemMatrix(built.compiled, built.compiled.items[i]!, seconds, world));
+    touched.add(part);
+  });
+  touched.forEach((part) => flushPart(part, true));
+}
+
+export function cullScene(built: BuiltScene, cameraPosition: Vector3): void {
+  built.parts.forEach((part) => cullLines(part, cameraPosition));
+}
+
+/** The shown objects that can be picked; lines aren't picked */
+export function getPickables(built: BuiltScene): Array<Object3D> {
+  const pickables: Array<Object3D> = [];
+  built.parts.forEach((part) => {
+    if (part.kind !== "line" && part.object.visible && part.object.parent?.visible !== false) {
+      pickables.push(part.object);
+    }
+  });
+  return pickables;
+}
+
+/** The index of the compiled item hit */
+export function getPickedItem(built: BuiltScene, hit: Intersection): number | undefined {
+  const p = built.partOfObject.get(hit.object);
+  const slot = p === undefined ? undefined : getHitSlot(built.parts[p]!, hit);
+  return slot === undefined ? undefined : built.itemsOfPart[p!]![slot];
+}
+
+export function disposeScene(built: BuiltScene): void {
+  built.state.disposed = true;
+  built.parts.forEach(disposePart);
+  built.root.removeFromParent();
+}
+
+function createPart(
+  compiled: CompiledScene,
+  indices: ReadonlyArray<number>,
+  targetStates: ReadonlyArray<TargetState>,
+  options: BuildOptions,
+  usedShapes: Set<string>,
+  state: { readonly disposed: boolean }
+): Part {
+  const items = indices.map((i) => compiled.items[i]!);
+  const first = items[0]!;
+  switch (first.role) {
+    case "text":
+      return createTextPart(
+        items.flatMap(({ mesh: { geometry: g } }) =>
+          g.type === "Text" ? [{ text: g.text, fontSize: g.fontSize, local: transform(g.pos, g.rot) }] : []
+        ),
+        options.atlas
+      );
+    case "line":
+      return createLinePart(
+        items.flatMap(({ mesh: { geometry: g } }) => (g.type === "Line" || g.type === "CulledLine" ? [g] : [])),
+        first.mesh.geometry.type === "Line" || first.mesh.geometry.type === "CulledLine" ? first.mesh.geometry.thickness : 1
+      );
+    default: {
+      const entries = items.map((item) => {
+        const shape = getSolidShape(item.mesh.geometry)!;
+        const geometry = options.geometries.get(shape.key) ?? createSolidGeometry(item.mesh.geometry);
+        options.geometries.set(shape.key, geometry);
+        usedShapes.add(shape.key);
+        return { geometry, local: shape.local };
+      });
+      if (first.role === "solid") {
+        return createSolidPart(entries, createClassMaterial(getMaterialClass(first, targetStates[first.target]!)));
+      }
+      // Images are hidden until their texture loads
+      const part = createImagePart(
+        entries[0]!.geometry,
+        entries[0]!.local,
+        createImageMaterial(first.mesh.material.backfaceCulling, options.useAlphaTest ?? true)
+      );
+      const g = first.mesh.geometry;
+      if (g.type === "Image" && options.textures) {
+        const url = getImageUrl(g.image, targetStates[first.target]!.materialState, options.materialStateImages);
+        loadTexture(options.textures, url)
+          .then((texture) => showImage(part.object, texture, state, options.onTextureLoaded))
+          .catch(() => undefined);
+      }
+      return part;
+    }
+  }
+}
+
+function showImage(
+  mesh: Mesh<BufferGeometry, MeshBasicMaterial>,
+  texture: Texture | undefined,
+  state: { readonly disposed: boolean },
+  onLoaded: (() => void) | undefined
+): void {
+  if (texture && !state.disposed) {
+    mesh.material.map = texture;
+    mesh.material.needsUpdate = true;
+    mesh.visible = true;
+    onLoaded?.();
+  }
+}
+
+const world = new Matrix4();
+const color = new Vector4();

package/src/renderers/three/build/materials.ts

@@ -0,0 +1,85 @@
+import { createSVG } from "abstract-image";
+import {
+  BackSide,
+  CanvasTexture,
+  DoubleSide,
+  FrontSide,
+  LinearFilter,
+  LinearMipmapLinearFilter,
+  type Material,
+  MeshBasicMaterial,
+  MeshStandardMaterial,
+  SRGBColorSpace,
+  type Texture,
+  TextureLoader,
+} from "three";
+import type { Image } from "../../../abstract-3d.js";
+import type { MaterialClass, MaterialState } from "../appearance/appearance.js";
+import { ERROR_IMG_KEY } from "../appearance/appearance.js";
+
+/** White materials, colored per instance, for each material class; images' materials and textures */
+
+export function createClassMaterial(c: MaterialClass): Material {
+  const side = c.side === "front" ? FrontSide : c.side === "back" ? BackSide : DoubleSide;
+  const common = { side, transparent: c.transparent, depthWrite: !c.transparent };
+  return c.lit ? new MeshStandardMaterial({ ...common, metalness: c.metalness, roughness: c.roughness }) : new MeshBasicMaterial(common);
+}
+
+export function createImageMaterial(backfaceCulling: boolean | undefined, useAlphaTest: boolean): MeshBasicMaterial {
+  return new MeshBasicMaterial({ side: backfaceCulling ? FrontSide : DoubleSide, alphaTest: useAlphaTest ? 0.8 : 0, transparent: true });
+}
+
+export function getImageUrl(image: Image, materialState: MaterialState | undefined, materialStateImages: Record<string, string> | undefined): string {
+  const errorUrl = materialState === "Error" ? materialStateImages?.[ERROR_IMG_KEY] : undefined;
+  return errorUrl ?? (image.type === "AbstractImage" ? `data:image/svg+xml,${createSVG(image.image)}` : image.url);
+}
+
+/** Each url's texture, loaded once */
+export type TextureCache = Map<string, Promise<Texture | undefined>>;
+
+export function loadTexture(cache: TextureCache, url: string): Promise<Texture | undefined> {
+  const svg = url.startsWith("data:image/svg+xml") || url.endsWith(".svg") || url.includes(".svg?");
+  const loading = cache.get(url) ?? (svg ? loadSvg(url) : loader.loadAsync(url).catch(() => undefined)).then((t) => t && applyFilters(t));
+  cache.set(url, loading);
+  return loading;
+}
+
+export function disposeTextures(cache: TextureCache): void {
+  cache.forEach((loading) => {
+    loading.then((texture) => texture?.dispose()).catch(() => undefined);
+  });
+  cache.clear();
+}
+
+const loader = new TextureLoader();
+const svgSize = 512;
+
+/** SVGs are rasterized at up to 512 px, as their own size is often small; from the r3f renderer's react-image-material.tsx */
+function loadSvg(url: string): Promise<Texture | undefined> {
+  const image = new Image();
+  image.src = url;
+  return image.decode().then(
+    () => rasterize(image),
+    () => undefined
+  );
+}
+
+function rasterize(image: HTMLImageElement): Texture | undefined {
+  const scale = svgSize / Math.max(image.naturalWidth, image.naturalHeight);
+  const canvas = document.createElement("canvas");
+  Object.assign(canvas, { width: image.naturalWidth * scale, height: image.naturalHeight * scale });
+  canvas.getContext("2d")?.drawImage(image, 0, 0, canvas.width, canvas.height);
+  return new CanvasTexture(canvas);
+}
+
+function applyFilters(texture: Texture): Texture {
+  Object.assign(texture, {
+    colorSpace: SRGBColorSpace,
+    minFilter: LinearMipmapLinearFilter,
+    magFilter: LinearFilter,
+    generateMipmaps: true,
+    anisotropy: 4,
+  });
+  texture.needsUpdate = true;
+  return texture;
+}