trid3d 0.2.0 → 0.3.1

package/README.md

@@ -10,21 +10,23 @@
 
 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, shaded and textured, with shader effects.
+> **Status:** early (0.x): the API can still change between minor versions. See [Upgrading](#upgrading).
 
 ## Features
 
 - **Scene** — holds a canvas, a camera and your objects, and runs the frame loop for you.
+- **Groups** — give any object `children` and they move, turn and scale with it (models made of parts, a moon orbiting a planet).
 - **Shapes** — cubes, boxes, spheres, cylinders, cones, tori and planes built in, `lathe` for round shapes and `extrude` for flat ones, or any mesh you define as vertices and edges.
+- **Mesh helpers** — clone, transform, displace, merge and measure meshes; seeded random numbers and smooth noise (`fbm2`, `fbm3`, tileable) for rocks, terrain and procedural textures.
 - **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, or made from the shape (planar, box, sphere and cylinder mapping). Repeat, offset and rotate them, or give each face its own material.
+- **Textures** — images, canvases or videos on faces, with texture coordinates from built-in shapes and OBJ files, or made from the shape (planar, box, sphere and cylinder mapping). Repeat, offset and rotate them, or give each face its own material. Or paint one in code: wood, marble, bricks and more, all seamless.
 - **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.
-- **Export** — `scene.screenshot()` and `scene.record()` save images and videos of the canvas; `exportOBJ` writes meshes, objects or whole scenes as OBJ files.
+- **OBJ files** — load models from a URL (with their `.mtl` colors and textures), or let users drop their own `.obj` files on the canvas.
+- **Export** — `scene.screenshot()` and `scene.record()` save images and videos of the canvas; `exportOBJ` / `exportModel` write meshes, objects or whole scenes as OBJ files with their MTL materials and textures.
 - **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.
+- **Tools** — orbit and fly cameras, object dragging, hover highlight, a move / rotate / scale gizmo, a view axes gizmo, an FPS meter and an OBJ uploader, one line each. Exact picking by triangles. Writing your own is a plain object with a few methods.
+- **Pure math** — every transform and projection step is exported, plus 4×4 matrices and rotations, so you can use the pipeline piece by piece.
 
 ## Install
 
@@ -36,7 +38,7 @@ No bundler? Use the CDN with an import map, or copy the `trid/` folder next to y
 
 ```html
 <script type="importmap">
-  { "imports": { "trid3d": "https://cdn.jsdelivr.net/npm/trid3d@0.1/trid/index.js" } }
+  { "imports": { "trid3d": "https://cdn.jsdelivr.net/npm/trid3d@0.3/trid/index.js" } }
 </script>
 ```
 
@@ -67,8 +69,8 @@ Without a bundler, serve the folder (`python3 -m http.server`) instead of openin
 ```js
 import { loadOBJ } from "trid3d";
 
-const mesh = await loadOBJ("models/teapot.obj", { fit: 1 }); // centered, 1 unit wide
-scene.add({ mesh });
+const mesh = await loadOBJ("models/teapot.obj", { fit: 1, materials: true }); // centered, 1 unit wide
+scene.add({ mesh, material: mesh.materials }); // colors and textures from its .mtl file
 ```
 
 Or let users load their own: `scene.use(new ObjUploader())` accepts dropped `.obj` files, and `uploader.open()` shows a file dialog.
@@ -79,12 +81,14 @@ Or let users load their own: `scene.use(new ObjUploader())` accepts dropped `.ob
 | --- | --- |
 | `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/export/` | Screenshots, video recording and OBJ export |
-| `trid/tools/` | Camera, object and overlay tools |
+| `trid/sceneGraph.js` | Groups: `children`, world matrices |
+| `trid/math/` | Transforms, camera directions, projection, matrices, rotations, random numbers and noise |
+| `trid/render/` | Renderers (Canvas 2D, WebGL), effects, shapes, mesh helpers, procedural textures, drawing, frame loop |
+| `trid/loaders/` | OBJ, MTL and texture loading |
+| `trid/export/` | Screenshots, video recording, OBJ and MTL export |
+| `trid/tools/` | Camera, object, gizmo and overlay tools |
 | `docs/` | Documentation site with live demos |
+| `test/` | Tests (`npm test`) |
 
 ## Documentation
 
@@ -99,12 +103,28 @@ npm run docs:dev
 
 See [`docs/README.md`](https://github.com/ZachR622/Trid/blob/master/docs/README.md) for building and editing the docs.
 
+## Tests
+
+```sh
+npm test
+```
+
+Uses Node's built-in test runner (Node 21+), so there's nothing to install. The tests cover shapes, mesh helpers, noise, textures, OBJ / MTL, picking, tools, groups and matrices, and the WebGL renderer's GPU memory on a fake WebGL context.
+
+## Upgrading
+
+### From 0.2 to 0.3
+
+- **Canvas textures are read once.** A canvas used as a `texture` is now uploaded once (faster, and sharper with mipmaps). If you draw on it again, call `updateTexture(canvas)` after drawing, or give its material `liveTexture: true` to read it every frame. Videos still play on their own. See [Changing a canvas](https://zachr622.github.io/Trid/textures#changing-a-canvas).
+- **The WebGL renderer frees unused GPU memory**: meshes and textures not drawn for 300 frames are freed (and sent again if they come back). Set `new WebGLRenderer({ releaseAfter: Infinity })` to keep the old behavior.
+- **Objects can have `children`**, and `mesh` is optional for a group. Code that walks `scene.objects` only sees the top level; use `worldObjects(scene)` to include children.
+- `parseOBJ` now sets `materialNames` / `faceMaterials` for a file with a single material too.
+
 ## Roadmap
 
 Roughly in order:
 
-- **More import and export formats** — `.mtl` material files for OBJ (colors and textures per part, both ways), STL; basic glTF later
-- **Parent/child transforms** — e.g. a moon orbiting a planet
-- **More tools** — a gizmo to move, rotate and scale objects with the mouse, a selection outline, a grid/axes helper
+- **More import and export formats** — STL; basic glTF later
+- **More tools** — a selection outline, a grid helper
 - **Post effects** (WebGL) — bloom, vignette, outlines, antialiasing and color grading over the whole image
-- **More tests** — `npm test` covers shapes and tools so far; the math functions are next
+- **More tests** — the canvas renderer's drawing and the remaining math functions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trid3d",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",

package/trid/export/mtl.js

@@ -0,0 +1,119 @@
+/**
+ * MTL export: the material file that goes with an OBJ file (colors,
+ * see-through and texture image names, one `newmtl` per material).
+ *
+ * The names match the `usemtl` lines `exportOBJ(input, { mtllib })` writes
+ * for the same input. `exportModel` gives all the files at once.
+ */
+
+import { exportEntries, exportOBJ, materialSlots } from "./obj.js";
+import { colorBytes } from "../render/proceduralTextures.js";
+import { textureReady, textureSize } from "../loaders/texture.js";
+
+/**
+ * The materials an export will name, with the file name for each texture.
+ *
+ * @param {Object|Object[]} input - An object, a group, a list of them or a Scene
+ * @param {Object} [opts]
+ * @param {(name:string, texture:Object) => string} [opts.textureFile] - File name for a material's
+ *   texture (default: the material's name + ".png")
+ * @returns {{ name:string, material:Object|null, texture:Object|null, file:string|null }[]}
+ */
+export function objMaterials(input, { textureFile = (name) => `${name}.png` } = {}) {
+  const { list } = materialSlots(exportEntries(input));
+  const files = new Map(); // one file per texture image, even when materials share it
+  return list.map(({ name, material }) => {
+    const texture = material?.texture ?? null;
+    if (texture && !files.has(texture)) files.set(texture, textureFile(name, texture));
+    return { name, material, texture, file: texture ? files.get(texture) : null };
+  });
+}
+
+/**
+ * Writes the text of an MTL file.
+ *
+ * `input` can be what `exportOBJ` takes (an object, a group, a list or a
+ * Scene: their materials are written, with the same names), or a list of
+ * plain material descriptions `{ name, fill?, opacity?, texture? }` where
+ * `texture` is the image's file name.
+ *
+ * Each material gets `Kd` (its fill color; white under a texture), `d` when
+ * it's see-through, and `map_Kd` with the texture's file name.
+ *
+ * @example
+ * download(exportOBJ(scene, { mtllib: "scene.mtl" }), "scene.obj");
+ * download(exportMTL(scene), "scene.mtl");
+ *
+ * @param {Object|Object[]} input
+ * @param {Object} [opts]
+ * @param {(name:string, texture:Object) => string} [opts.textureFile] - See `objMaterials`
+ * @param {string} [opts.header="Exported by Trid"] - Comment at the top; "" for none
+ * @returns {string}
+ */
+export function exportMTL(input, { textureFile, header = "Exported by Trid" } = {}) {
+  const items = Array.isArray(input) ? input : [input];
+  const plain = items.length > 0 && items.every((m) => m && !m.mesh && !m.children && !m.vertices && !m.objects && "name" in m);
+  const rows = plain
+    ? items.map((m) => ({ name: m.name, material: { fill: m.fill, opacity: m.opacity }, file: typeof m.texture === "string" ? m.texture : null }))
+    : objMaterials(input, { textureFile });
+
+  const num = (x) => (Math.round(x * 1e4) / 1e4).toString();
+  const out = header ? header.split("\n").map((l) => "# " + l) : [];
+  for (const { name, material, file } of rows) {
+    const fill = material?.fill ?? (file ? "#ffffff" : "#cccccc");
+    const [r, g, b, a] = colorBytes(fill);
+    const alpha = a * (material?.opacity ?? 1);
+    out.push("", `newmtl ${name}`);
+    out.push(`Kd ${num(r / 255)} ${num(g / 255)} ${num(b / 255)}`);
+    out.push("Ks 0 0 0", "illum 1");
+    if (alpha < 1) out.push(`d ${num(alpha)}`);
+    if (file) out.push(`map_Kd ${file}`);
+  }
+  return out.join("\n") + "\n";
+}
+
+/**
+ * A texture image as a PNG (or JPEG / WebP) file, to save next to an MTL file.
+ *
+ * @param {CanvasImageSource} src - An image, canvas, ImageBitmap or video frame
+ * @param {string} [type="image/png"]
+ * @returns {Promise<Blob>}
+ */
+export async function textureToBlob(src, type = "image/png") {
+  if (!textureReady(src)) throw new Error("textureToBlob: the texture isn't loaded yet");
+  const { w, h } = textureSize(src);
+  const canvas = typeof OffscreenCanvas !== "undefined" ? new OffscreenCanvas(w, h) : Object.assign(document.createElement("canvas"), { width: w, height: h });
+  canvas.getContext("2d").drawImage(src, 0, 0, w, h);
+  if (canvas.convertToBlob) return canvas.convertToBlob({ type });
+  return new Promise((resolve, reject) => canvas.toBlob((b) => (b ? resolve(b) : reject(new Error("Can't encode the texture"))), type));
+}
+
+/**
+ * Every file of a model, ready to save: the OBJ, its MTL and one image per
+ * texture. Save them in the same folder (or zip them) and the model opens
+ * with its colors and textures in Blender and other 3D programs.
+ *
+ * @example
+ * const files = await exportModel(scene, { name: "sword" });
+ * for (const f of files) await download(f.data, f.name);
+ *
+ * @param {Object|Object[]} input - An object, a group, a list of them or a Scene
+ * @param {Object} [opts]
+ * @param {string} [opts.name="model"] - Base name: model.obj, model.mtl
+ * @param {Object} [opts.obj] - More `exportOBJ` options
+ * @returns {Promise<{ name:string, data:string|Blob }[]>}
+ */
+export async function exportModel(input, { name = "model", obj = {} } = {}) {
+  const textureFile = (mat) => `${name}_${mat}.png`;
+  const files = [
+    { name: `${name}.obj`, data: exportOBJ(input, { ...obj, mtllib: `${name}.mtl` }) },
+    { name: `${name}.mtl`, data: exportMTL(input, { textureFile }) },
+  ];
+  const saved = new Set();
+  for (const { texture, file } of objMaterials(input, { textureFile })) {
+    if (!texture || saved.has(file)) continue;
+    saved.add(file);
+    files.push({ name: file, data: await textureToBlob(texture) });
+  }
+  return files;
+}

package/trid/export/obj.js

@@ -10,7 +10,8 @@
  * the right way round in Blender and other 3D programs.
  */
 
-import { localToWorld, rotateXYZ } from "../math/transform.js";
+import { transformPoint, normalMatrix, transformNormal, determinantMat4 } from "../math/matrix.js";
+import { forEachPlaced, worldMatrix } from "../sceneGraph.js";
 import { edgeSegments } from "../render/draw.js";
 import { materialsOf } from "../render/canvasRenderer.js";
 import { uvsFor, uvTransform, applyUVTransform } from "../render/uvMapping.js";
@@ -24,8 +25,90 @@ import { uvsFor, uvTransform, applyUVTransform } from "../render/uvMapping.js";
  * @property {boolean} [lines=true] - Write edges that aren't the side of a face as lines (`l`)
  * @property {number} [precision=6] - Decimals kept in numbers
  * @property {string} [header="Exported by Trid"] - Comment at the top of the file; "" for none
+ * @property {string} [mtllib] - Name of a .mtl file to link (`mtllib`): every object's materials
+ *   then get a `usemtl` name, the same ones `exportMTL` writes for the same input
  */
 
+/**
+ * The meshes an export input holds, each with the object it belongs to and
+ * its world matrix (null for a plain mesh). Groups are walked.
+ *
+ * @param {Object|Object[]} input - A mesh, an object, a group, a list of them or a Scene
+ * @returns {{ item:Object, mesh:Object, world:number[]|null }[]}
+ */
+export function exportEntries(input) {
+  const items = Array.isArray(input) ? input : Array.isArray(input?.objects) ? input.objects : [input];
+  const entries = [];
+  for (const item of items) {
+    if (!item) continue;
+    if (item.vertices) entries.push({ item, mesh: item, world: null });
+    else if (item.mesh || item.children) {
+      forEachPlaced([item], (root) => (root.parent ? worldMatrix(root.parent) : null), (obj, world) => {
+        if (obj.mesh) entries.push({ item: obj, mesh: obj.mesh, world });
+      });
+    } else {
+      throw new Error("exportOBJ: expected a mesh, a scene object, a list of them or a Scene");
+    }
+  }
+  return entries;
+}
+
+/** The OBJ object name of an entry. */
+const objectName = (entry, index, count) => entry.item.name ?? (count > 1 ? `object${index + 1}` : "object");
+
+/** A name safe for OBJ / MTL lines (no spaces). */
+const safe = (name) => String(name).trim().replace(/\s+/g, "_") || "material";
+
+/**
+ * The material names of an export, shared by `exportOBJ` (with `mtllib`) and
+ * `exportMTL`: one per material object (shared materials get one name), named
+ * after `material.name`, else after the object (`sword`, or `sword_1` for its
+ * second material). A mesh without materials keeps its OBJ material names.
+ *
+ * @param {{ item:Object, mesh:Object, world:number[]|null }[]} entries - From `exportEntries`
+ * @returns {{ nameOf:(entryIndex:number, k:number) => string|null,
+ *   list:{ name:string, material:Object|null }[] }}
+ */
+export function materialSlots(entries) {
+  const byMaterial = new Map(); // material object → name
+  const used = new Set();
+  const list = [];
+  const unique = (base) => {
+    let name = safe(base), n = 2;
+    while (used.has(name)) name = `${safe(base)}_${n++}`;
+    used.add(name);
+    return name;
+  };
+  const slots = entries.map((entry, index) => {
+    const mats = entry.world ? materialsOf(entry.item) : null;
+    const objName = objectName(entry, index, entries.length);
+    if (mats) {
+      return mats.map((mat, k) => {
+        if (!mat) return null;
+        if (!byMaterial.has(mat)) {
+          const name = unique(mat.name ?? (mats.length > 1 ? `${objName}_${k}` : objName));
+          byMaterial.set(mat, name);
+          list.push({ name, material: mat });
+        }
+        return byMaterial.get(mat);
+      });
+    }
+    // No material objects: names from the OBJ file it came from, if any
+    return (entry.mesh.materialNames ?? []).map((n) => {
+      const name = safe(n);
+      if (!used.has(name)) {
+        used.add(name);
+        list.push({ name, material: null });
+      }
+      return name;
+    });
+  });
+  return {
+    nameOf: (i, k) => slots[i]?.[k] ?? slots[i]?.[0] ?? null,
+    list,
+  };
+}
+
 /**
  * Writes meshes as the text of an OBJ file.
  *
@@ -33,6 +116,8 @@ import { uvsFor, uvTransform, applyUVTransform } from "../render/uvMapping.js";
  * - a mesh (`{ vertices, edges, faces }`): written as it is
  * - a scene object (`{ mesh, pos, rot, scale }`): its position, rotation and
  *   scale are applied, so it's written where it is in the scene
+ * - a group (an object with `children`): every mesh in it is written, each
+ *   where it's drawn, as its own object
  * - a list of meshes or objects, or a `Scene`: each becomes its own object (`o`)
  *   in the file, named after its `name` field when it has one
  *
@@ -43,8 +128,7 @@ import { uvsFor, uvTransform, applyUVTransform } from "../render/uvMapping.js";
  * @example
  * download(exportOBJ(scene), "scene.obj");
  */
-export function exportOBJ(input, { uvs = true, normals = true, lines = true, precision = 6, header = "Exported by Trid" } = {}) {
-  const items = Array.isArray(input) ? input : Array.isArray(input?.objects) ? input.objects : [input];
+export function exportOBJ(input, { uvs = true, normals = true, lines = true, precision = 6, header = "Exported by Trid", mtllib } = {}) {
   const num = (x) => {
     const s = (Math.abs(x) < 1e-12 ? 0 : x).toFixed(precision);
     return s.includes(".") ? s.replace(/\.?0+$/, "") : s; // 1.500000 → 1.5, 2.000000 → 2
@@ -52,21 +136,25 @@ export function exportOBJ(input, { uvs = true, normals = true, lines = true, pre
 
   const out = [];
   if (header) out.push(...header.split("\n").map((l) => "# " + l));
+  if (mtllib) out.push(`mtllib ${mtllib}`);
   let vBase = 0, tBase = 0, nBase = 0; // OBJ indices count across the whole file, from 1
 
-  items.forEach((item, index) => {
-    if (!item) return;
-    const isObject = !!item.mesh;
-    const mesh = isObject ? item.mesh : item;
+  // Plain meshes as they are; objects and their children where they're drawn (world matrix)
+  const entries = exportEntries(input);
+  const slots = mtllib ? materialSlots(entries) : null;
+
+  entries.forEach(({ item, mesh, world }, index) => {
     if (!mesh?.vertices) throw new Error("exportOBJ: expected a mesh, a scene object, a list of them or a Scene");
+    const isObject = !!world;
     const faces = mesh.faces ?? [];
-    const placed = isObject && item.pos && item.rot && item.scale;
+    // A mirrored object's faces are already turned around once
+    const mirrored = world ? determinantMat4(world) < 0 : false;
 
-    if (items.length > 1 || item.name) out.push(`o ${item.name ?? `object${index + 1}`}`);
+    if (entries.length > 1 || item.name) out.push(`o ${item.name ?? `object${index + 1}`}`);
 
     // Positions, in the scene's place when it's an object; Z flipped back to OBJ's right-handed axes
     for (const v of mesh.vertices) {
-      const p = placed ? localToWorld(v, item) : v;
+      const p = world ? transformPoint(world, v) : v;
       out.push(`v ${num(p.x)} ${num(p.y)} ${num(-p.z)}`);
     }
 
@@ -86,13 +174,9 @@ export function exportOBJ(input, { uvs = true, normals = true, lines = true, pre
     // Normals: turned like the object, and flipped back like the positions
     const writeNormals = !!(normals && mesh.normals && mesh.faceNormals?.some(Boolean));
     if (writeNormals) {
+      const nm = world ? normalMatrix(world) : null;
       for (const n of mesh.normals) {
-        let r = n;
-        if (placed) {
-          r = rotateXYZ({ x: n.x / item.scale.x, y: n.y / item.scale.y, z: n.z / item.scale.z }, item.rot);
-          const len = Math.hypot(r.x, r.y, r.z) || 1;
-          r = { x: r.x / len, y: r.y / len, z: r.z / len };
-        }
+        const r = nm ? transformNormal(nm, n) : n;
         out.push(`vn ${num(r.x)} ${num(r.y)} ${num(-r.z)}`);
       }
     }
@@ -100,20 +184,22 @@ export function exportOBJ(input, { uvs = true, normals = true, lines = true, pre
     // Faces, counter-clockwise again (the reverse of parseOBJ), with material names where they change
     const names = mesh.materialNames;
     const mats = isObject ? materialsOf(item) : null;
-    // Only when the names mean something: from the file, or a list of materials on the object
-    const named = !!(mesh.faceMaterials && (names || mats?.length > 1));
+    // Only when the names mean something: from the file, or a list of materials on the object.
+    // With an .mtl file, every material gets its name (the one exportMTL writes)
+    const named = slots ? slots.nameOf(index, 0) !== null : !!(mesh.faceMaterials && (names || mats?.length > 1));
     let current = null;
     faces.forEach((f, fi) => {
       if (f.length < 3) return;
       if (named) {
-        const k = mesh.faceMaterials[fi] ?? 0;
-        const name = names?.[k] ?? mats?.[k]?.name ?? `material${k}`;
+        const k = mesh.faceMaterials?.[fi] ?? 0;
+        const name = slots ? slots.nameOf(index, k) : names?.[k] ?? mats?.[k]?.name ?? `material${k}`;
         if (name !== current) out.push(`usemtl ${(current = name)}`);
       }
       const ts = writeUVs ? faceUVs[fi] : null;
       const ns = writeNormals ? mesh.faceNormals[fi] : null;
       const corners = [];
-      for (let k = f.length - 1; k >= 0; k--) {
+      const order = mirrored ? f.map((_, k) => k) : f.map((_, k) => f.length - 1 - k);
+      for (const k of order) {
         const v = vBase + f[k] + 1;
         const t = ts ? tBase + ts[k] + 1 : "";
         const n = ns ? nBase + ns[k] + 1 : "";