trid3d 0.1.1 → 0.3.0

package/README.md

@@ -10,19 +10,22 @@
 
 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.
+> **Status:** early. Objects can be wireframes or filled, shaded and textured, with shader effects.
 
 ## 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.
+- **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.
+- **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.
+- **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.
+- **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, so you can use the pipeline piece by piece.
 
 ## Install
@@ -81,6 +84,7 @@ Or let users load their own: `scene.use(new ObjUploader())` accepts dropped `.ob
 | `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 |
 | `docs/` | Documentation site with live demos |
 
@@ -99,7 +103,9 @@ See [`docs/README.md`](https://github.com/ZachR622/Trid/blob/master/docs/README.
 
 ## 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
+Roughly in order:
+
+- **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trid3d",
-  "version": "0.1.1",
+  "version": "0.3.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",
@@ -37,6 +37,7 @@
   ],
   "sideEffects": false,
   "scripts": {
+    "test": "node --test \"test/*.test.js\"",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"

package/trid/export/capture.js

@@ -0,0 +1,150 @@
+/**
+ * Saving what a scene shows: still images, videos, and a helper that
+ * downloads anything as a file.
+ */
+
+/**
+ * @typedef {Object} ScreenshotOptions
+ * @property {string} [type="image/png"] - "image/png", "image/jpeg" or "image/webp"
+ * @property {number} [quality=0.92] - For JPEG and WebP, from 0 to 1
+ * @property {number} [width] - Image width in pixels (default: the canvas's).
+ *   Line widths and tool overlays stay the same size in pixels.
+ * @property {number} [height] - Image height in pixels (default: the canvas's)
+ * @property {boolean} [tools=true] - Include what tools draw on top (FPS meter, labels…)
+ */
+
+/**
+ * Draws a new frame of the scene and returns it as an image file.
+ *
+ * The frame is drawn on a separate canvas, so the page doesn't change
+ * and it works whether or not the scene is running.
+ *
+ * @param {import("../scene.js").Scene} scene
+ * @param {ScreenshotOptions} [opts]
+ * @returns {Promise<Blob>}
+ */
+export function screenshot(scene, { type = "image/png", quality = 0.92, width, height, tools = true } = {}) {
+  const canvas = document.createElement("canvas");
+  canvas.width = Math.max(1, Math.round(width ?? scene.canvas.width));
+  canvas.height = Math.max(1, Math.round(height ?? scene.canvas.height));
+
+  // Draw the scene on the new canvas, then put the real one back
+  const saved = { canvas: scene.canvas, ctx: scene.ctx };
+  scene.canvas = canvas;
+  scene.ctx = canvas.getContext("2d");
+  try {
+    scene.renderer.render(scene);
+    if (tools) scene.tools.draw(scene.ctx);
+  } finally {
+    scene.canvas = saved.canvas;
+    scene.ctx = saved.ctx;
+  }
+
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(
+      (blob) => (blob ? resolve(blob) : reject(new Error("Trid: the browser couldn't make the image"))),
+      type,
+      quality,
+    );
+  });
+}
+
+/** Video formats to try, best first. Browsers each support a few of them. */
+const VIDEO_TYPES = [
+  "video/webm;codecs=vp9",
+  "video/webm;codecs=vp8",
+  "video/webm",
+  "video/mp4;codecs=avc1",
+  "video/mp4",
+];
+
+/**
+ * @typedef {Object} RecordOptions
+ * @property {number} [fps=60] - Frames per second of the video
+ * @property {string} [type] - Video format, like "video/webm" (default: the best one the browser has)
+ * @property {number} [bitsPerSecond=8000000] - Quality: higher is sharper and bigger
+ * @property {number} [duration] - Stop by itself after this many seconds
+ *
+ * @typedef {Object} Recording
+ * @property {string} type - The video format being recorded
+ * @property {() => Promise<Blob>} stop - Stops recording; resolves with the video
+ * @property {Promise<Blob>} done - Resolves with the video once recording stops
+ * @property {boolean} recording - Whether it's still recording
+ */
+
+/**
+ * Records the scene's canvas as a video, everything it shows, tools included.
+ * The scene has to be running (`scene.start`) for frames to be recorded.
+ *
+ * @param {import("../scene.js").Scene} scene
+ * @param {RecordOptions} [opts]
+ * @returns {Recording}
+ * @throws {Error} If the browser can't record a canvas
+ *
+ * @example
+ * const rec = scene.record({ duration: 3 });
+ * download(await rec.done, "clip.webm");
+ */
+export function record(scene, { fps = 60, type, bitsPerSecond = 8_000_000, duration } = {}) {
+  if (typeof MediaRecorder === "undefined" || !scene.canvas.captureStream) {
+    throw new Error("Trid: this browser can't record a canvas (no MediaRecorder or captureStream)");
+  }
+  const mimeType = type ?? VIDEO_TYPES.find((t) => MediaRecorder.isTypeSupported(t));
+  if (!mimeType) throw new Error("Trid: this browser can't record any video format Trid knows");
+
+  const stream = scene.canvas.captureStream(fps);
+  const recorder = new MediaRecorder(stream, { mimeType, videoBitsPerSecond: bitsPerSecond });
+  const chunks = [];
+  recorder.ondataavailable = (e) => e.data.size && chunks.push(e.data);
+
+  let timer = null;
+  const done = new Promise((resolve, reject) => {
+    recorder.onstop = () => {
+      clearTimeout(timer);
+      for (const track of stream.getTracks()) track.stop();
+      resolve(new Blob(chunks, { type: mimeType.split(";")[0] }));
+    };
+    recorder.onerror = (e) => reject(e.error ?? new Error("Trid: recording failed"));
+  });
+
+  recorder.start(250); // hand over data every 250 ms, so a long video isn't one huge piece at the end
+  if (duration != null) timer = setTimeout(() => recorder.state !== "inactive" && recorder.stop(), duration * 1000);
+
+  return {
+    type: mimeType,
+    done,
+    get recording() {
+      return recorder.state !== "inactive";
+    },
+    stop() {
+      if (recorder.state !== "inactive") recorder.stop();
+      return done;
+    },
+  };
+}
+
+/**
+ * Saves something as a file in the browser's downloads.
+ *
+ * @param {Blob|string|Promise<Blob|string>} data - A file (like a screenshot or video),
+ *   or text (like an OBJ file)
+ * @param {string} filename - Name of the saved file, like "scene.png"
+ * @returns {Promise<void>}
+ *
+ * @example
+ * download(scene.screenshot(), "scene.png");
+ * download(exportOBJ(mesh), "model.obj");
+ */
+export async function download(data, filename) {
+  const value = await data;
+  const blob = value instanceof Blob ? value : new Blob([value], { type: "text/plain" });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.style.display = "none";
+  document.body.append(a);
+  a.click();
+  a.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 1000); // after the browser has started the download
+}

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

@@ -0,0 +1,227 @@
+/**
+ * Wavefront OBJ export: the reverse of `parseOBJ`.
+ *
+ * Writes vertex positions (`v`), texture coordinates (`vt`), normals
+ * (`vn`), faces (`f`), lines (`l`) for edges that aren't part of a face,
+ * material names (`usemtl`) and one object (`o`) per scene object.
+ *
+ * Z is flipped back and faces turned back to counter-clockwise, so
+ * `parseOBJ(exportOBJ(mesh))` gives the same mesh, and the file opens
+ * the right way round in Blender and other 3D programs.
+ */
+
+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";
+
+/**
+ * @typedef {Object} ExportOBJOptions
+ * @property {boolean} [uvs=true] - Write texture coordinates. For an object whose
+ *   material has a `mapping`, `textureRepeat`, `textureOffset` or `textureRotation`,
+ *   the coordinates the renderer uses are written, so the texture lands the same way.
+ * @property {boolean} [normals=true] - Write the mesh's normals (`mesh.normals`), when it has them
+ * @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.
+ *
+ * `input` can be:
+ * - 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
+ *
+ * @param {Object|Object[]} input
+ * @param {ExportOBJOptions} [opts]
+ * @returns {string} The file's text
+ *
+ * @example
+ * download(exportOBJ(scene), "scene.obj");
+ */
+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
+  };
+
+  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
+
+  // 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 ?? [];
+    // A mirrored object's faces are already turned around once
+    const mirrored = world ? determinantMat4(world) < 0 : false;
+
+    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 = world ? transformPoint(world, v) : v;
+      out.push(`v ${num(p.x)} ${num(p.y)} ${num(-p.z)}`);
+    }
+
+    // Texture coordinates: the ones the first material draws with
+    const mat = isObject ? materialsOf(item)?.[0] : null;
+    const source = uvs ? uvsFor(mesh, mat?.mapping) : {};
+    const xf = mat ? uvTransform(mat) : null;
+    const faceUVs = source.faceUVs, meshUVs = source.uvs;
+    const writeUVs = !!(faceUVs && meshUVs && faceUVs.some(Boolean));
+    if (writeUVs) {
+      for (const t of meshUVs) {
+        const q = applyUVTransform(xf, t);
+        out.push(`vt ${num(q.u)} ${num(q.v)}`);
+      }
+    }
+
+    // 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) {
+        const r = nm ? transformNormal(nm, n) : n;
+        out.push(`vn ${num(r.x)} ${num(r.y)} ${num(-r.z)}`);
+      }
+    }
+
+    // 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.
+    // 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 = 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 = [];
+      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 : "";
+        corners.push(n !== "" ? `${v}/${t}/${n}` : t !== "" ? `${v}/${t}` : `${v}`);
+      }
+      out.push("f " + corners.join(" "));
+    });
+
+    // Edges that aren't the side of any face (wireframe-only meshes, or extra lines)
+    if (lines && mesh.edges) {
+      const onFace = new Set();
+      const key = (a, b) => (a < b ? a * 4294967296 + b : b * 4294967296 + a);
+      for (const f of faces) for (let k = 0; k < f.length; k++) onFace.add(key(f[k], f[(k + 1) % f.length]));
+      for (const [a, b] of edgeSegments(mesh.edges)) {
+        if (!onFace.has(key(a, b))) out.push(`l ${vBase + a + 1} ${vBase + b + 1}`);
+      }
+    }
+
+    vBase += mesh.vertices.length;
+    if (writeUVs) tBase += meshUVs.length;
+    if (writeNormals) nBase += mesh.normals.length;
+  });
+
+  return out.join("\n") + "\n";
+}