trid3d 0.0.0-stage → 0.1.1

package/trid/index.js

@@ -0,0 +1,53 @@
+/**
+ * Trid: a small 3D library for the HTML canvas.
+ *
+ * Everything the library offers, from one file:
+ *
+ *   import { Scene, makeShape, OrbitCamera } from "trid3d";        // with npm
+ *   import { Scene, makeShape, OrbitCamera } from "./trid/index.js"; // with the folder
+ *
+ * The individual modules can still be imported directly.
+ */
+
+// Scene
+export { Scene } from "./scene.js";
+
+// Shapes and meshes
+export { makeShape, scaleMesh } from "./render/shapes.js";
+
+// Renderers
+export { CanvasRenderer, DEFAULT_LIGHT, DEFAULT_AMBIENT } from "./render/canvasRenderer.js";
+export { WebGLRenderer, DEFAULT_FAR } from "./render/webglRenderer.js";
+
+// Effects
+export {
+  toon, rim, edgeGlow, unlit, gradient, fog,
+  buildEffects, effectsKey, uniformType, SURFACE_GLSL,
+} from "./render/effects.js";
+
+// Normals (smooth shading)
+export { cornerNormals, creaseOf, newell, DEFAULT_CREASE } from "./render/normals.js";
+
+// Loading files
+export { parseOBJ, loadOBJ, readOBJFile, pickOBJFile, fitMesh } from "./loaders/obj.js";
+export { loadTexture, textureReady, textureSize, textureIsLive } from "./loaders/texture.js";
+
+// Tools
+export {
+  OrbitCamera, FlyCamera, DragObject, HoverHighlight, FpsMeter, ObjUploader,
+  ToolManager, pick, screenBounds, worldPerPixel,
+} from "./tools/index.js";
+
+// Drawing and the frame loop
+export { clear, point, line, drawWireframe, drawInstance, edgeSegments } from "./render/draw.js";
+export { loop } from "./render/loop.js";
+export { parseColor } from "./render/color.js";
+
+// Math
+export {
+  localToWorld, worldToCamera, cameraToScreen, worldToScreen,
+  cameraForward, cameraRight, cameraUp, clipNear,
+  scale, translate, rotateX, rotateY, rotateZ, rotateXYZ,
+  DEFAULT_FOV, DEFAULT_NEAR,
+} from "./math/transform.js";
+export { project, screen } from "./math/projection.js";

package/trid/loaders/obj.js

@@ -0,0 +1,206 @@
+/**
+ * Wavefront OBJ loading.
+ *
+ * Reads vertex positions (`v`), texture coordinates (`vt`), normals
+ * (`vn`), faces (`f`) and polylines (`l`). Everything else (materials,
+ * groups) is ignored for now.
+ *
+ * OBJ files are right-handed with +Z toward the viewer. Trid is
+ * left-handed with the camera looking down +Z, so Z is flipped on
+ * load: a model that faces you in Blender faces you in Trid too.
+ */
+
+/**
+ * @typedef {Object} ObjMesh
+ * @property {{x:number,y:number,z:number}[]} vertices
+ * @property {number[][]} edges - Unique edges as [a, b] pairs, ready to draw
+ * @property {number[][]} faces - Polygons as vertex index lists
+ * @property {{x:number,y:number,z:number}[]} [normals] - Normals from the file (`vn`), if any
+ * @property {(number[]|null)[]} [faceNormals] - For each face, the normal index of each corner
+ *   (null when the file gives none for that face). Used by smooth shading.
+ * @property {{u:number,v:number}[]} [uvs] - Texture coordinates from the file (`vt`), if any
+ * @property {(number[]|null)[]} [faceUVs] - For each face, the texture coordinate index of
+ *   each corner (null when the file gives none for that face). Used by textures.
+ *
+ * @typedef {Object} ObjOptions
+ * @property {number} [fit] - If set, center the model on the origin and scale it
+ *   so its largest side is this long. Handy because OBJ files come in any size.
+ */
+
+/**
+ * Parses the text of an OBJ file into a mesh.
+ *
+ * @param {string} text - Contents of a .obj file
+ * @param {ObjOptions} [opts]
+ * @returns {ObjMesh}
+ * @throws {Error} If a face or line points at a vertex that doesn't exist
+ */
+export function parseOBJ(text, { fit } = {}) {
+  const vertices = [];
+  const faces = [];
+  const lines = [];
+  const normals = [];
+  const faceNormals = []; // per face: normal index of each corner, or null
+  const uvs = [];
+  const faceUVs = []; // per face: texture coordinate index of each corner, or null
+
+  const src = text.split(/\r?\n/);
+
+  for (let n = 0; n < src.length; n++) {
+    const line = src[n].trim();
+
+    if (line === "" || line[0] === "#") continue;
+
+    const parts = line.split(/\s+/);
+    const kind = parts[0];
+
+    if (kind === "v") {
+      vertices.push({ x: +(parts[1] ?? 0), y: +(parts[2] ?? 0), z: -(parts[3] ?? 0) });
+    } else if (kind === "vt") {
+      uvs.push({ u: +(parts[1] ?? 0), v: +(parts[2] ?? 0) });
+    } else if (kind === "vn") {
+      normals.push({ x: +(parts[1] ?? 0), y: +(parts[2] ?? 0), z: -(parts[3] ?? 0) });
+    } else if (kind === "f" || kind === "l") {
+      // "7", "7/1", "7//3", "7/1/3" all point at vertex 7. Negative = counted from the end.
+      const ids = parts.slice(1).map((p) => {
+        const i = parseInt(p, 10);
+        const idx = i < 0 ? vertices.length + i : i - 1;
+        if (!Number.isInteger(idx) || idx < 0 || idx >= vertices.length) {
+          throw new Error(`OBJ line ${n + 1}: bad vertex index "${p}"`);
+        }
+        return idx;
+      });
+      if (kind === "f" && ids.length >= 3) {
+        faces.push(ids.reverse()); // flipping Z flips the winding
+        // "7//3" and "7/1/3": the third number is the corner's normal
+        const ns = parts.slice(1).map((p) => {
+          const s = p.split("/")[2];
+          if (!s) return -1;
+          const i = parseInt(s, 10);
+          const idx = i < 0 ? normals.length + i : i - 1;
+          return idx >= 0 && idx < normals.length ? idx : -1;
+        });
+        faceNormals.push(ns.includes(-1) ? null : ns.reverse());
+        // "7/1" and "7/1/3": the second number is the corner's texture coordinate
+        const ts = parts.slice(1).map((p) => {
+          const s = p.split("/")[1];
+          if (!s) return -1;
+          const i = parseInt(s, 10);
+          const idx = i < 0 ? uvs.length + i : i - 1;
+          return idx >= 0 && idx < uvs.length ? idx : -1;
+        });
+        faceUVs.push(ts.includes(-1) ? null : ts.reverse());
+      } else if (kind === "l" && ids.length >= 2) lines.push(ids);
+    }
+  }
+
+  const seen = new Set();
+  const edges = [];
+  const addEdge = (a, b) => {
+    if (a === b) return;
+
+    // (2 to the power of 32) = 4294967296
+    // The parser uses it to turn an edge into a single number
+    const key = a < b ? a * 4294967296 + b : b * 4294967296 + a;
+
+    if (seen.has(key)) return;
+
+    seen.add(key);
+    edges.push([a, b]);
+  };
+
+  for (const f of faces) {
+    for (let i = 0; i < f.length; i++) addEdge(f[i], f[(i + 1) % f.length]);
+  }
+  for (const l of lines) {
+    for (let i = 0; i < l.length - 1; i++) addEdge(l[i], l[i + 1]);
+  }
+
+  const mesh = { vertices, edges, faces };
+  // Normals from the file, used by smooth shading
+  if (faceNormals.some((n) => n)) {
+    mesh.normals = normals;
+    mesh.faceNormals = faceNormals;
+  }
+  // Texture coordinates from the file
+  if (faceUVs.some((t) => t)) {
+    mesh.uvs = uvs;
+    mesh.faceUVs = faceUVs;
+  }
+  if (fit != null) fitMesh(mesh, fit);
+  return mesh;
+}
+
+/**
+ * Centers a mesh on the origin and scales it so its largest side is `size`.
+ * Changes the mesh in place.
+ *
+ * @param {{ vertices:{x:number,y:number,z:number}[] }} mesh
+ * @param {number} [size=1]
+ * @returns The same mesh
+ */
+export function fitMesh(mesh, size = 1) {
+  const vs = mesh.vertices;
+  if (vs.length === 0) return mesh;
+
+  const min = { x: Infinity, y: Infinity, z: Infinity };
+  const max = { x: -Infinity, y: -Infinity, z: -Infinity };
+  for (const v of vs) {
+    for (const k of ["x", "y", "z"]) {
+      if (v[k] < min[k]) min[k] = v[k];
+      if (v[k] > max[k]) max[k] = v[k];
+    }
+  }
+
+  const cx = (min.x + max.x) / 2, cy = (min.y + max.y) / 2, cz = (min.z + max.z) / 2;
+  const largest = Math.max(max.x - min.x, max.y - min.y, max.z - min.z);
+  const s = largest > 0 ? size / largest : 1;
+
+  for (const v of vs) {
+    v.x = (v.x - cx) * s;
+    v.y = (v.y - cy) * s;
+    v.z = (v.z - cz) * s;
+  }
+  return mesh;
+}
+
+/**
+ * Downloads an OBJ file and parses it.
+ *
+ * @param {string} url
+ * @param {ObjOptions} [opts]
+ * @returns {Promise<ObjMesh>}
+ */
+export async function loadOBJ(url, opts) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Could not load ${url} (${res.status})`);
+  return parseOBJ(await res.text(), opts);
+}
+
+/**
+ * Parses an OBJ file the user picked or dropped (a `File` or `Blob`).
+ *
+ * @param {Blob} file
+ * @param {ObjOptions} [opts]
+ * @returns {Promise<ObjMesh>}
+ */
+export async function readOBJFile(file, opts) {
+  return parseOBJ(await file.text(), opts);
+}
+
+/**
+ * Opens the browser's file dialog for .obj files.
+ * Must be called from a user action, like a button click.
+ *
+ * @returns {Promise<File|null>} The chosen file, or null if the dialog was cancelled
+ */
+export function pickOBJFile() {
+  return new Promise((resolve) => {
+    const input = document.createElement("input");
+    input.type = "file";
+    input.accept = ".obj";
+    input.addEventListener("change", () => resolve(input.files?.[0] ?? null));
+    input.addEventListener("cancel", () => resolve(null));
+    input.click();
+  });
+}

package/trid/loaders/texture.js

@@ -0,0 +1,56 @@
+/**
+ * Textures: images drawn on faces.
+ *
+ * A material's `texture` can be anything the canvas can draw:
+ * an `<img>`, a `<canvas>`, a `<video>` or an `ImageBitmap`.
+ * Canvases and videos are read again every frame, so they can change.
+ */
+
+/**
+ * Loads an image to use as a texture.
+ *
+ * @param {string} url
+ * @returns {Promise<HTMLImageElement>} The image, fully loaded
+ * @throws {Error} If the image can't be loaded
+ *
+ * @example
+ * const crate = await loadTexture("textures/crate.png");
+ * scene.add({ mesh: makeShape("cube"), material: { texture: crate } });
+ */
+export function loadTexture(url) {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    // Lets WebGL use images from other sites when they allow it (CORS)
+    img.crossOrigin = "anonymous";
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(new Error(`Could not load texture ${url}`));
+    img.src = url;
+  });
+}
+
+/** Whether a texture source has pixels to draw yet. */
+export function textureReady(src) {
+  if (!src) return false;
+  if (typeof HTMLImageElement !== "undefined" && src instanceof HTMLImageElement) {
+    return src.complete && src.naturalWidth > 0;
+  }
+  if (typeof HTMLVideoElement !== "undefined" && src instanceof HTMLVideoElement) {
+    return src.readyState >= 2;
+  }
+  return (src.width ?? 0) > 0 && (src.height ?? 0) > 0;
+}
+
+/** Pixel size of a texture source. */
+export function textureSize(src) {
+  return {
+    w: src.naturalWidth || src.videoWidth || src.width || 0,
+    h: src.naturalHeight || src.videoHeight || src.height || 0,
+  };
+}
+
+/** Whether a source can change over time (canvas, video), so it's read every frame. */
+export function textureIsLive(src) {
+  return (typeof HTMLCanvasElement !== "undefined" && src instanceof HTMLCanvasElement)
+    || (typeof HTMLVideoElement !== "undefined" && src instanceof HTMLVideoElement)
+    || (typeof OffscreenCanvas !== "undefined" && src instanceof OffscreenCanvas);
+}

package/trid/math/projection.js

@@ -0,0 +1,49 @@
+/**
+ * Converts normalized device coordinates (-1 to +1)
+ * into actual screen (pixel) coordinates.
+ *
+ * Normalized space:
+ *   x: -1 (left)  -> +1 (right)
+ *   y: -1 (bottom)-> +1 (top)
+ *
+ * Canvas space:
+ *   x: 0 -> width
+ *   y: 0 -> height (top-down)
+ *
+ * @param {{x:number, y:number}} p - Normalized 2D point
+ * @param {number} w - Canvas width
+ * @param {number} h - Canvas height
+ * @returns {{x:number, y:number}} Screen-space point
+ */
+export function screen(p, w, h) {
+  return {
+    x: (p.x + 1) / 2 * w,
+    y: (1 - (p.y + 1) / 2) * h,
+  };
+}
+
+/**
+ * Projects a 3D point onto a 2D plane using
+ * a perspective projection.
+ *
+ * The result is in normalized device coordinates (-1 to +1).
+ * `fov` is the vertical field of view; X is divided by `aspect`
+ * so shapes are not stretched on non-square canvases.
+ *
+ * NOTE:
+ * - z must be > 0 (in front of the camera)
+ * - smaller z => appears larger
+ * - larger z => appears smaller
+ *
+ * @param {{x:number, y:number, z:number}} p - 3D point (camera space)
+ * @param {number} fov - Vertical field of view in radians (default: 90°)
+ * @param {number} aspect - Canvas width / height (default: 1)
+ * @returns {{x:number, y:number}} 2D projected point
+ */
+export function project(p, fov = Math.PI / 2, aspect = 1) {
+  const f = 1 / Math.tan(fov / 2);
+  return {
+    x: (p.x * f) / (p.z * aspect),
+    y: (p.y * f) / p.z,
+  };
+}

package/trid/math/transform.js

@@ -0,0 +1,302 @@
+import { project, screen } from "./projection.js";
+
+/**
+ * Camera object. Every field is optional and falls back to its default.
+ *
+ * The camera looks down +Z when yaw and pitch are 0.
+ *
+ * @typedef {Object} Camera
+ * @property {number} [x=0] - Position on X
+ * @property {number} [y=0] - Position on Y
+ * @property {number} [z=0] - Position on Z
+ * @property {number} [yaw=0] - Turn around Y in radians (> 0 turns right)
+ * @property {number} [pitch=0] - Tilt around X in radians (> 0 looks up)
+ * @property {number} [fov=Math.PI/2] - Vertical field of view in radians
+ * @property {number} [near=0.01] - Near plane distance; closer geometry is clipped
+ * @property {number} [far=1000] - Far distance; farther geometry isn't drawn (WebGL renderer only)
+ */
+
+/** Default vertical field of view (90°). */
+export const DEFAULT_FOV = Math.PI / 2;
+
+/** Default near plane distance. */
+export const DEFAULT_NEAR = 0.01;
+
+/**
+ * Converts a vertex from local (mesh) space to world space
+ * using an instance transform.
+ *
+ * Transformation order:
+ * 1. Scale
+ * 2. Rotate (X then Y then Z)
+ * 3. Translate to world position
+ *
+ * @param {{x:number,y:number,z:number}} v - Local-space vertex
+ * @param {{
+ *   pos:{x:number,y:number,z:number},
+ *   rot:{x:number,y:number,z:number},
+ *   scale:{x:number,y:number,z:number}
+ * }} inst - Mesh instance transform
+ *
+ * @returns {{x:number,y:number,z:number}} World-space vertex
+ */
+export function localToWorld(v, inst) {
+  let p = scale(v, inst.scale.x, inst.scale.y, inst.scale.z);
+  p = rotateXYZ(p, inst.rot);
+  p = translate(p, inst.pos.x, inst.pos.y, inst.pos.z);
+  return p;
+}
+
+
+/**
+ * Converts a world-space point into camera space.
+ *
+ * Steps:
+ * 1. Move the point relative to the camera position
+ * 2. Undo the camera's yaw, then its pitch
+ *
+ * In camera space the camera sits at the origin looking down +Z.
+ *
+ * @param {{x:number,y:number,z:number}} pWorld - World-space point
+ * @param {Camera} camera - Camera object
+ *
+ * @returns {{x:number,y:number,z:number}} Camera-space point
+ */
+export function worldToCamera(pWorld, camera) {
+  let p = translate(pWorld, -(camera.x ?? 0), -(camera.y ?? 0), -(camera.z ?? 0));
+  p = rotateY(p, camera.yaw ?? 0);
+  p = rotateX(p, camera.pitch ?? 0);
+  return p;
+}
+
+/**
+ * Converts a camera-space point into screen-space coordinates.
+ *
+ * Steps:
+ * 1. Perspective projection (3D → 2D) using the camera's fov
+ *    and the canvas aspect ratio
+ * 2. Convert normalized coords to screen pixels
+ *
+ * NOTE: z must be > 0 (in front of the camera). Use `clipNear`
+ * on segments first if they may cross behind the camera.
+ *
+ * @param {{x:number,y:number,z:number}} pCam - Camera-space point
+ * @param {Camera} camera - Camera object
+ * @param {number} w - Canvas width
+ * @param {number} h - Canvas height
+ *
+ * @returns {{x:number,y:number}} Screen-space point
+ */
+export function cameraToScreen(pCam, camera, w, h) {
+  return screen(project(pCam, camera.fov ?? DEFAULT_FOV, w / h), w, h);
+}
+
+/**
+ * Converts a world-space point into screen-space coordinates.
+ *
+ * Steps:
+ * 1. World space → camera space (`worldToCamera`)
+ * 2. Camera space → screen pixels (`cameraToScreen`)
+ *
+ * @param {{x:number,y:number,z:number}} pWorld - World-space point
+ * @param {Camera} camera - Camera object
+ * @param {number} w - Canvas width
+ * @param {number} h - Canvas height
+ *
+ * @returns {{x:number,y:number}} Screen-space point
+ */
+export function worldToScreen(pWorld, camera, w, h) {
+  return cameraToScreen(worldToCamera(pWorld, camera), camera, w, h);
+}
+
+/**
+ * Direction the camera looks at, in world space (unit vector).
+ *
+ * @param {Camera} camera - Camera object
+ * @returns {{x:number,y:number,z:number}} Forward vector
+ */
+export function cameraForward(camera) {
+  const yaw = camera.yaw ?? 0;
+  const pitch = camera.pitch ?? 0;
+  return {
+    x: Math.sin(yaw) * Math.cos(pitch),
+    y: Math.sin(pitch),
+    z: Math.cos(yaw) * Math.cos(pitch),
+  };
+}
+
+/**
+ * Direction of the screen's right side, in world space (unit vector).
+ *
+ * @param {Camera} camera - Camera object
+ * @returns {{x:number,y:number,z:number}} Right vector
+ */
+export function cameraRight(camera) {
+  const yaw = camera.yaw ?? 0;
+  return {
+    x: Math.cos(yaw),
+    y: 0,
+    z: -Math.sin(yaw),
+  };
+}
+
+/**
+ * Direction of the screen's top side, in world space (unit vector).
+ *
+ * @param {Camera} camera - Camera object
+ * @returns {{x:number,y:number,z:number}} Up vector
+ */
+export function cameraUp(camera) {
+  const yaw = camera.yaw ?? 0;
+  const pitch = camera.pitch ?? 0;
+  return {
+    x: -Math.sin(pitch) * Math.sin(yaw),
+    y: Math.cos(pitch),
+    z: -Math.sin(pitch) * Math.cos(yaw),
+  };
+}
+
+/**
+ * Clips a camera-space segment against the near plane (z = near).
+ *
+ * - Both ends in front: segment returned unchanged
+ * - Both ends behind: returns null (nothing to draw)
+ * - One end behind: that end is moved onto the near plane
+ *
+ * @param {{x:number,y:number,z:number}} a - Segment start (camera space)
+ * @param {{x:number,y:number,z:number}} b - Segment end (camera space)
+ * @param {number} near - Near plane distance (> 0)
+ *
+ * @returns {[{x:number,y:number,z:number}, {x:number,y:number,z:number}] | null}
+ */
+export function clipNear(a, b, near) {
+  const aIn = a.z >= near;
+  const bIn = b.z >= near;
+
+  if (aIn && bIn) return [a, b];
+  if (!aIn && !bIn) return null;
+
+  const t = (near - a.z) / (b.z - a.z);
+  const p = {
+    x: a.x + (b.x - a.x) * t,
+    y: a.y + (b.y - a.y) * t,
+    z: near,
+  };
+
+  return aIn ? [a, p] : [p, b];
+}
+
+/**
+ * Scales a 3D point along each axis.
+ *
+ * @param {{x:number,y:number,z:number}} p - Input point
+ * @param {number} sx - Scale factor on X axis
+ * @param {number} sy - Scale factor on Y axis
+ * @param {number} sz - Scale factor on Z axis
+ * @returns {{x:number,y:number,z:number}} Scaled point
+ */
+export function scale(p, sx, sy, sz) {
+  return {
+    x: p.x * sx,
+    y: p.y * sy,
+    z: p.z * sz,
+  };
+}
+
+/**
+ * Translates a 3D point in space.
+ *
+ * @param {{x:number,y:number,z:number}} p - Input point
+ * @param {number} dx - Translation on X axis
+ * @param {number} dy - Translation on Y axis
+ * @param {number} dz - Translation on Z axis
+ * @returns {{x:number,y:number,z:number}} Translated point
+ */
+export function translate(p, dx, dy, dz) {
+  return {
+    x: p.x + dx,
+    y: p.y + dy,
+    z: p.z + dz,
+  };
+}
+
+/**
+ * Rotates a 3D point around the X axis (YZ plane).
+ *
+ * This creates an up/down “pitch” rotation.
+ *
+ * @param {{x:number,y:number,z:number}} p - Input point
+ * @param {number} angle - Rotation angle in radians
+ * @returns {{x:number,y:number,z:number}} Rotated point
+ */
+export function rotateX(p, angle) {
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+
+  return {
+    x: p.x,
+    y: p.y * c - p.z * s,
+    z: p.y * s + p.z * c,
+  };
+}
+
+/**
+ * Rotates a 3D point around the Y axis (XZ plane).
+ *
+ * This creates a left/right “yaw” rotation.
+ *
+ * @param {{x:number,y:number,z:number}} p - Input point
+ * @param {number} angle - Rotation angle in radians
+ * @returns {{x:number,y:number,z:number}} Rotated point
+ */
+export function rotateY(p, angle) {
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+
+  return {
+    x: p.x * c - p.z * s,
+    y: p.y,
+    z: p.x * s + p.z * c,
+  };
+}
+
+/**
+ * Rotates a 3D point around the Z axis (XY plane).
+ *
+ * This creates a “roll” rotation (spins in 2D).
+ *
+ * @param {{x:number,y:number,z:number}} p - Input point
+ * @param {number} angle - Rotation angle in radians
+ * @returns {{x:number,y:number,z:number}} Rotated point
+ */
+export function rotateZ(p, angle) {
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+
+  return {
+    x: p.x * c - p.y * s,
+    y: p.x * s + p.y * c,
+    z: p.z,
+  };
+}
+
+/**
+ * Applies Euler rotations to a point.
+ *
+ * Rotation order matters. This function applies:
+ * 1) rotateX
+ * 2) rotateY
+ * 3) rotateZ
+ *
+ * If you change the order, the final orientation will change.
+ *
+ * @param {{x:number,y:number,z:number}} p - Input point
+ * @param {{x:number,y:number,z:number}} rot - Rotation angles in radians
+ * @returns {{x:number,y:number,z:number}} Rotated point
+ */
+export function rotateXYZ(p, rot) {
+  let r = rotateX(p, rot.x);
+  r = rotateY(r, rot.y);
+  r = rotateZ(r, rot.z);
+  return r;
+}