trid3d 0.3.0 → 0.4.0

package/trid/tools/helpers.js

@@ -1,7 +1,22 @@
 import { worldToCamera, cameraToScreen, DEFAULT_FOV, DEFAULT_NEAR } from "../math/transform.js";
-import { transformPoint } from "../math/matrix.js";
+import { transformPoint, determinantMat4 } from "../math/matrix.js";
 import { worldMatrix, worldObjects, ancestors } from "../sceneGraph.js";
 import { edgeSegments, wireEdges } from "../render/draw.js";
+import { materialsOf } from "../render/canvasRenderer.js";
+import { newell } from "../render/normals.js";
+import { uvsFor, uvTransform, applyUVTransform } from "../render/uvMapping.js";
+
+/**
+ * Whether picking can find an object: not when it, or one of its groups,
+ * has `pickable: false` (helpers like a floor grid).
+ *
+ * @param {Object} obj
+ * @returns {boolean}
+ */
+export function isPickable(obj) {
+  for (let o = obj; o; o = o.parent) if (o.pickable === false) return false;
+  return true;
+}
 
 /**
  * Screen-space bounding box of an object, in canvas pixels.
@@ -51,6 +66,7 @@ export function screenBounds(scene, obj) {
  *
  * 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).
+ * Objects with `pickable: false` (or inside a group with it) are never found.
  *
  * @param {import("../scene.js").Scene} scene - Scene to search
  * @param {number} x - Canvas X in pixels
@@ -69,7 +85,7 @@ export function pick(scene, x, y, { filter = () => true, padding = 4, exact = fa
   let bestDepth = Infinity;
 
   for (const obj of worldObjects(scene)) {
-    if (!obj.mesh || !filter(obj)) continue;
+    if (!obj.mesh || !isPickable(obj) || !filter(obj)) continue;
 
     const depth = worldToCamera(transformPoint(obj.world, { x: 0, y: 0, z: 0 }), scene.camera).z;
     if (depth < near || depth >= bestDepth) continue;
@@ -94,6 +110,11 @@ export function pick(scene, x, y, { filter = () => true, padding = 4, exact = fa
  * Objects without faces (wireframes) are hit within `padding` pixels of
  * one of their lines.
  *
+ * The hit also says where on the face: the point (in the world and in the
+ * mesh's own space), the triangle and its barycentric weights, the face's
+ * normal, and the texture coordinates there (for painting on a model).
+ *
+ * Objects with `pickable: false` (or inside a group with it) are skipped.
  * 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.
@@ -101,7 +122,7 @@ export function pick(scene, x, y, { filter = () => true, padding = 4, exact = fa
  * @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);
+ *   if (hit) console.log(hit.object.name, "face", hit.face, "at", hit.point, "uv", hit.uv);
  * });
  *
  * @param {import("../scene.js").Scene} scene - Scene to search
@@ -111,7 +132,26 @@ export function pick(scene, x, y, { filter = () => true, padding = 4, exact = fa
  * @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}
+ * @returns {PickHit | null} null if nothing is hit
+ *
+ * @typedef {Object} PickHit
+ * @property {Object} object - The object with the mesh that was hit
+ * @property {number} face - Index in its `mesh.faces`, or -1 for a line of a wireframe
+ * @property {number} depth - Distance in front of the camera (camera-space z)
+ * @property {Object[]} path - The object, then its groups up to the top: `[part, group, ..., root]`
+ * @property {{x,y,z}} point - Where the hit is, in the world
+ * @property {{x,y,z}} local - Where the hit is, in the mesh's own space (`mesh.vertices` space)
+ * @property {number[]|null} triangle - The 3 vertex indices of the triangle hit (a face with
+ *   more corners is cut into a fan from its first corner); null for a line
+ * @property {number[]|null} barycentric - Weights of those 3 vertices at the hit (they add up
+ *   to 1; `local` = their weighted sum); null for a line
+ * @property {{x,y,z}|null} normal - Unit normal of the face hit, in the world, on its front
+ *   side; null for a line
+ * @property {{u,v}|null} uv - Texture coordinates at the hit (the face material's `mapping`,
+ *   before `textureRepeat` / `textureOffset` / `textureRotation`); null without any
+ * @property {{u,v}|null} textureUV - Where the texture is read at the hit: `uv` with the
+ *   material's repeat, offset and rotation (can be outside 0..1 when it repeats; image
+ *   pixel = `(fract(u) × width, (1 - fract(v)) × height)`); null without texture coordinates
  *   `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
@@ -124,7 +164,7 @@ export function pickHit(scene, x, y, { filter = () => true, padding = 4, objects
   let best = null;
 
   for (const object of worldObjects(objects)) {
-    if (!object.mesh?.vertices || !filter(object)) continue;
+    if (!object.mesh?.vertices || !isPickable(object) || !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));
@@ -141,7 +181,11 @@ export function pickHit(scene, x, y, { filter = () => true, padding = 4, objects
           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 };
+          if (closer(depth)) {
+            // Screen weights → weights on the triangle itself (perspective-correct)
+            const w = [bary[0] / cam[ia].z * depth, bary[1] / cam[ib].z * depth, bary[2] / cam[ic].z * depth];
+            best = { object, face, depth, triangle: [ia, ib, ic], corners: [0, i, i + 1], barycentric: w };
+          }
         }
       });
     } else {
@@ -152,12 +196,66 @@ export function pickHit(scene, x, y, { filter = () => true, padding = 4, objects
         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 (closer(depth)) best = { object, face: -1, depth, segment: [i, j], along: (t / cam[j].z) * depth };
       }
     }
   }
-  if (best) best.path = ancestors(best.object);
-  return best;
+  return best ? describeHit(best) : null;
+}
+
+/** Fills in where on the face (or line) a `pickHit` hit is. */
+function describeHit(h) {
+  const { object, face } = h;
+  const mesh = object.mesh;
+  const v = mesh.vertices;
+  const out = {
+    object, face, depth: h.depth, path: ancestors(object),
+    point: null, local: null, triangle: null, barycentric: null, normal: null, uv: null, textureUV: null,
+  };
+
+  if (face < 0) {
+    const [i, j] = h.segment, t = h.along;
+    out.local = lerp(v[i], v[j], t);
+    out.point = transformPoint(object.world, out.local);
+    return out;
+  }
+
+  const [a, b, c] = h.triangle, w = h.barycentric;
+  out.triangle = h.triangle;
+  out.barycentric = w;
+  out.local = {
+    x: w[0] * v[a].x + w[1] * v[b].x + w[2] * v[c].x,
+    y: w[0] * v[a].y + w[1] * v[b].y + w[2] * v[c].y,
+    z: w[0] * v[a].z + w[1] * v[b].z + w[2] * v[c].z,
+  };
+  out.point = transformPoint(object.world, out.local);
+
+  // The face's normal in the world; a mirrored object reverses its winding
+  const f = mesh.faces[face];
+  const n = newell(f.map((i) => transformPoint(object.world, v[i])));
+  const k = (determinantMat4(object.world) < 0 ? -1 : 1) / (Math.hypot(n.x, n.y, n.z) || 1);
+  out.normal = { x: n.x * k, y: n.y * k, z: n.z * k };
+
+  // Texture coordinates, from the face's material (its mapping, repeat, offset...)
+  const mats = materialsOf(object);
+  let m = mesh.faceMaterials?.[face] ?? 0;
+  if (mats && !(m >= 0 && m < mats.length && mats[m])) m = 0;
+  const mat = mats ? mats[m] : null;
+  const { uvs, faceUVs } = uvsFor(mesh, mat?.mapping);
+  const ft = faceUVs?.[face];
+  const ts = uvs && ft ? h.corners.map((corner) => uvs[ft[corner]]) : null;
+  if (ts && ts.every(Boolean)) {
+    out.uv = {
+      u: w[0] * ts[0].u + w[1] * ts[1].u + w[2] * ts[2].u,
+      v: w[0] * ts[0].v + w[1] * ts[1].v + w[2] * ts[2].v,
+    };
+    out.textureUV = applyUVTransform(mat ? uvTransform(mat) : null, out.uv);
+  }
+  return out;
+}
+
+function lerp(p, q, t) {
+  return { x: p.x + (q.x - p.x) * t, y: p.y + (q.y - p.y) * t, z: p.z + (q.z - p.z) * t };
 }
 
 /** Barycentric weights of (x, y) in triangle abc, or null if outside (or degenerate). */

package/trid/tools/index.js

@@ -1,5 +1,5 @@
 export { ToolManager } from "./manager.js";
-export { pick, pickHit, screenBounds, worldPerPixel } from "./helpers.js";
+export { pick, pickHit, isPickable, screenBounds, worldPerPixel } from "./helpers.js";
 export { OrbitCamera } from "./orbitCamera.js";
 export { DragObject } from "./dragObject.js";
 export { FlyCamera } from "./flyCamera.js";

package/trid/tools/transformGizmo.js

@@ -2,7 +2,7 @@ import { cameraForward, worldToCamera, worldToScreen, DEFAULT_NEAR } from "../ma
 import { applyTransformOp, matFromAxisAngle, mulVec } from "../math/rotation.js";
 import { meshBounds } from "../render/meshUtils.js";
 import { transformOpToLocal } from "../math/matrix.js";
-import { worldMatrix, ancestors } from "../sceneGraph.js";
+import { worldMatrix, worldPosition, ancestors } from "../sceneGraph.js";
 import { worldPerPixel } from "./helpers.js";
 
 const AXES = [
@@ -16,8 +16,9 @@ const UNIFORM = 3;
 const RING = 64;
 
 /**
- * Move, rotate and scale handles on one or more objects, around their
- * shared center (the middle of their bounding box). One tool, three modes:
+ * Move, rotate and scale handles on one or more objects, around a pivot:
+ * by default the middle of their bounding box (see `pivot`). One tool,
+ * three modes:
  *
  * - `"move"`: X, Y, Z arrows; drag one to move along that world axis
  * - `"rotate"`: X, Y, Z rings; drag along a ring to turn around that axis.
@@ -34,6 +35,16 @@ const RING = 64;
  * `apply: false` it only reports what the drag does (a `TransformOp`,
  * applied with `applyTransformOp`) so an app can apply it to its own data.
  *
+ * The pivot is where the handles sit and what rotate and scale turn and
+ * grow around (it's the ops' `center`):
+ * - `"bounds"` (default): the middle of the targets' bounding box
+ * - `"origin"`: the targets' origins (their `pos`, in the world; the average
+ *   of them for several targets)
+ * - a point `{ x, y, z }` in the world. It moves with the targets when the
+ *   gizmo moves them, so the handles stay on it
+ * - a function `(targets) => point | null`, asked every frame (for a pivot
+ *   an app keeps in its own data)
+ *
  * Add it **after** the camera tool: tools added later get clicks first, so
  * grabbing a handle doesn't also orbit. Clicks that miss the handles fall
  * through to the tools below.
@@ -51,15 +62,18 @@ export class TransformGizmo {
    * @param {Object[]} [opts.targets=[]] - Objects it edits (change `targets` at any time)
    * @param {number} [opts.size=70] - Handle length in CSS pixels (same on screen at any distance)
    * @param {boolean} [opts.apply=true] - Change the targets' transforms while dragging
+   * @param {"bounds"|"origin"|{x:number,y:number,z:number}|((targets:Object[]) => ({x:number,y:number,z:number}|null))} [opts.pivot="bounds"]
+   *   Where the handles sit and what rotate / scale go around (change `pivot` at any time)
    * @param {(targets:Object[]) => void} [opts.onGrab] - A handle was grabbed
    * @param {(op:Object, targets:Object[]) => void} [opts.onChange] - While dragging: the operation since the grab
    * @param {(op:Object, targets:Object[]) => void} [opts.onDrop] - On release: the whole operation
    */
-  constructor({ mode = "move", targets = [], size = 70, apply = true, onGrab, onChange, onDrop } = {}) {
+  constructor({ mode = "move", targets = [], size = 70, apply = true, pivot = "bounds", onGrab, onChange, onDrop } = {}) {
     this.mode = mode;
     this.targets = targets;
     this.size = size;
     this.apply = apply;
+    this.pivot = pivot;
     this.onGrab = onGrab;
     this.onChange = onChange;
     this.onDrop = onDrop;
@@ -74,9 +88,22 @@ export class TransformGizmo {
     this._cursor = false; // whether this tool set the canvas cursor
   }
 
-  /** Middle of the targets' bounding box in world space, or null. */
+  /** The pivot in world space (see `pivot`), or null when there are no targets. */
   center() {
-    return this.targets.length ? meshBounds(this.targets)?.center ?? null : null;
+    if (!this.targets.length) return null;
+    const p = this.pivot;
+    if (typeof p === "function") return p(this.targets) ?? null;
+    if (p && typeof p === "object") return { x: p.x, y: p.y, z: p.z };
+    if (p === "origin") {
+      const sum = { x: 0, y: 0, z: 0 };
+      for (const t of this.targets) {
+        const o = worldPosition(t);
+        sum.x += o.x; sum.y += o.y; sum.z += o.z;
+      }
+      const n = this.targets.length;
+      return { x: sum.x / n, y: sum.y / n, z: sum.z / n };
+    }
+    return meshBounds(this.targets)?.center ?? null;
   }
 
   /** Length of the handles in world units at a point, so they keep the same size on screen. */
@@ -186,6 +213,8 @@ export class TransformGizmo {
       parents: this.targets.map((t) => (t.parent ? worldMatrix(t.parent) : null)),
       // A target inside another target already moves with it
       moves: this.targets.map((t) => !ancestors(t).slice(1).some((a) => this.targets.includes(a))),
+      // A fixed pivot point, to move along with the targets
+      pivot: this.pivot && typeof this.pivot === "object" ? { ...this.pivot } : null,
       op: null,
     };
     this.dragging = true;
@@ -227,6 +256,11 @@ export class TransformGizmo {
       op = { mode: "scale", axis: AXES[d.id].dir, factor: Math.max(0.05, 1 + along()), center: d.center };
     }
     d.op = op;
+    if (d.pivot && op.mode === "move" && this.pivot && typeof this.pivot === "object") {
+      this.pivot.x = d.pivot.x + op.delta.x;
+      this.pivot.y = d.pivot.y + op.delta.y;
+      this.pivot.z = d.pivot.z + op.delta.z;
+    }
     if (this.apply) {
       this.targets.forEach((t, i) => {
         if (!d.moves[i]) return;