3draft 26.11.1013 → 26.11.3001

package/dist/csg.js

@@ -0,0 +1,239 @@
+// Boolean operations on closed solids: union, subtract (a - b) and intersect.
+// A BSP tree per solid (after Evan Wallace's csg.js): polygons are cut by the planes of the other solid
+// and the pieces inside or outside are kept, so every result face stays planar and convex, which is what
+// the rest of the engine assumes. The result is welded and its T-junctions are closed, so it is a closed
+// solid again and can go into the next boolean. Faces keep the color and material of the face they came from;
+// a face cut into a solid by the other one takes the color of the cutting face.
+import { sub, dot, cross, len } from './vec.js';
+import { faceNormal, bounds } from './mesh.js';
+import { validate } from './check.js';
+let CSG_EPS = 1e-6; // set per operation, relative to the size of the two solids
+const unit = (v) => {
+    const l = len(v) || 1;
+    return [v[0] / l, v[1] / l, v[2] / l];
+};
+const polysOf = (mesh) => mesh.faces.flatMap((f) => {
+    const pts = f.v.map((k) => mesh.positions[k]);
+    const n = unit(faceNormal(pts));
+    return len(faceNormal(pts)) < 1e-12 ? [] : [{ pts, n, w: dot(n, pts[0]), color: f.color, mat: f.mat }];
+});
+const flip = (p) => ({ ...p, pts: [...p.pts].reverse(), n: [-p.n[0], -p.n[1], -p.n[2]], w: -p.w });
+/** Cuts `p` by the plane into the four buckets. */
+const splitPoly = (plane, p, cf, cb, front, back) => {
+    const COPLANAR = 0;
+    const FRONT = 1;
+    const BACK = 2;
+    const SPANNING = 3;
+    let type = 0;
+    const types = p.pts.map((q) => {
+        const t = dot(plane.n, q) - plane.w;
+        const k = t < -CSG_EPS ? BACK : t > CSG_EPS ? FRONT : COPLANAR;
+        type |= k;
+        return k;
+    });
+    if (type === COPLANAR)
+        (dot(plane.n, p.n) > 0 ? cf : cb).push(p);
+    else if (type === FRONT)
+        front.push(p);
+    else if (type === BACK)
+        back.push(p);
+    else if (type === SPANNING) {
+        const f = [];
+        const b = [];
+        for (let i = 0; i < p.pts.length; i++) {
+            const j = (i + 1) % p.pts.length;
+            const ti = types[i];
+            const tj = types[j];
+            const vi = p.pts[i];
+            const vj = p.pts[j];
+            if (ti !== BACK)
+                f.push(vi);
+            if (ti !== FRONT)
+                b.push(vi);
+            if ((ti | tj) === SPANNING) {
+                const t = (plane.w - dot(plane.n, vi)) / dot(plane.n, sub(vj, vi));
+                const v = [vi[0] + (vj[0] - vi[0]) * t, vi[1] + (vj[1] - vi[1]) * t, vi[2] + (vj[2] - vi[2]) * t];
+                f.push(v);
+                b.push(v);
+            }
+        }
+        if (f.length >= 3)
+            front.push({ ...p, pts: f });
+        if (b.length >= 3)
+            back.push({ ...p, pts: b });
+    }
+};
+const build = (node, polys) => {
+    if (!polys.length)
+        return;
+    if (!node.plane)
+        node.plane = { n: polys[0].n, w: polys[0].w };
+    const front = [];
+    const back = [];
+    for (const p of polys)
+        splitPoly(node.plane, p, node.polys, node.polys, front, back);
+    if (front.length)
+        build((node.front ??= { plane: null, front: null, back: null, polys: [] }), front);
+    if (back.length)
+        build((node.back ??= { plane: null, front: null, back: null, polys: [] }), back);
+};
+const tree = (polys) => {
+    const node = { plane: null, front: null, back: null, polys: [] };
+    build(node, polys);
+    return node;
+};
+const invert = (node) => {
+    node.polys = node.polys.map(flip);
+    if (node.plane)
+        node.plane = { n: [-node.plane.n[0], -node.plane.n[1], -node.plane.n[2]], w: -node.plane.w };
+    invert0(node);
+};
+const invert0 = (node) => {
+    if (node.front)
+        invert(node.front);
+    if (node.back)
+        invert(node.back);
+    [node.front, node.back] = [node.back, node.front];
+};
+/** The parts of `polys` that are outside the solid of `node`. */
+const clipPolys = (node, polys) => {
+    if (!node.plane)
+        return [...polys];
+    let front = [];
+    let back = [];
+    for (const p of polys)
+        splitPoly(node.plane, p, front, back, front, back);
+    front = node.front ? clipPolys(node.front, front) : front;
+    back = node.back ? clipPolys(node.back, back) : [];
+    return [...front, ...back];
+};
+const clipTo = (node, other) => {
+    node.polys = clipPolys(other, node.polys);
+    if (node.front)
+        clipTo(node.front, other);
+    if (node.back)
+        clipTo(node.back, other);
+};
+const all = (node) => [...node.polys, ...(node.front ? all(node.front) : []), ...(node.back ? all(node.back) : [])];
+/** Polygons to a welded mesh: shared vertices, no sliver faces, T-junctions closed. */
+const toMesh = (polys, scale) => {
+    const cell = scale * 1e-5;
+    const ids = new Map();
+    const positions = [];
+    const weld = (p) => {
+        // look in the neighbouring cells too, so a point on a cell border still finds its twin
+        const base = p.map((c) => Math.round(c / cell));
+        for (let dx = -1; dx <= 1; dx++)
+            for (let dy = -1; dy <= 1; dy++)
+                for (let dz = -1; dz <= 1; dz++) {
+                    const hit = ids.get(`${base[0] + dx},${base[1] + dy},${base[2] + dz}`);
+                    if (hit !== undefined && len(sub(positions[hit], p)) <= cell * 1.5)
+                        return hit;
+                }
+        ids.set(base.join(','), positions.length);
+        positions.push(p);
+        return positions.length - 1;
+    };
+    let faces = polys.flatMap((p) => {
+        const v = [];
+        for (const q of p.pts) {
+            const k = weld(q);
+            if (v[v.length - 1] !== k)
+                v.push(k);
+        }
+        if (v.length > 1 && v[0] === v[v.length - 1])
+            v.pop();
+        if (v.length < 3)
+            return [];
+        const n = faceNormal(v.map((k) => positions[k]));
+        return len(n) < 1e-9 * scale * scale ? [] : [{ v, color: p.color, mat: p.mat }];
+    });
+    // T-junctions: a vertex lying on the edge of a neighbouring face gets inserted into that edge
+    const used = new Set(faces.flatMap((f) => f.v));
+    const verts = [...used];
+    if (verts.length * faces.length < 6e7) {
+        const tol = scale * 1e-5 * 3;
+        faces = faces.map((f) => {
+            const out = [];
+            for (let i = 0; i < f.v.length; i++) {
+                const a = f.v[i];
+                const b = f.v[(i + 1) % f.v.length];
+                out.push(a);
+                const pa = positions[a];
+                const pb = positions[b];
+                const d = sub(pb, pa);
+                const dl = len(d);
+                if (dl < tol * 4)
+                    continue;
+                const on = [];
+                for (const k of verts) {
+                    if (k === a || k === b)
+                        continue;
+                    const pk = positions[k];
+                    const t = dot(sub(pk, pa), d) / (dl * dl);
+                    if (t <= 0 || t >= 1)
+                        continue;
+                    if (len(cross(sub(pk, pa), d)) / dl <= tol)
+                        on.push({ t, k });
+                }
+                on.sort((x, y) => x.t - y.t);
+                for (const { k } of on)
+                    out.push(k);
+            }
+            return { ...f, v: out };
+        });
+    }
+    return { positions, faces };
+};
+const closedSolid = (name, m) => {
+    const v = validate(m);
+    if (!v.closed)
+        throw new Error(`boolean needs closed solids: ${name} has ${v.openEdges} open edge(s)`);
+    if (v.inside_out)
+        throw new Error(`boolean needs outward faces: ${name} is inside out`);
+};
+/**
+ * Boolean of two closed solids (outward CCW faces): 'union', 'subtract' (a minus b) or 'intersect'.
+ * Throws with a reason when an input is open or inside out.
+ */
+export const boolean = (a, b, op) => {
+    closedSolid('a', a);
+    closedSolid('b', b);
+    const sa = bounds(a);
+    const sb = bounds(b);
+    const scale = Math.max(sa.radius, sb.radius, 1e-9) * 2 + len(sub(sa.center, sb.center));
+    CSG_EPS = scale * 1e-9 * 1000;
+    const A = tree(polysOf(a));
+    const B = tree(polysOf(b));
+    if (op === 'union') {
+        clipTo(A, B);
+        clipTo(B, A);
+        invert(B);
+        clipTo(B, A);
+        invert(B);
+        build(A, all(B));
+    }
+    else if (op === 'subtract') {
+        invert(A);
+        clipTo(A, B);
+        clipTo(B, A);
+        invert(B);
+        clipTo(B, A);
+        invert(B);
+        build(A, all(B));
+        invert(A);
+    }
+    else {
+        invert(A);
+        clipTo(B, A);
+        invert(B);
+        clipTo(A, B);
+        clipTo(B, A);
+        build(A, all(B));
+        invert(A);
+    }
+    return toMesh(all(A), scale);
+};
+export const union = (a, b) => boolean(a, b, 'union');
+export const subtract = (a, b) => boolean(a, b, 'subtract');
+export const intersect = (a, b) => boolean(a, b, 'intersect');

package/dist/edit.d.ts

@@ -0,0 +1,23 @@
+import type { Mesh, Vec3 } from './types.js';
+/**
+ * Extrude a face: it is replaced (same index) by a copy moved `distance` along its
+ * normal and scaled by `scale` about its center, and one quad per edge joins the two.
+ *   distance > 0, scale 1      a prism out of the face
+ *   distance > 0, scale < 1    a taper (roof, spire, frustum)
+ *   distance 0,   scale < 1    an inset (a panel, a window frame)
+ *   distance < 0               a dent into the solid (a niche, a door recess)
+ * The new quads are appended after the existing faces; `color` recolors the cap and
+ * the quads, otherwise they keep the face color.
+ * Returns { mesh, cap, sides } with the index of the cap face and the new quad indices.
+ */
+export declare const extrudeFace: (mesh: Mesh, index: number, { distance, scale, color }?: {
+    distance?: number;
+    scale?: number;
+    color?: string;
+}) => {
+    mesh: Mesh;
+    cap: number;
+    sides: number[];
+};
+/** Move the vertices at `indices` by `delta` [dx, dy, dz]. Faces keep their vertices, so faces may stop being planar: check with validate(). */
+export declare const moveVertices: (mesh: Mesh, indices: number[], delta: Vec3) => Mesh;

package/dist/edit.js

@@ -0,0 +1,48 @@
+// Shaping an existing mesh: the topology edits a modeller does by hand.
+// Both functions return a NEW mesh; faces stay CCW from outside and closed meshes stay closed.
+import { add, sub, scale as mul, norm } from './vec.js';
+import { faceNormal, faceCenter } from './mesh.js';
+/**
+ * Extrude a face: it is replaced (same index) by a copy moved `distance` along its
+ * normal and scaled by `scale` about its center, and one quad per edge joins the two.
+ *   distance > 0, scale 1      a prism out of the face
+ *   distance > 0, scale < 1    a taper (roof, spire, frustum)
+ *   distance 0,   scale < 1    an inset (a panel, a window frame)
+ *   distance < 0               a dent into the solid (a niche, a door recess)
+ * The new quads are appended after the existing faces; `color` recolors the cap and
+ * the quads, otherwise they keep the face color.
+ * Returns { mesh, cap, sides } with the index of the cap face and the new quad indices.
+ */
+export const extrudeFace = (mesh, index, { distance = 0, scale = 1, color } = {}) => {
+    const face = mesh.faces[index];
+    if (!face)
+        throw new Error(`no face ${index}: this mesh has ${mesh.faces.length} faces`);
+    if (!(scale > 0))
+        throw new Error('scale must be positive');
+    if (distance === 0 && scale === 1)
+        throw new Error('nothing to do: give a distance or a scale other than 1');
+    const pts = face.v.map((k) => mesh.positions[k]);
+    const n = norm(faceNormal(pts));
+    const c = faceCenter(pts);
+    const moved = pts.map((p) => add(add(c, mul(sub(p, c), scale)), mul(n, distance)));
+    const base = mesh.positions.length;
+    const m = pts.length;
+    const tint = color ?? face.color;
+    const faces = mesh.faces.map((f, i) => (i === index ? { ...f, v: moved.map((_, j) => base + j), color: tint } : f));
+    const sides = [];
+    for (let i = 0; i < m; i++) {
+        sides.push(faces.length);
+        faces.push({ v: [face.v[i], face.v[(i + 1) % m], base + ((i + 1) % m), base + i], color: tint });
+    }
+    return { mesh: { positions: [...mesh.positions, ...moved], faces }, cap: index, sides };
+};
+/** Move the vertices at `indices` by `delta` [dx, dy, dz]. Faces keep their vertices, so faces may stop being planar: check with validate(). */
+export const moveVertices = (mesh, indices, delta) => {
+    const set = new Set();
+    for (const i of indices) {
+        if (!Number.isInteger(i) || i < 0 || i >= mesh.positions.length)
+            throw new Error(`vertex ${i} does not exist: this mesh has ${mesh.positions.length} vertices`);
+        set.add(i);
+    }
+    return { ...mesh, positions: mesh.positions.map((p, i) => (set.has(i) ? add(p, delta) : p)) };
+};

package/dist/gpu.d.ts

@@ -0,0 +1,77 @@
+import type { Palette } from './material.js';
+import type { Axes, Camera, Fit, Mesh, Vec3, ViewName, ViewSpec } from './types.js';
+type Handle = any;
+export interface GpuLight {
+    /** Direction towards the light, world space. */
+    direction?: Vec3;
+    /** Hemisphere ambient colors (rgb 0..1): up and down. */
+    sky?: Vec3;
+    ground?: Vec3;
+}
+export interface GpuMaterial {
+    ambient?: number;
+    diffuse?: number;
+    specular?: number;
+    shininess?: number;
+}
+export interface GpuRenderOptions {
+    /** CSS pixels, the canvas becomes size x size (times dpr in device pixels). */
+    size?: number;
+    fit?: Fit;
+    /** Clear color, rgb 0..1. */
+    background?: Vec3;
+    light?: GpuLight;
+    material?: GpuMaterial;
+    /** Named materials the faces point at (`face.mat`); pass a new object when an entry changes. */
+    palette?: Palette;
+    dpr?: number;
+    /** Many copies of one prototype mesh (modelled around the origin), drawn after `mesh`. */
+    instances?: {
+        mesh: Mesh;
+        data: Float32Array;
+    };
+}
+/** One copy of a prototype: its position, orthonormal frame and color. */
+export interface Instance {
+    at: Vec3;
+    axes: Axes;
+    color?: string;
+}
+export interface Pixels {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+}
+export interface Gpu {
+    render(mesh: Mesh, view: ViewName | ViewSpec, options?: GpuRenderOptions): void;
+    /** Same frame, drawn offscreen and read back as RGBA (tests, thumbnails). */
+    pixels(mesh: Mesh, view: ViewName | ViewSpec, options?: GpuRenderOptions): Promise<Pixels>;
+    destroy(): void;
+    device: Handle;
+    adapter: Handle;
+}
+/**
+ * Column-major 4x4 matrix (for WebGPU, z in 0..1) that maps world points exactly
+ * like camera.project(): the same pixels, plus a depth between near and far.
+ */
+export declare const viewProjection: (cam: Camera, near?: number, far?: number) => Float32Array;
+/** Triangle list for the GPU: flat face normals, face colors and materials. Float32Array, 13 floats per vertex. */
+export declare const buildVertices: (mesh: Mesh, palette?: Palette) => Float32Array;
+/**
+ * Per-instance data for drawInstances: one entry { at, axes: [ex, ey, ez], color } per copy of a
+ * prototype mesh (modelled around the origin). Float32Array, 15 floats per instance.
+ */
+export declare const buildInstances: (items: Instance[]) => Float32Array;
+export declare const defaultLight: Required<GpuLight>;
+export declare const defaultMaterial: Required<GpuMaterial>;
+/**
+ * Sets up WebGPU on a canvas. Rejects when WebGPU is not available.
+ * Returns { render(mesh, view, options), destroy() }.
+ * render options: size (CSS px, the canvas is made size x size), fit, instances { mesh, data } (many copies of one
+ * prototype mesh, data from buildInstances; drawn after the mesh), background [r,g,b] 0..1,
+ * light { direction, sky, ground }, material { ambient, diffuse, specular, shininess }, dpr.
+ */
+export declare const createGpu: (canvas: HTMLCanvasElement, { sampleCount }?: {
+    sampleCount?: number;
+}) => Promise<Gpu>;
+export {};