trid3d 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/public/logo.svg" width="96" alt="Trid logo">
+  <img src="https://raw.githubusercontent.com/ZachR622/Trid/master/docs/public/logo.svg" width="96" alt="Trid logo">
 </p>
 
 <h1 align="center">Trid</h1>
@@ -10,17 +10,18 @@
 
 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.
+- **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.
 - **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.
 - **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.
 - **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.
@@ -81,23 +82,29 @@ 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 |
 
 ## Documentation
 
-The docs explain every class, option and function, with live demos. To run them locally (Node 18+):
+**[zachr622.github.io/Trid](https://zachr622.github.io/Trid/)**: every class, option and function, with live demos.
+
+To run the docs locally (Node 18+):
 
 ```sh
 npm install
 npm run docs:dev
 ```
 
-See [`docs/README.md`](docs/README.md) for building and editing the docs.
+See [`docs/README.md`](https://github.com/ZachR622/Trid/blob/master/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
+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
-- **Tests** for the math functions
+- **More tools** — a gizmo to move, rotate and scale objects with the mouse, a selection outline, a grid/axes 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.0",
+  "version": "0.2.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",
@@ -17,15 +17,19 @@
     "type": "git",
     "url": "git+https://github.com/ZachR622/Trid.git"
   },
-  "homepage": "https://github.com/ZachR622/Trid#readme",
+  "homepage": "https://zachr622.github.io/Trid/",
   "bugs": {
     "url": "https://github.com/ZachR622/Trid/issues"
   },
   "type": "module",
   "main": "./trid/index.js",
   "module": "./trid/index.js",
+  "types": "./trid/index.d.ts",
   "exports": {
-    ".": "./trid/index.js",
+    ".": {
+      "types": "./trid/index.d.ts",
+      "default": "./trid/index.js"
+    },
     "./*": "./trid/*"
   },
   "files": [
@@ -33,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/obj.js

@@ -0,0 +1,141 @@
+/**
+ * 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 { localToWorld, rotateXYZ } from "../math/transform.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
+ */
+
+/**
+ * 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 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" } = {}) {
+  const items = Array.isArray(input) ? input : Array.isArray(input?.objects) ? input.objects : [input];
+  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));
+  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;
+    if (!mesh?.vertices) throw new Error("exportOBJ: expected a mesh, a scene object, a list of them or a Scene");
+    const faces = mesh.faces ?? [];
+    const placed = isObject && item.pos && item.rot && item.scale;
+
+    if (items.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;
+      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) {
+      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 };
+        }
+        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
+    const named = !!(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}`;
+        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 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";
+}