abstract-3d 3.1.2 → 4.0.0-beta.0

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

@@ -0,0 +1,95 @@
+import { N8AOPass } from "n8ao";
+import type { OrthographicCamera, PerspectiveCamera, Scene, WebGLRenderer } from "three";
+import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js";
+import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
+
+/**
+ * Quality tiers that spend the GPU where it shows: the camera is still most of the time, and a still frame can afford ambient occlusion that a moving
+ * one can't on a weak GPU. Low renders directly; medium adds ambient occlusion at rest, faded in; high has it while moving too. Effects only at rest
+ * is how progressive model viewers such as Sketchfab's stay fast; the AO is N8AO, configured as the r3f renderer's
+ */
+
+export type Tier = "low" | "medium" | "high";
+export type Quality = Tier | "auto";
+
+/** `auto` starts at medium, 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 };
+
+export type RenderPath = {
+  readonly tier: Tier;
+  /** With ambient occlusion, faded in by its intensity over the first frames at rest */
+  readonly composer: EffectComposer | undefined;
+  readonly ao: { readonly configuration: { intensity: number } } | undefined;
+  readonly fade: { frame: number };
+};
+
+const pixelRatioCaps: Record<Tier, number> = { low: 1, medium: 1.5, high: 2 };
+const windowSize = 30;
+const slowFrameMs = 25;
+/** Longer intervals are pauses between moves, not slow frames */
+const pauseMs = 250;
+const fadeFrames = 6;
+const intensity = 2;
+
+/** 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;
+}
+
+/** Also sets the renderer's pixel ratio, capped by the tier */
+export function createRenderPath(renderer: WebGLRenderer, scene: Scene, camera: PerspectiveCamera | OrthographicCamera, tier: Tier): RenderPath {
+  renderer.setPixelRatio(Math.min(window.devicePixelRatio, pixelRatioCaps[tier]));
+  if (tier === "low") {
+    return { tier, composer: undefined, ao: undefined, fade: { frame: 0 } };
+  }
+  const composer = new EffectComposer(renderer);
+  const ao = new N8AOPass(scene, camera);
+  Object.assign(ao.configuration, {
+    aoRadius: 40,
+    distanceFalloff: 0.2,
+    screenSpaceRadius: true,
+    halfRes: true,
+    denoiseSamples: 4,
+    gammaCorrection: false,
+  });
+  // Multisampled, as SMAA, which N8AO suggests, would lose the antialiased alpha at edges over the transparent background
+  ao.beautyRenderTarget.samples = 4;
+  composer.addPass(ao);
+  // Tone mapping and sRGB, which rendering to the screen otherwise does
+  composer.addPass(new OutputPass());
+  return { tier, composer, ao, fade: { frame: 0 } };
+}
+
+/** Renders a frame; true while the frame at rest needs more frames to fade its ambient occlusion in */
+export function renderPath(
+  path: RenderPath,
+  renderer: WebGLRenderer,
+  scene: Scene,
+  camera: PerspectiveCamera | OrthographicCamera,
+  moving: boolean
+): boolean {
+  if (!path.composer || !path.ao || (moving && path.tier === "medium")) {
+    path.fade.frame = 0;
+    renderer.render(scene, camera);
+    return false;
+  }
+  path.fade.frame = path.tier === "high" ? fadeFrames : Math.min(fadeFrames, path.fade.frame + 1);
+  path.ao.configuration.intensity = (intensity * path.fade.frame) / fadeFrames;
+  path.composer.render();
+  return path.fade.frame < fadeFrames;
+}
+
+export function disposeRenderPath(path: RenderPath): void {
+  path.composer?.passes.forEach((p) => p.dispose());
+  path.composer?.dispose();
+}

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

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import type { GlyphBitmap } from "./text.js";
+import { createGlyphAtlas, getGlyph, layoutText, RASTER_SIZE, SDF_BUFFER } from "./text.js";
+
+/** Glyphs of 20 px ink, 30 px of it above the baseline, a 24 px advance, filled with their char code */
+const rasterize = (char: string): GlyphBitmap => {
+  const [glyphWidth, glyphHeight] = char === " " ? [0, 0] : [20, 40];
+  const [width, height] = [glyphWidth + 2 * SDF_BUFFER, glyphHeight + 2 * SDF_BUFFER];
+  return {
+    data: new Uint8ClampedArray(width * height).fill(char.charCodeAt(0)),
+    width,
+    height,
+    glyphWidth,
+    glyphHeight,
+    glyphLeft: 2,
+    glyphTop: 30,
+    glyphAdvance: 24,
+  };
+};
+const em = (px: number): number => px / RASTER_SIZE;
+const round = (v: number): number => Math.round(v * 1e4) / 1e4;
+
+describe("getGlyph", () => {
+  it("packs each glyph once, left to right, and writes its bitmap", () => {
+    const atlas = createGlyphAtlas(rasterize, 64);
+    const a = getGlyph(atlas, "A");
+    expect(getGlyph(atlas, "A")).toBe(a);
+    const b = getGlyph(atlas, "B");
+    const data = atlas.texture.image.data as Uint8Array;
+    expect([data[0], data[28]]).toEqual([65, 66]);
+    expect(a.rect.map(round)).toEqual([0, round(48 / 64), round(28 / 64), round(-48 / 64)]);
+    expect(b.rect[0]).toBe(28 / 64);
+  });
+
+  it("starts a new row when a row is full", () => {
+    const atlas = createGlyphAtlas(rasterize, 128);
+    ["A", "B", "C", "D"].forEach((char) => getGlyph(atlas, char));
+    expect(getGlyph(atlas, "E").rect.slice(0, 2)).toEqual([0, 96 / 128]);
+  });
+
+  it("gives glyphs their bitmap's position and size in em, from the pen at the baseline", () => {
+    expect(getGlyph(createGlyphAtlas(rasterize, 64), "A")).toMatchObject({
+      left: em(2 - SDF_BUFFER),
+      top: em(30 + SDF_BUFFER),
+      width: em(28),
+      height: em(48),
+      advance: em(24),
+    });
+  });
+
+  it("leaves glyphs without ink out of the atlas", () => {
+    const atlas = createGlyphAtlas(rasterize, 64);
+    expect(getGlyph(atlas, " ").width).toBe(0);
+    expect(getGlyph(atlas, "A").rect[0]).toBe(0);
+  });
+});
+
+describe("layoutText", () => {
+  const atlas = createGlyphAtlas(rasterize, 256);
+
+  it("centers a line on the origin", () => {
+    const advance = 24 + 0.001 * 40;
+    const quads = layoutText(atlas, "AA", 40);
+    expect(quads.map((q) => round(q.x))).toEqual([round(-advance + 2 - SDF_BUFFER + 14), round(2 - SDF_BUFFER + 14)]);
+    expect(quads.map((q) => [round(q.width), round(q.height)])).toEqual([
+      [28, 48],
+      [28, 48],
+    ]);
+  });
+
+  it("stacks lines 1.5 font sizes apart, centered vertically as a block", () => {
+    // The block is 120 high; each baseline is half the 20 of leading and an ascent of 32 below its line's top, and the glyphs' centers 10 above it
+    expect(layoutText(atlas, "A\nA", 40).map((q) => round(q.y))).toEqual([28, -32]);
+  });
+
+  it("skips glyphs without ink but keeps their advance", () => {
+    expect(layoutText(atlas, "A A", 40)).toHaveLength(2);
+  });
+});

package/src/renderers/three/text/text.ts

@@ -0,0 +1,128 @@
+import TinySDF from "@mapbox/tiny-sdf";
+import { DataTexture, LinearFilter, RedFormat, UnsignedByteType } from "three";
+
+/**
+ * Text as signed distance field glyphs from the system font, packed into one atlas texture, so all text draws in one call. The glyph atlas is Mapbox
+ * GL JS's approach (its @mapbox/tiny-sdf rasterizes), and the distance field text Valve's (Green, "Improved Alpha-Tested Magnification for Vector
+ * Textures and Special Effects", SIGGRAPH 2007)
+ */
+
+export const RASTER_SIZE = 40;
+export const SDF_BUFFER = 4;
+/** The distance field's value at the glyph's edge, from tiny-sdf's default cutoff of 0.25 */
+export const SDF_EDGE = 0.75;
+const LINE_HEIGHT = 1.5;
+const LETTER_SPACING = 0.001;
+/** Of the font size, above the baseline, to center a line's glyphs in it */
+const ASCENT = 0.8;
+
+export type GlyphBitmap = ReturnType<TinySDF["draw"]>;
+export type Rasterize = (char: string) => GlyphBitmap;
+
+export type Glyph = {
+  /** The glyph's place in the atlas as a uv offset and scale, for a quad with uv (0, 0) at its bottom left */
+  readonly rect: readonly [number, number, number, number];
+  /** The bitmap's left and top edges and size, in em, from the pen at the baseline; no width for glyphs without ink */
+  readonly left: number;
+  readonly top: number;
+  readonly width: number;
+  readonly height: number;
+  readonly advance: number;
+};
+
+export type GlyphAtlas = {
+  readonly texture: DataTexture;
+  readonly size: number;
+  readonly glyphs: Map<string, Glyph>;
+  /** Where the next glyph goes: the current row's top and next x, and its height */
+  readonly shelf: { x: number; y: number; height: number };
+  readonly rasterize: Rasterize | undefined;
+  readonly sdf: { current?: TinySDF };
+};
+
+/** A quad of a laid out text, with its center and size in the text's units, centered on the origin */
+export type GlyphQuad = {
+  readonly glyph: Glyph;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+};
+
+/** Without `rasterize`, glyphs are rasterized with the OS's built-in Helvetica or Arial, on a canvas created at first use */
+export function createGlyphAtlas(rasterize?: Rasterize, size = 1024): GlyphAtlas {
+  const texture = new DataTexture(new Uint8Array(size * size), size, size, RedFormat, UnsignedByteType);
+  Object.assign(texture, { minFilter: LinearFilter, magFilter: LinearFilter, generateMipmaps: false });
+  return { texture, size, glyphs: new Map(), shelf: { x: 0, y: 0, height: 0 }, rasterize, sdf: {} };
+}
+
+export function getGlyph(atlas: GlyphAtlas, char: string): Glyph {
+  const cached = atlas.glyphs.get(char);
+  if (cached) {
+    return cached;
+  }
+  atlas.sdf.current ??= atlas.rasterize
+    ? undefined
+    : new TinySDF({ fontSize: RASTER_SIZE, buffer: SDF_BUFFER, radius: 10, fontFamily: "Helvetica, Arial, sans-serif" });
+  const bitmap = atlas.rasterize?.(char) ?? atlas.sdf.current!.draw(char);
+  const rect = bitmap.width > 2 * SDF_BUFFER && bitmap.height > 2 * SDF_BUFFER ? packGlyph(atlas, bitmap) : undefined;
+  const glyph: Glyph = {
+    rect: rect ?? [0, 0, 0, 0],
+    left: (bitmap.glyphLeft - SDF_BUFFER) / RASTER_SIZE,
+    top: (bitmap.glyphTop + SDF_BUFFER) / RASTER_SIZE,
+    width: rect ? bitmap.width / RASTER_SIZE : 0,
+    height: rect ? bitmap.height / RASTER_SIZE : 0,
+    advance: bitmap.glyphAdvance / RASTER_SIZE,
+  };
+  atlas.glyphs.set(char, glyph);
+  return glyph;
+}
+
+/** Copies the bitmap to the atlas, left to right in rows, or leaves it out when the atlas is full; shelf packing, as @mapbox/shelf-pack does */
+function packGlyph({ texture, size, shelf }: GlyphAtlas, bitmap: GlyphBitmap): Glyph["rect"] | undefined {
+  if (shelf.x + bitmap.width > size) {
+    Object.assign(shelf, { x: 0, y: shelf.y + shelf.height, height: 0 });
+  }
+  if (shelf.y + bitmap.height > size) {
+    return undefined;
+  }
+  const { x, y } = shelf;
+  const data = texture.image.data as Uint8Array;
+  for (let row = 0; row < bitmap.height; row++) {
+    data.set(bitmap.data.subarray(row * bitmap.width, (row + 1) * bitmap.width), (y + row) * size + x);
+  }
+  Object.assign(shelf, { x: x + bitmap.width, height: Math.max(shelf.height, bitmap.height) });
+  texture.needsUpdate = true;
+  // Bitmap rows run top down from the texture's v = 0, while the quad's uv runs bottom up
+  return [x / size, (y + bitmap.height) / size, bitmap.width / size, -bitmap.height / size];
+}
+
+/**
+ * Lays out the text centered on the origin, each line centered, as drei's Text (troika-three-text) did with the r3f renderer's line height and
+ * spacing
+ */
+export function layoutText(atlas: GlyphAtlas, text: string, fontSize: number): ReadonlyArray<GlyphQuad> {
+  const lineHeight = LINE_HEIGHT * fontSize;
+  const lines = text.split("\n");
+  return lines.flatMap((line, i) => {
+    const glyphs = Array.from(line, (char) => getGlyph(atlas, char));
+    const advances = glyphs.map((g) => (g.advance + LETTER_SPACING) * fontSize);
+    const baseline = (lines.length * lineHeight) / 2 - i * lineHeight - (lineHeight - fontSize) / 2 - ASCENT * fontSize;
+    const pen = { x: -advances.reduce((sum, a) => sum + a, 0) / 2 };
+    return glyphs.flatMap((glyph, j) => {
+      const x = pen.x;
+      pen.x += advances[j]!;
+      return glyph.width === 0
+        ? []
+        : [
+            {
+              glyph,
+              x: x + (glyph.left + glyph.width / 2) * fontSize,
+              y: baseline + (glyph.top - glyph.height / 2) * fontSize,
+              width: glyph.width * fontSize,
+              height: glyph.height * fontSize,
+            },
+          ];
+    });
+  });
+}

package/src/renderers/three/viewer/options.ts

@@ -0,0 +1,98 @@
+import type { Object3D, Texture } from "three";
+import type { Group, Relation, Scene, Vec3, View } from "../../../abstract-3d.js";
+import type { MaterialState } from "../appearance/appearance.js";
+import type { BufferZones, CameraOptions } from "../camera/camera.js";
+import type { ControlsOptions } from "../camera/controls.js";
+import type { ControlsHelper } from "../camera/gizmo.js";
+import type { Quality } from "../quality/quality.js";
+import type { MountOverlays } from "./overlays.js";
+
+/** The viewer's options, and what passing each of them in an update redoes; telling which actually changed is the caller's, e.g. React's dependencies */
+
+export type Popover<Content> = { readonly id: string; readonly pos: Vec3; readonly content: Content };
+
+export type SceneEvent = {
+  readonly nativeEvent: MouseEvent;
+  /** Where the pointer hit, in world space */
+  readonly point: Vec3;
+};
+
+/** A group's data: of the top-level group, and of the group the hit mesh is in */
+type Data = Record<string, string> | undefined;
+
+export type ViewerOptions<Content> = {
+  /** Undefined shows the fallback */
+  readonly scene?: Scene;
+  /** The id of a top-level group, which its hover, selection, material state and events are by; groups without an id can't be clicked */
+  readonly createGroupId?: (g: Group) => string;
+  readonly selectedIds?: Record<string, boolean>;
+  readonly hoveredIds?: ReadonlyArray<string>;
+  readonly activeComponents?: Record<string, MaterialState>;
+  /**
+   * The ids of the relations whose shape is drawn to be clicked, e.g. where a component can be inserted. While defined, even when empty, only the
+   * groups whose material state is Accept can be clicked
+   */
+  readonly activeRelations?: ReadonlyArray<string>;
+  readonly showDimensions?: boolean;
+  /** View, buffer zones and padding are read when the scene is fitted: first, and for a new camera or canvas size */
+  readonly camera?: CameraOptions;
+  readonly view?: View;
+  readonly bufferZones?: BufferZones;
+  readonly fitPadding?: number;
+  readonly controls?: ControlsOptions;
+  readonly gizmo?: ControlsHelper;
+  /** Replace the default lights, a weak ambient light, a key light from the upper left and two fills */
+  readonly lights?: ReadonlyArray<Object3D> | ((scene: Scene) => ReadonlyArray<Object3D>);
+  /** Lights faces by which way they turn and gives metal reflections: `studio` by default, `room` for three's RoomEnvironment, or null for none */
+  readonly environment?: Texture | "studio" | "room" | null;
+  readonly environmentIntensity?: number;
+  /** `low` by default, without ambient occlusion */
+  readonly quality?: Quality;
+  readonly useAlphaTest?: boolean;
+  readonly materialStateImages?: Record<string, string>;
+  readonly popovers?: ReadonlyArray<Popover<Content>>;
+  readonly getTooltips?: (id: string) => ReadonlyArray<Popover<Content>>;
+  /** Mounts popover and tooltip content, e.g. as React portals; without it, strings and DOM nodes are mounted directly */
+  readonly onOverlays?: MountOverlays<Content>;
+  /** A built scene's shaders are compiled, so its first frame renders without a stall, e.g. to hide a fallback */
+  readonly onLoad?: () => void;
+  readonly onClickGroup?: (id: string, rootData: Data, data: Data, event: SceneEvent) => void;
+  /** Called with no id when the pointer leaves the group */
+  readonly onHoverGroup?: (id: string | undefined, rootData: Data, data: Data, event: SceneEvent) => void;
+  readonly onContextMenuGroup?: (id: string, rootData: Data, data: Data, left: number, top: number, event: SceneEvent) => void;
+  readonly onClickRelation?: (relation: Relation, event: SceneEvent) => void;
+};
+
+/** What an update has to redo, in the order it's redone */
+export type Change = "compile" | "build" | "camera" | "controls" | "gizmo" | "lights" | "quality" | "paint" | "dimensions" | "overlays";
+
+/** What passing each option redoes; callbacks and what's read later need nothing */
+export const effects: { readonly [K in keyof ViewerOptions<unknown>]-?: ReadonlyArray<Change> } = {
+  scene: ["compile", "build", "lights", "overlays"],
+  createGroupId: ["compile", "build"],
+  activeComponents: ["build"],
+  activeRelations: ["build"],
+  useAlphaTest: ["build"],
+  materialStateImages: ["build"],
+  selectedIds: ["paint"],
+  hoveredIds: ["paint"],
+  showDimensions: ["dimensions"],
+  camera: ["camera"],
+  view: [],
+  bufferZones: [],
+  fitPadding: [],
+  controls: ["controls"],
+  gizmo: ["gizmo"],
+  lights: ["lights"],
+  environment: ["lights"],
+  environmentIntensity: ["lights"],
+  quality: ["quality"],
+  popovers: ["overlays"],
+  getTooltips: ["overlays"],
+  onOverlays: [],
+  onLoad: [],
+  onClickGroup: ["paint"],
+  onHoverGroup: [],
+  onContextMenuGroup: [],
+  onClickRelation: [],
+};

package/src/renderers/three/viewer/overlays.ts

@@ -0,0 +1,71 @@
+import { Scene, type Vector3 } from "three";
+import { CSS2DObject, CSS2DRenderer } from "three/addons/renderers/CSS2DRenderer.js";
+
+/**
+ * HTML elements over the canvas at 3D anchors, e.g. popovers and tooltips, placed by three.js's CSS2DRenderer; their content is mounted by the app,
+ * or directly
+ */
+
+export type Overlay<Content> = {
+  readonly key: string;
+  /** In world space */
+  readonly position: Vector3;
+  readonly content: Content;
+};
+
+export type MountedOverlay<Content> = { readonly key: string; readonly element: HTMLElement; readonly content: Content };
+
+/** Mounts the overlays' content into their elements, called when the set of overlays or their content changes */
+export type MountOverlays<Content> = (overlays: ReadonlyArray<MountedOverlay<Content>>) => void;
+
+export type OverlayLayer<Content> = {
+  readonly renderer: CSS2DRenderer;
+  readonly scene: Scene;
+  readonly mounted: Map<string, { readonly object: CSS2DObject; overlay: Overlay<Content> }>;
+};
+
+export function createOverlayLayer<Content>(container: HTMLElement): OverlayLayer<Content> {
+  const renderer = new CSS2DRenderer();
+  renderer.domElement.style.cssText = "position:absolute;inset:0;overflow:hidden;pointer-events:none";
+  container.append(renderer.domElement);
+  return { renderer, scene: new Scene(), mounted: new Map() };
+}
+
+/** Without `mount`, strings and DOM nodes are mounted as they are */
+export function setOverlays<Content>(
+  layer: OverlayLayer<Content>,
+  overlays: ReadonlyArray<Overlay<Content>>,
+  mount: MountOverlays<Content> | undefined
+): void {
+  const keys = new Set<string>();
+  const changed = { current: false };
+  overlays.forEach((overlay) => {
+    keys.add(overlay.key);
+    const existing = layer.mounted.get(overlay.key);
+    changed.current ||= existing?.overlay.content !== overlay.content;
+    const object = existing?.object ?? new CSS2DObject(document.createElement("div"));
+    object.position.copy(overlay.position);
+    if (existing) {
+      existing.overlay = overlay;
+    } else {
+      object.element.style.pointerEvents = "none";
+      layer.scene.add(object);
+      layer.mounted.set(overlay.key, { object, overlay });
+    }
+  });
+  layer.mounted.forEach(({ object }, key) => {
+    if (!keys.has(key)) {
+      // Its element is removed with it
+      layer.scene.remove(object);
+      layer.mounted.delete(key);
+      changed.current = true;
+    }
+  });
+  if (changed.current && mount) {
+    mount(Array.from(layer.mounted, ([key, { object, overlay }]) => ({ key, element: object.element, content: overlay.content })));
+  } else if (changed.current) {
+    layer.mounted.forEach(({ object, overlay: { content } }) =>
+      object.element.replaceChildren(content instanceof Node ? content : String(content ?? ""))
+    );
+  }
+}