trid3d 0.4.0 → 0.6.0

package/README.md

@@ -4,19 +4,20 @@
 
 <h1 align="center">Trid</h1>
 
-<p align="center">A small 3D library for the HTML canvas. No dependencies, no build step.</p>
+<p align="center">Model, light and draw 3D on the HTML canvas. No dependencies, no build step.</p>
 
 ---
 
-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.
+Trid gives you a scene, shapes you can model in code, lights, effects, model loading and mouse/keyboard tools, all in plain ES modules you can drop next to your page. See the [docs](https://zachr622.github.io/Trid/) for live demos.
 
 > **Status:** early (0.x): the API can still change between minor versions. See [Upgrading](#upgrading).
 
 ## Features
 
-- **Scene** — holds a canvas, a camera and your objects, and runs the frame loop for you.
+- **Scene** — holds a canvas, a camera, lights and your objects, and runs the frame loop for you. The background can be a color or see-through (`"transparent"`), so a model can float over your page.
 - **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.
+- **Shapes** — cubes, boxes (sharp or rounded), spheres, cylinders, cones, tori and planes built in, `lathe` for round shapes (a point on the axis closes it to a tip) and `extrude` for flat ones, or any mesh you define as vertices, faces and edges.
+- **Modeling** — smooth curves through a few points (`spline`), shapes swept along a 3D path (`sweep`: tails, horns, pipes, rails), surfaces through cross-sections (`loft`: bodies, bottles, hulls, heads), subdivision surfaces with creases (`subdivideMesh`: box modeling), shapes that melt together (`blobMesh`: creatures, clay; or any distance field with `sdfMesh`), rounded or cut edges on any mesh (`bevelMesh`), taper, twist, bend and bulge deformers, mesh cleanup and checks (weld, clean, validate, fix winding), and rays, inside tests and distances against meshes and scenes (`meshQuery`, `raycastScene`).
 - **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.
 - **Lights** — ambient, directional and point lights, with colors and intensities, as many as you need (up to 8 at once besides ambient).
@@ -26,7 +27,7 @@ Trid gives you a scene, a camera, shapes, model loading and mouse/keyboard tools
 - **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 (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.
+- **Camera** — position, yaw, pitch and field of view (50° by default), with near-plane clipping.
 - **Tools** — orbit and fly cameras, object dragging, hover highlight, a move / rotate / scale gizmo (with a pivot of your choice), a view axes gizmo, a floor grid, an FPS meter and an OBJ uploader, one line each. Exact picking by triangles, with the hit point and texture coordinates under the mouse. Writing your own is a plain object with a few methods.
 - **Pure math** — every transform and projection step is exported, plus 4×4 matrices and rotations, so you can use the pipeline piece by piece.
 
@@ -40,7 +41,7 @@ No bundler? Use the CDN with an import map, or copy the `trid/` folder next to y
 
 ```html
 <script type="importmap">
-  { "imports": { "trid3d": "https://cdn.jsdelivr.net/npm/trid3d@0.3/trid/index.js" } }
+  { "imports": { "trid3d": "https://cdn.jsdelivr.net/npm/trid3d@0.6/trid/index.js" } }
 </script>
 ```
 
@@ -55,13 +56,22 @@ No bundler? Use the CDN with an import map, or copy the `trid/` folder next to y
 // main.js
 import { Scene, makeShape, OrbitCamera } from "trid3d";
 
-const scene = new Scene(document.getElementById("canvas"), { width: 800, height: 400 });
-const cube = scene.add({ mesh: makeShape("cube"), color: "#E9806E" });              // wireframe
-const ball = scene.add({ mesh: makeShape("sphere"), material: { fill: "#8ab4f8" } }); // filled and shaded
-ball.pos.x = 0.8;
+const scene = new Scene(document.getElementById("canvas"), {
+  width: 800, height: 400,
+  camera: { z: -1.5 }, // a step back
+});
+
+// A cube with rounded edges, filled and smoothly shaded
+const cube = scene.add({
+  mesh: makeShape("cube", { radius: 0.08 }),
+  material: { fill: "#E9806E", smooth: true },
+});
 
 scene.use(new OrbitCamera()); // drag to orbit, scroll to zoom
-scene.start((dt) => (cube.rot.y += dt));
+scene.start((dt) => {
+  cube.rot.x += dt * 0.5;
+  cube.rot.y += dt * 0.35;
+});
 ```
 
 Without a bundler, serve the folder (`python3 -m http.server`) instead of opening the file directly: browsers block module imports from `file://` pages.
@@ -86,6 +96,7 @@ Or let users load their own: `scene.use(new ObjUploader())` accepts dropped `.ob
 | `trid/sceneGraph.js` | Groups: `children`, world matrices |
 | `trid/math/` | Transforms, camera directions, projection, matrices, rotations, random numbers and noise |
 | `trid/render/` | Renderers (Canvas 2D, WebGL), lights, effects, post effects, shapes, grids, mesh helpers, procedural textures, drawing, frame loop |
+| `trid/modeling/` | Modeling tools: curves, sweep, loft, subdivision, blobs, bevel, deformers, cleanup, queries (rays, inside, distance) |
 | `trid/loaders/` | OBJ, MTL and texture loading |
 | `trid/export/` | Screenshots, video recording, OBJ and MTL export |
 | `trid/tools/` | Camera, object, gizmo and overlay tools |
@@ -111,10 +122,16 @@ See [`docs/README.md`](https://github.com/ZachR622/Trid/blob/master/docs/README.
 npm test
 ```
 
-Uses Node's built-in test runner (Node 21+), so there's nothing to install. The tests cover shapes, mesh helpers, noise, textures, OBJ / MTL, picking, tools, groups and matrices, lights, post effects, grids, and the WebGL renderer's GPU memory on a fake WebGL context.
+Uses Node's built-in test runner (Node 21+), so there's nothing to install. The tests cover shapes (lathe poles included), mesh helpers, curves, sweeps, lofts, subdivision, blobs, bevels, deformers, mesh cleanup, mesh and scene queries, noise, textures, OBJ / MTL, picking, tools, groups and matrices, lights, post effects, grids, the field of view, see-through backgrounds, and the WebGL renderer's GPU memory on a fake WebGL context.
 
 ## Upgrading
 
+### From 0.5 to 0.6
+
+- **The cone's tip is a single point** (a pole), so the cone is closed: `isClosed` and `validateMesh` no longer report a hole there. It has fewer vertices than before (its tip ring of 32 is now 1), and its side faces are triangles. Any `lathe` profile point with `r: 0` works the same way.
+- **The default field of view is 50°** (`DEFAULT_FOV`), instead of 90°. Scenes whose camera has no `fov` look about twice as close, like in most 3D tools. To keep the old view, give the camera `fov: Math.PI / 2`.
+- **`background: null` is see-through**, like `"transparent"` (it used to come out black). `clear()` now empties the canvas before painting the background, so see-through and half see-through backgrounds work; opaque ones look the same.
+
 ### From 0.3 to 0.4
 
 - **Lights are a list**: `scene.lights`. A scene still starts with one directional light and an ambient level, and looks the same. `scene.light` and `scene.ambient` are now shortcuts for the first directional light's direction and the first ambient light's intensity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trid3d",
-  "version": "0.4.0",
+  "version": "0.6.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",

package/trid/index.d.ts

@@ -43,7 +43,7 @@ export interface Camera {
   yaw?: number;
   /** Tilt around X in radians, > 0 looks up (default 0) */
   pitch?: number;
-  /** Vertical field of view in radians (default Math.PI / 2) */
+  /** Vertical field of view in radians (default DEFAULT_FOV: 50°) */
   fov?: number;
   /** Near plane distance; closer geometry is clipped (default 0.01) */
   near?: number;
@@ -192,8 +192,8 @@ export interface SceneOptions {
   width?: number;
   /** Sets canvas.height (keeps the current one if omitted) */
   height?: number;
-  /** Clear color (default "#141414") */
-  background?: string;
+  /** Clear color (default "#141414"); "transparent", a see-through rgba() or null: the page shows behind */
+  background?: string | null;
   /** Default wireframe color (default "#ffffff") */
   color?: string;
   /** Default wireframe width (default 3) */
@@ -221,7 +221,7 @@ export class Scene {
 
   canvas: HTMLCanvasElement;
   ctx: CanvasRenderingContext2D;
-  background: string;
+  background: string | null;
   color: string;
   lineWidth: number;
   camera: Camera;
@@ -284,8 +284,10 @@ export interface ShapeOptions {
   r?: number;
   /** Sphere latitude bands (default 12) */
   rings?: number;
-  /** Points around: sphere (24), cylinder / cone (32), torus (48) */
+  /** Points around: sphere (24), cylinder / cone (32), torus (48); rows per rounded edge of a cube / box with `radius` (4) */
   segments?: number;
+  /** Cube / box: round the edges and corners by this much (default 0: sharp) */
+  radius?: 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) */
@@ -1424,8 +1426,8 @@ export function worldPerPixel(scene: Scene, depth: number): number;
 // Drawing and the frame loop
 // ---------------------------------------------------------------------------
 
-/** Fills the whole canvas with a color. */
-export function clear(ctx: CanvasRenderingContext2D, w: number, h: number, color: string): void;
+/** Clears the whole canvas, then fills it with a color ("transparent" or null: left see-through). */
+export function clear(ctx: CanvasRenderingContext2D, w: number, h: number, color?: string | null): void;
 /** Draws a square point centered at a screen position. */
 export function point(ctx: CanvasRenderingContext2D, p: Vec2, color: string, size?: number): void;
 /** Draws a line between two screen points. */
@@ -1465,7 +1467,7 @@ export function parseColor(ctx: CanvasRenderingContext2D, color: string): RGBA;
 // Math
 // ---------------------------------------------------------------------------
 
-/** Default vertical field of view (90°). */
+/** Default vertical field of view: 50° (in radians). */
 export const DEFAULT_FOV: number;
 /** Default near plane distance. */
 export const DEFAULT_NEAR: number;
@@ -1632,3 +1634,416 @@ export function noise3(x: number, y: number, z: number, opts?: NoiseOptions): nu
 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;
+
+// Modeling: curves
+
+export interface SplineOptions {
+  /** Points made between two control points (default 8) */
+  segments?: number;
+  /** The last point joins the first (a loop); the result doesn't repeat the first point (default false) */
+  closed?: boolean;
+  /** 0 = uniform, 0.5 = centripetal: no loops or overshoot (default), 1 = chordal */
+  alpha?: number;
+  /** 0 = smooth (default), 1 = straight lines between the points */
+  tension?: number;
+  /** Instead of `segments`: this many points in all, evenly spaced by length */
+  count?: number;
+  /** Instead of `segments`: points about this far apart, evenly spaced */
+  spacing?: number;
+}
+
+/**
+ * A smooth curve through `points` (Catmull-Rom: it passes through every
+ * point). Works with 2D, 3D and lathe `{ r, y }` points: every number field
+ * of the first point is a coordinate, and the result has the same fields.
+ */
+export function spline<P extends Point2 | Vec3 | ProfilePoint>(points: P[], opts?: SplineOptions): P[];
+
+export interface ResampleOptions {
+  /** Number of points in all */
+  count?: number;
+  /** Distance between points (used when `count` isn't given) */
+  spacing?: number;
+  /** The points form a loop (default false) */
+  closed?: boolean;
+}
+
+/** Points along a polyline, evenly spaced by length. The ends stay where they are. */
+export function resamplePath<P extends Point2 | Vec3 | ProfilePoint>(points: P[], opts?: ResampleOptions): P[];
+
+// Modeling: sweep
+
+/** A size along a path: a number, numbers spread evenly from start to end, or a function of t (0 at the start, 1 at the end). */
+export type SizeAlong = number | number[] | ((t: number) => number);
+
+export interface SweepOptions {
+  /** The cross-section: x to the path's side, y to its "up" (default: a circle of `radius`) */
+  profile?: Point2[];
+  /** The profile is a closed outline (default true); false = an open line, for ribbons, leaves and roads */
+  profileClosed?: boolean;
+  /** Radius of the default circle (default 0.1). Ignored with a `profile` */
+  radius?: SizeAlong;
+  /** Points around the default circle (default 16) */
+  segments?: number;
+  /** Size of the section along the path (default 1). 0 at an end closes it into a point */
+  scale?: SizeAlong;
+  /** Turn of the section from start to end, in radians (default 0). Whole turns on a closed path */
+  twist?: number;
+  /** The path is a loop: its end joins its start (default false) */
+  closed?: boolean;
+  /** Close the ends with flat caps (default true; open paths with closed profiles) */
+  caps?: boolean;
+  /** Keep the section's y pointed this way (roads, rails, frames). Default: carried along the path without spinning */
+  up?: Vec3;
+  /** Stretch the section at sharp corners so the tube keeps its thickness (default true) */
+  miter?: boolean;
+}
+
+/**
+ * Moves a cross-section along a 3D path: tails, horns, tentacles, handles,
+ * pipes, cables, rails. Without `profile`, a round tube of `radius`.
+ * Clockwise faces; uvs: u around the section, v along the path.
+ */
+export function sweep(path: Vec3[], opts?: SweepOptions): Mesh;
+
+// Modeling: loft
+
+/** A 2D section, placed along the loft's axis or path. */
+export interface LoftOutline {
+  /** Closed outline: x to the side, y up (either direction; one point = a tip) */
+  outline: Point2[];
+  /** Where it is: the position on the axis, or 0 (start) to 1 (end) along a path (default: evenly spread) */
+  at?: number;
+  /** Size, the same both ways or per direction (default 1); 0 = a tip */
+  scale?: number | { x?: number; y?: number };
+  /** Turn in its own plane, in radians (default 0) */
+  rotate?: number;
+  /** Move in its own plane (default none) */
+  offset?: Partial<Point2>;
+}
+
+/** A section as a ring of 3D points, used where it is. */
+export interface LoftRing {
+  points: Vec3[];
+}
+
+export interface LoftOptions {
+  /** Straight axis the outlines are placed along (default "z"). x/y of an outline: "z" → X/Y, "y" → X/Z, "x" → Z/Y */
+  axis?: "x" | "y" | "z";
+  /** A 3D path to place the outlines along instead of the axis */
+  path?: Vec3[];
+  /** With `path`: keep the outlines' y pointed this way (default: carried along without spinning) */
+  up?: Vec3;
+  /** The surface loops back to its first section (a closed path, or 3D rings in a loop; default false) */
+  closed?: boolean;
+  /** Close the ends with flat caps (default true) */
+  caps?: boolean;
+  /** Rows between two sections, on average (default 6) */
+  segments?: number;
+  /** Points around each section (default: kept when every section has the same count, else the most any has, at least 24) */
+  points?: number;
+  /** Smooth curves between sections, never past them (default true); false = straight */
+  smooth?: boolean;
+  /** Line sections up so the surface doesn't twist (default true) */
+  align?: boolean;
+}
+
+/**
+ * A surface through cross-sections: bodies, bottles, hulls, car bodies,
+ * heads. Every section is an `outline` (2D, placed along an axis or a path)
+ * or every section is `points` (a 3D ring). Clockwise faces; uvs: u around,
+ * v along. Throws when the two kinds are mixed.
+ */
+export function loft(sections: LoftOutline[] | LoftRing[], opts?: LoftOptions): Mesh;
+
+// Modeling: deformers
+
+export interface AxisRange {
+  /** Axis the effect goes along (default "y") */
+  axis?: "x" | "y" | "z";
+  /** Start of the part that changes: 0 = the mesh's low end on the axis, 1 = its high end (default 0) */
+  from?: number;
+  /** End of the part that changes, same measure (default 1). Past it, the full effect carries on */
+  to?: number;
+  /** A point the axis line goes through (default: the middle of the mesh's box) */
+  center?: Partial<Vec3>;
+}
+
+export interface TaperOptions extends AxisRange {
+  /** Size at the end of the range (default 0.5), or a function of how far into the range (0 to 1) giving the size */
+  amount?: number | ((w: number) => number);
+}
+
+export interface TwistOptions extends AxisRange {
+  /** Turn at the end of the range, in radians (default π/2), or a function of how far into the range (0 to 1) */
+  angle?: number | ((w: number) => number);
+}
+
+export interface BendOptions extends AxisRange {
+  /** Angle of the arc, in radians (default π/2); negative curves the other way */
+  angle?: number;
+  /** Axis it curves toward (default: "z" for a "y" axis, "z" for "x", "y" for "z") */
+  toward?: "x" | "y" | "z";
+}
+
+export interface BulgeOptions {
+  /** Middle of the bulge */
+  center: Vec3;
+  /** Distance where it fades to nothing */
+  radius: number;
+  /** How far the middle moves (default 0.1); negative = a dent */
+  amount?: number;
+  /** "normal": along the surface, works on flat sides (default); "radial": away from `center` (put it inside the part) */
+  mode?: "normal" | "radial";
+}
+
+/** Narrows or widens a mesh along an axis, in place. Returns the same mesh. */
+export function taperMesh<M extends Mesh>(mesh: M, opts?: TaperOptions): M;
+/** Turns a mesh around an axis, more and more along it, in place (same direction as rotateX / Y / Z). Returns the same mesh. */
+export function twistMesh<M extends Mesh>(mesh: M, opts?: TwistOptions): M;
+/** Bends a mesh into an arc along an axis, in place; past the range it goes on straight. Returns the same mesh. */
+export function bendMesh<M extends Mesh>(mesh: M, opts?: BendOptions): M;
+/** Pushes the surface out (or in) around a point, fading at `radius`, in place. Returns the same mesh. */
+export function bulgeMesh<M extends Mesh>(mesh: M, opts: BulgeOptions): M;
+
+// Modeling: cleanup and checks
+
+/**
+ * Merges vertices closer than `epsilon` (default: a ten-millionth of the
+ * mesh's size), in place. Texture coordinates and normals (per corner) are
+ * kept; corners that meet are removed. Returns the same mesh.
+ */
+export function weldVertices<M extends Mesh>(mesh: M, epsilon?: number): M;
+
+export interface CleanOptions {
+  /** Merge vertices at the same place first: true, or the distance (default false) */
+  weld?: boolean | number;
+}
+
+/**
+ * Removes what's broken, in place: faces to missing or bad vertices, repeated
+ * corners, faces with fewer than 3 corners, crossed or of no area, repeated
+ * faces, bad corner lists (set to null), bad edges, and unused vertices,
+ * texture coordinates and normals. Returns the same mesh.
+ */
+export function cleanMesh<M extends Mesh>(mesh: M, opts?: CleanOptions): M;
+
+export interface MeshProblem {
+  /** What's wrong, e.g. "bad-index", "no-area", "turned-face", "inside-out", "open-edge" */
+  kind: string;
+  /** "error": breaks drawing or export; "warning": draws wrong; "info": worth knowing */
+  level: "error" | "warning" | "info";
+  /** A short sentence, with the first few faces / vertices / edges concerned */
+  message: string;
+  faces?: number[];
+  vertices?: number[];
+  edges?: number[];
+}
+
+/** Lists what's wrong with a mesh, without changing it (one entry per kind of problem; empty when fine). */
+export function validateMesh(mesh: Mesh): MeshProblem[];
+
+/**
+ * Turns faces in place so neighbors agree and each piece points outward
+ * (clockwise from outside). Works without welding. Returns the same mesh.
+ */
+export function fixWinding<M extends Mesh>(mesh: M): M;
+
+// Modeling: subdivision
+
+export interface SubdivideOptions {
+  /** Times to subdivide (default 1, at most 6); each level makes about 4 times the faces */
+  levels?: number;
+  /** false: only split the faces, keep the shape (default true) */
+  smooth?: boolean;
+  /** Edges where faces meet sharper than this (degrees) stay hard (default: none) */
+  creaseAngle?: number;
+  /** Edges that stay hard: pairs or polylines of vertex indices, e.g. [[0, 1], [4, 5, 6, 7, 4]] */
+  creases?: number[][];
+  /** "smooth": texture coordinates smoothed with the surface, seams kept (default); "linear": only split */
+  uvs?: "smooth" | "linear";
+}
+
+/**
+ * Smooths a mesh by subdividing it (Catmull-Clark): a rough cage becomes a
+ * smooth surface. Returns a new mesh of quads (the original isn't changed),
+ * welded, with texture coordinates and materials; own normals are dropped.
+ */
+export function subdivideMesh(mesh: Mesh, opts?: SubdivideOptions): Mesh;
+
+// Modeling: blobs (distance fields)
+
+/** How a blob shape joins what's before it: melts in (default), carves it, or keeps only the overlap. */
+export type BlobOp = "add" | "subtract" | "intersect";
+
+interface BlobBase {
+  /** How it joins what's before it (default "add") */
+  op?: BlobOp;
+  /** Same as op: "subtract" */
+  subtract?: boolean;
+  /** How far it melts into what's before it, as a distance (default: the blobMesh / blobField `blend`) */
+  blend?: number;
+}
+
+export type BlobShape = BlobBase & (
+  | { kind: "sphere"; center: Vec3; radius: number }
+  /** Turned by `rot` (radians, X then Y then Z) */
+  | { kind: "ellipsoid"; center: Vec3; radii: Vec3; rot?: Vec3 }
+  /** A capsule between two points; `ra` / `rb` instead of `radius` make a rounded cone */
+  | { kind: "capsule"; a: Vec3; b: Vec3; radius?: number; ra?: number; rb?: number }
+  /** A capped cylinder between two points, edges rounded by `round` */
+  | { kind: "cylinder"; a: Vec3; b: Vec3; radius: number; round?: number }
+  /** A box of `size`, edges rounded by `round`, turned by `rot` */
+  | { kind: "box"; center: Vec3; size: Vec3; round?: number; rot?: Vec3 }
+  /** A ring lying flat in XZ (like makeShape("torus")), turned by `rot` */
+  | { kind: "torus"; center: Vec3; R: number; tube: number; rot?: Vec3 }
+);
+
+export interface SdfMeshOptions {
+  /** Grid cells along the longest side (default 64, 4 to 256); more is finer and slower */
+  resolution?: number;
+  /** "nets": surface nets, even quads (default); "cubes": marching cubes, triangles. Both are watertight */
+  method?: "nets" | "cubes";
+  /** Pull vertices exactly onto the surface (default true) */
+  project?: boolean;
+  /** Normals from the field, for smooth shading (default true) */
+  normals?: boolean;
+  /** Texture mapping for the uvs, as for computeUVs (default "box"); false: none */
+  uvs?: MappingType | Mapping | false;
+  /** Skip grid blocks far from the surface, trusting the field to be about the distance (default true) */
+  sparse?: boolean;
+}
+
+export interface BlobMeshOptions extends Omit<SdfMeshOptions, "sparse"> {
+  /** How far shapes melt into each other, as a distance (default: a tenth of the model's size). A shape's own `blend` wins */
+  blend?: number;
+}
+
+/** One smooth mesh of shapes that melt together (added, subtracted or intersected, in order). */
+export function blobMesh(shapes: BlobShape[], opts?: BlobMeshOptions): Mesh;
+
+/** The distance field of blob shapes (negative inside), to mix with your own math and mesh with sdfMesh. */
+export function blobField(shapes: BlobShape[], opts?: { blend?: number }): (p: Vec3) => number;
+
+/** The surface where `field(p)` is 0 (negative inside), within `bounds`, as a mesh. */
+export function sdfMesh(field: (p: Vec3) => number, bounds: { min: Vec3; max: Vec3 }, opts?: SdfMeshOptions): Mesh;
+
+// Modeling: bevel
+
+export interface BevelOptions {
+  /** Size of the rounding: the radius of the ball rolled along the edges (default: a twentieth of the mesh's size). Shrinks where bevels would overlap */
+  radius?: number;
+  /** Rows across each rounded edge (default 3); 1 = a flat cut (chamfer) */
+  segments?: number;
+  /** Edges where faces meet sharper than this (degrees) are beveled (default 30) */
+  angle?: number;
+  /** "edges": round the edges, corners become pieces of a sphere (default); "vertices": cut only the corners */
+  mode?: "edges" | "vertices";
+  /** Instead of `angle`: the edges to bevel, as pairs or polylines of vertex indices */
+  edges?: number[][];
+  /** With mode "vertices", instead of `angle`: the corners to cut, as vertex indices */
+  vertices?: number[];
+}
+
+/**
+ * Rounds (or cuts flat) the sharp edges of a mesh, like a bevel modifier.
+ * Returns a new mesh, welded, with texture coordinates and materials kept.
+ * Edges along an open border stay sharp.
+ */
+export function bevelMesh(mesh: Mesh, opts?: BevelOptions): Mesh;
+
+// Modeling: queries (rays, inside, distance)
+
+/** Which faces a ray counts: "both" (default), "front" (hit from outside) or "back" (hit from inside). */
+export type RaySide = "both" | "front" | "back";
+
+export interface RaycastOptions {
+  /** Ignore hits farther than this (default Infinity) */
+  maxDistance?: number;
+  /** Which faces count (default "both") */
+  side?: RaySide;
+}
+
+/** Where a ray met a mesh, in the mesh's own space. */
+export interface MeshHit {
+  point: Vec3;
+  /** Unit normal of the face, pointing out of the mesh (whichever side the ray came from) */
+  normal: Vec3;
+  /** From the ray's origin */
+  distance: number;
+  /** Index in `mesh.faces` */
+  face: number;
+  /** true when the ray met the face from outside */
+  front: boolean;
+  /** The 3 vertex indices of the triangle hit (faces with more corners are fans from their first corner) */
+  triangle: [number, number, number];
+  /** Weights of those vertices at the point (they add up to 1) */
+  barycentric: [number, number, number];
+}
+
+/** The nearest point of a mesh's surface. */
+export type MeshClosest = Omit<MeshHit, "front">;
+
+/** A mesh prepared for many questions (a snapshot: editing the mesh later doesn't change it). */
+export interface MeshQuery {
+  /** Triangles in the query (faces split into fans) */
+  readonly triangleCount: number;
+  /** The mesh's box */
+  readonly bounds: { min: Vec3; max: Vec3 };
+  /** The first place a ray meets the surface, or null. `direction` can be any length but zero */
+  raycast(origin: Vec3, direction: Vec3, opts?: RaycastOptions): MeshHit | null;
+  /** Whether a point is inside (only meaningful for a closed mesh, see `isClosed`) */
+  contains(p: Vec3): boolean;
+  /** The nearest point of the surface, or null when nothing is within `maxDistance` */
+  closest(p: Vec3, opts?: { maxDistance?: number }): MeshClosest | null;
+  /** Distance to the surface (Infinity when nothing is within `maxDistance`) */
+  distance(p: Vec3, maxDistance?: number): number;
+}
+
+/** Prepares a mesh for many ray, inside and distance questions (builds a BVH once). */
+export function meshQuery(mesh: Mesh): MeshQuery;
+
+/** One-off `meshQuery(mesh).raycast(...)`. For many rays on one mesh, keep a `meshQuery`. */
+export function raycastMesh(mesh: Mesh, origin: Vec3, direction: Vec3, opts?: RaycastOptions): MeshHit | null;
+
+/** One-off `meshQuery(mesh).contains(p)`. */
+export function pointInMesh(mesh: Mesh, p: Vec3): boolean;
+
+/** One-off `meshQuery(mesh).distance(p, maxDistance)`. */
+export function distanceToMesh(mesh: Mesh, p: Vec3, maxDistance?: number): number;
+
+/** One-off `meshQuery(mesh).closest(p, opts)`. */
+export function closestPointOnMesh(mesh: Mesh, p: Vec3, opts?: { maxDistance?: number }): MeshClosest | null;
+
+/** Whether a mesh is closed (watertight): every edge, matched by position, shared by exactly two faces. */
+export function isClosed(mesh: Mesh): boolean;
+
+/** What `raycastScene` found: a `MeshHit` in world space, plus the object. */
+export interface SceneHit extends MeshHit {
+  object: SceneObject;
+  /** The object, then its groups up to the top: `[part, group, ..., root]` */
+  path: SceneObject[];
+  /** Where the hit is, in the mesh's own space (`point` is in the world) */
+  local: Vec3;
+}
+
+export interface RaycastSceneOptions extends RaycastOptions {
+  /** Return false to skip an object */
+  filter?: (obj: SceneObject) => boolean;
+  /** Only these objects (and their children) */
+  objects?: SceneObjectInput[];
+}
+
+/**
+ * The first object a ray meets, in world space (the 3D version of `pickHit`).
+ * Hidden objects, `pickable: false` ones and objects without faces are skipped.
+ */
+export function raycastScene(
+  scene: Scene | SceneObjectInput[],
+  origin: Vec3,
+  direction: Vec3,
+  opts?: RaycastSceneOptions,
+): SceneHit | null;
+
+/** Forgets the prepared query `raycastScene` keeps for a mesh (after editing it in place once `dirty` was cleared). */
+export function clearQueryCache(mesh: Mesh): void;

package/trid/index.js

@@ -81,3 +81,16 @@ export {
 
 // Random numbers and noise
 export { rng, noise2, noise3, fbm2, fbm3 } from "./math/noise.js";
+
+// Modeling
+export { spline, resamplePath } from "./modeling/curves.js";
+export { sweep } from "./modeling/sweep.js";
+export { loft } from "./modeling/loft.js";
+export { taperMesh, twistMesh, bendMesh, bulgeMesh } from "./modeling/deform.js";
+export { weldVertices, cleanMesh, validateMesh, fixWinding } from "./modeling/cleanup.js";
+export { subdivideMesh } from "./modeling/subdivide.js";
+export { blobMesh, blobField, sdfMesh } from "./modeling/blobs.js";
+export { bevelMesh } from "./modeling/bevel.js";
+export {
+  meshQuery, raycastMesh, pointInMesh, distanceToMesh, closestPointOnMesh, isClosed, raycastScene, clearQueryCache,
+} from "./modeling/query.js";

package/trid/math/projection.js

@@ -1,3 +1,9 @@
+/**
+ * Default vertical field of view: 50°, a normal lens (like most 3D tools).
+ * Wider shows more but makes everything smaller; set `camera.fov` to change it.
+ */
+export const DEFAULT_FOV = (50 * Math.PI) / 180;
+
 /**
  * Converts normalized device coordinates (-1 to +1)
  * into actual screen (pixel) coordinates.
@@ -36,11 +42,11 @@ export function screen(p, w, h) {
  * - larger z => appears smaller
  *
  * @param {{x:number, y:number, z:number}} p - 3D point (camera space)
- * @param {number} fov - Vertical field of view in radians (default: 90°)
+ * @param {number} fov - Vertical field of view in radians (default: `DEFAULT_FOV`, 50°)
  * @param {number} aspect - Canvas width / height (default: 1)
  * @returns {{x:number, y:number}} 2D projected point
  */
-export function project(p, fov = Math.PI / 2, aspect = 1) {
+export function project(p, fov = DEFAULT_FOV, aspect = 1) {
   const f = 1 / Math.tan(fov / 2);
   return {
     x: (p.x * f) / (p.z * aspect),

package/trid/math/transform.js

@@ -1,4 +1,6 @@
-import { project, screen } from "./projection.js";
+import { project, screen, DEFAULT_FOV } from "./projection.js";
+
+export { DEFAULT_FOV };
 
 /**
  * Camera object. Every field is optional and falls back to its default.
@@ -11,14 +13,11 @@ import { project, screen } from "./projection.js";
  * @property {number} [z=0] - Position on Z
  * @property {number} [yaw=0] - Turn around Y in radians (> 0 turns right)
  * @property {number} [pitch=0] - Tilt around X in radians (> 0 looks up)
- * @property {number} [fov=Math.PI/2] - Vertical field of view in radians
+ * @property {number} [fov=DEFAULT_FOV] - Vertical field of view in radians (default 50°)
  * @property {number} [near=0.01] - Near plane distance; closer geometry is clipped
  * @property {number} [far=1000] - Far distance; farther geometry isn't drawn (WebGL renderer only)
  */
 
-/** Default vertical field of view (90°). */
-export const DEFAULT_FOV = Math.PI / 2;
-
 /** Default near plane distance. */
 export const DEFAULT_NEAR = 0.01;