@woosh/meep-engine 3.20.0 → 3.22.0

package/src/shade/playground/vgeo_viewer/cut_geometry.js

@@ -0,0 +1,460 @@
+import { assert } from "../../../core/assert.js";
+import { UINT16_MAX } from "../../../core/binary/UINT16_MAX.js";
+import { hsv_to_rgb } from "../../../core/color/hsv/hsv_to_rgb.js";
+import {
+    decode_octahedron_to_unit
+} from "../../../core/geom/3d/normal/octahedron/decode_octahedron_to_unit.js";
+import { Attribute } from "../../renderer/geometry/Attribute.js";
+import { Geometry } from "../../renderer/geometry/Geometry.js";
+import { StandardAttributes } from "../../renderer/geometry/StandardAttributes.js";
+import {
+    VGEO_ATTRIBUTE
+} from "../../renderer/geometry/virtual/format/attribute/VGEO_ATTRIBUTE.js";
+import {
+    VGEO_ATTRIBUTES
+} from "../../renderer/geometry/virtual/format/attribute/VGEO_ATTRIBUTES.js";
+import {
+    vgeo_payload_attribute_offset
+} from "../../renderer/geometry/virtual/format/payload/vgeo_payload_attribute_offset.js";
+
+/**
+ * Turning a cut into something drawable.
+ *
+ * Payloads are `SHADE_MESHLET_V1`'s (`VGEO_FORMAT.md` §8): the index section first, three 8-bit
+ * local indices per triangle, then the attribute sections. Position is always read — it is raw
+ * float32, never constant-compressed — and the stored normal section only when a normal display asks
+ * for it, because the direct geometry path carries position and colour per vertex and nowhere to put
+ * the rest.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Everything in the container is little-endian (§2).
+ * @type {boolean}
+ */
+const LE = true;
+
+/**
+ * The `encoding_flags` bit that says a cluster's normal section holds one constant-compressed word
+ * for the whole cluster instead of one per vertex.
+ * @type {number}
+ */
+const NORMAL_COMPRESSION_FLAG = VGEO_ATTRIBUTES[VGEO_ATTRIBUTE.NORMAL].compression_flag;
+
+/**
+ * What a cluster's colour is keyed on.
+ *
+ * The two normal modes are not keyed on the cluster at all: they paint every vertex with its own
+ * direction, and the cluster boundaries go with it. `stored normal` is the container's own
+ * {@link VGEO_ATTRIBUTE.NORMAL}, decoded out of the payload — the only mode that shows an attribute
+ * the file carries rather than something derived from it. `geometric normal` is the area-weighted
+ * normal of the decoded triangles, which is what every other mode shades with. The pair is the
+ * point: they agree where the builder's normals still describe the geometry it shipped, and a source
+ * with no normals at all makes the first one flat.
+ *
+ * `clamp` is the streaming one: it paints the clusters a coarser page is standing in for, so the
+ * regions still waiting on bytes are visible as regions rather than as a number in a panel.
+ *
+ * @enum {string}
+ */
+export const VGEO_COLOR_MODE = {
+    Cluster: 'cluster',
+    Group: 'group',
+    Page: 'page',
+    Level: 'level',
+    Error: 'error',
+    Clamp: 'clamp',
+    StoredNormal: 'stored normal',
+    GeometricNormal: 'geometric normal',
+};
+
+/**
+ * Key colours are spread by the golden ratio so that adjacent ids never land on adjacent hues —
+ * neighbouring clusters are exactly what has to be told apart.
+ * @type {number}
+ */
+const HUE_STEP = 0.6180339887498949;
+
+/**
+ * Key lights, baked into vertex colour.
+ *
+ * The direct path carries position and colour per vertex and nothing else — no normal reaches the
+ * shader — so shading happens here, once per cut, against normals derived from the decoded
+ * triangles. Two opposed lights and a generous ambient, so that no part of the surface is black and
+ * every cluster's colour stays readable wherever it faces.
+ *
+ * @type {number[]}
+ */
+const KEY_LIGHT = [0.35, 0.78, 0.52];
+
+/**
+ * @type {number[]}
+ */
+const FILL_LIGHT = [-0.55, -0.25, -0.79];
+
+/**
+ * Ceiling on a baked colour's brightest channel.
+ *
+ * The pass draws at `AfterTransparency`, so everything it writes still goes through the tonemapper,
+ * and the tonemapper desaturates as it approaches white. Pushed to 1.0 the clusters come out pastel
+ * and stop being tellable apart, which defeats the only thing the colour is for — so the shading
+ * range is deliberately kept below it.
+ *
+ * @type {number}
+ */
+const COLOR_CEILING = 0.9;
+
+/**
+ * One cluster's worth of decoded stored normals, reused across clusters.
+ *
+ * Sized for the largest cluster a `u8` `vertex_count` can *state* rather than the largest the format
+ * permits, which is 128. The two differ only on a file that has broken §11 — and with validation off
+ * by default, nothing upstream has looked. A scratch that is twice as large as it needs to be costs
+ * three kilobytes; a short one would come back as a handful of quietly wrong colours.
+ *
+ * @type {Float32Array}
+ */
+const stored_normals = new Float32Array(256 * 3);
+
+/**
+ * One decoded direction, on its way from the octahedral codec into a caller's array.
+ * @type {Float32Array}
+ */
+const scratch_direction = new Float32Array(3);
+
+/**
+ * Decode one cluster's stored normal section into unit vectors.
+ *
+ * The section is one octahedral `u32` per vertex, or a single word for the whole cluster when the
+ * encoder found every vertex agreeing — which is also what a source lacking normals encodes to, so
+ * the constant case is the ordinary one and not an exception. A stride of zero is what reads it:
+ * every vertex fetches the same word, and the loop does not have to know which case it is in.
+ *
+ * @param {VGeoPage} page
+ * @param {number} cluster index within the page
+ * @param {Float32Array} out at least `3 · vertex_count` long
+ */
+function read_cluster_normals(page, cluster, out) {
+    const vertex_count = page.vertex_count[cluster];
+
+    assert.greaterThanOrEqual(
+        out.length, vertex_count * 3, 'out must hold three components per cluster vertex'
+    );
+
+    const encoding_flags = page.encoding_flags[cluster];
+
+    const at = page.payload_at(cluster)
+        + vgeo_payload_attribute_offset(
+            VGEO_ATTRIBUTE.NORMAL, vertex_count, page.triangle_count[cluster], encoding_flags
+        );
+
+    const stride = (encoding_flags & NORMAL_COMPRESSION_FLAG) === 0 ? 4 : 0;
+
+    for (let i = 0; i < vertex_count; i++) {
+        const word = page.data.getUint32(at + i * stride, LE);
+
+        const u = ((word & 0xFFFF) / UINT16_MAX) * 2 - 1;
+        const v = (((word >>> 16) & 0xFFFF) / UINT16_MAX) * 2 - 1;
+
+        decode_octahedron_to_unit(scratch_direction, 0, u, v);
+
+        /*
+         The encoder hands the octahedral codec `(nx, nz, ny)` — Shade's own convention, matched so
+         that a `.vgeo` payload is byte for byte a `MeshletBatch` one — so the decode comes back in
+         that order and has to be put back.
+         */
+        out[i * 3] = scratch_direction[0];
+        out[i * 3 + 1] = scratch_direction[2];
+        out[i * 3 + 2] = scratch_direction[1];
+    }
+}
+
+/**
+ * Paint a run of vertices with their own directions and no shading: `rgb = n · 0.5 + 0.5`, scaled by
+ * {@link COLOR_CEILING} for the same reason every other mode is.
+ *
+ * Unlit on purpose. A direction multiplied by how much light it happens to catch is unreadable
+ * exactly where reading it matters — a normal facing away from both lights would come out black, and
+ * black is not a direction.
+ *
+ * @param {Float32Array} colors four per vertex
+ * @param {number} first index of the run's first vertex
+ * @param {number} count vertices in the run
+ * @param {Float32Array} directions unit vectors, three components apiece
+ * @param {number} directions_offset index of the run's first component within `directions`
+ */
+function paint_directions(colors, first, count, directions, directions_offset) {
+    for (let i = 0; i < count; i++) {
+        const d = directions_offset + i * 3;
+        const o = (first + i) * 4;
+
+        colors[o] = COLOR_CEILING * (directions[d] * 0.5 + 0.5);
+        colors[o + 1] = COLOR_CEILING * (directions[d + 1] * 0.5 + 0.5);
+        colors[o + 2] = COLOR_CEILING * (directions[d + 2] * 0.5 + 0.5);
+        colors[o + 3] = 1;
+    }
+}
+
+/**
+ * A cut, decoded into one geometry.
+ *
+ * Nothing about it depends on where the camera is: the mesh is drawn solid and the depth buffer
+ * orders it, so the triangle list is uploaded once when the cut is taken and never touched again.
+ */
+export class VGeoCutGeometry {
+    /**
+     * Position and colour, indexed by {@link triangles}.
+     * @type {Geometry}
+     */
+    geometry = new Geometry();
+
+    /**
+     * `3 · triangle_count` — the full triangle list, in cluster order, and the geometry's index.
+     * @type {Uint32Array}
+     */
+    triangles = new Uint32Array(0);
+
+    /**
+     * @type {number}
+     */
+    triangle_count = 0;
+
+    /**
+     * @type {number}
+     */
+    vertex_count = 0;
+}
+
+/**
+ * Decode the selected clusters into one geometry.
+ *
+ * @param {VGeoCut} cut
+ * @param {VGEO_COLOR_MODE} color_mode
+ * @returns {VGeoCutGeometry}
+ */
+export function vgeo_build_cut_geometry(cut, color_mode) {
+    const vertex_count = cut.vertex_count;
+    const triangle_count = cut.triangle_count;
+
+    const positions = new Float32Array(vertex_count * 3);
+    const colors = new Float32Array(vertex_count * 4);
+    const normals = new Float32Array(vertex_count * 3);
+
+    const result = new VGeoCutGeometry();
+
+    result.triangles = new Uint32Array(triangle_count * 3);
+    result.triangle_count = triangle_count;
+    result.vertex_count = vertex_count;
+
+    const triangles = result.triangles;
+
+    const count = cut.clusters.length;
+
+    /*
+     The error ramp spans the *cut's* own errors, not the file's. Normalizing against the coarsest
+     error in the container would be defensible and useless: a fine cut's clusters all sit orders of
+     magnitude below it and the whole model comes out one flat colour. What the question actually is
+     — which parts of this cut settled for more error than the rest — is a question about this cut.
+     */
+    let error_low = Number.POSITIVE_INFINITY;
+    let error_high = 0;
+
+    for (let c = 0; c < count; c++) {
+        const error = cut.pages[c].self_error[cut.clusters[c]];
+
+        error_low = Math.min(error_low, error);
+        error_high = Math.max(error_high, error);
+    }
+
+    const error_span = error_high - error_low;
+
+    /**
+     * First vertex of each selected cluster, so colour can be applied per cluster after the normals
+     * are known.
+     * @type {Uint32Array}
+     */
+    const cluster_vertex_first = new Uint32Array(count);
+
+    let vertex_cursor = 0;
+    let triangle_cursor = 0;
+
+    for (let c = 0; c < count; c++) {
+        const page = cut.pages[c];
+        const id = cut.clusters[c];
+
+        const cluster_vertices = page.vertex_count[id];
+        const cluster_triangles = page.triangle_count[id];
+
+        const payload = page.payload_at(id);
+
+        cluster_vertex_first[c] = vertex_cursor;
+
+        const position_at = payload + vgeo_payload_attribute_offset(
+            VGEO_ATTRIBUTE.POSITION, cluster_vertices, cluster_triangles, page.encoding_flags[id]
+        );
+
+        /*
+         Read a word at a time rather than viewed in place: a Float32Array view demands 4-byte
+         alignment against the *page's* buffer, which is a property of where the decode happened to
+         land it and not something the format promises.
+         */
+        for (let i = 0; i < cluster_vertices * 3; i++) {
+            positions[vertex_cursor * 3 + i] = page.data.getFloat32(position_at + i * 4, LE);
+        }
+
+        for (let i = 0; i < cluster_triangles * 3; i++) {
+            triangles[triangle_cursor * 3 + i] = vertex_cursor + page.bytes[payload + i];
+        }
+
+        vertex_cursor += cluster_vertices;
+        triangle_cursor += cluster_triangles;
+    }
+
+    assert.equal(vertex_cursor, vertex_count, 'decoded vertices must match the cut');
+    assert.equal(triangle_cursor, triangle_count, 'decoded triangles must match the cut');
+
+    // Area-weighted vertex normals, which is all shading reads. Clusters share no vertices, so
+    // accumulating over the whole list still gives each cluster its own smoothing — the crease that
+    // leaves at a cluster seam is a feature here, not an artefact.
+    for (let t = 0; t < triangle_count; t++) {
+        const a = triangles[t * 3] * 3;
+        const b = triangles[t * 3 + 1] * 3;
+        const c = triangles[t * 3 + 2] * 3;
+
+        const abx = positions[b] - positions[a];
+        const aby = positions[b + 1] - positions[a + 1];
+        const abz = positions[b + 2] - positions[a + 2];
+
+        const acx = positions[c] - positions[a];
+        const acy = positions[c + 1] - positions[a + 1];
+        const acz = positions[c + 2] - positions[a + 2];
+
+        const nx = aby * acz - abz * acy;
+        const ny = abz * acx - abx * acz;
+        const nz = abx * acy - aby * acx;
+
+        normals[a] += nx; normals[a + 1] += ny; normals[a + 2] += nz;
+        normals[b] += nx; normals[b + 1] += ny; normals[b + 2] += nz;
+        normals[c] += nx; normals[c + 1] += ny; normals[c + 2] += nz;
+    }
+
+    // Normalized here rather than where they are read, because two things read them now — the
+    // shading, and `geometric normal` — and a direction is the same direction for both.
+    for (let v = 0; v < vertex_count; v++) {
+        const n = v * 3;
+
+        const length = Math.hypot(normals[n], normals[n + 1], normals[n + 2]);
+
+        // A vertex left with no area around it has no direction to give. Zero shades as ambient and
+        // displays as mid grey, and both say "nothing here" rather than inventing an answer.
+        const scale = length > 0 ? 1 / length : 0;
+
+        normals[n] *= scale;
+        normals[n + 1] *= scale;
+        normals[n + 2] *= scale;
+    }
+
+    const tint = new Float32Array(3);
+
+    for (let c = 0; c < count; c++) {
+        const page = cut.pages[c];
+        const id = cut.clusters[c];
+
+        const first = cluster_vertex_first[c];
+        const vertices = page.vertex_count[id];
+
+        if (color_mode === VGEO_COLOR_MODE.StoredNormal) {
+            read_cluster_normals(page, id, stored_normals);
+
+            paint_directions(colors, first, vertices, stored_normals, 0);
+
+            continue;
+        }
+
+        if (color_mode === VGEO_COLOR_MODE.GeometricNormal) {
+            paint_directions(colors, first, vertices, normals, first * 3);
+
+            continue;
+        }
+
+        if (color_mode === VGEO_COLOR_MODE.Error) {
+            // cool where the cut is refined, hot where it settled for the most error
+            const t = error_span > 0 ? (page.self_error[id] - error_low) / error_span : 0;
+
+            hsv_to_rgb(tint, 0, 0.68 * (1 - t), 0.9, 1);
+        } else if (color_mode === VGEO_COLOR_MODE.Clamp) {
+            /*
+             Two colours and nothing in between. Amber is a cluster standing in for a page that has
+             not arrived; slate is the cut the container's metric actually selects. The question this
+             mode answers is where, not how much, so a ramp would only make it harder to read.
+             */
+            const waiting = cut.clamped_keys.has(page.index * 65536 + id);
+
+            tint[0] = waiting ? 1 : 0.42;
+            tint[1] = waiting ? 0.66 : 0.52;
+            tint[2] = waiting ? 0.16 : 0.62;
+        } else {
+            hsv_to_rgb(tint, 0, (color_key(page, id, color_mode) * HUE_STEP) % 1, 0.85, 1);
+        }
+
+        const end = first + vertices;
+
+        for (let v = first; v < end; v++) {
+            const n = v * 3;
+
+            const nx = normals[n];
+            const ny = normals[n + 1];
+            const nz = normals[n + 2];
+
+            const key_term = Math.max(
+                0, nx * KEY_LIGHT[0] + ny * KEY_LIGHT[1] + nz * KEY_LIGHT[2]
+            );
+
+            const fill_term = Math.max(
+                0, nx * FILL_LIGHT[0] + ny * FILL_LIGHT[1] + nz * FILL_LIGHT[2]
+            );
+
+            const shade = COLOR_CEILING * (0.22 + 0.60 * key_term + 0.18 * fill_term);
+
+            colors[v * 4] = tint[0] * shade;
+            colors[v * 4 + 1] = tint[1] * shade;
+            colors[v * 4 + 2] = tint[2] * shade;
+            colors[v * 4 + 3] = 1;
+        }
+    }
+
+    result.geometry.addAttribute(Attribute.from(positions, 3, StandardAttributes.Position));
+    result.geometry.addAttribute(Attribute.from(colors, 4, StandardAttributes.Color));
+    result.geometry.index = Attribute.from(result.triangles, 1, StandardAttributes.Index);
+
+    return result;
+}
+
+/**
+ * What a hue is spread from, for the modes that key on an identity rather than on a value.
+ *
+ * Page index enters the cluster and group keys because clusters are numbered per page now, exactly
+ * as the format numbers them — without it, cluster 0 of every page would come out the same colour.
+ *
+ * @param {VGeoPage} page
+ * @param {number} cluster
+ * @param {VGEO_COLOR_MODE} color_mode
+ * @returns {number}
+ */
+function color_key(page, cluster, color_mode) {
+    switch (color_mode) {
+        case VGEO_COLOR_MODE.Group:
+            return page.index * 65536 + page.group_of_cluster[cluster];
+        case VGEO_COLOR_MODE.Page:
+            return page.index;
+        case VGEO_COLOR_MODE.Level:
+            // A non-root page spans one contiguous band, so its min is the level of everything in
+            // it; the root page is the one that can span several and there is nothing per cluster to
+            // read it from.
+            return page.min_level;
+        default:
+            return page.index * 65536 + cluster;
+    }
+}

package/src/shade/playground/vgeo_viewer/index.html

@@ -0,0 +1,77 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — .vgeo viewer</title>
+
+    <!-- an empty icon rather than none: the browser asks for /favicon.ico otherwise, and a 404 in
+         the console of a debugging tool is noise where noise is the signal -->
+    <link rel="icon" href="data:,">
+
+    <style>
+        :root { color-scheme: dark; }
+
+        html, body { height: 100%; margin: 0; overflow: hidden; background: #070b10; }
+
+        /* the canvas is appended to the body at start-up, so it comes after both of these in DOM
+           order and would paint over them without a stacking order of their own */
+        #vgeo-panel {
+            position: absolute; top: 0; right: 0; width: 340px; max-height: 100vh; overflow-y: auto;
+            z-index: 10; padding: 12px 14px; box-sizing: border-box;
+            font: 12px/1.45 ui-monospace, "Cascadia Mono", Consolas, monospace;
+            color: #dfe6ee; background: rgba(12, 16, 22, 0.88);
+            border-left: 1px solid #2b3947;
+        }
+
+        #vgeo-panel h1 { margin: 0 0 8px; font-size: 13px; letter-spacing: 0.06em; color: #7fd2ff; }
+
+        #vgeo-panel h2 {
+            margin: 14px 0 6px; font-size: 11px; letter-spacing: 0.12em; text-transform: uppercase;
+            color: #6b7c8d; border-bottom: 1px solid #24313d; padding-bottom: 3px;
+        }
+
+        #vgeo-panel .row { display: flex; justify-content: space-between; gap: 8px; }
+        #vgeo-panel .row span:last-child { color: #f2f6fa; text-align: right; }
+        #vgeo-panel .count { font-size: 30px; line-height: 1.1; color: #8fe388; }
+        #vgeo-panel .muted { color: #6b7c8d; }
+        #vgeo-panel .bad { color: #ff8a7a; }
+        #vgeo-panel .warn { color: #ffbe55; }
+        #vgeo-panel .good { color: #8fe388; }
+
+        #vgeo-panel button {
+            width: 100%; margin: 8px 0 2px; padding: 7px; cursor: pointer;
+            font: inherit; color: #061018; background: #7fd2ff; border: 0; border-radius: 3px;
+        }
+
+        #vgeo-panel button:hover { background: #a5e0ff; }
+        #vgeo-panel button:disabled { opacity: 0.4; cursor: default; }
+        #vgeo-panel label { display: flex; align-items: center; gap: 6px; margin: 3px 0; cursor: pointer; }
+        #vgeo-panel input[type=range] { width: 100%; }
+
+        #vgeo-panel select {
+            width: 100%; font: inherit; background: #16202b; color: #dfe6ee;
+            border: 1px solid #2b3947; padding: 3px;
+        }
+
+        #vgeo-panel ol { margin: 4px 0; padding-left: 18px; }
+
+        #vgeo-drop {
+            position: absolute; inset: 0; z-index: 20;
+            display: none; align-items: center; justify-content: center;
+            font: 20px ui-monospace, monospace; color: #7fd2ff;
+            background: rgba(6, 12, 20, 0.82); border: 3px dashed #7fd2ff; box-sizing: border-box;
+        }
+
+        #vgeo-drop.active { display: flex; }
+    </style>
+</head>
+<body>
+
+<div id="vgeo-drop">drop a .vgeo file</div>
+
+<div id="vgeo-panel"><h1>.vgeo viewer</h1></div>
+
+<script type="module" src="./main.js"></script>
+
+</body>
+</html>

package/src/shade/playground/vgeo_viewer/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/vgeo_viewer/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vgeo_viewer/main.js"],"names":[],"mappings":""}