trid3d 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZachR622
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="docs/public/logo.svg" width="96" alt="Trid logo">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">Trid</h1>
+
+<p align="center">A small 3D library for the HTML canvas. No dependencies, no build step.</p>
+
+---
+
+Trid gives you a scene, a camera, shapes, model loading and mouse/keyboard tools, all in plain ES modules you can drop next to your page.
+
+> **Status:** early. Objects can be wireframes or filled and shaded; textures and shaders are on the way.
+
+## Features
+
+- **Scene** — holds a canvas, a camera and your objects, and runs the frame loop for you.
+- **Shapes** — cubes, boxes and spheres built in, or any mesh you define as vertices and edges.
+- **Filled faces** — give an object a `material` to fill and shade its faces, flat or smooth, with one directional light.
+- **Textures** — images, canvases or videos on faces, with texture coordinates from built-in shapes and OBJ files.
+- **Effects** — stack shader effects like toon, rim and edge glow, gradients and fog on a material, or write your own in GLSL.
+- **Two renderers** — the canvas 2D context by default, or `WebGLRenderer` for exact depth and big models, with the same scene code.
+- **OBJ files** — load models from a URL, or let users drop their own `.obj` files on the canvas.
+- **Camera** — position, yaw, pitch and field of view, with near-plane clipping.
+- **Tools** — orbit and fly cameras, object dragging, hover highlight, an FPS meter and an OBJ uploader, one line each. Writing your own is a plain object with a few methods.
+- **Pure math** — every transform and projection step is exported, so you can use the pipeline piece by piece.
+
+## Install
+
+```sh
+npm install trid3d
+```
+
+No bundler? Use the CDN with an import map, or copy the `trid/` folder next to your page and import `./trid/index.js`:
+
+```html
+<script type="importmap">
+  { "imports": { "trid3d": "https://cdn.jsdelivr.net/npm/trid3d@0.1/trid/index.js" } }
+</script>
+```
+
+## Quick start
+
+```html
+<canvas id="canvas"></canvas>
+<script type="module" src="main.js"></script>
+```
+
+```js
+// main.js
+import { Scene, makeShape, OrbitCamera } from "trid3d";
+
+const scene = new Scene(document.getElementById("canvas"), { width: 800, height: 400 });
+const cube = scene.add({ mesh: makeShape("cube"), color: "#E9806E" });              // wireframe
+const ball = scene.add({ mesh: makeShape("sphere"), material: { fill: "#8ab4f8" } }); // filled and shaded
+ball.pos.x = 0.8;
+
+scene.use(new OrbitCamera()); // drag to orbit, scroll to zoom
+scene.start((dt) => (cube.rot.y += dt));
+```
+
+Without a bundler, serve the folder (`python3 -m http.server`) instead of opening the file directly: browsers block module imports from `file://` pages.
+
+### Loading a model
+
+```js
+import { loadOBJ } from "trid3d";
+
+const mesh = await loadOBJ("models/teapot.obj", { fit: 1 }); // centered, 1 unit wide
+scene.add({ mesh });
+```
+
+Or let users load their own: `scene.use(new ObjUploader())` accepts dropped `.obj` files, and `uploader.open()` shows a file dialog.
+
+## Project layout
+
+| Folder | Content |
+| --- | --- |
+| `trid/index.js` | Entry file: exports everything (`"trid3d"`) |
+| `trid/scene.js` | The `Scene` class |
+| `trid/math/` | Transforms, camera directions, projection |
+| `trid/render/` | Renderers (Canvas 2D, WebGL), effects, shapes, drawing, frame loop |
+| `trid/loaders/` | OBJ and texture loading |
+| `trid/tools/` | Camera, object and overlay tools |
+| `docs/` | Documentation site with live demos |
+
+## Documentation
+
+The docs explain every class, option and function, with live demos. To run them locally (Node 18+):
+
+```sh
+npm install
+npm run docs:dev
+```
+
+See [`docs/README.md`](docs/README.md) for building and editing the docs.
+
+## Roadmap
+
+- **More shapes** — cylinder, cone, torus, plane/grid
+- **More tools** — rotate/scale objects with the mouse, selection outline
+- **Parent/child transforms** — e.g. a moon orbiting a planet
+- **Tests** for the math functions

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "trid3d",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A small 3D library for the HTML canvas: wireframes, filled and smooth faces, textures and shader effects, drawn with Canvas 2D or WebGL. No dependencies.",
+  "keywords": [
+    "3d",
+    "canvas",
+    "webgl",
+    "wireframe",
+    "renderer",
+    "obj",
+    "shader"
+  ],
+  "license": "MIT",
+  "author": "ZachR622",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZachR622/Trid.git"
+  },
+  "homepage": "https://github.com/ZachR622/Trid#readme",
+  "bugs": {
+    "url": "https://github.com/ZachR622/Trid/issues"
+  },
+  "type": "module",
+  "main": "./trid/index.js",
+  "module": "./trid/index.js",
+  "exports": {
+    ".": "./trid/index.js",
+    "./*": "./trid/*"
+  },
+  "files": [
+    "trid"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "devDependencies": {
+    "vitepress": "^1.6.4"
+  }
+}

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,
+  };
+}