@woosh/meep-engine 3.27.0 → 3.28.0

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

@@ -1,460 +0,0 @@
-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

@@ -1,77 +0,0 @@
-<!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>