@woosh/meep-engine 3.56.0 → 3.58.0

package/src/generation/foliage/analysis/crown_opacity_measure.js

@@ -0,0 +1,627 @@
+import { tri2_rasterize_barycentric } from "../../../core/geom/2d/triangle/tri2_rasterize_barycentric.js";
+import { assert } from "../../../core/assert.js";
+import { typed_array_value_denormalize } from "../../../core/collection/array/typed/typed_array_value_denormalize.js";
+import { convex_hull_monotone_2d } from "../../../core/geom/2d/convex-hull/convex_hull_monotone_2d.js";
+import { clamp } from "../../../core/math/clamp.js";
+import {
+    computeUnsignedDistanceField_Chamfer
+} from "../../../engine/graphics/texture/sampler/distance/computeUnsignedDistanceField_Chamfer.js";
+import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
+import { StandardAttributes } from "../../../shade/renderer/geometry/StandardAttributes.js";
+import { CrownOpacity } from "./CrownOpacity.js";
+import { crown_opacity_frames } from "./crown_opacity_frames.js";
+
+/**
+ * The FIA five-foot rule (Schomaker et al. 2007, glossary): foliage more than this far below the crown above it is a
+ * straggler, not part of the live crown. 5 ft in metres.
+ * @type {number}
+ */
+const FIVE_FOOT_RULE = 1.524;
+
+/**
+ * Normal visual acuity, one minute of arc, as a tangent: the finest detail a rater sees, per metre of viewing distance.
+ * @type {number}
+ */
+const OBSERVER_ACUITY = Math.tan(Math.PI / (180 * 60));
+
+/**
+ * The raters' distance from the tree, in tree lengths. FIA crews "stay at least one-half tree length from the tree"
+ * and see the top better further out (Schomaker et al. 2007, §2.2); one length is where they rate from.
+ * @type {number}
+ */
+const VIEWING_DISTANCE = 1;
+
+/**
+ * A raster at the observer's acuity is a few thousand pixels across; past this the pixel size is wrong, not the tree.
+ * @type {number}
+ */
+const MAX_PIXEL_COUNT = 1 << 27;
+
+const FLAG_DRAWN = 1;
+const FLAG_FOLIAGE = 2;
+const FLAG_DILATED = 4;
+
+const scratch_position = new Float64Array(2);
+const scratch_sample = new Float64Array(1);
+
+/**
+ * Raster state shared by every view of one measurement, grown to the largest view.
+ */
+class CrownRaster {
+    width = 0;
+    height = 0;
+    /**
+     * Transmittance of everything drawn.
+     * @type {Float32Array}
+     */
+    transmittance = new Float32Array(0);
+    /**
+     * Transmittance of the foliage alone.
+     * @type {Float32Array}
+     */
+    foliage_transmittance = new Float32Array(0);
+    /**
+     * @type {Uint8Array}
+     */
+    flags = new Uint8Array(0);
+    /**
+     * Chamfer distance, in pixels, written in place over its own source mask.
+     * @type {Float32Array}
+     */
+    distance = new Float32Array(0);
+    /**
+     * Hull candidates, 2 per row.
+     * @type {Float64Array}
+     */
+    points = new Float64Array(0);
+    distance_sampler = new Sampler2D(new Float32Array(0), 1, 0, 0);
+
+    /**
+     * @param {number} width
+     * @param {number} height
+     */
+    reset(width, height) {
+        const n = width * height;
+        if (n > MAX_PIXEL_COUNT) {
+            throw new Error(`crown raster of ${width}x${height} pixels: the pixel size is too small for this crown`);
+        }
+        if (this.flags.length < n) {
+            this.transmittance = new Float32Array(n);
+            this.foliage_transmittance = new Float32Array(n);
+            this.flags = new Uint8Array(n);
+            this.distance = new Float32Array(n);
+        }
+        if (this.points.length < height * 4) {
+            this.points = new Float64Array(height * 4);
+        }
+        this.width = width;
+        this.height = height;
+        this.transmittance.fill(1.0, 0, n);
+        this.foliage_transmittance.fill(1.0, 0, n);
+        this.flags.fill(0, 0, n);
+
+        this.distance_sampler.data = this.distance.subarray(0, n);
+        this.distance_sampler.width = width;
+        this.distance_sampler.height = height;
+    }
+}
+
+/**
+ * Lowest foliage of the live crown, by the FIA five-foot rule: walking down from the top, foliage joins the crown
+ * while it is within `gap` of the foliage above it.
+ *
+ * The rule is written for branch attachments on the bole; the foliage heights stand in for them, since a branch whose
+ * leaves are within the gap of the crown above is attached within it too.
+ *
+ * @param {Float32Array} positions foliage vertex positions
+ * @param {number} gap
+ * @returns {number}
+ */
+function compute_crown_base(positions, gap) {
+    const n = positions.length / 3;
+    const heights = new Float64Array(n);
+    for (let i = 0; i < n; i++) {
+        heights[i] = positions[i * 3 + 1];
+    }
+    heights.sort();
+
+    let base = heights[n - 1];
+    for (let i = n - 2; i >= 0; i--) {
+        if (base - heights[i] > gap) {
+            break;
+        }
+        base = heights[i];
+    }
+    return base;
+}
+
+/**
+ * @param {Float64Array} projected out, 2 pixel coordinates per vertex
+ * @param {Float32Array} positions
+ * @param {number} ax image x axis
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx image y axis
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} x0 world offset of pixel 0
+ * @param {number} y0
+ * @param {number} inv_pixel
+ */
+function project_vertices(projected, positions, ax, ay, az, bx, by, bz, x0, y0, inv_pixel) {
+    const n = positions.length / 3;
+    for (let i = 0; i < n; i++) {
+        const px = positions[i * 3];
+        const py = positions[i * 3 + 1];
+        const pz = positions[i * 3 + 2];
+        projected[i * 2] = (px * ax + py * ay + pz * az - x0) * inv_pixel;
+        projected[i * 2 + 1] = (px * bx + py * by + pz * bz - y0) * inv_pixel;
+    }
+}
+
+/**
+ * @param {Float64Array} bounds `[x_min, y_min, x_max, y_max]` of the view, grown in place
+ * @param {Float32Array} positions
+ * @param {number} ax image x axis
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx image y axis
+ * @param {number} by
+ * @param {number} bz
+ */
+function extend_view_bounds(bounds, positions, ax, ay, az, bx, by, bz) {
+    for (let i = 0; i < positions.length; i += 3) {
+        const x = positions[i] * ax + positions[i + 1] * ay + positions[i + 2] * az;
+        const y = positions[i] * bx + positions[i + 1] * by + positions[i + 2] * bz;
+        bounds[0] = Math.min(bounds[0], x);
+        bounds[1] = Math.min(bounds[1], y);
+        bounds[2] = Math.max(bounds[2], x);
+        bounds[3] = Math.max(bounds[3], y);
+    }
+}
+
+/**
+ * Draws every triangle of a geometry into the raster. Pixel `(i, j)` is the point sample at `(i + 0.5, j + 0.5)`;
+ * an edge through a pixel centre belongs to one of the two triangles sharing it, so a mesh draws each point once.
+ *
+ * Bark is opaque. A card's coverage at a pixel is its atlas alpha there, bilinearly sampled: the renderer's hashed
+ * alpha test keeps a fragment with probability equal to that alpha, so this is the coverage it draws, in expectation.
+ * A covered leaf passes `leaf_transmittance` of the light it covers.
+ *
+ * @param {CrownRaster} raster
+ * @param {Float64Array} projected
+ * @param {Float32Array} positions
+ * @param {Float32Array|null} uvs `null` for opaque geometry
+ * @param {ArrayLike<number>|null} index
+ * @param {number} triangle_count
+ * @param {Sampler2D|null} atlas
+ * @param {number} alpha_channel
+ * @param {number} alpha_scale
+ * @param {number} leaf_transmittance
+ * @param {number} crown_base fragments below this height are not part of the crown
+ */
+function raster_geometry(
+    raster, projected, positions, uvs, index, triangle_count,
+    atlas, alpha_channel, alpha_scale, leaf_transmittance, crown_base
+) {
+    const v = RASTER_VISITOR;
+    v.raster = raster;
+    v.uvs = uvs;
+    v.atlas = atlas;
+    v.atlas_w = uvs !== null ? atlas.width : 0;
+    v.atlas_h = uvs !== null ? atlas.height : 0;
+    v.alpha_channel = alpha_channel;
+    v.alpha_scale = alpha_scale;
+    v.blocked = 1.0 - leaf_transmittance;
+    v.crown_base = crown_base;
+
+    for (let t = 0; t < triangle_count; t++) {
+        let i0, i1, i2;
+        if (index !== null) {
+            i0 = index[t * 3];
+            i1 = index[t * 3 + 1];
+            i2 = index[t * 3 + 2];
+        } else {
+            i0 = t * 3;
+            i1 = t * 3 + 1;
+            i2 = t * 3 + 2;
+        }
+
+        const h0 = positions[i0 * 3 + 1];
+        const h1 = positions[i1 * 3 + 1];
+        const h2 = positions[i2 * 3 + 1];
+        if (Math.max(h0, h1, h2) < crown_base) {
+            continue;
+        }
+        v.i0 = i0;
+        v.i1 = i1;
+        v.i2 = i2;
+        v.h0 = h0;
+        v.h1 = h1;
+        v.h2 = h2;
+        // only a triangle across the crown base is cut per fragment: one wholly above keeps every fragment, where an
+        // interpolated height could round below a base it sits on
+        v.cut_at_base = Math.min(h0, h1, h2) < crown_base;
+
+        tri2_rasterize_barycentric(
+            raster.width, raster.height,
+            projected[i0 * 2], projected[i0 * 2 + 1],
+            projected[i1 * 2], projected[i1 * 2 + 1],
+            projected[i2 * 2], projected[i2 * 2 + 1],
+            v
+        );
+    }
+}
+
+/**
+ * What one pixel of a triangle does to the raster: bark makes it opaque, a leaf passes what its alpha does not cover.
+ */
+const RASTER_VISITOR = {
+    /** @type {CrownRaster|null} */
+    raster: null,
+    /** @type {Float32Array|null} */
+    uvs: null,
+    /** @type {Sampler2D|null} */
+    atlas: null,
+    atlas_w: 0,
+    atlas_h: 0,
+    alpha_channel: 0,
+    alpha_scale: 1,
+    blocked: 1,
+    crown_base: -Infinity,
+    i0: 0, i1: 0, i2: 0,
+    h0: 0, h1: 0, h2: 0,
+    cut_at_base: false,
+    visit(col, row, l0, l1, l2) {
+        if (this.cut_at_base && l0 * this.h0 + l1 * this.h1 + l2 * this.h2 < this.crown_base) return;
+
+        const raster = this.raster;
+        const k = row * raster.width + col;
+
+        const uvs = this.uvs;
+        if (uvs === null) {
+            raster.transmittance[k] = 0.0;
+            raster.flags[k] |= FLAG_DRAWN;
+            return;
+        }
+
+        const T_foliage = raster.foliage_transmittance;
+        if (T_foliage[k] === 0.0) {
+            // an opaque leaf is already here: nothing behind or in front of it changes the pixel
+            return;
+        }
+
+        const i0 = this.i0, i1 = this.i1, i2 = this.i2;
+        const u = l0 * uvs[i0 * 2] + l1 * uvs[i1 * 2] + l2 * uvs[i2 * 2];
+        const v = l0 * uvs[i0 * 2 + 1] + l1 * uvs[i1 * 2 + 1] + l2 * uvs[i2 * 2 + 1];
+        scratch_position[0] = u * this.atlas_w - 0.5;
+        scratch_position[1] = v * this.atlas_h - 0.5;
+        this.atlas.sampleChannelBilinearArray(scratch_sample, 0, scratch_position, 0, this.alpha_channel);
+        const alpha = clamp(scratch_sample[0] * this.alpha_scale, 0.0, 1.0);
+        if (alpha <= 0.0) return;
+
+        const pass = 1.0 - alpha * this.blocked;
+        raster.transmittance[k] *= pass;
+        T_foliage[k] *= pass;
+        raster.flags[k] |= FLAG_DRAWN | FLAG_FOLIAGE;
+    }
+};
+
+/**
+ * Marks the foliated part of the view: the morphological closing of the foliage's pixels by a ball of `radius_px`,
+ * so a gap narrower than the ball's diameter is a microhole within the foliage and a wider one is a large gap
+ * between foliage, outside. The ball is the 3x3 chamfer metric's (an octagon through the disc's axis and diagonal
+ * points, 90% of its area).
+ *
+ * @param {CrownRaster} raster
+ * @param {number} radius_px
+ */
+function mark_foliated(raster, radius_px) {
+    const n = raster.width * raster.height;
+    const flags = raster.flags;
+    const distance = raster.distance;
+    const sampler = raster.distance_sampler;
+    const far = raster.width + raster.height;
+
+    // dilate; the chamfer reads each source pixel before it writes it, so the mask is its own output
+    for (let k = 0; k < n; k++) {
+        distance[k] = flags[k] & FLAG_FOLIAGE ? 1 : 0;
+    }
+    computeUnsignedDistanceField_Chamfer(sampler, sampler, 0, 1, Math.SQRT2, far);
+    for (let k = 0; k < n; k++) {
+        distance[k] = distance[k] <= radius_px ? 0 : 1;
+    }
+
+    // erode the dilation
+    computeUnsignedDistanceField_Chamfer(sampler, sampler, 0, 1, Math.SQRT2, far);
+    for (let k = 0; k < n; k++) {
+        if (distance[k] > radius_px) {
+            flags[k] |= FLAG_DILATED;
+        }
+    }
+}
+
+/**
+ * Integrates one view over its crown outline: the convex hull of every pixel the crown draws.
+ *
+ * FIA's crown density outline is "a normal, expected crown that encompasses the branch tips", rated "as if [the
+ * crown is] full" with dieback and open areas inside it (Schomaker et al. 2007, §2.3.5.2). The convex hull is the
+ * smallest outline that encompasses every branch tip without the observer's judgement of which notches to bridge.
+ *
+ * @param {CrownRaster} raster
+ * @param {Float64Array} out `[outline pixels, density sum, foliated pixels, transparency sum]`
+ */
+function integrate_view(raster, out) {
+    const width = raster.width;
+    const height = raster.height;
+    const flags = raster.flags;
+    const T = raster.transmittance;
+    const T_foliage = raster.foliage_transmittance;
+
+    // the hull of the drawn pixels' centres is the hull of each row's first and last drawn pixel
+    const points = raster.points;
+    let point_count = 0;
+    for (let row = 0; row < height; row++) {
+        const row_offset = row * width;
+        let first = -1;
+        let last = -1;
+        for (let col = 0; col < width; col++) {
+            if (flags[row_offset + col] & FLAG_DRAWN) {
+                if (first < 0) first = col;
+                last = col;
+            }
+        }
+        if (first < 0) continue;
+        points[point_count * 2] = first;
+        points[point_count * 2 + 1] = row;
+        point_count++;
+        if (last !== first) {
+            points[point_count * 2] = last;
+            points[point_count * 2 + 1] = row;
+            point_count++;
+        }
+    }
+
+    out.fill(0);
+    if (point_count === 0) {
+        return;
+    }
+
+    const hull = convex_hull_monotone_2d(points, point_count);
+    const hull_count = hull.length;
+
+    let row_lo = height;
+    let row_hi = -1;
+    for (let h = 0; h < hull_count; h++) {
+        const y = points[hull[h] * 2 + 1];
+        row_lo = Math.min(row_lo, y);
+        row_hi = Math.max(row_hi, y);
+    }
+
+    let outline = 0;
+    let density_sum = 0.0;
+    let foliated = 0;
+    let transparency_sum = 0.0;
+
+    for (let row = row_lo; row <= row_hi; row++) {
+        // the hull's span on this row
+        let x_lo = Infinity;
+        let x_hi = -Infinity;
+        for (let h = 0; h < hull_count; h++) {
+            const a = hull[h];
+            const b = hull[(h + 1) % hull_count];
+            const ax = points[a * 2], ay = points[a * 2 + 1];
+            const bx = points[b * 2], by = points[b * 2 + 1];
+            if (row < Math.min(ay, by) || row > Math.max(ay, by)) continue;
+            if (ay === by) {
+                x_lo = Math.min(x_lo, ax, bx);
+                x_hi = Math.max(x_hi, ax, bx);
+            } else {
+                const x = ax + (row - ay) * (bx - ax) / (by - ay);
+                x_lo = Math.min(x_lo, x);
+                x_hi = Math.max(x_hi, x);
+            }
+        }
+
+        const col_lo = Math.max(0, Math.ceil(x_lo - 1e-9));
+        const col_hi = Math.min(width - 1, Math.floor(x_hi + 1e-9));
+        const row_offset = row * width;
+        for (let col = col_lo; col <= col_hi; col++) {
+            const k = row_offset + col;
+            outline++;
+            density_sum += 1.0 - T[k];
+            if (flags[k] & FLAG_DILATED) {
+                foliated++;
+                transparency_sum += T_foliage[k];
+            }
+        }
+    }
+
+    out[0] = outline;
+    out[1] = density_sum;
+    out[2] = foliated;
+    out[3] = transparency_sum;
+}
+
+/**
+ * Measures how opaque a tree crown is, as the USDA Forest Inventory and Analysis program rates it in the field
+ * (Schomaker et al. 2007, GTR SRS-102), by rasterising what the renderer draws in orthographic views from every frame
+ * of a `frame_count` x `frame_count` hemi-octahedral impostor grid (`crown_opacity_frames`). A view and its opposite
+ * see mirrored images of the same transmittance, so the hemisphere holds every view once; the grid's rim is the
+ * horizon, where FIA rates from, and its centre the view from directly below. Rim frames come in opposite pairs, and
+ * each pair is measured once.
+ *
+ * - **Crown**: everything above the live crown base, which is the lowest foliage reached from the top without a
+ *   vertical gap in foliage wider than the FIA five-foot rule's 1.524 m. Nothing below it is drawn.
+ * - **Crown outline**: the convex hull of every pixel the crown draws (bark or foliage), with every gap inside it.
+ * - **Crown density**: the mean of `1 - T` over the outline, `T` the transmittance of bark and foliage together.
+ *   From below, over the footprint, this is the light the crown intercepts (Nowak 1996).
+ * - **Foliated part**: FIA rates transparency "where foliage or remnants of foliage occur", excluding macroholes
+ *   and "the spaces between clumps of foliage" (§2.3.7). Here it is the morphological closing of the foliage's pixels
+ *   by a ball of `microhole_radius`, inside the outline: gaps narrower than two radii are microholes, wider ones are
+ *   large gaps and drop out.
+ * - **Foliage transparency**: the mean foliage-only transmittance over the foliated part. Bark does not count, as
+ *   FIA's raters "exclude the branches from foliage ... as if the light were penetrating the branches".
+ *
+ * Each pixel is a point sample of what the renderer draws there. The outline and the foliated part are extremes over
+ * those samples, and grow as finer pixels catch thinner twigs and leaf stalks, so the pixel size is part of the
+ * definition: by default it is what a rater sees, one minute of arc (normal acuity) from one tree length away, the
+ * tree's length being the height of everything drawn.
+ *
+ * `leaf_transmittance` is the fraction of the light a leaf lets through where it covers. Our shading model has no
+ * leaf translucency, so it defaults to 0; it is the hook for when the shading model gains one.
+ *
+ * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} bark opaque geometry
+ * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} foliage cards, `uv0` into `atlas`
+ * @param {Sampler2D|null} atlas the cards' texture; required with `foliage`
+ * @param {Object} options
+ * @param {number} options.microhole_radius closing radius separating microholes from large gaps, m
+ * @param {number} [options.pixel_size] m, the tree's height times the tangent of one minute of arc by default
+ * @param {number} [options.frame_count=9] frames along each side of the grid; odd, so the vertical is a frame. At 9
+ *        every preset's hemisphere means are within 0.2 points of 13's; 5 is off by up to 1.6, 3 by up to 5.8
+ * @param {number} [options.leaf_transmittance=0] fraction of light a leaf passes, in `[0, 1]`
+ * @param {number} [options.atlas_alpha_channel=3] channel of `atlas` holding the cards' coverage
+ * @param {CrownOpacity} [out]
+ * @returns {CrownOpacity}
+ */
+export function crown_opacity_measure(bark, foliage, atlas, {
+    microhole_radius,
+    pixel_size,
+    frame_count = 9,
+    leaf_transmittance = 0,
+    atlas_alpha_channel = 3
+}, out = new CrownOpacity()) {
+    assert.greaterThan(microhole_radius, 0, 'microhole_radius');
+    assert.isNonNegativeInteger(frame_count, 'frame_count');
+    assert.equal(frame_count % 2, 1, 'frame_count must be odd, so the vertical is a frame');
+    assert.greaterThanOrEqual(leaf_transmittance, 0, 'leaf_transmittance');
+    assert.lessThanOrEqual(leaf_transmittance, 1, 'leaf_transmittance');
+    if (foliage !== null) {
+        assert.defined(atlas, 'atlas');
+        assert.notNull(atlas, 'atlas');
+        assert.equal(atlas.isSampler2D, true, 'atlas.isSampler2D !== true');
+    }
+
+    const bark_positions = bark !== null ? bark.getAttribute(StandardAttributes.Position).data : null;
+    const foliage_positions = foliage !== null ? foliage.getAttribute(StandardAttributes.Position).data : null;
+    const foliage_uvs = foliage !== null ? foliage.getAttribute(StandardAttributes.TextureCoordinates0).data : null;
+    const alpha_scale = foliage !== null ? typed_array_value_denormalize(1, atlas.data) : 0;
+
+    const bounds = new Float64Array(4);
+    if (pixel_size === undefined) {
+        bounds[1] = Infinity;
+        bounds[3] = -Infinity;
+        if (bark_positions !== null) {
+            extend_view_bounds(bounds, bark_positions, 0, 1, 0, 0, 1, 0);
+        }
+        if (foliage_positions !== null) {
+            extend_view_bounds(bounds, foliage_positions, 0, 1, 0, 0, 1, 0);
+        }
+        pixel_size = (bounds[3] - bounds[1]) * VIEWING_DISTANCE * OBSERVER_ACUITY;
+    }
+    assert.greaterThan(pixel_size, 0, 'pixel_size');
+
+    const crown_base = foliage_positions !== null && foliage_positions.length > 0
+        ? compute_crown_base(foliage_positions, FIVE_FOOT_RULE)
+        : -Infinity;
+
+    out.resize(frame_count);
+    crown_opacity_frames(out);
+    out.crown_base = crown_base;
+    out.pixel_size = pixel_size;
+    out.microhole_radius = microhole_radius;
+
+    const inv_pixel = 1.0 / pixel_size;
+    const radius_px = microhole_radius * inv_pixel;
+    // the closing's dilation reaches radius_px past the outermost foliage, and has to stay inside the raster
+    const pad = Math.ceil(radius_px) + 2;
+
+    const bark_projected = new Float64Array(bark_positions !== null ? bark_positions.length / 3 * 2 : 0);
+    const foliage_projected = new Float64Array(foliage_positions !== null ? foliage_positions.length / 3 * 2 : 0);
+    const raster = new CrownRaster();
+    const sums = new Float64Array(4);
+    const pixel_area = pixel_size * pixel_size;
+
+    const frame_total = frame_count * frame_count;
+    for (let frame = 0; frame < frame_total; frame++) {
+        const i = frame % frame_count;
+        const j = (frame - i) / frame_count;
+        const on_rim = i === 0 || j === 0 || i === frame_count - 1 || j === frame_count - 1;
+        const opposite = (frame_count - 1 - j) * frame_count + (frame_count - 1 - i);
+        if (on_rim && opposite < frame) {
+            // its opposite on the horizon sees the mirror image
+            out.density[frame] = out.density[opposite];
+            out.transparency[frame] = out.transparency[opposite];
+            out.outline_area[frame] = out.outline_area[opposite];
+            out.foliated_area[frame] = out.foliated_area[opposite];
+            continue;
+        }
+
+        // image axes: x horizontal across the view, y the rest of the way up (on the horizon, the vertical)
+        const dx = out.directions[frame * 3];
+        const dy = out.directions[frame * 3 + 1];
+        const dz = out.directions[frame * 3 + 2];
+        let ax, ay, az, bx, by, bz;
+        if (dx === 0 && dz === 0) {
+            ax = 1; ay = 0; az = 0;
+            bx = 0; by = 0; bz = 1;
+        } else {
+            const m = 1 / Math.sqrt(dx * dx + dz * dz);
+            ax = dz * m; ay = 0; az = -dx * m;
+            bx = dy * az; by = dz * ax - dx * az; bz = -dy * ax;
+        }
+
+        bounds[0] = Infinity;
+        bounds[1] = Infinity;
+        bounds[2] = -Infinity;
+        bounds[3] = -Infinity;
+        if (bark_positions !== null) {
+            extend_view_bounds(bounds, bark_positions, ax, ay, az, bx, by, bz);
+        }
+        if (foliage_positions !== null) {
+            extend_view_bounds(bounds, foliage_positions, ax, ay, az, bx, by, bz);
+        }
+        const x_min = bounds[0], y_min = bounds[1], x_max = bounds[2], y_max = bounds[3];
+
+        sums.fill(0);
+        if (x_min <= x_max) {
+            const width = Math.ceil((x_max - x_min) * inv_pixel) + 2 * pad;
+            const height = Math.ceil((y_max - y_min) * inv_pixel) + 2 * pad;
+            raster.reset(width, height);
+            const x0 = x_min - pad * pixel_size;
+            const y0 = y_min - pad * pixel_size;
+
+            if (bark_positions !== null) {
+                project_vertices(bark_projected, bark_positions, ax, ay, az, bx, by, bz, x0, y0, inv_pixel);
+                raster_geometry(
+                    raster, bark_projected, bark_positions, null,
+                    bark.index !== null ? bark.index.data : null, bark.getPrimitiveCount(),
+                    null, 0, 0, 0, crown_base
+                );
+            }
+            if (foliage_positions !== null) {
+                project_vertices(foliage_projected, foliage_positions, ax, ay, az, bx, by, bz, x0, y0, inv_pixel);
+                raster_geometry(
+                    raster, foliage_projected, foliage_positions, foliage_uvs,
+                    foliage.index !== null ? foliage.index.data : null, foliage.getPrimitiveCount(),
+                    atlas, atlas_alpha_channel, alpha_scale, leaf_transmittance, crown_base
+                );
+            }
+
+            mark_foliated(raster, radius_px);
+            integrate_view(raster, sums);
+        }
+
+        const density = sums[1] / sums[0];
+        const transparency = sums[3] / sums[2];
+        const outline_area = sums[0] * pixel_area;
+        const foliated_area = sums[2] * pixel_area;
+
+        out.density[frame] = density;
+        out.transparency[frame] = transparency;
+        out.outline_area[frame] = outline_area;
+        out.foliated_area[frame] = foliated_area;
+    }
+
+    return out;
+}

package/src/generation/foliage/analysis/foliage_measure_leaf_area.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @typedef {Object} FoliageLeafArea
+ * @property {number} total one-sided leaf area of every card, m^2
+ * @property {Float64Array} by_card one-sided leaf area of each attachment, m^2
+ * @property {Float64Array} by_generator one-sided leaf area of the cards each `config.branches` generator's branches
+ *           carry, m^2
+ * @property {number} crown_projected_area area of the crown seen from straight above, m^2: the convex hull of every
+ *           vertex of a card triangle that shows any leaf, projected onto the horizontal (x, z) plane
+ * @property {number} crown_leaf_area_index `total / crown_projected_area`, the tree's own leaf area index
+ */
+/**
+ * Measures the one-sided leaf area a tree's foliage cards draw.
+ *
+ * Builds the cards as `tree_mesh_build_foliage` draws them and integrates the atlas's alpha over each triangle. A
+ * triangle maps its atlas UVs onto itself affinely, so every texel's leaf lands on it at the triangle's own ratio of
+ * area to UV area: its leaf area is its area times the alpha-weighted fraction of its UV footprint. Everything the
+ * cards do to their tiles is therefore measured, not modelled: each card's own tile (`attachments.variant_indices`)
+ * and scale (`attachments.scales`), every plane a cross or tri-star stands up, the strip below the tile's anchor
+ * (`foliage_tile_layout`) that a folded card does not draw, folds, arches and droops, a frond's segments and tapering envelope, and a hull card's fan, which
+ * shows only the texels inside its tile's hull.
+ *
+ * Where it approximates:
+ * - each texel's alpha stands over its whole square (the reconstruction `FoliageAtlasCutout.coverage` sums), at the
+ *   atlas's full resolution; a semi-transparent texel counts as that fraction of leaf, which is the expected area the
+ *   path tracer's stochastic alpha test leaves opaque
+ * - the atlas's alpha is stored in 8 bits, so it differs from the unrounded alpha `FoliageAtlasCutout.coverage` sums
+ *   by up to half a step per texel
+ * - every card counts: the full set, before any LOD decimates it or enlarges what it keeps to compensate
+ * - cards in their rest pose: wind bends cards without stretching them, but this measures none of it
+ * - leaf is whatever the atlas draws opaque, the petioles and rachis it draws included
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} config
+ * @param {import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout|null} cutout the atlas's fitted shape, which
+ *        hull cards outline; `null` draws them over whole tiles, as `tree_mesh_build_foliage` does
+ * @param {import("../../../engine/graphics/texture/sampler/Sampler2D.js").Sampler2D} albedo the atlas the cards show,
+ *        8-bit RGBA with straight alpha: `make_foliage_material(...).texture_albedo.image.source`
+ * @returns {FoliageLeafArea}
+ */
+export function foliage_measure_leaf_area(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, attachments: import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet, config: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, cutout: import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout | null, albedo: import("../../../engine/graphics/texture/sampler/Sampler2D.js").Sampler2D): FoliageLeafArea;
+export type FoliageLeafArea = {
+    /**
+     * one-sided leaf area of every card, m^2
+     */
+    total: number;
+    /**
+     * one-sided leaf area of each attachment, m^2
+     */
+    by_card: Float64Array;
+    /**
+     * one-sided leaf area of the cards each `config.branches` generator's branches
+     * carry, m^2
+     */
+    by_generator: Float64Array;
+    /**
+     * area of the crown seen from straight above, m^2: the convex hull of every
+     * vertex of a card triangle that shows any leaf, projected onto the horizontal (x, z) plane
+     */
+    crown_projected_area: number;
+    /**
+     * `total / crown_projected_area`, the tree's own leaf area index
+     */
+    crown_leaf_area_index: number;
+};
+//# sourceMappingURL=foliage_measure_leaf_area.d.ts.map