trid3d 0.1.1 → 0.2.0

package/trid/index.d.ts

@@ -56,10 +56,11 @@ export interface Camera {
  *
  * An edge with 2 indices is a single segment; with 3 or more it's a closed loop.
  * Faces are clockwise as seen from their front.
+ * Without `edges`, an object with no material draws the outline of each face.
  */
 export interface Mesh {
   vertices: Vec3[];
-  edges: number[][];
+  edges?: number[][];
   faces?: number[][];
   /** Per-corner normals, used by smooth shading */
   normals?: Vec3[];
@@ -69,6 +70,11 @@ export interface Mesh {
   uvs?: UV[];
   /** For each face, the index into `uvs` of each corner (null: none for that face) */
   faceUVs?: (number[] | null)[];
+  /**
+   * For each face, which entry of the object's material list it uses
+   * (when `material` is a list). Built-in cubes and boxes number their sides 0 to 5.
+   */
+  faceMaterials?: number[];
   /** Set after changing the mesh in place so renderers rebuild their caches */
   dirty?: boolean;
 }
@@ -104,8 +110,25 @@ export interface Material {
   pixelated?: boolean;
   /** Effects applied in order, like `[toon(), rim()]` */
   effects?: Effect[];
+  /** Where texture coordinates come from: the mesh's own ("uv", default) or made from its shape */
+  mapping?: Mapping;
+  /** How many times the texture repeats across (default 1) */
+  textureRepeat?: number | UV;
+  /** Moves the texture; 1 is its whole width or height */
+  textureOffset?: UV;
+  /** Turns the texture around its center, in radians */
+  textureRotation?: number;
 }
 
+/** Ways to make texture coordinates from a mesh's shape. */
+export type MappingType = "uv" | "planar" | "box" | "sphere" | "cylinder";
+
+/**
+ * A texture mapping: a type, or a type with an axis. `axis` is the projection
+ * direction for "planar" (default "z") and the wrap axis for "sphere" and "cylinder" (default "y").
+ */
+export type Mapping = MappingType | { type: MappingType; axis?: "x" | "y" | "z" };
+
 /** What you pass to `scene.add`. Missing transform fields get defaults. */
 export interface SceneObjectInput {
   mesh: Mesh;
@@ -116,8 +139,8 @@ export interface SceneObjectInput {
   color?: string;
   /** Wireframe width (default: the scene's lineWidth) */
   lineWidth?: number;
-  /** Draw faces instead of only lines */
-  material?: Material;
+  /** Draw faces instead of only lines. A list gives each group of faces its own (see `Mesh.faceMaterials`) */
+  material?: Material | Material[];
   /** Set to false to make `DragObject` ignore this object */
   draggable?: boolean;
   /** Set to false to make `HoverHighlight` ignore this object */
@@ -191,6 +214,10 @@ export class Scene {
   start(update?: (dt: number, time: number, scene: Scene) => void): this;
   /** Stops the frame loop. The last frame stays on the canvas. */
   stop(): void;
+  /** Draws a new frame and returns it as an image file. The page's canvas doesn't change. */
+  screenshot(opts?: ScreenshotOptions): Promise<Blob>;
+  /** Starts recording the canvas as a video. */
+  record(opts?: RecordOptions): Recording;
   /** Stops the loop, removes every tool and frees the renderer's resources. */
   destroy(): void;
   /** Whether the frame loop is running. */
@@ -202,26 +229,79 @@ export class Scene {
 // ---------------------------------------------------------------------------
 
 export interface ShapeOptions {
-  /** Cube size (default 0.5) */
+  /** Cube size, or plane width (default 0.5 cube, 1 plane) */
   size?: number;
   /** Box width (default 0.6) */
   w?: number;
-  /** Box height (default 0.6) */
+  /** Box height (default 0.6), or cylinder / cone height (default 0.8) */
   h?: number;
   /** Box depth (default 0.6) */
   d?: number;
-  /** Sphere radius (default 0.45) */
+  /** Radius: sphere (0.45), cylinder (0.3), cone base (0.35) */
   r?: number;
   /** Sphere latitude bands (default 12) */
   rings?: number;
-  /** Sphere points per ring (default 24) */
+  /** Points around: sphere (24), cylinder / cone (32), torus (48) */
   segments?: number;
+  /** Cone top radius: 0 = pointed, > 0 = tapered cylinder (default 0) */
+  rTop?: number;
+  /** Torus: distance from the center to the middle of the tube (default 0.35) */
+  R?: number;
+  /** Torus tube radius (default 0.12) */
+  tube?: number;
+  /** Torus points around the tube (default 20) */
+  tubeSegments?: number;
+  /** Plane cells per side (default 8) */
+  div?: number;
+  /** Plane: lifts each vertex, for terrain */
+  height?: (x: number, z: number) => number;
+}
+
+export type ShapeKind = "cube" | "box" | "sphere" | "cylinder" | "cone" | "torus" | "plane";
+
+/**
+ * Creates a built-in mesh (with edges, faces and texture coordinates), centered
+ * on the origin. Cylinders, cones and tori stand along Y; the plane lies in XZ facing +Y.
+ */
+export function makeShape(kind: ShapeKind, opts?: ShapeOptions): Mesh;
+
+/** A point of a `lathe` profile: distance from the Y axis and height. */
+export interface ProfilePoint {
+  r: number;
+  y: number;
 }
 
-export type ShapeKind = "cube" | "box" | "sphere";
+export interface LatheOptions {
+  /** Points around the axis (default 32) */
+  segments?: number;
+  /** Close the bottom with a flat cap (default false) */
+  capBottom?: boolean;
+  /** Close the top with a flat cap (default false) */
+  capTop?: boolean;
+  /** The profile's last point joins its first, for torus-like shapes (default false) */
+  closed?: boolean;
+}
 
-/** Creates a built-in mesh (with faces and texture coordinates). */
-export function makeShape(kind: ShapeKind, opts?: ShapeOptions): Mesh;
+/**
+ * Spins a profile around the Y axis (vases, bottles, columns, chess pieces).
+ * Walk the profile so the outside is on its right: bottom to top for a vase.
+ */
+export function lathe(profile: ProfilePoint[], opts?: LatheOptions): Mesh;
+
+/** A 2D point (x right, y up). */
+export interface Point2 {
+  x: number;
+  y: number;
+}
+
+/**
+ * Turns a flat outline in the XY plane into a solid `depth` thick along Z
+ * (default 0.2), centered on the origin. Either direction, concave is fine, no holes.
+ */
+export function extrude(outline: Point2[], depth?: number): Mesh;
+
+/** Cuts a counter-clockwise polygon into counter-clockwise triangles (ear clipping). */
+export function triangulate(pts: Point2[]): number[][];
 
 /** Scales a mesh's vertices in place. Returns the same mesh. */
 export function scaleMesh<M extends { vertices: Vec3[] }>(mesh: M, sx?: number, sy?: number, sz?: number): M;
@@ -237,6 +317,9 @@ export const DEFAULT_AMBIENT: number;
 /** Default far distance (WebGL renderer). */
 export const DEFAULT_FAR: number;
 
+/** An object's materials as a list, or null when it's a wireframe. */
+export function materialsOf(obj: { material?: Material | Material[] }): Material[] | null;
+
 export interface CanvasRendererOptions {
   /**
    * Split faces bigger than this fraction of their mesh's size (like 0.05)
@@ -394,6 +477,41 @@ export function uniformType(value: unknown): "float" | "vec2" | "vec3" | "vec4"
 /** The GLSL declaration of `Surface`, shared by every effect. */
 export const SURFACE_GLSL: string;
 
+// ---------------------------------------------------------------------------
+// Texture mapping
+// ---------------------------------------------------------------------------
+
+/** Texture coordinates for every face corner. */
+export interface MeshUVs {
+  uvs: UV[];
+  faceUVs: number[][];
+}
+
+/** The mapping types. */
+export const MAPPINGS: readonly MappingType[];
+
+/** Texture coordinates made from a mesh's shape. The mesh isn't changed. */
+export function computeUVs(mesh: Mesh, mapping: Mapping): MeshUVs;
+
+/** Replaces a mesh's texture coordinates with ones made from its shape, in place. */
+export function mapUVs<M extends Mesh>(mesh: M, mapping: Mapping): M & MeshUVs;
+
+/** The texture coordinates a renderer uses for a mesh and mapping (cached). */
+export function uvsFor(mesh: Mesh, mapping?: Mapping): { uvs?: UV[]; faceUVs?: (number[] | null)[] };
+
+/** A material's repeat, offset and rotation as [a, b, c, d, e, f], or null when they change nothing. */
+export function uvTransform(material: Material): [number, number, number, number, number, number] | null;
+
+/** Applies a `uvTransform` matrix to one texture coordinate. */
+export function applyUVTransform(m: number[] | null, uv: UV): UV;
+export function applyUVTransform(m: number[] | null, uv: UV | null): UV | null;
+
+/** A mapping as `{ type, axis }`. Throws for an unknown type or axis. */
+export function mappingOf(mapping?: Mapping): { type: MappingType; axis?: "x" | "y" | "z" };
+
+/** A short string naming a mapping, for caches ("" for "uv"). */
+export function mappingKey(mapping?: Mapping): string;
+
 // ---------------------------------------------------------------------------
 // Normals
 // ---------------------------------------------------------------------------
@@ -417,6 +535,8 @@ export function newell(pts: Vec3[]): Vec3;
 /** A mesh loaded from an OBJ file. Always has faces. */
 export interface ObjMesh extends Mesh {
   faces: number[][];
+  /** Material names from `usemtl` lines, when the file uses more than one */
+  materialNames?: string[];
 }
 
 export interface ObjOptions {
@@ -444,6 +564,80 @@ export function textureSize(src: TextureSource): { w: number; h: number };
 /** Whether a source can change over time (canvas, video). */
 export function textureIsLive(src: TextureSource): boolean;
 
+// ---------------------------------------------------------------------------
+// Exporting
+// ---------------------------------------------------------------------------
+
+export interface ExportOBJOptions {
+  /**
+   * Write texture coordinates (default true). For an object whose material has a
+   * `mapping` or texture repeat/offset/rotation, the coordinates it's drawn with are written.
+   */
+  uvs?: boolean;
+  /** Write the mesh's normals when it has them (default true) */
+  normals?: boolean;
+  /** Write edges that aren't the side of a face as lines (default true) */
+  lines?: boolean;
+  /** Decimals kept in numbers (default 6) */
+  precision?: number;
+  /** Comment at the top of the file; "" for none (default "Exported by Trid") */
+  header?: string;
+}
+
+/** Something exportOBJ can write: a mesh, or an object placed in a scene. */
+export type OBJExportable = Mesh | (SceneObjectInput & Partial<Transform> & { name?: string });
+
+/**
+ * Writes meshes as the text of an OBJ file. Objects are written where they are
+ * in the scene; a list or a Scene gives one `o` per object.
+ */
+export function exportOBJ(input: OBJExportable | OBJExportable[] | Scene, opts?: ExportOBJOptions): string;
+
+export interface ScreenshotOptions {
+  /** "image/png" (default), "image/jpeg" or "image/webp" */
+  type?: string;
+  /** For JPEG and WebP, from 0 to 1 (default 0.92) */
+  quality?: number;
+  /** Image width in pixels (default: the canvas's) */
+  width?: number;
+  /** Image height in pixels (default: the canvas's) */
+  height?: number;
+  /** Include what tools draw on top (default true) */
+  tools?: boolean;
+}
+
+export interface RecordOptions {
+  /** Frames per second (default 60) */
+  fps?: number;
+  /** Video format, like "video/webm" (default: the best one the browser has) */
+  type?: string;
+  /** Quality: higher is sharper and bigger (default 8,000,000) */
+  bitsPerSecond?: number;
+  /** Stop by itself after this many seconds */
+  duration?: number;
+}
+
+/** A video being recorded. */
+export interface Recording {
+  /** The video format being recorded */
+  readonly type: string;
+  /** Whether it's still recording */
+  readonly recording: boolean;
+  /** Resolves with the video once recording stops */
+  readonly done: Promise<Blob>;
+  /** Stops recording; resolves with the video */
+  stop(): Promise<Blob>;
+}
+
+/** Draws a new frame of a scene and returns it as an image file. */
+export function screenshot(scene: Scene, opts?: ScreenshotOptions): Promise<Blob>;
+
+/** Records a scene's canvas as a video. Throws if the browser can't. */
+export function record(scene: Scene, opts?: RecordOptions): Recording;
+
+/** Saves a file or text in the browser's downloads. */
+export function download(data: Blob | string | Promise<Blob | string>, filename: string): Promise<void>;
+
 // ---------------------------------------------------------------------------
 // Tools
 // ---------------------------------------------------------------------------
@@ -529,6 +723,12 @@ export interface OrbitCameraOptions {
   pan?: boolean;
   /** Allow zooming (default true) */
   zoom?: boolean;
+  /** Turn around the target on its own, paused while dragging (default false) */
+  autoRotate?: boolean;
+  /** Auto-rotate speed in radians per second; negative turns the other way (default 0.5) */
+  autoRotateSpeed?: number;
+  /** Seconds to wait after a drag before auto-rotating again (default 0) */
+  autoRotateDelay?: number;
 }
 
 /** Mouse camera controls that turn around a target point. */
@@ -548,6 +748,9 @@ export class OrbitCamera implements Tool {
   rotate: boolean;
   pan: boolean;
   zoom: boolean;
+  autoRotate: boolean;
+  autoRotateSpeed: number;
+  autoRotateDelay: number;
   blockContextMenu: boolean;
   /** Places the camera from the target, distance, yaw and pitch. */
   apply(camera: Camera): void;
@@ -744,7 +947,9 @@ export function drawInstance(
   lineWidth?: number,
 ): void;
 /** Turns edge definitions into pairs of vertex indices. */
-export function edgeSegments(edges: number[][]): Generator<[number, number]>;
+export function edgeSegments(edges?: number[][]): Generator<[number, number]>;
+/** The lines a wireframe draws for a mesh: its `edges`, or its face outlines when it has none. */
+export function wireEdges(mesh: { edges?: number[][]; faces?: number[][] }): number[][];
 
 /** Runs `update` every animation frame. Returns a function that stops it. */
 export function loop(update: (dt: number, time: number) => void, opts?: { maxDt?: number }): () => void;

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