trid3d 0.2.0 → 0.3.1

package/trid/scene.js

@@ -1,6 +1,7 @@
 import { CanvasRenderer, DEFAULT_LIGHT, DEFAULT_AMBIENT } from "./render/canvasRenderer.js";
 import { loop } from "./render/loop.js";
 import { ToolManager } from "./tools/manager.js";
+import { linkTree } from "./sceneGraph.js";
 import { screenshot, record } from "./export/capture.js";
 
 /**
@@ -71,27 +72,37 @@ export class Scene {
   }
 
   /**
-   * Adds an object to the scene, filling in missing transform fields.
+   * Adds an object to the scene, filling in missing transform fields
+   * (down its `children` too).
    *
-   * @param {{ mesh:{ vertices:{x:number,y:number,z:number}[], edges:number[][] } }} obj - Mesh instance
+   * An object can be a group: give it `children`, objects placed relative
+   * to it, and leave out `mesh` if it's only there to hold them. Moving it
+   * moves them all. See `trid/sceneGraph.js`.
+   *
+   * @example
+   * const car = scene.add({ children: [{ mesh: body }, { mesh: wheel, pos: { x: 0.4, y: -0.2, z: 0 } }] });
+   * car.pos.x += 0.1; // the body and the wheel move together
+   *
+   * @param {Object} obj - An object: `mesh` and/or `children`, plus pos, rot, scale, material...
    * @returns The same object, so it can be kept and animated
    */
   add(obj) {
-    obj.pos ??= { x: 0, y: 0, z: 0 };
-    obj.rot ??= { x: 0, y: 0, z: 0 };
-    obj.scale ??= { x: 1, y: 1, z: 1 };
+    linkTree(obj, null);
     this.objects.push(obj);
     return obj;
   }
 
   /**
-   * Removes an object from the scene. Does nothing if it isn't in it.
+   * Removes an object: from the scene's top level, or from its group's
+   * `children`. Its own children go with it. Does nothing if it isn't there.
    *
-   * @param {Object} obj - Object previously passed to `add`
+   * @param {Object} obj - Object previously added (or a child of one)
    */
   remove(obj) {
-    const i = this.objects.indexOf(obj);
-    if (i !== -1) this.objects.splice(i, 1);
+    const list = obj.parent ? obj.parent.children : this.objects;
+    const i = list?.indexOf(obj) ?? -1;
+    if (i !== -1) list.splice(i, 1);
+    if (obj.parent) obj.parent = null;
   }
 
   /**

package/trid/sceneGraph.js

@@ -0,0 +1,131 @@
+import { mat4FromTransform, mulMat4, transformPoint } from "./math/matrix.js";
+
+/**
+ * Groups: any object can have `children`, placed relative to it. An object
+ * without a `mesh` is just a group. Moving, turning or scaling an object
+ * moves its whole subtree.
+ *
+ *   const sword = scene.add({ pos, children: [
+ *     { mesh: blade },
+ *     { name: "hilt", children: [{ mesh: guard }, { mesh: grip, pos: { x: 0, y: -0.12, z: 0 } }] },
+ *   ] });
+ *   sword.rot.y += dt; // everything turns
+ *
+ * `children` is a plain array, read every frame: push and splice freely.
+ * Each object gets two read-only-by-convention fields, kept up to date every
+ * frame (and set right away by `scene.add`):
+ * - `parent`: the object it's a child of, or null at the top
+ * - `world`: its world matrix (parent's world matrix × its own transform)
+ * Both are non-enumerable, so they don't show up in JSON or `{ ...obj }`.
+ *
+ * `visible: false` hides an object and everything under it.
+ */
+
+/** Sets a field without making it enumerable (keeps objects clean for JSON and spreads). */
+function hidden(obj, key, value) {
+  if (Object.prototype.hasOwnProperty.call(obj, key)) obj[key] = value;
+  else Object.defineProperty(obj, key, { value, writable: true, configurable: true, enumerable: false });
+}
+
+/** Fills missing transform fields, like `scene.add` does. */
+function fill(obj) {
+  obj.pos ??= { x: 0, y: 0, z: 0 };
+  obj.rot ??= { x: 0, y: 0, z: 0 };
+  obj.scale ??= { x: 1, y: 1, z: 1 };
+}
+
+/**
+ * An object's world matrix, worked out now from its own transform and its
+ * parents' (following `obj.parent`). Use it between frames, after changing
+ * a transform; renderers keep `obj.world` up to date on their own.
+ *
+ * @param {Object} obj - A scene object
+ * @returns {number[]} 4×4 matrix (see `trid/math/matrix.js`)
+ */
+export function worldMatrix(obj) {
+  const own = mat4FromTransform(obj);
+  return obj.parent ? mulMat4(worldMatrix(obj.parent), own) : own;
+}
+
+/**
+ * Where an object's origin is in the world, now (with its parents).
+ *
+ * @param {Object} obj - A scene object
+ * @returns {{x:number, y:number, z:number}}
+ */
+export function worldPosition(obj) {
+  return transformPoint(worldMatrix(obj), { x: 0, y: 0, z: 0 });
+}
+
+/**
+ * Calls `fn(obj, world)` for every visible object under some roots, parents
+ * before children, with each one's world matrix. Changes nothing: objects
+ * don't need to be in a scene.
+ *
+ * @param {Object[]} roots - Top objects
+ * @param {(root:Object) => number[]|null} baseOf - Matrix a root's own transform goes under (null: none)
+ * @param {(obj:Object, world:number[], parent:Object|null) => void} fn
+ */
+export function forEachPlaced(roots, baseOf, fn) {
+  const visit = (obj, parent, parentWorld) => {
+    if (!obj || typeof obj !== "object") return;
+    const world = parentWorld ? mulMat4(parentWorld, mat4FromTransform(obj)) : mat4FromTransform(obj);
+    if (obj.visible === false) return;
+    fn(obj, world, parent);
+    if (Array.isArray(obj.children)) for (const child of obj.children) visit(child, obj, world);
+  };
+  for (const root of roots) visit(root, root?.parent ?? null, baseOf(root));
+}
+
+/**
+ * Every visible object of a scene (or of a list of objects and their
+ * subtrees), parents before their children, with `parent` and `world` set
+ * and missing transforms filled in. Groups without a mesh are included;
+ * renderers skip them.
+ *
+ * Objects given in a list keep their place in the scene: an object that is
+ * a child of a group still gets its parents' transforms.
+ *
+ * @param {Object|Object[]} input - A Scene, a scene object or a list of them
+ * @returns {Object[]} The objects, flattened
+ */
+export function worldObjects(input) {
+  const roots = Array.isArray(input) ? input : Array.isArray(input?.objects) ? input.objects : input ? [input] : [];
+  // The scene's own list is the top: those have no parent
+  if (roots === input?.objects) for (const obj of roots) if (obj && obj.parent) hidden(obj, "parent", null);
+  const out = [];
+  forEachPlaced(roots, (root) => (root.parent ? worldMatrix(root.parent) : null), (obj, world, parent) => {
+    fill(obj);
+    if (obj.parent !== parent) hidden(obj, "parent", parent);
+    hidden(obj, "world", world);
+    out.push(obj);
+  });
+  // Hidden objects still get their links (so a hidden group's children know their parent)
+  for (const root of roots) if (root?.visible === false) linkTree(root, root.parent ?? null);
+  return out;
+}
+
+/**
+ * Sets `parent` links and fills transforms down a subtree, right away.
+ * `scene.add` calls it, so `obj.parent` works before the first frame.
+ *
+ * @param {Object} obj
+ * @param {Object|null} [parent=null]
+ */
+export function linkTree(obj, parent = null) {
+  fill(obj);
+  if (obj.parent !== parent) hidden(obj, "parent", parent);
+  if (Array.isArray(obj.children)) for (const child of obj.children) linkTree(child, obj);
+}
+
+/**
+ * The chain from an object up to the top of its tree: `[obj, parent, ..., root]`.
+ *
+ * @param {Object} obj
+ * @returns {Object[]}
+ */
+export function ancestors(obj) {
+  const path = [];
+  for (let o = obj; o; o = o.parent) path.push(o);
+  return path;
+}

package/trid/tools/dragObject.js

@@ -1,5 +1,7 @@
 import { worldToCamera, cameraForward, cameraRight, cameraUp } from "../math/transform.js";
 import { pick, worldPerPixel } from "./helpers.js";
+import { invertMat4, transformDirection } from "../math/matrix.js";
+import { worldMatrix, worldPosition } from "../sceneGraph.js";
 
 /**
  * Click an object to pick it, then drag to move it.
@@ -7,9 +9,14 @@ import { pick, worldPerPixel } from "./helpers.js";
  * - Drag: moves the object parallel to the screen, following the cursor
  * - Shift + drag: moves it toward or away from the camera instead
  *
- * Objects are picked with `pick` (screen-space bounding box).
+ * Objects are picked with `pick`: by screen-space bounding box, or by their
+ * triangles with `exact: true`.
  * Set `obj.draggable = false` to make an object ignore this tool.
  *
+ * Inside a group, the part clicked moves within its group (it follows the
+ * cursor however the group is turned or scaled). With `root: true`, the
+ * whole group moves instead (the top-level object of what was clicked).
+ *
  * Add this tool after a camera tool so clicking an object drags it
  * and clicking empty space still moves the camera.
  */
@@ -19,6 +26,8 @@ export class DragObject {
    * @param {number} [opts.button=0] - Mouse button that drags (0 left, 1 middle, 2 right)
    * @param {(obj:Object) => boolean} [opts.filter] - Which objects can be dragged
    *   (default: those without `draggable: false`)
+   * @param {boolean} [opts.exact=false] - Pick by triangles instead of bounding boxes (see `pickHit`)
+   * @param {boolean} [opts.root=false] - Drag the top-level object (the whole group) of what was clicked
    * @param {(obj:Object) => void} [opts.onPick] - Called when an object is picked
    * @param {(obj:Object) => void} [opts.onMove] - Called each time the object moves
    * @param {(obj:Object) => void} [opts.onDrop] - Called when the object is released
@@ -26,12 +35,16 @@ export class DragObject {
   constructor({
     button = 0,
     filter = obj => obj.draggable !== false,
+    exact = false,
+    root = false,
     onPick,
     onMove,
     onDrop,
   } = {}) {
     this.button = button;
     this.filter = filter;
+    this.exact = exact;
+    this.root = root;
     this.onPick = onPick;
     this.onMove = onMove;
     this.onDrop = onDrop;
@@ -43,8 +56,12 @@ export class DragObject {
   pointerDown(e, scene) {
     if (e.button !== this.button) return false;
 
-    const obj = pick(scene, e.x, e.y, { filter: this.filter });
+    let obj = pick(scene, e.x, e.y, { filter: this.filter, exact: this.exact });
     if (!obj) return false;
+    if (this.root) {
+      while (obj.parent) obj = obj.parent;
+      if (obj.draggable === false) return false;
+    }
 
     this.dragging = obj;
     this.onPick?.(obj);
@@ -56,23 +73,30 @@ export class DragObject {
     if (!obj) return;
 
     const cam = scene.camera;
-    const depth = worldToCamera(obj.pos, cam).z;
+    const depth = worldToCamera(worldPosition(obj), cam).z;
     const k = worldPerPixel(scene, depth);
 
+    // How far to move in the world
+    let move;
     if (e.shiftKey) {
       // Drag up pushes the object away, drag down pulls it closer
       const f = cameraForward(cam);
       const amount = -e.dy * k;
-      obj.pos.x += f.x * amount;
-      obj.pos.y += f.y * amount;
-      obj.pos.z += f.z * amount;
+      move = { x: f.x * amount, y: f.y * amount, z: f.z * amount };
     } else {
       const r = cameraRight(cam);
       const u = cameraUp(cam);
-      obj.pos.x += (r.x * e.dx - u.x * e.dy) * k;
-      obj.pos.y += (r.y * e.dx - u.y * e.dy) * k;
-      obj.pos.z += (r.z * e.dx - u.z * e.dy) * k;
+      move = {
+        x: (r.x * e.dx - u.x * e.dy) * k,
+        y: (r.y * e.dx - u.y * e.dy) * k,
+        z: (r.z * e.dx - u.z * e.dy) * k,
+      };
     }
+    // Inside a group, `pos` is in the group's space: turn the move into it
+    if (obj.parent) move = transformDirection(invertMat4(worldMatrix(obj.parent)), move);
+    obj.pos.x += move.x;
+    obj.pos.y += move.y;
+    obj.pos.z += move.z;
 
     this.onMove?.(obj);
   }

package/trid/tools/helpers.js

@@ -1,9 +1,14 @@
-import { localToWorld, worldToCamera, cameraToScreen, DEFAULT_FOV, DEFAULT_NEAR } from "../math/transform.js";
+import { worldToCamera, cameraToScreen, DEFAULT_FOV, DEFAULT_NEAR } from "../math/transform.js";
+import { transformPoint } from "../math/matrix.js";
+import { worldMatrix, worldObjects, ancestors } from "../sceneGraph.js";
+import { edgeSegments, wireEdges } from "../render/draw.js";
 
 /**
  * Screen-space bounding box of an object, in canvas pixels.
  * Only vertices in front of the camera's near plane are used.
  *
+ * Objects inside groups are measured where they're drawn.
+ *
  * @param {import("../scene.js").Scene} scene - Scene the object is in
  * @param {Object} obj - Mesh instance (mesh, pos, rot, scale)
  * @returns {{minX:number, minY:number, maxX:number, maxY:number} | null}
@@ -12,10 +17,11 @@ import { localToWorld, worldToCamera, cameraToScreen, DEFAULT_FOV, DEFAULT_NEAR
 export function screenBounds(scene, obj) {
   const { camera, canvas } = scene;
   const near = camera.near ?? DEFAULT_NEAR;
+  const world = worldMatrix(obj);
   let box = null;
 
   for (const v of obj.mesh.vertices) {
-    const pCam = worldToCamera(localToWorld(v, obj), camera);
+    const pCam = worldToCamera(transformPoint(world, v), camera);
     if (pCam.z < near) continue;
 
     const p = cameraToScreen(pCam, camera, canvas.width, canvas.height);
@@ -35,27 +41,37 @@ export function screenBounds(scene, obj) {
 /**
  * Finds the object under a canvas pixel.
  *
- * An object is hit when the point is inside its screen-space
- * bounding box (plus `padding`). When several objects are hit,
- * the one whose center is closest to the camera wins.
+ * By default an object is hit when the point is inside its screen-space
+ * bounding box (plus `padding`), and when several are hit, the one whose
+ * center is closest to the camera wins. That's fast, but it can't tell apart
+ * objects that overlap on screen (a sword guard in front of its blade).
+ *
+ * With `exact: true` it tests the object's actual triangles (see `pickHit`),
+ * so the click always matches what's drawn.
+ *
+ * Objects inside groups are found too: the result is the object with the
+ * mesh that was hit (use `pickHit(...).path`, or `obj.parent`, for its groups).
  *
  * @param {import("../scene.js").Scene} scene - Scene to search
  * @param {number} x - Canvas X in pixels
  * @param {number} y - Canvas Y in pixels
  * @param {Object} [opts]
  * @param {(obj:Object) => boolean} [opts.filter] - Only consider objects that pass
- * @param {number} [opts.padding=4] - Extra pixels around each box
+ * @param {number} [opts.padding=4] - Extra pixels around each box (exact: how close to a line counts, for objects without faces)
+ * @param {boolean} [opts.exact=false] - Test triangles instead of bounding boxes
  * @returns {Object | null} The object, or null if nothing is hit
  */
-export function pick(scene, x, y, { filter = () => true, padding = 4 } = {}) {
+export function pick(scene, x, y, { filter = () => true, padding = 4, exact = false } = {}) {
+  if (exact) return pickHit(scene, x, y, { filter, padding })?.object ?? null;
+
   const near = scene.camera.near ?? DEFAULT_NEAR;
   let best = null;
   let bestDepth = Infinity;
 
-  for (const obj of scene.objects) {
-    if (!filter(obj)) continue;
+  for (const obj of worldObjects(scene)) {
+    if (!obj.mesh || !filter(obj)) continue;
 
-    const depth = worldToCamera(obj.pos, scene.camera).z;
+    const depth = worldToCamera(transformPoint(obj.world, { x: 0, y: 0, z: 0 }), scene.camera).z;
     if (depth < near || depth >= bestDepth) continue;
 
     const box = screenBounds(scene, obj);
@@ -71,6 +87,89 @@ export function pick(scene, x, y, { filter = () => true, padding = 4 } = {}) {
   return best;
 }
 
+/**
+ * Exact picking: the nearest object whose drawn surface is under a canvas
+ * pixel, with which face was hit and how far it is. Every face is projected
+ * with the same math as the renderers and tested triangle by triangle.
+ * Objects without faces (wireframes) are hit within `padding` pixels of
+ * one of their lines.
+ *
+ * Faces with a corner behind the camera's near plane are skipped. The cost
+ * is one pass over the objects' vertices per call: fine for clicks and hover
+ * on models of a few thousand faces.
+ *
+ * @example
+ * canvas.addEventListener("click", (e) => {
+ *   const hit = pickHit(scene, e.offsetX * canvas.width / canvas.clientWidth, e.offsetY * canvas.height / canvas.clientHeight);
+ *   if (hit) console.log(hit.object.name, "face", hit.face);
+ * });
+ *
+ * @param {import("../scene.js").Scene} scene - Scene to search
+ * @param {number} x - Canvas X in pixels
+ * @param {number} y - Canvas Y in pixels
+ * @param {Object} [opts]
+ * @param {(obj:Object) => boolean} [opts.filter] - Only consider objects that pass
+ * @param {number} [opts.padding=4] - How many pixels from a line count as a hit (objects without faces)
+ * @param {Object[]} [opts.objects=scene.objects] - Objects to test (with their children)
+ * @returns {{ object:Object, face:number, depth:number, path:Object[] } | null}
+ *   `object` has the mesh that was hit, `face` is the index in its
+ *   `mesh.faces` (-1 for a line), `depth` the distance in front of the
+ *   camera, `path` the object then its groups up to the top
+ *   (`[part, group, ..., root]`); null if nothing is hit
+ */
+export function pickHit(scene, x, y, { filter = () => true, padding = 4, objects = scene.objects } = {}) {
+  const { camera, canvas } = scene;
+  const w = canvas.width, h = canvas.height;
+  const near = camera.near ?? DEFAULT_NEAR;
+  let best = null;
+
+  for (const object of worldObjects(objects)) {
+    if (!object.mesh?.vertices || !filter(object)) continue;
+    const mesh = object.mesh;
+    const cam = mesh.vertices.map((v) => worldToCamera(transformPoint(object.world, v), camera));
+    const scr = cam.map((p) => (p.z > near ? cameraToScreen(p, camera, w, h) : null));
+    const closer = (depth) => !best || depth < best.depth;
+
+    if (mesh.faces?.length) {
+      mesh.faces.forEach((f, face) => {
+        // Polygons as triangle fans
+        for (let i = 1; i < f.length - 1; i++) {
+          const ia = f[0], ib = f[i], ic = f[i + 1];
+          const a = scr[ia], b = scr[ib], c = scr[ic];
+          if (!a || !b || !c) continue;
+          const bary = barycentric(x, y, a, b, c);
+          if (!bary) continue;
+          // Depth blended by 1/z, like perspective does (exact on tilted faces)
+          const depth = 1 / (bary[0] / cam[ia].z + bary[1] / cam[ib].z + bary[2] / cam[ic].z);
+          if (closer(depth)) best = { object, face, depth };
+        }
+      });
+    } else {
+      for (const [i, j] of edgeSegments(wireEdges(mesh))) {
+        const a = scr[i], b = scr[j];
+        if (!a || !b) continue;
+        const dx = b.x - a.x, dy = b.y - a.y;
+        const t = Math.max(0, Math.min(1, ((x - a.x) * dx + (y - a.y) * dy) / (dx * dx + dy * dy || 1)));
+        if (Math.hypot(x - (a.x + t * dx), y - (a.y + t * dy)) > padding) continue;
+        const depth = 1 / ((1 - t) / cam[i].z + t / cam[j].z);
+        if (closer(depth)) best = { object, face: -1, depth };
+      }
+    }
+  }
+  if (best) best.path = ancestors(best.object);
+  return best;
+}
+
+/** Barycentric weights of (x, y) in triangle abc, or null if outside (or degenerate). */
+function barycentric(x, y, a, b, c) {
+  const d = (b.y - c.y) * (a.x - c.x) + (c.x - b.x) * (a.y - c.y);
+  if (Math.abs(d) < 1e-9) return null;
+  const u = ((b.y - c.y) * (x - c.x) + (c.x - b.x) * (y - c.y)) / d;
+  const v = ((c.y - a.y) * (x - c.x) + (a.x - c.x) * (y - c.y)) / d;
+  const t = 1 - u - v;
+  return u >= 0 && v >= 0 && t >= 0 ? [u, v, t] : null;
+}
+
 /**
  * How many world units one canvas pixel covers at a given distance
  * from the camera. Useful to make things follow the cursor exactly.

package/trid/tools/hoverHighlight.js

@@ -14,11 +14,13 @@ export class HoverHighlight {
    * @param {string} [opts.color="#ffffff"] - Highlight color
    * @param {(obj:Object) => boolean} [opts.filter] - Which objects can be highlighted
    *   (default: those without `hoverable: false`)
+   * @param {boolean} [opts.exact=false] - Pick by triangles instead of bounding boxes (see `pickHit`)
    * @param {(obj:Object|null) => void} [opts.onChange] - Called when the hovered object changes
    */
-  constructor({ color = "#ffffff", filter = obj => obj.hoverable !== false, onChange } = {}) {
+  constructor({ color = "#ffffff", filter = obj => obj.hoverable !== false, exact = false, onChange } = {}) {
     this.color = color;
     this.filter = filter;
+    this.exact = exact;
     this.onChange = onChange;
 
     /** The object under the pointer, or null. */
@@ -28,7 +30,7 @@ export class HoverHighlight {
   }
 
   pointerMove(e, scene) {
-    this._set(pick(scene, e.x, e.y, { filter: this.filter }));
+    this._set(pick(scene, e.x, e.y, { filter: this.filter, exact: this.exact }));
   }
 
   pointerLeave() {

package/trid/tools/index.js

@@ -1,8 +1,10 @@
 export { ToolManager } from "./manager.js";
-export { pick, screenBounds, worldPerPixel } from "./helpers.js";
+export { pick, pickHit, screenBounds, worldPerPixel } from "./helpers.js";
 export { OrbitCamera } from "./orbitCamera.js";
 export { DragObject } from "./dragObject.js";
 export { FlyCamera } from "./flyCamera.js";
 export { HoverHighlight } from "./hoverHighlight.js";
 export { FpsMeter } from "./fpsMeter.js";
 export { ObjUploader } from "./objUploader.js";
+export { ViewGizmo } from "./viewGizmo.js";
+export { TransformGizmo } from "./transformGizmo.js";

package/trid/tools/orbitCamera.js

@@ -100,6 +100,15 @@ export class OrbitCamera {
     camera.z = this.target.z - f.z * this.distance;
   }
 
+  /**
+   * Restarts the auto-rotate wait (`autoRotateDelay`), as if the user had
+   * just dragged. For other tools that turn the camera, so auto-rotate
+   * doesn't fight them.
+   */
+  holdAutoRotate() {
+    this._idle = 0;
+  }
+
   pointerDown(e) {
     const panButton = e.button === 1 || e.button === 2 || (e.button === 0 && e.shiftKey);