trid3d 0.0.0-stage → 0.1.1

package/trid/scene.js

@@ -0,0 +1,167 @@
+import { CanvasRenderer, DEFAULT_LIGHT, DEFAULT_AMBIENT } from "./render/canvasRenderer.js";
+import { loop } from "./render/loop.js";
+import { ToolManager } from "./tools/manager.js";
+
+/**
+ * Holds a canvas, a camera and a list of objects, and draws them.
+ *
+ * Objects are mesh instances. Any missing transform field is filled
+ * with a default when the object is added:
+ * - `pos`   → { x: 0, y: 0, z: 0 }
+ * - `rot`   → { x: 0, y: 0, z: 0 }
+ * - `scale` → { x: 1, y: 1, z: 1 }
+ *
+ * Each object can also set its own `color` and `lineWidth`;
+ * otherwise the scene's defaults are used. An object with a
+ * `material` draws its mesh's faces (filled and shaded) instead of
+ * only lines: `{ mesh, material: { fill: "#E9806E" } }`.
+ *
+ * Tools (camera controls, dragging, overlays...) are added with
+ * `use`. See `trid/tools/`.
+ *
+ * Typical usage:
+ *   const scene = new Scene(canvas, { width: 800, height: 800 });
+ *   const box = scene.add({ mesh: makeShape("cube"), color: "#E9806E" });
+ *   scene.start((dt) => { box.rot.y += dt; });
+ */
+export class Scene {
+  /**
+   * @param {HTMLCanvasElement} canvas - Canvas to draw on
+   * @param {Object} [opts]
+   * @param {number} [opts.width] - Sets canvas.width (keeps the current one if omitted)
+   * @param {number} [opts.height] - Sets canvas.height (keeps the current one if omitted)
+   * @param {string} [opts.background="#141414"] - Clear color
+   * @param {string} [opts.color="#ffffff"] - Default wireframe color
+   * @param {number} [opts.lineWidth=3] - Default wireframe width
+   * @param {import("./math/transform.js").Camera} [opts.camera={ z: -1 }] - Camera
+   * @param {{x:number,y:number,z:number}} [opts.light] - Direction light comes from
+   *   (default: above, left and in front)
+   * @param {number} [opts.ambient=0.25] - Brightness of faces turned away from the light (0..1)
+   * @param {{ render(scene:Scene): void, dispose?(): void }} [opts.renderer] - What draws the scene
+   *   (default: a new `CanvasRenderer`; or a `WebGLRenderer`)
+   */
+  constructor(canvas, {
+    width,
+    height,
+    background = "#141414",
+    color = "#ffffff",
+    lineWidth = 3,
+    camera = { z: -1 },
+    light = { ...DEFAULT_LIGHT },
+    ambient = DEFAULT_AMBIENT,
+    renderer = new CanvasRenderer(),
+  } = {}) {
+    this.canvas = canvas;
+    this.ctx = canvas.getContext("2d");
+    if (width !== undefined) canvas.width = width;
+    if (height !== undefined) canvas.height = height;
+
+    this.background = background;
+    this.color = color;
+    this.lineWidth = lineWidth;
+    this.camera = camera;
+    this.light = light;
+    this.ambient = ambient;
+    this.renderer = renderer;
+    this.objects = [];
+    this.tools = new ToolManager(this);
+
+    this._stop = null;
+  }
+
+  /**
+   * Adds an object to the scene, filling in missing transform fields.
+   *
+   * @param {{ mesh:{ vertices:{x:number,y:number,z:number}[], edges:number[][] } }} obj - Mesh instance
+   * @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 };
+    this.objects.push(obj);
+    return obj;
+  }
+
+  /**
+   * Removes an object from the scene. Does nothing if it isn't in it.
+   *
+   * @param {Object} obj - Object previously passed to `add`
+   */
+  remove(obj) {
+    const i = this.objects.indexOf(obj);
+    if (i !== -1) this.objects.splice(i, 1);
+  }
+
+  /**
+   * Adds a tool to the scene. Tools added later get the first chance
+   * at mouse clicks and scrolls, so add camera tools first and
+   * object tools (like `DragObject`) after them.
+   *
+   * @param {import("./tools/manager.js").Tool} tool - Tool to add
+   * @returns The same tool
+   */
+  use(tool) {
+    this.tools.add(tool);
+    return tool;
+  }
+
+  /**
+   * Removes a tool from the scene. Does nothing if it isn't in it.
+   *
+   * @param {import("./tools/manager.js").Tool} tool - Tool previously passed to `use`
+   */
+  unuse(tool) {
+    this.tools.remove(tool);
+  }
+
+  /**
+   * Clears the canvas, draws every object once (through the
+   * renderer), then lets tools draw on top.
+   */
+  render() {
+    this.renderer.render(this);
+    this.tools.draw(this.ctx);
+  }
+
+  /**
+   * Starts the frame loop: each frame updates the tools, calls
+   * `update`, then calls `render`.
+   * Calling `start` while running restarts the loop with the new `update`.
+   *
+   * @param {(dt:number, time:number, scene:Scene) => void} [update] - Per-frame logic
+   * @returns {Scene} This scene
+   */
+  start(update) {
+    this.stop();
+    this._stop = loop((dt, time) => {
+      this.tools.update(dt);
+      update?.(dt, time, this);
+      this.render();
+    });
+    return this;
+  }
+
+  /**
+   * Stops the frame loop. The last frame stays on the canvas.
+   */
+  stop() {
+    this._stop?.();
+    this._stop = null;
+  }
+
+  /**
+   * Stops the loop, removes every tool (and its event listeners) and
+   * frees the renderer's resources. Use it when the scene is no longer needed.
+   */
+  destroy() {
+    this.stop();
+    this.tools.clear();
+    this.renderer.dispose?.();
+  }
+
+  /** Whether the frame loop is running. */
+  get running() {
+    return this._stop !== null;
+  }
+}

package/trid/tools/dragObject.js

@@ -0,0 +1,89 @@
+import { worldToCamera, cameraForward, cameraRight, cameraUp } from "../math/transform.js";
+import { pick, worldPerPixel } from "./helpers.js";
+
+/**
+ * Click an object to pick it, then drag to move it.
+ *
+ * - 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).
+ * Set `obj.draggable = false` to make an object ignore this tool.
+ *
+ * Add this tool after a camera tool so clicking an object drags it
+ * and clicking empty space still moves the camera.
+ */
+export class DragObject {
+  /**
+   * @param {Object} [opts]
+   * @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 {(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
+   */
+  constructor({
+    button = 0,
+    filter = obj => obj.draggable !== false,
+    onPick,
+    onMove,
+    onDrop,
+  } = {}) {
+    this.button = button;
+    this.filter = filter;
+    this.onPick = onPick;
+    this.onMove = onMove;
+    this.onDrop = onDrop;
+
+    /** The object being dragged, or null. */
+    this.dragging = null;
+  }
+
+  pointerDown(e, scene) {
+    if (e.button !== this.button) return false;
+
+    const obj = pick(scene, e.x, e.y, { filter: this.filter });
+    if (!obj) return false;
+
+    this.dragging = obj;
+    this.onPick?.(obj);
+    return true;
+  }
+
+  pointerMove(e, scene) {
+    const obj = this.dragging;
+    if (!obj) return;
+
+    const cam = scene.camera;
+    const depth = worldToCamera(obj.pos, cam).z;
+    const k = worldPerPixel(scene, depth);
+
+    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;
+    } 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;
+    }
+
+    this.onMove?.(obj);
+  }
+
+  pointerUp() {
+    const obj = this.dragging;
+    this.dragging = null;
+    if (obj) this.onDrop?.(obj);
+  }
+
+  detach() {
+    this.dragging = null;
+  }
+}

package/trid/tools/flyCamera.js

@@ -0,0 +1,111 @@
+import { cameraForward, cameraRight } from "../math/transform.js";
+
+const MAX_PITCH = Math.PI / 2 - 0.01;
+
+/**
+ * Keyboard + mouse camera that flies freely through the scene.
+ *
+ * - W / S: forward / back
+ * - A / D: left / right
+ * - E / Q: up / down
+ * - Arrow keys: turn
+ * - Left drag: look around
+ * - Hold Shift: move faster
+ *
+ * Keys use physical positions (`KeyboardEvent.code`), so on AZERTY
+ * the same keys are Z / Q / S / D. Keys are ignored while typing in
+ * an input field. Don't use it together with another tool that
+ * moves the camera.
+ */
+export class FlyCamera {
+  /**
+   * @param {Object} [opts]
+   * @param {number} [opts.speed=1] - Units per second
+   * @param {number} [opts.fastMultiplier=3] - Speed multiplier while Shift is held
+   * @param {number} [opts.turnSpeed=1.5] - Radians per second with the arrow keys
+   * @param {number} [opts.lookSpeed=0.005] - Radians per dragged pixel
+   */
+  constructor({ speed = 1, fastMultiplier = 3, turnSpeed = 1.5, lookSpeed = 0.005 } = {}) {
+    this.speed = speed;
+    this.fastMultiplier = fastMultiplier;
+    this.turnSpeed = turnSpeed;
+    this.lookSpeed = lookSpeed;
+
+    this._keys = new Set();
+    this._onKeyDown = this._onKeyDown.bind(this);
+    this._onKeyUp = this._onKeyUp.bind(this);
+    this._onBlur = () => this._keys.clear();
+  }
+
+  attach() {
+    window.addEventListener("keydown", this._onKeyDown);
+    window.addEventListener("keyup", this._onKeyUp);
+    window.addEventListener("blur", this._onBlur);
+  }
+
+  detach() {
+    window.removeEventListener("keydown", this._onKeyDown);
+    window.removeEventListener("keyup", this._onKeyUp);
+    window.removeEventListener("blur", this._onBlur);
+    this._keys.clear();
+  }
+
+  _onKeyDown(e) {
+    const tag = e.target?.tagName;
+    if (tag === "INPUT" || tag === "TEXTAREA" || e.target?.isContentEditable) return;
+    if (!HANDLED_KEYS.has(e.code)) return;
+
+    this._keys.add(e.code);
+    // Stop arrow keys from scrolling the page
+    if (e.code.startsWith("Arrow")) e.preventDefault();
+  }
+
+  _onKeyUp(e) {
+    this._keys.delete(e.code);
+  }
+
+  pointerDown(e) {
+    return e.button === 0;
+  }
+
+  pointerMove(e, scene) {
+    const cam = scene.camera;
+    cam.yaw = (cam.yaw ?? 0) + e.dx * this.lookSpeed;
+    cam.pitch = clampPitch((cam.pitch ?? 0) - e.dy * this.lookSpeed);
+  }
+
+  update(dt, scene) {
+    const keys = this._keys;
+    if (keys.size === 0) return;
+
+    const cam = scene.camera;
+    const turn = this.turnSpeed * dt;
+    if (keys.has("ArrowLeft")) cam.yaw = (cam.yaw ?? 0) - turn;
+    if (keys.has("ArrowRight")) cam.yaw = (cam.yaw ?? 0) + turn;
+    if (keys.has("ArrowUp")) cam.pitch = clampPitch((cam.pitch ?? 0) + turn);
+    if (keys.has("ArrowDown")) cam.pitch = clampPitch((cam.pitch ?? 0) - turn);
+
+    const fast = keys.has("ShiftLeft") || keys.has("ShiftRight");
+    const step = this.speed * (fast ? this.fastMultiplier : 1) * dt;
+    const f = cameraForward(cam);
+    const r = cameraRight(cam);
+
+    const forward = (keys.has("KeyW") ? 1 : 0) - (keys.has("KeyS") ? 1 : 0);
+    const right = (keys.has("KeyD") ? 1 : 0) - (keys.has("KeyA") ? 1 : 0);
+    const up = (keys.has("KeyE") ? 1 : 0) - (keys.has("KeyQ") ? 1 : 0);
+
+    cam.x = (cam.x ?? 0) + (f.x * forward + r.x * right) * step;
+    cam.y = (cam.y ?? 0) + (f.y * forward + up) * step;
+    cam.z = (cam.z ?? 0) + (f.z * forward + r.z * right) * step;
+  }
+}
+
+const HANDLED_KEYS = new Set([
+  "KeyW", "KeyA", "KeyS", "KeyD", "KeyQ", "KeyE",
+  "ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown",
+  "ShiftLeft", "ShiftRight",
+]);
+
+function clampPitch(pitch) {
+  return Math.max(-MAX_PITCH, Math.min(MAX_PITCH, pitch));
+}

package/trid/tools/fpsMeter.js

@@ -0,0 +1,51 @@
+/**
+ * Draws the frames per second in a corner of the canvas.
+ *
+ * The value is averaged and refreshed every `interval` seconds,
+ * so it stays readable. It only counts while the scene is running.
+ */
+export class FpsMeter {
+  /**
+   * @param {Object} [opts]
+   * @param {string} [opts.color="#ffffff"] - Text color
+   * @param {string} [opts.font="14px monospace"] - CSS font
+   * @param {"top-left"|"top-right"|"bottom-left"|"bottom-right"} [opts.corner="top-left"]
+   * @param {number} [opts.interval=0.5] - Seconds between refreshes
+   */
+  constructor({ color = "#ffffff", font = "14px monospace", corner = "top-left", interval = 0.5 } = {}) {
+    this.color = color;
+    this.font = font;
+    this.corner = corner;
+    this.interval = interval;
+
+    /** Last measured frames per second. */
+    this.fps = 0;
+    this._frames = 0;
+    this._time = 0;
+  }
+
+  update(dt) {
+    // The loop's first frame has dt = 0; counting it would inflate the reading
+    if (dt <= 0) return;
+    this._frames++;
+    this._time += dt;
+    if (this._time >= this.interval) {
+      this.fps = Math.round(this._frames / this._time);
+      this._frames = 0;
+      this._time = 0;
+    }
+  }
+
+  draw(ctx, scene) {
+    const pad = 8;
+    const { width, height } = scene.canvas;
+    const right = this.corner.endsWith("right");
+    const bottom = this.corner.startsWith("bottom");
+
+    ctx.font = this.font;
+    ctx.fillStyle = this.color;
+    ctx.textAlign = right ? "right" : "left";
+    ctx.textBaseline = bottom ? "bottom" : "top";
+    ctx.fillText(`${this.fps} FPS`, right ? width - pad : pad, bottom ? height - pad : pad);
+  }
+}

package/trid/tools/helpers.js

@@ -0,0 +1,85 @@
+import { localToWorld, worldToCamera, cameraToScreen, DEFAULT_FOV, DEFAULT_NEAR } from "../math/transform.js";
+
+/**
+ * Screen-space bounding box of an object, in canvas pixels.
+ * Only vertices in front of the camera's near plane are used.
+ *
+ * @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}
+ *          The box, or null if the whole object is behind the camera
+ */
+export function screenBounds(scene, obj) {
+  const { camera, canvas } = scene;
+  const near = camera.near ?? DEFAULT_NEAR;
+  let box = null;
+
+  for (const v of obj.mesh.vertices) {
+    const pCam = worldToCamera(localToWorld(v, obj), camera);
+    if (pCam.z < near) continue;
+
+    const p = cameraToScreen(pCam, camera, canvas.width, canvas.height);
+    if (!box) {
+      box = { minX: p.x, minY: p.y, maxX: p.x, maxY: p.y };
+    } else {
+      box.minX = Math.min(box.minX, p.x);
+      box.minY = Math.min(box.minY, p.y);
+      box.maxX = Math.max(box.maxX, p.x);
+      box.maxY = Math.max(box.maxY, p.y);
+    }
+  }
+
+  return box;
+}
+
+/**
+ * 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.
+ *
+ * @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
+ * @returns {Object | null} The object, or null if nothing is hit
+ */
+export function pick(scene, x, y, { filter = () => true, padding = 4 } = {}) {
+  const near = scene.camera.near ?? DEFAULT_NEAR;
+  let best = null;
+  let bestDepth = Infinity;
+
+  for (const obj of scene.objects) {
+    if (!filter(obj)) continue;
+
+    const depth = worldToCamera(obj.pos, scene.camera).z;
+    if (depth < near || depth >= bestDepth) continue;
+
+    const box = screenBounds(scene, obj);
+    if (!box) continue;
+
+    if (x >= box.minX - padding && x <= box.maxX + padding &&
+        y >= box.minY - padding && y <= box.maxY + padding) {
+      best = obj;
+      bestDepth = depth;
+    }
+  }
+
+  return best;
+}
+
+/**
+ * How many world units one canvas pixel covers at a given distance
+ * from the camera. Useful to make things follow the cursor exactly.
+ *
+ * @param {import("../scene.js").Scene} scene - Scene (for camera fov and canvas height)
+ * @param {number} depth - Distance in front of the camera (camera-space z)
+ * @returns {number} World units per pixel
+ */
+export function worldPerPixel(scene, depth) {
+  const fov = scene.camera.fov ?? DEFAULT_FOV;
+  return (depth * 2 * Math.tan(fov / 2)) / scene.canvas.height;
+}

package/trid/tools/hoverHighlight.js

@@ -0,0 +1,62 @@
+import { pick } from "./helpers.js";
+
+/**
+ * Changes an object's color while the pointer is over it.
+ *
+ * The object's own `color` is put back when the pointer leaves it,
+ * when it leaves the canvas, or when the tool is removed. Objects
+ * with a `material` get their fill changed too.
+ * Set `obj.hoverable = false` to make an object ignore this tool.
+ */
+export class HoverHighlight {
+  /**
+   * @param {Object} [opts]
+   * @param {string} [opts.color="#ffffff"] - Highlight color
+   * @param {(obj:Object) => boolean} [opts.filter] - Which objects can be highlighted
+   *   (default: those without `hoverable: false`)
+   * @param {(obj:Object|null) => void} [opts.onChange] - Called when the hovered object changes
+   */
+  constructor({ color = "#ffffff", filter = obj => obj.hoverable !== false, onChange } = {}) {
+    this.color = color;
+    this.filter = filter;
+    this.onChange = onChange;
+
+    /** The object under the pointer, or null. */
+    this.hovered = null;
+    this._savedColor = undefined;
+    this._savedMaterial = undefined;
+  }
+
+  pointerMove(e, scene) {
+    this._set(pick(scene, e.x, e.y, { filter: this.filter }));
+  }
+
+  pointerLeave() {
+    this._set(null);
+  }
+
+  detach() {
+    this._set(null);
+  }
+
+  _set(obj) {
+    if (obj === this.hovered) return;
+
+    if (this.hovered) {
+      if (this._savedColor === undefined) delete this.hovered.color;
+      else this.hovered.color = this._savedColor;
+      if (this._savedMaterial) this.hovered.material = this._savedMaterial;
+    }
+
+    this.hovered = obj;
+    if (obj) {
+      this._savedColor = obj.color;
+      obj.color = this.color;
+      // Swap in a copy, so other objects sharing the material don't change
+      this._savedMaterial = obj.material;
+      if (obj.material) obj.material = { ...obj.material, fill: this.color };
+    }
+
+    this.onChange?.(obj);
+  }
+}

package/trid/tools/index.js

@@ -0,0 +1,8 @@
+export { ToolManager } from "./manager.js";
+export { pick, 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";