trid3d 0.0.0-stage → 0.1.0

package/trid/tools/manager.js

@@ -0,0 +1,241 @@
+/**
+ * A tool plugs into a Scene to add interaction or extra drawing.
+ * Every method is optional.
+ *
+ * @typedef {Object} Tool
+ * @property {(scene:Scene) => void} [attach] - Called when the tool is added
+ * @property {(scene:Scene) => void} [detach] - Called when the tool is removed
+ * @property {(e:ToolPointerEvent, scene:Scene) => boolean} [pointerDown]
+ *   Return true to take the drag: the following moves and the release
+ *   go only to this tool
+ * @property {(e:ToolPointerEvent, scene:Scene) => void} [pointerMove]
+ *   Called for the tool holding the drag, or for every tool while hovering
+ * @property {(e:ToolPointerEvent, scene:Scene) => void} [pointerUp] - Drag released
+ * @property {(scene:Scene) => void} [pointerLeave] - Pointer left the canvas (not dragging)
+ * @property {(e:ToolWheelEvent, scene:Scene) => boolean} [wheel]
+ *   Return true to use the scroll (stops the page from scrolling)
+ * @property {(dt:number, scene:Scene) => void} [update] - Called every frame before the scene's update
+ * @property {(ctx:CanvasRenderingContext2D, scene:Scene) => void} [draw] - Called after the objects are drawn
+ * @property {boolean} [blockContextMenu] - Disable the right-click menu on the canvas
+ *
+ * @typedef {Object} ToolPointerEvent
+ * @property {number} x - Pointer X in canvas pixels
+ * @property {number} y - Pointer Y in canvas pixels
+ * @property {number} dx - X movement since the last event, in canvas pixels
+ * @property {number} dy - Y movement since the last event, in canvas pixels
+ * @property {number} button - Button that changed (0 left, 1 middle, 2 right)
+ * @property {boolean} shiftKey
+ * @property {boolean} ctrlKey
+ * @property {boolean} altKey
+ * @property {PointerEvent} original - The DOM event
+ *
+ * @typedef {Object} ToolWheelEvent
+ * @property {number} x - Pointer X in canvas pixels
+ * @property {number} y - Pointer Y in canvas pixels
+ * @property {number} deltaY - Scroll amount (> 0 scrolls down)
+ * @property {WheelEvent} original - The DOM event
+ *
+ * @typedef {import("../scene.js").Scene} Scene
+ */
+
+/**
+ * Keeps a scene's tools and sends them canvas pointer events.
+ *
+ * Tools added later get the first chance at a pointer down or a
+ * scroll, like layers stacked on top of each other. The first tool
+ * that returns true takes it.
+ *
+ * Pointer positions are converted to canvas pixels, so they match
+ * the drawing even when the canvas is resized with CSS.
+ */
+export class ToolManager {
+  /**
+   * @param {Scene} scene - Scene whose canvas receives the events
+   */
+  constructor(scene) {
+    this.scene = scene;
+    /** @type {Tool[]} */
+    this.list = [];
+
+    this._active = null;
+    this._pointerId = null;
+    this._last = { x: 0, y: 0 };
+    this._listening = false;
+
+    this._onDown = this._onDown.bind(this);
+    this._onMove = this._onMove.bind(this);
+    this._onUp = this._onUp.bind(this);
+    this._onLeave = this._onLeave.bind(this);
+    this._onWheel = this._onWheel.bind(this);
+    this._onContextMenu = this._onContextMenu.bind(this);
+  }
+
+  /**
+   * Adds a tool and calls its `attach`. Adding the same tool twice does nothing.
+   *
+   * @param {Tool} tool
+   */
+  add(tool) {
+    if (this.list.includes(tool)) return;
+    this.list.push(tool);
+    tool.attach?.(this.scene);
+    this._listen();
+  }
+
+  /**
+   * Removes a tool and calls its `detach`. Does nothing if it isn't added.
+   *
+   * @param {Tool} tool
+   */
+  remove(tool) {
+    const i = this.list.indexOf(tool);
+    if (i === -1) return;
+    if (this._active === tool) this._release();
+    this.list.splice(i, 1);
+    tool.detach?.(this.scene);
+    if (this.list.length === 0) this._unlisten();
+  }
+
+  /** Removes every tool. */
+  clear() {
+    for (const tool of [...this.list]) this.remove(tool);
+  }
+
+  /**
+   * Calls every tool's `update`.
+   *
+   * @param {number} dt - Seconds since the last frame
+   */
+  update(dt) {
+    for (const tool of this.list) tool.update?.(dt, this.scene);
+  }
+
+  /**
+   * Calls every tool's `draw`.
+   *
+   * @param {CanvasRenderingContext2D} ctx
+   */
+  draw(ctx) {
+    for (const tool of this.list) tool.draw?.(ctx, this.scene);
+  }
+
+  _listen() {
+    if (this._listening) return;
+    const c = this.scene.canvas;
+    c.addEventListener("pointerdown", this._onDown);
+    c.addEventListener("pointermove", this._onMove);
+    c.addEventListener("pointerup", this._onUp);
+    c.addEventListener("pointercancel", this._onUp);
+    c.addEventListener("pointerleave", this._onLeave);
+    c.addEventListener("wheel", this._onWheel, { passive: false });
+    c.addEventListener("contextmenu", this._onContextMenu);
+    // Let tools receive touch drags instead of the page scrolling
+    c.style.touchAction = "none";
+    this._listening = true;
+  }
+
+  _unlisten() {
+    if (!this._listening) return;
+    const c = this.scene.canvas;
+    c.removeEventListener("pointerdown", this._onDown);
+    c.removeEventListener("pointermove", this._onMove);
+    c.removeEventListener("pointerup", this._onUp);
+    c.removeEventListener("pointercancel", this._onUp);
+    c.removeEventListener("pointerleave", this._onLeave);
+    c.removeEventListener("wheel", this._onWheel);
+    c.removeEventListener("contextmenu", this._onContextMenu);
+    c.style.touchAction = "";
+    this._listening = false;
+  }
+
+  /** Converts a DOM event position to canvas pixels. */
+  _toCanvas(e) {
+    const c = this.scene.canvas;
+    const rect = c.getBoundingClientRect();
+    return {
+      x: (e.clientX - rect.left) * (c.width / rect.width),
+      y: (e.clientY - rect.top) * (c.height / rect.height),
+    };
+  }
+
+  _pointerEvent(e) {
+    const { x, y } = this._toCanvas(e);
+    const ev = {
+      x, y,
+      dx: x - this._last.x,
+      dy: y - this._last.y,
+      button: e.button,
+      shiftKey: e.shiftKey,
+      ctrlKey: e.ctrlKey,
+      altKey: e.altKey,
+      original: e,
+    };
+    this._last = { x, y };
+    return ev;
+  }
+
+  _onDown(e) {
+    if (this._active) return;
+    const ev = this._pointerEvent(e);
+    ev.dx = ev.dy = 0;
+
+    for (let i = this.list.length - 1; i >= 0; i--) {
+      const tool = this.list[i];
+      if (tool.pointerDown?.(ev, this.scene) === true) {
+        this._active = tool;
+        this._pointerId = e.pointerId;
+        this.scene.canvas.setPointerCapture?.(e.pointerId);
+        e.preventDefault();
+        return;
+      }
+    }
+  }
+
+  _onMove(e) {
+    if (this._active && e.pointerId !== this._pointerId) return;
+    const ev = this._pointerEvent(e);
+
+    if (this._active) {
+      this._active.pointerMove?.(ev, this.scene);
+    } else {
+      for (const tool of this.list) tool.pointerMove?.(ev, this.scene);
+    }
+  }
+
+  _onUp(e) {
+    if (!this._active || e.pointerId !== this._pointerId) return;
+    const ev = this._pointerEvent(e);
+    const tool = this._active;
+    this._release();
+    tool.pointerUp?.(ev, this.scene);
+  }
+
+  _onLeave() {
+    if (this._active) return;
+    for (const tool of this.list) tool.pointerLeave?.(this.scene);
+  }
+
+  _onWheel(e) {
+    const { x, y } = this._toCanvas(e);
+    const ev = { x, y, deltaY: e.deltaY, original: e };
+
+    for (let i = this.list.length - 1; i >= 0; i--) {
+      if (this.list[i].wheel?.(ev, this.scene) === true) {
+        e.preventDefault();
+        return;
+      }
+    }
+  }
+
+  _onContextMenu(e) {
+    if (this.list.some(tool => tool.blockContextMenu)) e.preventDefault();
+  }
+
+  _release() {
+    if (this._pointerId !== null) {
+      this.scene.canvas.releasePointerCapture?.(this._pointerId);
+    }
+    this._active = null;
+    this._pointerId = null;
+  }
+}

package/trid/tools/objUploader.js

@@ -0,0 +1,153 @@
+import { readOBJFile, pickOBJFile } from "../loaders/obj.js";
+
+/**
+ * Lets the user load .obj files into the scene.
+ *
+ * - Drag and drop a .obj file onto the canvas
+ * - Or call `open()` from a button click to show the file dialog
+ *
+ * By default the new model replaces the last one it loaded. Pass
+ * `onLoad` to decide yourself what happens with it.
+ */
+export class ObjUploader {
+  /**
+   * @param {Object} [opts]
+   * @param {number|null} [opts.fit=1] - Size of the model's largest side (null keeps the file's units)
+   * @param {string} [opts.color] - Color of loaded models (default: the scene's color)
+   * @param {boolean} [opts.replace=true] - Remove the previously loaded model first
+   * @param {string} [opts.hint="Drop an .obj file here"] - Text shown while nothing is loaded ("" for none)
+   * @param {(obj:Object, file:File, scene:Scene) => void} [opts.onLoad] - Called with the object after it's added
+   * @param {(err:Error, file:File) => void} [opts.onError] - Called when a file can't be read
+   */
+  constructor({
+    fit = 1,
+    color,
+    replace = true,
+    hint = "Drop an .obj file here",
+    onLoad,
+    onError = (err) => console.error(err),
+  } = {}) {
+    this.fit = fit;
+    this.color = color;
+    this.replace = replace;
+    this.hint = hint;
+    this.onLoad = onLoad;
+    this.onError = onError;
+
+    /** The last object this tool added, or null. */
+    this.object = null;
+
+    this._scene = null;
+    this._dragging = false;
+    this._onDragOver = this._onDragOver.bind(this);
+    this._onDragLeave = this._onDragLeave.bind(this);
+    this._onDrop = this._onDrop.bind(this);
+  }
+
+  attach(scene) {
+    this._scene = scene;
+    const c = scene.canvas;
+    c.addEventListener("dragover", this._onDragOver);
+    c.addEventListener("dragleave", this._onDragLeave);
+    c.addEventListener("drop", this._onDrop);
+  }
+
+  detach(scene) {
+    const c = scene.canvas;
+    c.removeEventListener("dragover", this._onDragOver);
+    c.removeEventListener("dragleave", this._onDragLeave);
+    c.removeEventListener("drop", this._onDrop);
+    this._scene = null;
+  }
+
+  /**
+   * Shows the file dialog and loads the chosen file.
+   * Call it from a user action, like a button click.
+   *
+   * @returns {Promise<Object|null>} The added object, or null if cancelled or failed
+   */
+  async open() {
+    const file = await pickOBJFile();
+    return file ? this.load(file) : null;
+  }
+
+  /**
+   * Loads a .obj `File` (or `Blob`) into the scene.
+   *
+   * @param {File} file
+   * @returns {Promise<Object|null>} The added object, or null if it failed
+   */
+  async load(file) {
+    const scene = this._scene;
+    if (!scene) return null;
+
+    let mesh;
+    try {
+      mesh = await readOBJFile(file, this.fit == null ? {} : { fit: this.fit });
+    } catch (err) {
+      this.onError(err, file);
+      return null;
+    }
+    if (this._scene !== scene) return null;
+
+    if (this.replace && this.object) scene.remove(this.object);
+    const obj = { mesh };
+    if (this.color) obj.color = this.color;
+    this.object = scene.add(obj);
+    this.onLoad?.(this.object, file, scene);
+    this._redraw();
+    return this.object;
+  }
+
+  draw(ctx, scene) {
+    const { width, height } = scene.canvas;
+    const showHint = this.hint && !this.object;
+    if (!this._dragging && !showHint) return;
+
+    ctx.save();
+    if (this._dragging) {
+      ctx.strokeStyle = "rgba(255, 255, 255, 0.6)";
+      ctx.lineWidth = 3;
+      ctx.setLineDash([10, 8]);
+      ctx.strokeRect(8, 8, width - 16, height - 16);
+    }
+    if (showHint || this._dragging) {
+      ctx.fillStyle = "rgba(255, 255, 255, 0.7)";
+      ctx.font = "16px sans-serif";
+      ctx.textAlign = "center";
+      ctx.textBaseline = "middle";
+      ctx.fillText(this._dragging ? "Drop to load" : this.hint, width / 2, height / 2);
+    }
+    ctx.restore();
+  }
+
+  // A running scene redraws every frame; a stopped one needs a nudge
+  _redraw() {
+    if (this._scene && !this._scene.running) this._scene.render();
+  }
+
+  _onDragOver(e) {
+    if (!e.dataTransfer?.types.includes("Files")) return;
+    e.preventDefault(); // allows the drop
+    e.dataTransfer.dropEffect = "copy";
+    if (!this._dragging) {
+      this._dragging = true;
+      this._redraw();
+    }
+  }
+
+  _onDragLeave() {
+    this._dragging = false;
+    this._redraw();
+  }
+
+  _onDrop(e) {
+    e.preventDefault();
+    this._dragging = false;
+    this._redraw();
+    const files = [...(e.dataTransfer?.files ?? [])];
+    const file = files.find((f) => f.name.toLowerCase().endsWith(".obj"));
+    if (file) this.load(file);
+    else if (files.length) this.onError(new Error("Not an .obj file"), files[0]);
+  }
+}

package/trid/tools/orbitCamera.js

@@ -0,0 +1,132 @@
+import { cameraForward, cameraRight, cameraUp } from "../math/transform.js";
+import { worldPerPixel } from "./helpers.js";
+
+const MAX_PITCH = Math.PI / 2 - 0.01;
+
+/**
+ * Mouse camera controls that turn around a target point.
+ *
+ * - Left drag: orbit around the target
+ * - Right drag, middle drag or Shift + left drag: pan (moves the target)
+ * - Scroll: zoom in and out
+ *
+ * The tool drives `scene.camera` (x, y, z, yaw, pitch). Its own
+ * `target`, `distance`, `yaw` and `pitch` can be changed at any time.
+ * Don't use it together with another tool that moves the camera.
+ */
+export class OrbitCamera {
+  /**
+   * @param {Object} [opts]
+   * @param {{x:number,y:number,z:number}} [opts.target={x:0,y:0,z:0}] - Point to orbit around
+   * @param {number} [opts.distance] - Distance to the target (default: the camera's current distance)
+   * @param {number} [opts.yaw] - Starting yaw (default: the camera's yaw)
+   * @param {number} [opts.pitch] - Starting pitch (default: the camera's pitch)
+   * @param {number} [opts.rotateSpeed=0.005] - Radians per dragged pixel
+   * @param {number} [opts.zoomSpeed=0.001] - Zoom amount per scroll unit
+   * @param {number} [opts.minDistance=0.1] - Closest zoom
+   * @param {number} [opts.maxDistance=100] - Farthest zoom
+   * @param {boolean} [opts.rotate=true] - Allow orbiting
+   * @param {boolean} [opts.pan=true] - Allow panning
+   * @param {boolean} [opts.zoom=true] - Allow zooming
+   */
+  constructor({
+    target = { x: 0, y: 0, z: 0 },
+    distance,
+    yaw,
+    pitch,
+    rotateSpeed = 0.005,
+    zoomSpeed = 0.001,
+    minDistance = 0.1,
+    maxDistance = 100,
+    rotate = true,
+    pan = true,
+    zoom = true,
+  } = {}) {
+    this.target = target;
+    this.distance = distance;
+    this.yaw = yaw;
+    this.pitch = pitch;
+    this.rotateSpeed = rotateSpeed;
+    this.zoomSpeed = zoomSpeed;
+    this.minDistance = minDistance;
+    this.maxDistance = maxDistance;
+    this.rotate = rotate;
+    this.pan = pan;
+    this.zoom = zoom;
+
+    this.blockContextMenu = true;
+    this._mode = null;
+  }
+
+  attach(scene) {
+    const cam = scene.camera;
+    const t = this.target;
+    this.yaw ??= cam.yaw ?? 0;
+    this.pitch ??= cam.pitch ?? 0;
+    this.distance ??= Math.hypot(
+      (cam.x ?? 0) - t.x, (cam.y ?? 0) - t.y, (cam.z ?? 0) - t.z
+    ) || 1;
+    this.apply(cam);
+  }
+
+  /**
+   * Places the camera from the target, distance, yaw and pitch.
+   * Called automatically every frame and after each drag or scroll.
+   *
+   * @param {import("../math/transform.js").Camera} camera - Camera to move
+   */
+  apply(camera) {
+    this.pitch = Math.max(-MAX_PITCH, Math.min(MAX_PITCH, this.pitch));
+    this.distance = Math.max(this.minDistance, Math.min(this.maxDistance, this.distance));
+
+    camera.yaw = this.yaw;
+    camera.pitch = this.pitch;
+    const f = cameraForward(camera);
+    camera.x = this.target.x - f.x * this.distance;
+    camera.y = this.target.y - f.y * this.distance;
+    camera.z = this.target.z - f.z * this.distance;
+  }
+
+  pointerDown(e) {
+    const panButton = e.button === 1 || e.button === 2 || (e.button === 0 && e.shiftKey);
+
+    if (panButton && this.pan) this._mode = "pan";
+    else if (e.button === 0 && this.rotate) this._mode = "rotate";
+    else return false;
+
+    return true;
+  }
+
+  pointerMove(e, scene) {
+    if (this._mode === "rotate") {
+      this.yaw += e.dx * this.rotateSpeed;
+      this.pitch -= e.dy * this.rotateSpeed;
+    } else if (this._mode === "pan") {
+      // Move the target so the point under the cursor follows it
+      const k = worldPerPixel(scene, this.distance);
+      const r = cameraRight(scene.camera);
+      const u = cameraUp(scene.camera);
+      this.target.x += (-r.x * e.dx + u.x * e.dy) * k;
+      this.target.y += (-r.y * e.dx + u.y * e.dy) * k;
+      this.target.z += (-r.z * e.dx + u.z * e.dy) * k;
+    } else {
+      return;
+    }
+    this.apply(scene.camera);
+  }
+
+  pointerUp() {
+    this._mode = null;
+  }
+
+  wheel(e, scene) {
+    if (!this.zoom) return false;
+    this.distance *= Math.exp(e.deltaY * this.zoomSpeed);
+    this.apply(scene.camera);
+    return true;
+  }
+
+  update(dt, scene) {
+    this.apply(scene.camera);
+  }
+}