abstract-3d 4.0.0-beta.9 → 4.0.0

package/src/renderers/svg/svg-order.ts

@@ -0,0 +1,172 @@
+import type { Vec3 } from "../../abstract-3d.js";
+import type { zOrderElement } from "./svg-geometries/shared.js";
+
+/**
+ * Elements in drawing order, back to front, by Newell's ordering without splitting: of two elements that overlap on screen, one entirely behind the
+ * other's plane, or the other entirely in front of its plane, is drawn first. Elements are drawn by mean depth otherwise, each after those it must be
+ * drawn after, depth first; elements overlapping in a cycle, which only splitting them could resolve, are drawn where the cycle is met. Elements
+ * entirely inside an opaque convex polygon in front of them are left out, as they can't be seen
+ */
+export function orderElements(elements: ReadonlyArray<zOrderElement>): ReadonlyArray<zOrderElement> {
+  const items: Array<Item | undefined> = [];
+  const swept: Array<number> = [];
+  const byDepth: Array<number> = [];
+  elements.forEach((e, i) => {
+    items.push(e.polygon && createItem(e.polygon, !!e.opaque));
+    byDepth.push(i);
+    if (e.polygon) {
+      swept.push(i);
+    }
+  });
+  swept.sort((a, b) => items[a]!.min.x - items[b]!.min.x);
+  byDepth.sort((a, b) => elements[a]!.zOrder - elements[b]!.zOrder);
+
+  // Sweep along x: each item is compared with the active ones whose bounds still overlap it on screen, dropping the others in the same pass
+  const behind: Array<Array<number>> = [];
+  const hidden = new Uint8Array(elements.length);
+  const active: Array<number> = [];
+  for (const i of swept) {
+    const a = items[i]!;
+    active.length = active.reduce((kept, j) => {
+      const b = items[j]!;
+      if (b.max.x <= a.min.x + eps) {
+        return kept;
+      }
+      active[kept] = j;
+      const order = b.min.y < a.max.y - eps && a.min.y < b.max.y - eps ? getOrder(a, b) : 0;
+      if (order !== 0) {
+        const [back, front] = order < 0 ? [i, j] : [j, i];
+        (behind[front] ??= []).push(back);
+        hidden[back] ||= covers(items[front]!, items[back]!) ? 1 : 0;
+      }
+      return kept + 1;
+    }, 0);
+    active.push(i);
+  }
+
+  // Depth first: an element is drawn when it's met on the stack again, after the elements behind it; 1 while it waits, 2 once drawn
+  const state = new Uint8Array(elements.length);
+  const stack: Array<number> = [];
+  const ordered: Array<zOrderElement> = [];
+  for (const start of byDepth) {
+    stack.push(start);
+    while (stack.length > 0) {
+      const i = stack.pop()!;
+      if (state[i] === 0) {
+        state[i] = 1;
+        stack.push(i);
+        behind[i]?.forEach((j) => state[j] === 0 && stack.push(j));
+      } else if (state[i] === 1) {
+        state[i] = 2;
+        if (!hidden[i]) {
+          ordered.push(elements[i]!);
+        }
+      }
+    }
+  }
+  return ordered;
+}
+
+/** Distances below this, in the scene's units, are equal */
+const eps = 1e-3;
+
+type Item = {
+  readonly points: ReadonlyArray<Vec3>;
+  readonly min: Vec3;
+  readonly max: Vec3;
+  /** The screen's normals of the polygon's edges, which separate it from polygons it doesn't overlap */
+  readonly axes: ReadonlyArray<readonly [number, number]>;
+  /** Its plane, oriented toward the viewer, unless it's a line or a point, or seen edge on */
+  readonly plane?: { readonly normal: Vec3; readonly d: number };
+  /** The winding on screen of an opaque convex polygon, 1 or -1, by which it can hide others; 0 for others */
+  readonly occluder: number;
+};
+
+/** In one pass over the points: their bounds, edge normals on screen, plane by Newell's method, and whether they're a convex polygon */
+function createItem(points: ReadonlyArray<Vec3>, opaque: boolean): Item {
+  const min = { x: Infinity, y: Infinity, z: Infinity };
+  const max = { x: -Infinity, y: -Infinity, z: -Infinity };
+  const normal = { x: 0, y: 0, z: 0 };
+  // The smallest and largest turn at a corner on screen, the same sign throughout for a convex polygon
+  const turns = { min: 0, max: 0 };
+  const axes: Array<readonly [number, number]> = [];
+  points.forEach((p, i) => {
+    Object.assign(min, { x: Math.min(min.x, p.x), y: Math.min(min.y, p.y), z: Math.min(min.z, p.z) });
+    Object.assign(max, { x: Math.max(max.x, p.x), y: Math.max(max.y, p.y), z: Math.max(max.z, p.z) });
+    const q = points[(i + 1) % points.length]!;
+    normal.x += (p.y - q.y) * (p.z + q.z);
+    normal.y += (p.z - q.z) * (p.x + q.x);
+    normal.z += (p.x - q.x) * (p.y + q.y);
+    if (Math.abs(q.x - p.x) + Math.abs(q.y - p.y) > eps) {
+      axes.push([q.y - p.y, p.x - q.x]);
+    }
+    const o = points[(i + points.length - 1) % points.length]!;
+    const turn = (p.x - o.x) * (q.y - p.y) - (p.y - o.y) * (q.x - p.x);
+    Object.assign(turns, { min: Math.min(turns.min, turn), max: Math.max(turns.max, turn) });
+  });
+  const convex = points.length >= 3 && (turns.min >= -eps || turns.max <= eps);
+  const occluder = opaque && convex ? Math.sign(normal.z) : 0;
+  const length = Math.hypot(normal.x, normal.y, normal.z);
+  if (points.length < 3 || length < eps || Math.abs(normal.z) < 1e-6 * length) {
+    return { points, min, max, axes, occluder: 0 };
+  }
+  // Toward the viewer, at +z
+  const s = Math.sign(normal.z) / length;
+  const n = { x: normal.x * s, y: normal.y * s, z: normal.z * s };
+  const p0 = points[0]!;
+  return { points, min, max, axes, plane: { normal: n, d: n.x * p0.x + n.y * p0.y + n.z * p0.z }, occluder };
+}
+
+/** -1 if `a` is drawn before `b`, 1 if after, 0 if they don't overlap or nothing decides */
+function getOrder(a: Item, b: Item): number {
+  if (a.max.z <= b.min.z + eps) {
+    return -1;
+  }
+  if (b.max.z <= a.min.z + eps) {
+    return 1;
+  }
+  if (!overlap(a, b)) {
+    return 0;
+  }
+  const aToB = b.plane ? getSide(a.points, b.plane) : 0;
+  if (aToB !== 0) {
+    return aToB;
+  }
+  return a.plane ? -getSide(b.points, a.plane) : 0;
+}
+
+/** -1 if the points are all behind the plane, 1 if all in front of it, 0 if on both sides or in it */
+function getSide(points: ReadonlyArray<Vec3>, { normal: n, d }: NonNullable<Item["plane"]>): number {
+  const range = { min: Infinity, max: -Infinity };
+  points.forEach((p) => {
+    const distance = n.x * p.x + n.y * p.y + n.z * p.z - d;
+    Object.assign(range, { min: Math.min(range.min, distance), max: Math.max(range.max, distance) });
+  });
+  return range.max <= eps && range.min < -eps ? -1 : range.min >= -eps && range.max > eps ? 1 : 0;
+}
+
+/** Whether the polygons overlap on screen by more than touching: no edge normal of either separates them */
+function overlap(a: Item, b: Item): boolean {
+  return a.axes.every(([x, y]) => !separates(a, b, x, y)) && b.axes.every(([x, y]) => !separates(a, b, x, y));
+}
+
+function separates(a: Item, b: Item, x: number, y: number): boolean {
+  const range = { aMin: Infinity, aMax: -Infinity, bMin: Infinity, bMax: -Infinity };
+  a.points.forEach((p) => Object.assign(range, { aMin: Math.min(range.aMin, p.x * x + p.y * y), aMax: Math.max(range.aMax, p.x * x + p.y * y) }));
+  b.points.forEach((p) => Object.assign(range, { bMin: Math.min(range.bMin, p.x * x + p.y * y), bMax: Math.max(range.bMax, p.x * x + p.y * y) }));
+  const tolerance = eps * Math.hypot(x, y);
+  return range.aMax <= range.bMin + tolerance || range.bMax <= range.aMin + tolerance;
+}
+
+/** Whether the front's opaque convex polygon contains all of the back's points on screen, so the back can't be seen; not for a single point, e.g. text */
+function covers(front: Item, back: Item): boolean {
+  const { points, occluder } = front;
+  return (
+    occluder !== 0 &&
+    back.points.length >= 2 &&
+    points.every((p, i) => {
+      const q = points[(i + 1) % points.length]!;
+      return back.points.every((r) => occluder * ((q.x - p.x) * (r.y - p.y) - (q.y - p.y) * (r.x - p.x)) >= -eps * Math.hypot(q.x - p.x, q.y - p.y));
+    })
+  );
+}

package/src/renderers/svg/svg.ts

@@ -29,6 +29,7 @@ import { plane } from "./svg-geometries/svg-plane.js";
 import { polygon } from "./svg-geometries/svg-polygon.js";
 import { shape } from "./svg-geometries/svg-shape.js";
 import { text } from "./svg-geometries/svg-text.js";
+import { orderElements } from "./svg-order.js";
 
 export type SvgScene = {
   readonly scene: Scene;
@@ -89,26 +90,29 @@ function renderInternal(
     rotation: options?.rotation ?? 0,
     imageBg: options?.imageBg ?? false,
   };
-  const cameraRot = rotationForCameraPos(opts.view);
+  // Isometric: the front turned 45° to show the side, and tilted by arctan(1/√2) to show the top, so the three axes are foreshortened alike
+  const isometric = opts.view === "TopLeft" || opts.view === "TopRight";
+  const view = isometric ? "front" : opts.view;
+  const isometricRot = isometric
+    ? vec3RotCombine(vec3(Math.atan(1 / Math.SQRT2), 0, 0), vec3(0, ((opts.view === "TopRight" ? -1 : 1) * Math.PI) / 4, 0))
+    : vec3Zero;
+  const cameraRot = vec3RotCombine(isometricRot, rotationForCameraPos(view));
   const viewRot = opts.rotation ? vec3RotCombine(vec3(0, 0, (opts.rotation * Math.PI) / 180), cameraRot) : cameraRot;
   const unitRot = vec3RotCombine(viewRot, scene.rotation_deprecated ?? vec3Zero);
 
-  const unitCenter = vec3Rot(scene.center_deprecated ?? vec3Zero, vec3Zero, rotationForCameraPos(opts.view));
+  const unitCenter = vec3Rot(scene.center_deprecated ?? vec3Zero, vec3Zero, cameraRot);
   const [unitSize] = sizeBoundsForCameraPos(scene.size_deprecated, unitCenter, unitRot);
   const svgSize = vec2(unitSize.x + 1.5 * opts.stroke_thickness, unitSize.y + 1.5 * opts.stroke_thickness);
   const svgCenter = vec2(offset.x + opts.stroke_thickness * 0.75, offset.y + opts.stroke_thickness * 0.75);
   const point = (x: number, y: number): Vec2 => vec2(svgCenter.x + x, svgCenter.y - y);
   const unitCenterFlipped = vec3Flip(unitCenter);
 
-  const elements = Array<zOrderElement>();
-  for (const g of scene.groups) {
-    elements.push(...svgGroup(g, unitCenterFlipped, unitRot, point, opts));
-  }
+  const elements = [...orderElements(scene.groups.flatMap((g) => svgGroup(g, unitCenterFlipped, unitRot, point, opts)))];
   const dimOpts: SvgOptions = { ...opts, only_stroke: false, gray_scale: false };
-  elements.sort((a, b) => a.zOrder - b.zOrder);
-  const visibleViews = calculateVisibleViews(opts.view, scene.rotation_deprecated);
+  const visibleViews = calculateVisibleViews(view, scene.rotation_deprecated);
 
-  for (const dim of scene.dimensions_deprecated?.dimensions ?? []) {
+  // Dimensions are drawn for the flat views
+  for (const dim of isometric ? [] : (scene.dimensions_deprecated?.dimensions ?? [])) {
     const d = dimensionConvertToTypeMesh(dim, scene.rotation_deprecated ?? vec3Zero, scene.dimensions_deprecated?.material);
     if (isViewVisible(d.views[0], visibleViews)) {
       const pos = vec3TransRot(d.pos, unitCenterFlipped, unitRot);

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

@@ -45,6 +45,8 @@ export type BuildOptions = {
   readonly materialStateImages?: Record<string, string>;
   readonly useAlphaTest?: boolean;
   readonly onTextureLoaded?: () => void;
+  /** Lit by the studio, whose reflections metals show; true by default */
+  readonly studio?: boolean;
 };
 
 export type BuiltScene = {
@@ -233,7 +235,7 @@ function createPart(
       });
       if (first.role === "solid") {
         const c = getMaterialClass(first, targetStates[first.target]!);
-        const part = createSolidPart(entries, createClassMaterial(c));
+        const part = createSolidPart(entries, createClassMaterial(c, options.studio !== false));
         Object.assign(part.object, { castShadow: c.castShadow, receiveShadow: c.lit });
         return part;
       }

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

@@ -21,18 +21,26 @@ 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 {
+/**
+ * Without reflections, i.e. without the studio, metals keep at most a little metalness, satin from the lights' highlights, as they'd be black, having
+ * almost no diffuse light
+ */
+export function createClassMaterial(c: MaterialClass, reflections: boolean): Material {
   const side = c.side === "front" ? FrontSide : c.side === "back" ? BackSide : DoubleSide;
   const common = { side, transparent: c.transparent, depthWrite: !c.transparent };
   if (!c.lit) {
     return new MeshBasicMaterial(common);
   }
+  const metalness = c.type ? (finishes[c.type].metalness ?? 0) : c.metalness;
   const material = c.type
-    ? new MeshPhysicalMaterial({ ...common, ...finishes[c.type] })
-    : new MeshStandardMaterial({ ...common, metalness: c.metalness, roughness: c.roughness });
+    ? new MeshPhysicalMaterial({ ...common, ...finishes[c.type], metalness: reflections ? metalness : Math.min(metalness, plainMetalness) })
+    : new MeshStandardMaterial({ ...common, metalness: reflections ? metalness : Math.min(metalness, plainMetalness), roughness: c.roughness });
   return Object.assign(material, { onBeforeCompile: roundEdges });
 }
 
+/** The most metalness without reflections */
+const plainMetalness = 0.4;
+
 /**
  * The physical finish of each type of surface, in the material's color: metals reflect their color; galvanized and aluminum sheet keep some of their
  * color diffuse, so faces that mirror the studio's dark surroundings aren't black; the others are dielectrics with a white reflection; painted sheet

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

@@ -43,8 +43,14 @@ export type ViewerOptions<Content> = {
   readonly gizmo?: ControlsHelper;
   /** Lights added to the photographed studio and key light that light the scene; none by default */
   readonly lights?: ReadonlyArray<Object3D> | ((scene: Scene) => ReadonlyArray<Object3D>);
-  /** Of the studio's light, 0.8 by default, the key light giving the rest */
+  /** Of the studio's light, or without the studio of its plain light, 0.6 by default, the key light giving the rest */
   readonly environmentIntensity?: number;
+  /**
+   * The photographed studio's light and reflections, on by default. Off, three-point lighting emulates it, a weak sky and floor light, the key light,
+   * a fill and a rim light, without reflections, so metals are satin at most; a first visit then shows the scene about 400 ms sooner, as its shaders
+   * compile without the reflection code. Changing it rebuilds the scene
+   */
+  readonly studio?: boolean;
   /** A soft shadow on the ground under the scene, rendered once per build; on by default */
   readonly groundShadow?: boolean;
   /** The solids' shadows on themselves, e.g. under a roof, cast by the key light from the upper left front; on by default */
@@ -90,6 +96,7 @@ export const effects: { readonly [K in keyof ViewerOptions<unknown>]-?: Readonly
   gizmo: ["gizmo"],
   lights: ["lights"],
   environmentIntensity: ["lights"],
+  studio: ["build", "lights"],
   groundShadow: ["shadow"],
   shadows: ["shadow"],
   quality: ["quality"],

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

@@ -1,6 +1,8 @@
 import {
   type BufferGeometry,
+  DirectionalLight,
   Group,
+  HemisphereLight,
   NeutralToneMapping,
   OrthographicCamera,
   PerspectiveCamera,
@@ -136,7 +138,9 @@ export function createViewer<Content>(container: HTMLElement, options: ViewerOpt
   };
   v.scene.add(v.lights);
   // Loaded while the first frame builds the scene
-  loadStudio(v).catch(() => undefined);
+  if (options.studio !== false) {
+    loadStudio(v).catch(() => undefined);
+  }
   const signal = { signal: v.listeners.signal };
   canvas.addEventListener("pointermove", (e) => onPointerMove(v, e), signal);
   canvas.addEventListener("pointerleave", (e) => setHovered(v, undefined, e), signal);
@@ -282,7 +286,7 @@ function rebuild<Content>(v: Viewer<Content>): void {
     v.scene.add(v.built.root);
     v.built.dimensions.visible = options.showDimensions ?? true;
     // Compiled in parallel where the driver can, as three.js's compileAsync example, and after the studio arrived, which they use
-    loadStudio(v)
+    (options.studio === false ? Promise.resolve() : loadStudio(v))
       .catch(() => undefined)
       .then(() => v.renderer.compileAsync(v.scene, v.camera))
       .then(() => onLoaded(v))
@@ -517,12 +521,26 @@ function getGroupArgs<Content>(
   }
 }
 
-/** The scene is lit by a photographed studio as its environment; apps can add their own lights */
+/** The scene is lit by a photographed studio as its environment, or without it by a plain sky and floor light; apps can add their own lights */
 function updateLights<Content>(v: Viewer<Content>): void {
-  const { scene, lights, environmentIntensity = studioIntensity } = v.options;
+  const { scene, lights, environmentIntensity = studioIntensity, studio = true } = v.options;
   v.lights.clear();
   (typeof lights === "function" ? (scene ? lights(scene) : []) : (lights ?? [])).forEach((o) => v.lights.add(o));
   v.scene.environmentIntensity = environmentIntensity;
+  v.scene.environment = studio ? (v.studio.texture ?? null) : null;
+  if (studio) {
+    loadStudio(v).catch(() => undefined);
+  } else {
+    // The studio emulated by three-point lighting: a weak sky and floor light, so faces differ by which way they turn, the key light, a fill from
+    // the other side, so the key light's shadow side isn't flat, and a rim light from behind, which outlines edges
+    const [fill, rim] = [
+      new DirectionalLight(0xffffff, environmentIntensity * fillIntensity),
+      new DirectionalLight(0xffffff, environmentIntensity * rimIntensity),
+    ];
+    fill.position.copy(fillDirection);
+    rim.position.copy(rimDirection);
+    v.lights.add(new HemisphereLight(0xffffff, floorColor, environmentIntensity * skyIntensity), fill, rim);
+  }
 }
 
 /** The studio, loaded once, its own chunk; set when it arrives, so the scene's shaders are compiled after it, with it */
@@ -535,7 +553,7 @@ function loadStudio<Content>(v: Viewer<Content>): Promise<unknown> {
         return texture;
       }
       v.studio.texture = texture;
-      v.scene.environment = texture;
+      v.scene.environment = v.options.studio === false ? null : texture;
       invalidate(v);
       return texture;
     });
@@ -565,6 +583,14 @@ function updateOverlays<Content>(v: Viewer<Content>): void {
 
 /** The studio's share of the light, the key light giving the rest, so the key light's shadows show */
 const studioIntensity = 0.6;
+/** Without the studio, of its three-point lighting, by the environment's intensity; the key light is the studio's, the floor as the studio's */
+const skyIntensity = 1.5;
+const fillIntensity = 1.5;
+const rimIntensity = 2;
+const floorColor = 0xe6e6e6;
+/** From the right, opposite the key light from the upper left front, and lower; the rim light from behind and above */
+const fillDirection = new Vector3(1.5, 0.5, 1);
+const rimDirection = new Vector3(0.5, 1.5, -1.5);
 
 const raycaster = new Raycaster();
 const ndc = new Vector2();