trid3d 0.2.0 → 0.3.0

package/trid/index.d.ts

@@ -106,6 +106,11 @@ export interface Material {
   smooth?: boolean | number;
   /** Image drawn on the faces (needs texture coordinates). `fill` tints it. */
   texture?: TextureSource;
+  /**
+   * Read the texture again every frame (default: only videos). For a canvas redrawn every
+   * frame; for one redrawn now and then, call `updateTexture(canvas)` instead.
+   */
+  liveTexture?: boolean;
   /** Keep texture pixels sharp instead of smoothing them (default false) */
   pixelated?: boolean;
   /** Effects applied in order, like `[toon(), rim()]` */
@@ -129,12 +134,22 @@ export type MappingType = "uv" | "planar" | "box" | "sphere" | "cylinder";
  */
 export type Mapping = MappingType | { type: MappingType; axis?: "x" | "y" | "z" };
 
-/** What you pass to `scene.add`. Missing transform fields get defaults. */
+/**
+ * What you pass to `scene.add`. Missing transform fields get defaults.
+ * Give it `children` to make a group (and leave out `mesh` for a group that only holds them).
+ */
 export interface SceneObjectInput {
-  mesh: Mesh;
+  /** What's drawn. Leave it out for a group that only holds `children` */
+  mesh?: Mesh;
   pos?: Vec3;
   rot?: Vec3;
   scale?: Vec3;
+  /** Objects placed relative to this one: they move, turn and scale with it. Read every frame */
+  children?: SceneObjectInput[];
+  /** Set to false to hide this object and everything under it (default true) */
+  visible?: boolean;
+  /** A name, used by `exportOBJ` and handy for finding objects */
+  name?: string;
   /** Wireframe color (default: the scene's color) */
   color?: string;
   /** Wireframe width (default: the scene's lineWidth) */
@@ -151,7 +166,12 @@ export interface SceneObjectInput {
  * An object in a scene, after `scene.add` filled in its transform.
  * Extra fields you add (like `{ mesh, name: "box" }`) are kept in the type.
  */
-export type SceneObject<T extends SceneObjectInput = SceneObjectInput> = T & Transform;
+export type SceneObject<T extends SceneObjectInput = SceneObjectInput> = T & Transform & {
+  /** The group it's a child of, or null at the top. Kept up to date by the scene (not enumerable) */
+  parent: SceneObject | null;
+  /** World matrix from the last frame: parents' transforms × its own (not enumerable). See `worldMatrix` */
+  world: Mat4;
+};
 
 // ---------------------------------------------------------------------------
 // Scene
@@ -298,7 +318,16 @@ export interface Point2 {
  * 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;
+export interface ExtrudeOptions {
+  /** How much the edges between sides and front / back are cut, up to half the depth (default 0) */
+  bevel?: number;
+  /** Steps around a bevel: 1 = flat chamfer, more = rounded (default 1) */
+  bevelSegments?: number;
+  /** Size of the back compared to the front, around the outline's middle (default 1) */
+  taper?: number;
+}
+
+export function extrude(outline: Point2[], depth?: number, opts?: ExtrudeOptions): Mesh;
 
 /** Cuts a counter-clockwise polygon into counter-clockwise triangles (ear clipping). */
 export function triangulate(pts: Point2[]): number[][];
@@ -306,6 +335,53 @@ 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;
 
+/** A transform to bake into a mesh; parts left out change nothing. A scene object fits. */
+export interface MeshTransform {
+  pos?: Partial<Vec3>;
+  rot?: Partial<Vec3>;
+  scale?: Partial<Vec3>;
+}
+
+/** Deep copy of a mesh (vertices, edges, faces, UVs, normals, materials). */
+export function cloneMesh<M extends Mesh>(mesh: M): M;
+
+/**
+ * Bakes a transform into a mesh's vertices, in place (scale, rotate X→Y→Z, move).
+ * Normals turn with it; a mirroring scale reverses the faces. Returns the same mesh.
+ */
+export function transformMesh<M extends Mesh>(mesh: M, transform: MeshTransform): M;
+
+/**
+ * Moves every vertex to `fn(vertex, index)`, in place. Removes the mesh's own normals
+ * (they no longer fit), so the renderers compute new ones. Returns the same mesh.
+ */
+export function displaceMesh<M extends Mesh>(mesh: M, fn: (v: Vec3, index: number) => Vec3): M;
+
+export interface MergeOptions {
+  /** Faces of the i-th mesh use material i (default false: keep each mesh's faceMaterials) */
+  materialPerMesh?: boolean;
+}
+
+/**
+ * Joins meshes into a new one, keeping faces, edges, UVs, normals and materials.
+ * Scene objects in the list are merged where they stand (transform baked in).
+ */
+export function mergeMeshes(items: (Mesh | SceneObjectInput)[], opts?: MergeOptions): Mesh;
+
+/** A box around some geometry. */
+export interface Bounds {
+  min: Vec3;
+  max: Vec3;
+  center: Vec3;
+  size: Vec3;
+}
+
+/**
+ * The box around a mesh, a scene object, a list of them or a Scene (objects measured
+ * where they stand). Null when there are no vertices.
+ */
+export function meshBounds(input: Mesh | SceneObjectInput | (Mesh | SceneObjectInput)[] | Scene): Bounds | null;
+
 // ---------------------------------------------------------------------------
 // Renderers
 // ---------------------------------------------------------------------------
@@ -338,6 +414,8 @@ export class CanvasRenderer implements Renderer {
 export interface WebGLRendererOptions {
   /** Smooth edges (default true) */
   antialias?: boolean;
+  /** Free meshes and textures not drawn for this many frames (default 300, about 5 s). Infinity: never */
+  releaseAfter?: number;
 }
 
 /** Draws a scene with WebGL and a depth buffer. */
@@ -349,7 +427,13 @@ export class WebGLRenderer implements Renderer {
   /** The hidden canvas WebGL draws on. */
   canvas: HTMLCanvasElement;
   gl: WebGLRenderingContext | WebGL2RenderingContext;
+  /** Frames a mesh or texture can go undrawn before it's freed (Infinity: never). */
+  releaseAfter: number;
+  /** What's on the graphics card right now. */
+  readonly memory: { meshes: number; buffers: number; textures: number };
   render(scene: Scene): void;
+  /** Frees a mesh's buffers or a texture now; it's sent again if drawn again. */
+  release(item: Mesh | TextureSource): void;
   /** Frees the graphics card memory. The renderer can't be used afterwards. */
   dispose(): void;
 }
@@ -535,15 +619,36 @@ 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 */
+  /** Material names from `usemtl` lines, in the order they first appear */
   materialNames?: string[];
+  /** The .mtl file the OBJ names (`mtllib`) */
+  mtllib?: string;
+  /** With `loadOBJ(url, { materials: true })`: one material per `materialNames` entry, from the .mtl file */
+  materials?: Material[];
 }
 
 export interface ObjOptions {
   /** Center the model and scale it so its largest side is this long */
   fit?: number;
+  /** `loadOBJ` only: also load the .mtl file and its textures into `mesh.materials` (default false) */
+  materials?: boolean;
 }
 
+/** A material from an MTL file. */
+export interface MtlMaterial {
+  name: string;
+  /** "#rrggbb" from `Kd`, or "rgba(...)" when see-through */
+  fill?: string;
+  /** From `d` / `Tr`, 0 to 1 */
+  opacity?: number;
+  /** The texture's file name (`map_Kd`), relative to the .mtl file */
+  textureFile?: string;
+}
+/** Parses the text of an MTL file: materials by name. */
+export function parseMTL(text: string): Record<string, MtlMaterial>;
+/** The materials of a parsed OBJ from its .mtl file (one per `materialNames` entry), textures loaded. */
+export function loadMaterials(mesh: ObjMesh, base: URL | string): Promise<Material[]>;
+
 /** Parses the text of an OBJ file. */
 export function parseOBJ(text: string, opts?: ObjOptions): ObjMesh;
 /** Downloads an OBJ file and parses it. */
@@ -561,8 +666,15 @@ export function loadTexture(url: string): Promise<HTMLImageElement>;
 export function textureReady(src: TextureSource | null | undefined): boolean;
 /** Pixel size of a texture source. */
 export function textureSize(src: TextureSource): { w: number; h: number };
-/** Whether a source can change over time (canvas, video). */
-export function textureIsLive(src: TextureSource): boolean;
+/** Whether a texture is read again every frame: videos, or any source whose material has `liveTexture: true`. */
+export function textureIsLive(src: TextureSource, material?: { liveTexture?: boolean }): boolean;
+/**
+ * Tells the renderers a texture changed (call it after drawing on a canvas used as a texture):
+ * it's read again once, on the next frame. Canvases are otherwise read only once.
+ */
+export function updateTexture(src: TextureSource): void;
+/** How many times `updateTexture` was called for a source (0 when never). */
+export function textureVersion(src: TextureSource): number;
 
 // ---------------------------------------------------------------------------
 // Exporting
@@ -582,8 +694,37 @@ export interface ExportOBJOptions {
   precision?: number;
   /** Comment at the top of the file; "" for none (default "Exported by Trid") */
   header?: string;
+  /** Link this .mtl file and name every material (the names `exportMTL` writes) */
+  mtllib?: string;
+}
+
+/** A material description for `exportMTL`. */
+export interface MtlDescription {
+  name: string;
+  fill?: string;
+  opacity?: number;
+  /** Texture file name */
+  texture?: string;
 }
 
+/** The materials an export names, with each texture's file name. */
+export function objMaterials(
+  input: OBJExportable | OBJExportable[] | Scene,
+  opts?: { textureFile?: (name: string, texture: TextureSource) => string },
+): { name: string; material: Material | null; texture: TextureSource | null; file: string | null }[];
+/** Writes an MTL file: for what `exportOBJ` takes (same names), or for plain descriptions. */
+export function exportMTL(
+  input: OBJExportable | OBJExportable[] | Scene | MtlDescription[],
+  opts?: { textureFile?: (name: string, texture: TextureSource) => string; header?: string },
+): string;
+/** A texture image as a PNG (or other) file. */
+export function textureToBlob(src: TextureSource, type?: string): Promise<Blob>;
+/** Every file of a model: name.obj, name.mtl and one PNG per texture. */
+export function exportModel(
+  input: OBJExportable | OBJExportable[] | Scene,
+  opts?: { name?: string; obj?: ExportOBJOptions },
+): Promise<{ name: string; data: string | Blob }[]>;
+
 /** Something exportOBJ can write: a mesh, or an object placed in a scene. */
 export type OBJExportable = Mesh | (SceneObjectInput & Partial<Transform> & { name?: string });
 
@@ -754,6 +895,8 @@ export class OrbitCamera implements Tool {
   blockContextMenu: boolean;
   /** Places the camera from the target, distance, yaw and pitch. */
   apply(camera: Camera): void;
+  /** Restarts the auto-rotate wait, as if the user had just dragged (for tools that turn the camera). */
+  holdAutoRotate(): void;
   attach(scene: Scene): void;
   pointerDown(e: ToolPointerEvent): boolean;
   pointerMove(e: ToolPointerEvent, scene: Scene): void;
@@ -792,6 +935,10 @@ export interface DragObjectOptions {
   button?: number;
   /** Which objects can be dragged (default: those without `draggable: false`) */
   filter?: (obj: SceneObject) => boolean;
+  /** Pick by triangles instead of bounding boxes (default false, see `pickHit`) */
+  exact?: boolean;
+  /** Drag the top-level object (the whole group) of what was clicked (default false) */
+  root?: boolean;
   /** Called when an object is picked */
   onPick?: (obj: SceneObject) => void;
   /** Called each time the object moves */
@@ -805,6 +952,8 @@ export class DragObject implements Tool {
   constructor(opts?: DragObjectOptions);
   button: number;
   filter: (obj: SceneObject) => boolean;
+  exact: boolean;
+  root: boolean;
   onPick?: (obj: SceneObject) => void;
   onMove?: (obj: SceneObject) => void;
   onDrop?: (obj: SceneObject) => void;
@@ -821,6 +970,8 @@ export interface HoverHighlightOptions {
   color?: string;
   /** Which objects can be highlighted (default: those without `hoverable: false`) */
   filter?: (obj: SceneObject) => boolean;
+  /** Pick by triangles instead of bounding boxes (default false, see `pickHit`) */
+  exact?: boolean;
   /** Called when the hovered object changes */
   onChange?: (obj: SceneObject | null) => void;
 }
@@ -830,6 +981,7 @@ export class HoverHighlight implements Tool {
   constructor(opts?: HoverHighlightOptions);
   color: string;
   filter: (obj: SceneObject) => boolean;
+  exact: boolean;
   onChange?: (obj: SceneObject | null) => void;
   /** The object under the pointer, or null. */
   hovered: SceneObject | null;
@@ -897,6 +1049,97 @@ export class ObjUploader implements Tool {
   draw(ctx: CanvasRenderingContext2D, scene: Scene): void;
 }
 
+export interface ViewGizmoOptions {
+  /** Camera controls to turn (default: the scene's first OrbitCamera). Without one, it only shows the axes */
+  orbit?: OrbitCamera;
+  /** Where it sits (default "top-right") */
+  corner?: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+  /** Radius in CSS pixels (default 42) */
+  size?: number;
+  /** Distance from the canvas corner in CSS pixels (default 14) */
+  margin?: number | { x: number; y: number };
+  /** Seconds the camera takes to turn to a clicked axis (default 0.35) */
+  duration?: number;
+}
+
+/**
+ * The X, Y, Z axes in a corner, turning with the camera; click one to look along it.
+ * Add it after the OrbitCamera.
+ */
+export class ViewGizmo implements Tool {
+  constructor(opts?: ViewGizmoOptions);
+  orbit: OrbitCamera | null;
+  corner: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+  size: number;
+  margin: { x: number; y: number };
+  duration: number;
+  /** Hide or show the gizmo without removing the tool. */
+  visible: boolean;
+  /** Whether a canvas pixel is on the gizmo (as last drawn). */
+  contains(x: number, y: number): boolean;
+  /** Turns the camera smoothly to look at its target from `dir` ({ x: 0, y: 1, z: 0 }: from above). */
+  lookAlong(dir: Vec3): void;
+  attach(scene: Scene): void;
+  detach(): void;
+  pointerDown(e: ToolPointerEvent): boolean;
+  update(dt: number, scene: Scene): void;
+  draw(ctx: CanvasRenderingContext2D, scene: Scene): void;
+}
+
+export type TransformMode = "move" | "rotate" | "scale";
+
+/** A move, rotate or scale in world space, as `TransformGizmo` reports it. */
+export type TransformOp =
+  | { mode: "move"; delta: Vec3 }
+  /** A right-handed turn of `angle` radians around the unit `axis`, about `center` */
+  | { mode: "rotate"; axis: Vec3; angle: number; center: Vec3 }
+  /** `factor` about `center`: uniform when `axis` is null, otherwise along that unit axis */
+  | { mode: "scale"; axis: Vec3 | null; factor: number; center: Vec3 };
+
+export interface TransformGizmoOptions {
+  /** Default "move" */
+  mode?: TransformMode;
+  /** Objects it edits (default none) */
+  targets?: SceneObject[];
+  /** Handle length in CSS pixels (default 70) */
+  size?: number;
+  /** Change the targets' transforms while dragging (default true) */
+  apply?: boolean;
+  /** A handle was grabbed */
+  onGrab?: (targets: SceneObject[]) => void;
+  /** While dragging: the operation since the grab */
+  onChange?: (op: TransformOp, targets: SceneObject[]) => void;
+  /** On release: the whole operation */
+  onDrop?: (op: TransformOp, targets: SceneObject[]) => void;
+}
+
+/**
+ * Move arrows, rotate rings or scale handles on one or more objects, around their
+ * shared center. Add it after the camera tool.
+ */
+export class TransformGizmo implements Tool {
+  constructor(opts?: TransformGizmoOptions);
+  mode: TransformMode;
+  targets: SceneObject[];
+  size: number;
+  apply: boolean;
+  onGrab?: (targets: SceneObject[]) => void;
+  onChange?: (op: TransformOp, targets: SceneObject[]) => void;
+  onDrop?: (op: TransformOp, targets: SceneObject[]) => void;
+  /** Hide the handles (and ignore clicks) without removing the tool. */
+  visible: boolean;
+  /** True while a handle is being dragged. */
+  readonly dragging: boolean;
+  /** Middle of the targets' bounding box in world space, or null. */
+  center(): Vec3 | null;
+  draw(ctx: CanvasRenderingContext2D, scene: Scene): void;
+  pointerDown(e: ToolPointerEvent, scene: Scene): boolean;
+  pointerMove(e: ToolPointerEvent, scene: Scene): void;
+  pointerUp(): void;
+  pointerLeave(scene: Scene): void;
+  detach(scene: Scene): void;
+}
+
 export interface ScreenBox {
   minX: number;
   minY: number;
@@ -909,9 +1152,31 @@ export function pick(
   scene: Scene,
   x: number,
   y: number,
-  opts?: { filter?: (obj: SceneObject) => boolean; padding?: number },
+  opts?: { filter?: (obj: SceneObject) => boolean; padding?: number; exact?: boolean },
 ): SceneObject | null;
 
+/** What `pickHit` found. */
+export interface PickHit {
+  object: SceneObject;
+  /** Index in `mesh.faces`, or -1 for a line of a wireframe */
+  face: number;
+  /** Distance in front of the camera */
+  depth: number;
+  /** The object, then its groups up to the top: `[part, group, ..., root]` */
+  path: SceneObject[];
+}
+
+/**
+ * Exact picking: the nearest object whose triangles (or, without faces, lines
+ * within `padding` pixels) are under a canvas pixel.
+ */
+export function pickHit(
+  scene: Scene,
+  x: number,
+  y: number,
+  opts?: { filter?: (obj: SceneObject) => boolean; padding?: number; objects?: SceneObject[] },
+): PickHit | null;
+
 /** Screen-space bounding box of an object, or null if it's all behind the camera. */
 export function screenBounds(scene: Scene, obj: SceneObject): ScreenBox | null;
 
@@ -945,6 +1210,8 @@ export function drawInstance(
   h: number,
   color: string,
   lineWidth?: number,
+  /** World matrix to place it with (e.g. `obj.world` inside a group); default: its own transform */
+  world?: Mat4,
 ): void;
 /** Turns edge definitions into pairs of vertex indices. */
 export function edgeSegments(edges?: number[][]): Generator<[number, number]>;
@@ -986,3 +1253,145 @@ export function rotateXYZ(p: Vec3, rot: Vec3): Vec3;
 export function project(p: Vec3, fov?: number, aspect?: number): Vec2;
 /** Normalized coordinates to canvas pixels. */
 export function screen(p: Vec2, w: number, h: number): Vec2;
+
+// ---------------------------------------------------------------------------
+// Rotations
+// ---------------------------------------------------------------------------
+
+/** 3×3 matrix, row-major (m[row][col]), applied as M · v. */
+export type Mat3 = [[number, number, number], [number, number, number], [number, number, number]];
+
+/** The matrix `rotateXYZ(p, rot)` applies. */
+export function matFromEuler(rot: Vec3): Mat3;
+/** Angles for `rotateXYZ` (an object's `rot`) from a rotation matrix; the inverse of `matFromEuler`. */
+export function eulerFromMat(m: Mat3): Vec3;
+/** A right-handed turn of `angle` radians around a unit `axis`. */
+export function matFromAxisAngle(axis: Vec3, angle: number): Mat3;
+/** Matrix product a · b (b is applied first). */
+export function mulMat(a: Mat3, b: Mat3): Mat3;
+/** m · v */
+export function mulVec(m: Mat3, v: Vec3): Vec3;
+/** Applies a world-space move / rotate / scale to a transform and returns the new one. */
+export function applyTransformOp(t: Transform, op: TransformOp): Transform;
+
+// ---------------------------------------------------------------------------
+// Procedural textures
+// ---------------------------------------------------------------------------
+
+export type TextureStyle = "noise" | "marble" | "wood" | "bricks" | "checker" | "bark" | "spots" | "stripes" | "solid";
+/** The built-in styles of `makeTexture`. */
+export const TEXTURE_STYLES: TextureStyle[];
+
+export interface MakeTextureOptions {
+  /** Width and height in pixels (default 256) */
+  size?: number;
+  /** [first, second]: hex, rgb() / rgba(), CSS names or [r, g, b, a?] (default: suits the style) */
+  colors?: (string | number[])[];
+  /** How many times the pattern repeats across, a whole number (default 4) */
+  scale?: number;
+  /** Another whole number gives another texture of the same style (default 0) */
+  seed?: number;
+  /** Fine speckles on top, 0 to 1 (default 0) */
+  grain?: number;
+  /** Paint into this canvas instead of a new one (calls `updateTexture` for you) */
+  canvas?: HTMLCanvasElement | OffscreenCanvas;
+}
+
+/**
+ * Paints a seamless procedural texture on a canvas. `style` is a built-in style, or
+ * `(u, v) => t` (0: first color, 1: second).
+ */
+export function makeTexture(
+  style?: TextureStyle | ((u: number, v: number) => number),
+  opts?: MakeTextureOptions,
+): HTMLCanvasElement | OffscreenCanvas;
+/** The pixels of a procedural texture (RGBA, top row first), without a canvas. */
+export function texturePixels(
+  style?: TextureStyle | ((u: number, v: number) => number),
+  opts?: Omit<MakeTextureOptions, "canvas">,
+): { width: number; height: number; data: Uint8ClampedArray };
+/** [r, g, b, a] (0..255, a 0..1) from a color string or array. */
+export function colorBytes(color: string | number[]): [number, number, number, number];
+
+// ---------------------------------------------------------------------------
+// Groups (scene graph)
+// ---------------------------------------------------------------------------
+
+/**
+ * Every visible object of a scene (or of objects and their subtrees), parents first,
+ * with `parent` and `world` set. Groups without a mesh are included.
+ */
+export function worldObjects(input: Scene | SceneObjectInput | SceneObjectInput[]): SceneObject[];
+/** An object's world matrix right now, from its transform and its parents'. */
+export function worldMatrix(obj: SceneObjectInput): Mat4;
+/** Where an object's origin is in the world right now. */
+export function worldPosition(obj: SceneObjectInput): Vec3;
+/** The chain from an object up to the top: `[obj, parent, ..., root]`. */
+export function ancestors(obj: SceneObject): SceneObject[];
+/**
+ * Calls `fn(obj, world, parent)` for every visible object under some roots, parents first,
+ * without changing anything. `baseOf(root)` is the matrix a root goes under (null: none).
+ */
+export function forEachPlaced(
+  roots: SceneObjectInput[],
+  baseOf: (root: SceneObjectInput) => Mat4 | null,
+  fn: (obj: SceneObjectInput, world: Mat4, parent: SceneObjectInput | null) => void,
+): void;
+
+// ---------------------------------------------------------------------------
+// Matrices
+// ---------------------------------------------------------------------------
+
+/** 4×4 transform matrix, 16 numbers in column-major order (`m[col * 4 + row]`), like WebGL. */
+export type Mat4 = number[];
+
+/** The identity matrix. */
+export function identityMat4(): Mat4;
+/** The matrix of a transform: scale, rotate X → Y → Z, then move. */
+export function mat4FromTransform(t: MeshTransform): Mat4;
+/** a · b (b applied first): a child's world matrix is `mulMat4(parentWorld, childLocal)`. */
+export function mulMat4(a: Mat4, b: Mat4): Mat4;
+/** Inverse of a transform matrix (identity if it flattens space). */
+export function invertMat4(m: Mat4): Mat4;
+/** Determinant of the 3×3 part: < 0 when the matrix mirrors. */
+export function determinantMat4(m: Mat4): number;
+/** A point through a matrix. */
+export function transformPoint(m: Mat4, p: Vec3): Vec3;
+/** A direction or offset through a matrix (not moved). */
+export function transformDirection(m: Mat4, v: Vec3): Vec3;
+/** The 3×3 normal matrix (inverse transpose), column-major. */
+export function normalMatrix(m: Mat4): number[];
+/** A normal through a normal matrix, unit length. */
+export function transformNormal(nm: number[], n: Vec3): Vec3;
+/** A world-space `TransformOp` in a parent's space, for objects inside groups. */
+export function transformOpToLocal(op: TransformOp, parentWorld: Mat4): TransformOp;
+
+// ---------------------------------------------------------------------------
+// Random numbers and noise
+// ---------------------------------------------------------------------------
+
+/** A seeded random generator (mulberry32): each call returns the next number in [0, 1). */
+export function rng(seed?: number): () => number;
+
+export interface NoiseOptions {
+  /** Whole number; another seed gives other noise (default 0) */
+  seed?: number;
+  /** Repeat every this many units, a whole number, for seamless textures (default 0: never) */
+  period?: number;
+}
+
+export interface FbmOptions extends NoiseOptions {
+  /** Layers of detail (default 5) */
+  octaves?: number;
+  /** Strength of each layer compared to the one before (default 0.5) */
+  gain?: number;
+}
+
+/** Smooth 2D value noise in [0, 1). */
+export function noise2(x: number, y: number, opts?: NoiseOptions): number;
+/** Smooth 3D value noise in [0, 1). */
+export function noise3(x: number, y: number, z: number, opts?: NoiseOptions): number;
+/** Fractal 2D noise: octaves of noise2, each twice as fine. About [0, 1), averaging 0.5. */
+export function fbm2(x: number, y: number, opts?: FbmOptions): number;
+/** Fractal 3D noise: octaves of noise3, each twice as fine. About [0, 1), averaging 0.5. */
+export function fbm3(x: number, y: number, z: number, opts?: FbmOptions): number;

package/trid/index.js

@@ -11,9 +11,11 @@
 
 // Scene
 export { Scene } from "./scene.js";
+export { worldObjects, worldMatrix, worldPosition, ancestors, forEachPlaced } from "./sceneGraph.js";
 
 // Shapes and meshes
 export { makeShape, scaleMesh, lathe, extrude, triangulate } from "./render/shapes.js";
+export { cloneMesh, transformMesh, displaceMesh, mergeMeshes, meshBounds } from "./render/meshUtils.js";
 
 // Renderers
 export { CanvasRenderer, DEFAULT_LIGHT, DEFAULT_AMBIENT, materialsOf } from "./render/canvasRenderer.js";
@@ -25,6 +27,9 @@ export {
   buildEffects, effectsKey, uniformType, SURFACE_GLSL,
 } from "./render/effects.js";
 
+// Procedural textures
+export { makeTexture, texturePixels, colorBytes, TEXTURE_STYLES } from "./render/proceduralTextures.js";
+
 // Texture mapping
 export { computeUVs, mapUVs, uvsFor, uvTransform, applyUVTransform, mappingOf, mappingKey, MAPPINGS } from "./render/uvMapping.js";
 
@@ -32,17 +37,20 @@ export { computeUVs, mapUVs, uvsFor, uvTransform, applyUVTransform, mappingOf, m
 export { cornerNormals, creaseOf, newell, DEFAULT_CREASE } from "./render/normals.js";
 
 // Loading files
-export { parseOBJ, loadOBJ, readOBJFile, pickOBJFile, fitMesh } from "./loaders/obj.js";
-export { loadTexture, textureReady, textureSize, textureIsLive } from "./loaders/texture.js";
+export { parseOBJ, loadOBJ, loadMaterials, readOBJFile, pickOBJFile, fitMesh } from "./loaders/obj.js";
+export { parseMTL } from "./loaders/mtl.js";
+export { loadTexture, textureReady, textureSize, textureIsLive, updateTexture, textureVersion } from "./loaders/texture.js";
 
 // Exporting
 export { exportOBJ } from "./export/obj.js";
+export { exportMTL, objMaterials, exportModel, textureToBlob } from "./export/mtl.js";
 export { screenshot, record, download } from "./export/capture.js";
 
 // Tools
 export {
   OrbitCamera, FlyCamera, DragObject, HoverHighlight, FpsMeter, ObjUploader,
-  ToolManager, pick, screenBounds, worldPerPixel,
+  ViewGizmo, TransformGizmo,
+  ToolManager, pick, pickHit, screenBounds, worldPerPixel,
 } from "./tools/index.js";
 
 // Drawing and the frame loop
@@ -58,3 +66,11 @@ export {
   DEFAULT_FOV, DEFAULT_NEAR,
 } from "./math/transform.js";
 export { project, screen } from "./math/projection.js";
+export { matFromEuler, eulerFromMat, matFromAxisAngle, mulMat, mulVec, applyTransformOp } from "./math/rotation.js";
+export {
+  identityMat4, mat4FromTransform, mulMat4, invertMat4, determinantMat4,
+  transformPoint, transformDirection, normalMatrix, transformNormal, transformOpToLocal,
+} from "./math/matrix.js";
+
+// Random numbers and noise
+export { rng, noise2, noise3, fbm2, fbm3 } from "./math/noise.js";

package/trid/loaders/mtl.js

@@ -0,0 +1,63 @@
+/**
+ * MTL loading: the material file an OBJ file names with `mtllib`.
+ *
+ * Reads each `newmtl` block's diffuse color (`Kd`), see-through (`d`, or
+ * `Tr` = 1 - d) and diffuse texture (`map_Kd`, options like `-s 1 1 1`
+ * skipped). Everything else is ignored.
+ */
+
+/**
+ * @typedef {Object} MtlMaterial
+ * @property {string} name
+ * @property {string} [fill] - "#rrggbb" from `Kd` (or "rgba(...)" when see-through)
+ * @property {number} [opacity] - From `d` / `Tr`, 0 to 1
+ * @property {string} [textureFile] - The texture's file name (`map_Kd`), relative to the .mtl file
+ */
+
+/**
+ * Parses the text of an MTL file.
+ *
+ * @param {string} text
+ * @returns {Object<string, MtlMaterial>} Materials by name
+ */
+export function parseMTL(text) {
+  const materials = {};
+  let m = null;
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === "" || line[0] === "#") continue;
+    const [key, ...rest] = line.split(/\s+/);
+    const k = key.toLowerCase();
+    if (k === "newmtl") {
+      const name = rest.join(" ");
+      m = materials[name] = { name };
+    } else if (!m) {
+      continue;
+    } else if (k === "kd") {
+      const [r, g, b] = rest.map(Number);
+      const hex = (x) => Math.round(Math.min(1, Math.max(0, x || 0)) * 255).toString(16).padStart(2, "0");
+      m.fill = `#${hex(r)}${hex(g ?? r)}${hex(b ?? r)}`;
+    } else if (k === "d") {
+      m.opacity = Math.min(1, Math.max(0, Number(rest[0])));
+    } else if (k === "tr") {
+      m.opacity = Math.min(1, Math.max(0, 1 - Number(rest[0])));
+    } else if (k === "map_kd") {
+      // Skip options ("-s 1 1 1", "-bm 0.5", "-clamp on"...): the file name is what's left
+      const words = [...rest];
+      const takes = { "-s": 3, "-o": 3, "-t": 3, "-mm": 2, "-bm": 1, "-blendu": 1, "-blendv": 1, "-clamp": 1, "-texres": 1, "-imfchan": 1, "-boost": 1, "-cc": 1 };
+      while (words.length && words[0][0] === "-") {
+        const opt = words.shift().toLowerCase();
+        words.splice(0, takes[opt] ?? 1);
+      }
+      if (words.length) m.textureFile = words.join(" ");
+    }
+  }
+  // See-through fills as rgba, so materials can use them directly
+  for (const mat of Object.values(materials)) {
+    if (mat.fill && mat.opacity !== undefined && mat.opacity < 1) {
+      const [r, g, b] = [1, 3, 5].map((i) => parseInt(mat.fill.slice(i, i + 2), 16));
+      mat.fill = `rgba(${r}, ${g}, ${b}, ${mat.opacity})`;
+    }
+  }
+  return materials;
+}