trid3d 0.1.0 → 0.2.0

package/trid/index.js

@@ -13,10 +13,10 @@
 export { Scene } from "./scene.js";
 
 // Shapes and meshes
-export { makeShape, scaleMesh } from "./render/shapes.js";
+export { makeShape, scaleMesh, lathe, extrude, triangulate } from "./render/shapes.js";
 
 // Renderers
-export { CanvasRenderer, DEFAULT_LIGHT, DEFAULT_AMBIENT } from "./render/canvasRenderer.js";
+export { CanvasRenderer, DEFAULT_LIGHT, DEFAULT_AMBIENT, materialsOf } from "./render/canvasRenderer.js";
 export { WebGLRenderer, DEFAULT_FAR } from "./render/webglRenderer.js";
 
 // Effects
@@ -25,6 +25,9 @@ export {
   buildEffects, effectsKey, uniformType, SURFACE_GLSL,
 } from "./render/effects.js";
 
+// Texture mapping
+export { computeUVs, mapUVs, uvsFor, uvTransform, applyUVTransform, mappingOf, mappingKey, MAPPINGS } from "./render/uvMapping.js";
+
 // Normals (smooth shading)
 export { cornerNormals, creaseOf, newell, DEFAULT_CREASE } from "./render/normals.js";
 
@@ -32,6 +35,10 @@ export { cornerNormals, creaseOf, newell, DEFAULT_CREASE } from "./render/normal
 export { parseOBJ, loadOBJ, readOBJFile, pickOBJFile, fitMesh } from "./loaders/obj.js";
 export { loadTexture, textureReady, textureSize, textureIsLive } from "./loaders/texture.js";
 
+// Exporting
+export { exportOBJ } from "./export/obj.js";
+export { screenshot, record, download } from "./export/capture.js";
+
 // Tools
 export {
   OrbitCamera, FlyCamera, DragObject, HoverHighlight, FpsMeter, ObjUploader,
@@ -39,7 +46,7 @@ export {
 } from "./tools/index.js";
 
 // Drawing and the frame loop
-export { clear, point, line, drawWireframe, drawInstance, edgeSegments } from "./render/draw.js";
+export { clear, point, line, drawWireframe, drawInstance, edgeSegments, wireEdges } from "./render/draw.js";
 export { loop } from "./render/loop.js";
 export { parseColor } from "./render/color.js";
 

package/trid/loaders/obj.js

@@ -2,8 +2,8 @@
  * 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.
+ * (`vn`), faces (`f`), polylines (`l`) and material names (`usemtl`).
+ * Everything else (.mtl files, 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
@@ -21,6 +21,9 @@
  * @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.
+ * @property {string[]} [materialNames] - Material names from `usemtl` lines, in the order they first appear
+ * @property {number[]} [faceMaterials] - For each face, its index in `materialNames`. Give the
+ *   object a list of materials in the same order to color or texture each part.
  *
  * @typedef {Object} ObjOptions
  * @property {number} [fit] - If set, center the model on the origin and scale it
@@ -43,6 +46,9 @@ export function parseOBJ(text, { fit } = {}) {
   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 materialNames = [];
+  const faceMaterials = []; // per face: index in materialNames
+  let material = 0;
 
   const src = text.split(/\r?\n/);
 
@@ -60,6 +66,10 @@ export function parseOBJ(text, { fit } = {}) {
       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 === "usemtl") {
+      const name = parts.slice(1).join(" ");
+      material = materialNames.indexOf(name);
+      if (material < 0) material = materialNames.push(name) - 1;
     } 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) => {
@@ -72,6 +82,7 @@ export function parseOBJ(text, { fit } = {}) {
       });
       if (kind === "f" && ids.length >= 3) {
         faces.push(ids.reverse()); // flipping Z flips the winding
+        faceMaterials.push(material);
         // "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];
@@ -127,6 +138,11 @@ export function parseOBJ(text, { fit } = {}) {
     mesh.uvs = uvs;
     mesh.faceUVs = faceUVs;
   }
+  // Parts using different materials
+  if (materialNames.length > 1) {
+    mesh.materialNames = materialNames;
+    mesh.faceMaterials = faceMaterials;
+  }
   if (fit != null) fitMesh(mesh, fit);
   return mesh;
 }

package/trid/render/canvasRenderer.js

@@ -1,11 +1,26 @@
 import { localToWorld, worldToCamera, cameraToScreen, clipNear, rotateXYZ, DEFAULT_NEAR } from "../math/transform.js";
-import { clear, drawInstance, edgeSegments } from "./draw.js";
+import { clear, drawInstance, edgeSegments, wireEdges } from "./draw.js";
 import { parseColor } from "./color.js";
 import { newell, cornerNormals, creaseOf } from "./normals.js";
 import { textureReady, textureSize, textureIsLive } from "../loaders/texture.js";
+import { uvsFor, uvTransform, applyUVTransform } from "./uvMapping.js";
 
 export { newell };
 
+/**
+ * An object's materials as a list (`material` can be one material or a
+ * list of them, picked per face by `mesh.faceMaterials`). Null when the
+ * object is a wireframe.
+ *
+ * @returns {Material[]|null}
+ */
+export function materialsOf(obj) {
+  const m = obj.material;
+  if (!m) return null;
+  if (!Array.isArray(m)) return [m];
+  return m.length && m[0] ? m : null;
+}
+
 /** Direction light comes from when the scene doesn't set one: above, left, in front. */
 export const DEFAULT_LIGHT = { x: -0.5, y: 1, z: -0.8 };
 
@@ -16,6 +31,10 @@ export const DEFAULT_AMBIENT = 0.25;
  * Material: how an object's faces look. Objects without one are drawn
  * as wireframes using their `color` and `lineWidth`.
  *
+ * An object's `material` can also be a list: each face then uses the
+ * entry `mesh.faceMaterials[face]` points at (the first one by default).
+ * Built-in cubes and boxes number their sides 0 to 5.
+ *
  * @typedef {Object} Material
  * @property {string} [fill] - Face color, any CSS color (default: the scene's color)
  * @property {boolean} [shade=true] - Darken faces that turn away from the light
@@ -26,6 +45,11 @@ export const DEFAULT_AMBIENT = 0.25;
  * @property {CanvasImageSource} [texture] - Image drawn on the faces (needs texture coordinates:
  *   built-in shapes and OBJ files with `vt` have them). `fill` tints it (default white).
  * @property {boolean} [pixelated=false] - Keep texture pixels sharp instead of smoothing them
+ * @property {import("./uvMapping.js").Mapping} [mapping="uv"] - Where texture coordinates come
+ *   from: the mesh's own ("uv"), or made from its shape ("planar", "box", "sphere", "cylinder")
+ * @property {number|{u:number,v:number}} [textureRepeat=1] - How many times the image repeats across
+ * @property {{u:number,v:number}} [textureOffset] - Moves the image (1 = its whole width or height)
+ * @property {number} [textureRotation=0] - Turns the image around its center, in radians
  * @property {Object[]} [effects] - Effects applied in order, like `[toon(), rim()]`.
  *   See trid/render/effects.js. The canvas renderer runs them once per face.
  */
@@ -79,7 +103,7 @@ export class CanvasRenderer {
     this._frame++;
 
     // Wireframes only: nothing to sort
-    if (!scene.objects.some((o) => o.material)) {
+    if (!scene.objects.some((o) => materialsOf(o))) {
       for (const obj of scene.objects) {
         drawInstance(ctx, obj, camera, w, h, obj.color ?? scene.color, obj.lineWidth ?? scene.lineWidth);
       }
@@ -97,17 +121,17 @@ export class CanvasRenderer {
     const background = this._rgba(ctx, scene.background);
 
     for (const obj of scene.objects) {
+      const mats = materialsOf(obj);
       // Split big faces (cached per mesh); extra vertices are midpoints of existing ones
-      const split = obj.material && this.maxFaceSize ? this._split(obj.mesh) : null;
+      const split = mats && this.maxFaceSize ? this._split(obj.mesh) : null;
       const verts = split ? withMidpoints(obj.mesh.vertices, split.mids) : obj.mesh.vertices;
       const world = verts.map((v) => localToWorld(v, obj));
       const cam = world.map((p) => worldToCamera(p, camera));
       const color = obj.color ?? scene.color;
       const lineWidth = obj.lineWidth ?? scene.lineWidth;
-      const mat = obj.material;
 
-      if (!mat) {
-        for (const [i, j] of edgeSegments(obj.mesh.edges)) {
+      if (!mats) {
+        for (const [i, j] of edgeSegments(wireEdges(obj.mesh))) {
           const seg = clipNear(cam[i], cam[j], near);
           if (!seg) continue;
           items.push({
@@ -119,19 +143,14 @@ export class CanvasRenderer {
         continue;
       }
 
-      const fill = mat.fill ?? (mat.texture ? "#ffffff" : scene.color);
-      const shade = mat.shade !== false;
-      const outline = mat.wireframe ? color : null;
-
-      // Smooth shading: a normal per face corner (split faces get midpoints' normals by averaging)
-      const crease = shade ? creaseOf(mat.smooth) : null;
-      const corners = crease ? cornerNormals(obj.mesh, crease) : null;
       const sourceFaces = obj.mesh.faces ?? [];
       const base = obj.mesh.vertices.length;
-      const normalAt = (F, i) => {
+
+      // Smooth shading: a normal per face corner (split faces get midpoints' normals by averaging)
+      const normalAt = (corners, F, i) => {
         if (i < base) return corners[F][sourceFaces[F].indexOf(i)];
         const [a, b] = split.mids[i - base];
-        const na = normalAt(F, a), nb = normalAt(F, b);
+        const na = normalAt(corners, F, a), nb = normalAt(corners, F, b);
         return normalize({ x: na.x + nb.x, y: na.y + nb.y, z: na.z + nb.z });
       };
       const lightAt = (n, back) => {
@@ -140,47 +159,69 @@ export class CanvasRenderer {
         const d = (back ? -1 : 1) * (r.x * light.x + r.y * light.y + r.z * light.z);
         return ambient + (1 - ambient) * Math.max(0, d);
       };
-
-      // Textures: each triangle is filled with the image, mapped by its corners' texture coordinates
-      const meshUVs = obj.mesh.uvs, faceUVs = obj.mesh.faceUVs;
-      let tex = null;
-      if (mat.texture && textureReady(mat.texture)) {
-        if (faceUVs && meshUVs) tex = mat.texture;
-        else if (!this._warned.has(obj.mesh)) {
-          this._warned.add(obj.mesh);
-          console.warn("Trid: this mesh has no texture coordinates (uvs / faceUVs), so its texture isn't drawn");
-        }
-      }
-      const uvAt = (F, i) => {
-        const t = faceUVs?.[F];
-        if (!t || !meshUVs) return null;
-        if (i < base) return meshUVs[t[sourceFaces[F].indexOf(i)]];
-        const [a, b] = split.mids[i - base];
-        const ta = uvAt(F, a), tb = uvAt(F, b);
-        return ta && tb ? { u: (ta.u + tb.u) / 2, v: (ta.v + tb.v) / 2 } : null;
-      };
       const flatLight = (face, back) => {
         const nw = normalize(newell(face.map((i) => world[i])));
         const d = (back ? -1 : 1) * (nw.x * light.x + nw.y * light.y + nw.z * light.z);
         return ambient + (1 - ambient) * Math.max(0, d);
       };
-
-      // Effects run once per face, at its center (see trid/render/effects.js)
-      const effects = mat.effects?.length ? mat.effects : null;
       const toWorldNormal = (n) =>
         normalize(rotateXYZ({ x: n.x / obj.scale.x, y: n.y / obj.scale.y, z: n.z / obj.scale.z }, obj.rot));
 
+      // Everything a material needs, worked out once per object and frame
+      const prepare = (mat) => {
+        const shade = mat.shade !== false;
+        const crease = shade ? creaseOf(mat.smooth) : null;
+        // Texture coordinates: the mesh's own, or made from its shape (mat.mapping)
+        const { uvs: meshUVs, faceUVs } = uvsFor(obj.mesh, mat.mapping);
+        const xf = uvTransform(mat);
+        const rawUV = (F, i) => {
+          const t = faceUVs?.[F];
+          if (!t || !meshUVs) return null;
+          if (i < base) return meshUVs[t[sourceFaces[F].indexOf(i)]];
+          const [a, b] = split.mids[i - base];
+          const ta = rawUV(F, a), tb = rawUV(F, b);
+          return ta && tb ? { u: (ta.u + tb.u) / 2, v: (ta.v + tb.v) / 2 } : null;
+        };
+        let tex = null;
+        if (mat.texture && textureReady(mat.texture)) {
+          if (faceUVs && meshUVs) tex = mat.texture;
+          else if (!this._warned.has(obj.mesh)) {
+            this._warned.add(obj.mesh);
+            console.warn("Trid: this mesh has no texture coordinates (uvs / faceUVs), so its texture isn't drawn. Set material.mapping to make some.");
+          }
+        }
+        return {
+          mat, shade, tex,
+          fill: mat.fill ?? (mat.texture ? "#ffffff" : scene.color),
+          outline: mat.wireframe ? color : null,
+          corners: crease ? cornerNormals(obj.mesh, crease) : null,
+          effects: mat.effects?.length ? mat.effects : null,
+          uvAt: (F, i) => applyUVTransform(xf, rawUV(F, i)),
+        };
+      };
+      // Which material each face uses (mesh.faceMaterials), prepared when first needed
+      const looks = new Array(mats.length);
+      const faceMats = obj.mesh.faceMaterials;
+      const lookOf = (F) => {
+        let k = faceMats?.[F] ?? 0;
+        if (!(k >= 0 && k < mats.length && mats[k])) k = 0;
+        return (looks[k] ??= prepare(mats[k]));
+      };
+
       const faces = split ? split.faces : sourceFaces;
       for (let f = 0; f < faces.length; f++) {
         const face = faces[f];
         if (face.length < 3) continue;
+        const F = split ? split.origins[f] : f; // the mesh face this one comes from
+        const L = lookOf(F);
+        const { fill, shade, outline, corners } = L;
         const pts = face.map((i) => cam[i]);
 
         // Seen from behind? (camera sits at the origin of camera space)
         const n = newell(pts);
         const c = centroid(pts);
         const back = n.x * c.x + n.y * c.y + n.z * c.z >= 0;
-        if (back && !mat.doubleSided) continue;
+        if (back && !L.mat.doubleSided) continue;
 
         const clipped = clipPolygon(pts, near);
         if (clipped.length < 3) continue;
@@ -188,13 +229,13 @@ export class CanvasRenderer {
         // Which edges are real outlines (split faces have extra inner edges); null = all
         const edges = split && clipped === pts ? split.masks[f] : null;
 
-        if (tex && clipped === pts) {
-          const F = split ? split.origins[f] : f;
-          const ts = face.map((i) => uvAt(F, i));
+        // Textures: each triangle is filled with the image, mapped by its corners' texture coordinates
+        if (L.tex && clipped === pts) {
+          const ts = face.map((i) => L.uvAt(F, i));
           if (ts.every(Boolean)) {
             let lit;
             if (!shade) lit = face.map(() => 1);
-            else if (corners) lit = face.map((i) => lightAt(normalAt(F, i), back));
+            else if (corners) lit = face.map((i) => lightAt(normalAt(corners, F, i), back));
             else lit = face.map(() => flatLight(face, back));
             const screen = pts.map(toScreen);
             const n = face.length;
@@ -203,7 +244,7 @@ export class CanvasRenderer {
               items.push({
                 depth: c.z,
                 poly: [screen[0], screen[k], screen[k + 1]],
-                texture: { src: tex, uvs: [ts[0], ts[k], ts[k + 1]], pixelated: !!mat.pixelated, tint: fill },
+                texture: { src: L.tex, uvs: [ts[0], ts[k], ts[k + 1]], pixelated: !!L.mat.pixelated, tint: fill },
                 lit: [lit[0], lit[k], lit[k + 1]],
                 outline, lineWidth,
                 edges: n === 3 ? edges : fan,
@@ -213,12 +254,12 @@ export class CanvasRenderer {
           }
         }
 
-        if (effects) {
+        // Effects run once per face, at its center (see trid/render/effects.js)
+        if (L.effects) {
           // Normal: the face's own, or the average of its corners when smooth
           let nw;
           if (corners) {
-            const F = split ? split.origins[f] : f;
-            const sum = face.map((i) => toWorldNormal(normalAt(F, i)))
+            const sum = face.map((i) => toWorldNormal(normalAt(corners, F, i)))
               .reduce((a, b) => ({ x: a.x + b.x, y: a.y + b.y, z: a.z + b.z }), { x: 0, y: 0, z: 0 });
             nw = normalize(sum);
           } else {
@@ -230,16 +271,16 @@ export class CanvasRenderer {
           const toCam = { x: camPos.x - position.x, y: camPos.y - position.y, z: camPos.z - position.z };
           const diffuse = Math.max(0, nw.x * light.x + nw.y * light.y + nw.z * light.z);
           const lit = shade ? ambient + (1 - ambient) * diffuse : 1;
-          const base = this._rgba(ctx, fill);
+          const rgba = this._rgba(ctx, fill);
           const s = {
-            base, normal: nw, position, local: centroid(face.map((i) => verts[i])),
+            base: rgba, normal: nw, position, local: centroid(face.map((i) => verts[i])),
             view: normalize(toCam), lightDir: light, diffuse, light: lit, ambient,
-            uv: centerUV(face.map((i) => uvAt(split ? split.origins[f] : f, i))),
+            uv: centerUV(face.map((i) => L.uvAt(F, i))),
             depth: Math.hypot(toCam.x, toCam.y, toCam.z), time, background,
             rgba: (v) => (typeof v === "string" ? this._rgba(ctx, v) : Array.isArray(v) ? v : [v.x, v.y, v.z, 1]),
           };
-          let col = [base[0] * lit, base[1] * lit, base[2] * lit, base[3]];
-          for (const e of effects) if (e.canvas) col = e.canvas(col, s, e.uniforms ?? {});
+          let col = [rgba[0] * lit, rgba[1] * lit, rgba[2] * lit, rgba[3]];
+          for (const e of L.effects) if (e.canvas) col = e.canvas(col, s, e.uniforms ?? {});
           const k = col.map((x) => Math.min(1, Math.max(0, x)));
           items.push({
             depth: c.z,
@@ -251,8 +292,7 @@ export class CanvasRenderer {
         }
 
         if (corners) {
-          const F = split ? split.origins[f] : f;
-          const lit = face.map((i) => lightAt(normalAt(F, i), back));
+          const lit = face.map((i) => lightAt(normalAt(corners, F, i), back));
           if (clipped === pts) {
             // One gradient per triangle: brightness changes linearly across a triangle
             const screen = pts.map(toScreen);
@@ -276,14 +316,7 @@ export class CanvasRenderer {
           continue;
         }
 
-        let brightness = 1;
-        if (shade) {
-          const nw = normalize(newell(face.map((i) => world[i])));
-          const s = back ? -1 : 1;
-          const d = s * (nw.x * light.x + nw.y * light.y + nw.z * light.z);
-          brightness = ambient + (1 - ambient) * Math.max(0, d);
-        }
-
+        const brightness = shade ? flatLight(face, back) : 1;
         items.push({
           depth: c.z,
           poly: clipped.map(toScreen),

package/trid/render/draw.js

@@ -59,11 +59,11 @@ export function line(ctx, p1, p2, color, width = 4) {
  * - An edge with 3+ indices is a closed loop: the last index
  *   connects back to the first
  *
- * @param {number[][]} edges - Edge definitions using vertex indices
+ * @param {number[][]} [edges] - Edge definitions using vertex indices (none: no segments)
  * @returns {Generator<[number, number]>} Index pairs to connect
  */
 export function* edgeSegments(edges) {
-  for (const e of edges) {
+  for (const e of edges ?? []) {
     const closed = e.length > 2;
     const count = closed ? e.length : e.length - 1;
     for (let i = 0; i < count; i++) {
@@ -72,6 +72,17 @@ export function* edgeSegments(edges) {
   }
 }
 
+/**
+ * The lines to draw for a mesh shown as a wireframe: its `edges`, or the
+ * outline of each face when it has no `edges` (a face-only mesh).
+ *
+ * @param {{ edges?: number[][], faces?: number[][] }} mesh
+ * @returns {number[][]} Edge definitions (faces are closed loops)
+ */
+export function wireEdges(mesh) {
+  return mesh.edges ?? mesh.faces ?? [];
+}
+
 /**
  * Draws a wireframe object by connecting projected vertices
  * using index-based edge definitions.
@@ -115,7 +126,7 @@ export function drawWireframe(ctx, points2, edges, color, width = 4) {
  *
  * @param {CanvasRenderingContext2D} ctx - Canvas 2D context
  * @param {{
- *   mesh:{ vertices:{x:number,y:number,z:number}[], edges:number[][] },
+ *   mesh:{ vertices:{x:number,y:number,z:number}[], edges?:number[][], faces?:number[][] },
  *   pos:{x:number,y:number,z:number},
  *   rot:{x:number,y:number,z:number},
  *   scale:{x:number,y:number,z:number}
@@ -134,7 +145,7 @@ export function drawInstance(ctx, inst, camera, w, h, color, lineWidth = 3) {
   ctx.strokeStyle = color;
 
   ctx.beginPath();
-  for (const [i, j] of edgeSegments(inst.mesh.edges)) {
+  for (const [i, j] of edgeSegments(wireEdges(inst.mesh))) {
     const seg = clipNear(ptsCam[i], ptsCam[j], near);
     if (!seg) continue;
     const a = cameraToScreen(seg[0], camera, w, h);