@woosh/meep-engine 3.55.0 → 3.57.0

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

@@ -0,0 +1,118 @@
+/**
+ * How opaque a crown is, in the terms of the USDA Forest Inventory and Analysis crown indicators (Schomaker et al.
+ * 2007, GTR SRS-102, §2.3.5 and §2.3.7), from orthographic views of everything the renderer draws.
+ *
+ * The views are the frames of a hemi-octahedral impostor, `frame_count` x `frame_count` of them, frame `(i, j)` at
+ * index `j * frame_count + i`. A view and its opposite see the same mirrored image, so the upper hemisphere holds every
+ * view once: its rim is the horizon, where FIA rates from, and its centre the vertical, Nowak's (1996) view from below.
+ *
+ * Produced by `crown_opacity_measure`. Every ratio is in `[0, 1]`; a frame that sees nothing of the crown has `NaN`
+ * ratios and zero areas.
+ */
+export class CrownOpacity {
+    /**
+     * Frames along each side of the grid.
+     * @type {number}
+     */
+    frame_count: number;
+    /**
+     * Unit direction of each frame's view axis, 3 per frame, on the upper hemisphere (y up).
+     * @type {Float64Array}
+     */
+    directions: Float64Array;
+    /**
+     * Solid angle each frame stands for, steradians: the frame's cell of the grid, mapped onto the hemisphere.
+     * They sum to `2 PI`.
+     * @type {Float64Array}
+     */
+    solid_angles: Float64Array;
+    /**
+     * Azimuth each horizon frame stands for, radians: half the arc to each of its neighbours on the rim. Zero off the
+     * horizon; they sum to `2 PI`.
+     * @type {Float64Array}
+     */
+    horizon_weights: Float64Array;
+    /**
+     * Crown density of each frame: the share of the crown outline that crown stem, branches and foliage block.
+     * @type {Float64Array}
+     */
+    density: Float64Array;
+    /**
+     * Foliage transparency of each frame: the share of skylight through the foliage, over the foliated part of the
+     * outline, with branches treated as if light passed them.
+     * @type {Float64Array}
+     */
+    transparency: Float64Array;
+    /**
+     * Area of each frame's crown outline, m^2.
+     * @type {Float64Array}
+     */
+    outline_area: Float64Array;
+    /**
+     * Area of each frame's foliated part of the outline, m^2.
+     * @type {Float64Array}
+     */
+    foliated_area: Float64Array;
+    /**
+     * Height of the live crown base: nothing below it is part of the crown.
+     * @type {number}
+     */
+    crown_base: number;
+    /**
+     * Width of a raster pixel, m.
+     * @type {number}
+     */
+    pixel_size: number;
+    /**
+     * Radius of the closing that separates microholes from the large gaps between foliage, m.
+     * @type {number}
+     */
+    microhole_radius: number;
+    /**
+     * @param {number} frame_count
+     * @returns {this}
+     */
+    resize(frame_count: number): this;
+    /**
+     * Index of the frame that looks along the vertical, the grid's centre.
+     * @returns {number}
+     */
+    vertical_frame(): number;
+    /**
+     * Crown density over every direction, each frame weighted by its solid angle.
+     * @returns {number}
+     */
+    mean_density(): number;
+    /**
+     * Foliage transparency over every direction, each frame weighted by its solid angle.
+     * @returns {number}
+     */
+    mean_transparency(): number;
+    /**
+     * Crown density seen from the side, as FIA rates it: the horizon frames, each weighted by its azimuth.
+     * @returns {number}
+     */
+    side_density(): number;
+    /**
+     * Foliage transparency seen from the side, as FIA rates it: the horizon frames, each weighted by its azimuth.
+     * @returns {number}
+     */
+    side_transparency(): number;
+    /**
+     * Crown density seen from directly below: the share of light from above that the crown intercepts over its
+     * footprint, as Nowak (1996) measured it.
+     * @returns {number}
+     */
+    below_density(): number;
+    /**
+     * Foliage transparency seen from directly below.
+     * @returns {number}
+     */
+    below_transparency(): number;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isCrownOpacity: boolean;
+}
+//# sourceMappingURL=CrownOpacity.d.ts.map

package/src/generation/foliage/analysis/CrownOpacity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CrownOpacity.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/analysis/CrownOpacity.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH;IACI;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,YAFU,YAAY,CAEW;IAEjC;;;;OAIG;IACH,cAFU,YAAY,CAEa;IAEnC;;;;OAIG;IACH,iBAFU,YAAY,CAEgB;IAEtC;;;OAGG;IACH,SAFU,YAAY,CAEQ;IAE9B;;;;OAIG;IACH,cAFU,YAAY,CAEa;IAEnC;;;OAGG;IACH,cAFU,YAAY,CAEa;IAEnC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,YAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;OAGG;IACH,oBAHW,MAAM,GACJ,IAAI,CAehB;IAED;;;OAGG;IACH,kBAFa,MAAM,CAKlB;IAED;;;OAGG;IACH,gBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,qBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,gBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,qBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,sBAFa,MAAM,CAIlB;IAqBL;;;OAGG;IACH,yBAFU,OAAO,CAEoB;CAxBpC"}

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

@@ -0,0 +1,182 @@
+/**
+ * How opaque a crown is, in the terms of the USDA Forest Inventory and Analysis crown indicators (Schomaker et al.
+ * 2007, GTR SRS-102, §2.3.5 and §2.3.7), from orthographic views of everything the renderer draws.
+ *
+ * The views are the frames of a hemi-octahedral impostor, `frame_count` x `frame_count` of them, frame `(i, j)` at
+ * index `j * frame_count + i`. A view and its opposite see the same mirrored image, so the upper hemisphere holds every
+ * view once: its rim is the horizon, where FIA rates from, and its centre the vertical, Nowak's (1996) view from below.
+ *
+ * Produced by `crown_opacity_measure`. Every ratio is in `[0, 1]`; a frame that sees nothing of the crown has `NaN`
+ * ratios and zero areas.
+ */
+export class CrownOpacity {
+    /**
+     * Frames along each side of the grid.
+     * @type {number}
+     */
+    frame_count = 0;
+
+    /**
+     * Unit direction of each frame's view axis, 3 per frame, on the upper hemisphere (y up).
+     * @type {Float64Array}
+     */
+    directions = new Float64Array(0);
+
+    /**
+     * Solid angle each frame stands for, steradians: the frame's cell of the grid, mapped onto the hemisphere.
+     * They sum to `2 PI`.
+     * @type {Float64Array}
+     */
+    solid_angles = new Float64Array(0);
+
+    /**
+     * Azimuth each horizon frame stands for, radians: half the arc to each of its neighbours on the rim. Zero off the
+     * horizon; they sum to `2 PI`.
+     * @type {Float64Array}
+     */
+    horizon_weights = new Float64Array(0);
+
+    /**
+     * Crown density of each frame: the share of the crown outline that crown stem, branches and foliage block.
+     * @type {Float64Array}
+     */
+    density = new Float64Array(0);
+
+    /**
+     * Foliage transparency of each frame: the share of skylight through the foliage, over the foliated part of the
+     * outline, with branches treated as if light passed them.
+     * @type {Float64Array}
+     */
+    transparency = new Float64Array(0);
+
+    /**
+     * Area of each frame's crown outline, m^2.
+     * @type {Float64Array}
+     */
+    outline_area = new Float64Array(0);
+
+    /**
+     * Area of each frame's foliated part of the outline, m^2.
+     * @type {Float64Array}
+     */
+    foliated_area = new Float64Array(0);
+
+    /**
+     * Height of the live crown base: nothing below it is part of the crown.
+     * @type {number}
+     */
+    crown_base = -Infinity;
+
+    /**
+     * Width of a raster pixel, m.
+     * @type {number}
+     */
+    pixel_size = 0;
+
+    /**
+     * Radius of the closing that separates microholes from the large gaps between foliage, m.
+     * @type {number}
+     */
+    microhole_radius = 0;
+
+    /**
+     * @param {number} frame_count
+     * @returns {this}
+     */
+    resize(frame_count) {
+        if (this.frame_count !== frame_count) {
+            const n = frame_count * frame_count;
+            this.frame_count = frame_count;
+            this.directions = new Float64Array(n * 3);
+            this.solid_angles = new Float64Array(n);
+            this.horizon_weights = new Float64Array(n);
+            this.density = new Float64Array(n);
+            this.transparency = new Float64Array(n);
+            this.outline_area = new Float64Array(n);
+            this.foliated_area = new Float64Array(n);
+        }
+        return this;
+    }
+
+    /**
+     * Index of the frame that looks along the vertical, the grid's centre.
+     * @returns {number}
+     */
+    vertical_frame() {
+        const half = (this.frame_count - 1) >> 1;
+        return half * this.frame_count + half;
+    }
+
+    /**
+     * Crown density over every direction, each frame weighted by its solid angle.
+     * @returns {number}
+     */
+    mean_density() {
+        return weighted_mean(this.density, this.solid_angles);
+    }
+
+    /**
+     * Foliage transparency over every direction, each frame weighted by its solid angle.
+     * @returns {number}
+     */
+    mean_transparency() {
+        return weighted_mean(this.transparency, this.solid_angles);
+    }
+
+    /**
+     * Crown density seen from the side, as FIA rates it: the horizon frames, each weighted by its azimuth.
+     * @returns {number}
+     */
+    side_density() {
+        return weighted_mean(this.density, this.horizon_weights);
+    }
+
+    /**
+     * Foliage transparency seen from the side, as FIA rates it: the horizon frames, each weighted by its azimuth.
+     * @returns {number}
+     */
+    side_transparency() {
+        return weighted_mean(this.transparency, this.horizon_weights);
+    }
+
+    /**
+     * Crown density seen from directly below: the share of light from above that the crown intercepts over its
+     * footprint, as Nowak (1996) measured it.
+     * @returns {number}
+     */
+    below_density() {
+        return this.density[this.vertical_frame()];
+    }
+
+    /**
+     * Foliage transparency seen from directly below.
+     * @returns {number}
+     */
+    below_transparency() {
+        return this.transparency[this.vertical_frame()];
+    }
+}
+
+/**
+ * @param {Float64Array} values
+ * @param {Float64Array} weights
+ * @returns {number}
+ */
+function weighted_mean(values, weights) {
+    let sum = 0.0;
+    let weight_sum = 0.0;
+    for (let i = 0; i < values.length; i++) {
+        const w = weights[i];
+        if (w > 0) {
+            sum += values[i] * w;
+            weight_sum += w;
+        }
+    }
+    return sum / weight_sum;
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+CrownOpacity.prototype.isCrownOpacity = true;

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

@@ -0,0 +1,10 @@
+/**
+ * Lays out the views of a hemi-octahedral impostor grid in `out`, sized to `out.frame_count`: frame `(i, j)` looks
+ * along `HemiOctahedralUvEncoder`'s direction for `(i, j) / (frame_count - 1)`, the impostor shader's `FrameXYToRay`.
+ * Fills each frame's direction, the solid angle of its cell (half a frame spacing each way, inside the grid), and on
+ * the rim, the azimuth it stands for.
+ *
+ * @param {import("./CrownOpacity.js").CrownOpacity} out
+ */
+export function crown_opacity_frames(out: import("./CrownOpacity.js").CrownOpacity): void;
+//# sourceMappingURL=crown_opacity_frames.d.ts.map

package/src/generation/foliage/analysis/crown_opacity_frames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crown_opacity_frames.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/analysis/crown_opacity_frames.js"],"names":[],"mappings":"AAiEA;;;;;;;GAOG;AACH,0CAFW,OAAO,mBAAmB,EAAE,YAAY,QAkClD"}

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

@@ -0,0 +1,132 @@
+import { assert } from "../../../core/assert.js";
+import { HemiOctahedralUvEncoder } from "../../../engine/graphics/impostors/octahedral/grid/HemiOctahedralUvEncoder.js";
+
+const encoder = new HemiOctahedralUvEncoder();
+const scratch_uv = new Float64Array(2);
+const scratch_direction = new Float64Array(3);
+const scratch_a = new Float64Array(3);
+const scratch_b = new Float64Array(3);
+const scratch_c = new Float64Array(3);
+const scratch_d = new Float64Array(3);
+
+/**
+ * The hemi-octahedron point over `(x, z)` on the unit sphere, `x`, `z` the encoder's in-plane coordinates.
+ * @param {Float64Array} out
+ * @param {number} x
+ * @param {number} z
+ */
+function lift(out, x, z) {
+    const y = 1.0 - Math.abs(x) - Math.abs(z);
+    const m = 1.0 / Math.sqrt(x * x + y * y + z * z);
+    out[0] = x * m;
+    out[1] = y * m;
+    out[2] = z * m;
+}
+
+/**
+ * Solid angle of the spherical triangle over three unit vectors (Van Oosterom and Strackee 1983).
+ * @param {Float64Array} a
+ * @param {Float64Array} b
+ * @param {Float64Array} c
+ * @returns {number}
+ */
+function spherical_triangle_solid_angle(a, b, c) {
+    const triple = a[0] * (b[1] * c[2] - b[2] * c[1])
+        + a[1] * (b[2] * c[0] - b[0] * c[2])
+        + a[2] * (b[0] * c[1] - b[1] * c[0]);
+    const ab = a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+    const bc = b[0] * c[0] + b[1] * c[1] + b[2] * c[2];
+    const ca = c[0] * a[0] + c[1] * a[1] + c[2] * a[2];
+    return 2.0 * Math.abs(Math.atan2(triple, 1.0 + ab + bc + ca));
+}
+
+/**
+ * Solid angle of a frame's cell `[u0, u1] x [v0, v1]` of the grid, its corners on the sphere `a, b, c, d` in order.
+ *
+ * The encoder maps the cell linearly onto the hemi-octahedron. Its creases, `u = v` and `u + v = 1`, run through
+ * the frames and meet the cells' edges only at their corners, so each edge lies on one face, where a straight line
+ * projects to a great-circle arc: the cell is the spherical quadrilateral on its corners, exactly.
+ *
+ * @param {number} u0
+ * @param {number} v0
+ * @param {number} u1
+ * @param {number} v1
+ * @returns {number}
+ */
+function cell_solid_angle(u0, v0, u1, v1) {
+    // the encoder's x = u - v, z = u + v - 1
+    lift(scratch_a, u0 - v0, u0 + v0 - 1);
+    lift(scratch_b, u1 - v0, u1 + v0 - 1);
+    lift(scratch_c, u1 - v1, u1 + v1 - 1);
+    lift(scratch_d, u0 - v1, u0 + v1 - 1);
+    return spherical_triangle_solid_angle(scratch_a, scratch_b, scratch_c)
+        + spherical_triangle_solid_angle(scratch_a, scratch_c, scratch_d);
+}
+
+/**
+ * Lays out the views of a hemi-octahedral impostor grid in `out`, sized to `out.frame_count`: frame `(i, j)` looks
+ * along `HemiOctahedralUvEncoder`'s direction for `(i, j) / (frame_count - 1)`, the impostor shader's `FrameXYToRay`.
+ * Fills each frame's direction, the solid angle of its cell (half a frame spacing each way, inside the grid), and on
+ * the rim, the azimuth it stands for.
+ *
+ * @param {import("./CrownOpacity.js").CrownOpacity} out
+ */
+export function crown_opacity_frames(out) {
+    const N = out.frame_count;
+    assert.greaterThanOrEqual(N, 2, 'frame_count');
+
+    const h = 1 / (N - 1);
+
+    for (let j = 0; j < N; j++) {
+        for (let i = 0; i < N; i++) {
+            const f = j * N + i;
+            scratch_uv[0] = i * h;
+            scratch_uv[1] = j * h;
+            encoder.uv_to_unit(scratch_direction, scratch_uv);
+            out.directions[f * 3] = scratch_direction[0];
+            out.directions[f * 3 + 1] = scratch_direction[1];
+            out.directions[f * 3 + 2] = scratch_direction[2];
+
+            out.solid_angles[f] = cell_solid_angle(
+                Math.max(0, (i - 0.5) * h), Math.max(0, (j - 0.5) * h),
+                Math.min(1, (i + 0.5) * h), Math.min(1, (j + 0.5) * h)
+            );
+            out.horizon_weights[f] = 0;
+        }
+    }
+
+    // the rim, in order around the grid's border
+    const rim_count = 4 * (N - 1);
+    for (let r = 0; r < rim_count; r++) {
+        const f = rim_frame(N, r);
+        const prev = rim_frame(N, (r + rim_count - 1) % rim_count);
+        const next = rim_frame(N, (r + 1) % rim_count);
+        out.horizon_weights[f] = 0.5 * (azimuth_between(out.directions, prev, f) + azimuth_between(out.directions, f, next));
+    }
+}
+
+/**
+ * Frame index of the `r`-th frame around the grid's border.
+ * @param {number} N
+ * @param {number} r
+ * @returns {number}
+ */
+function rim_frame(N, r) {
+    const side = N - 1;
+    if (r < side) return r;
+    if (r < 2 * side) return (r - side) * N + side;
+    if (r < 3 * side) return side * N + (3 * side - r);
+    return (4 * side - r) * N;
+}
+
+/**
+ * @param {Float64Array} directions
+ * @param {number} a
+ * @param {number} b
+ * @returns {number} the azimuth between two horizon frames, radians
+ */
+function azimuth_between(directions, a, b) {
+    let d = Math.atan2(directions[b * 3 + 2], directions[b * 3]) - Math.atan2(directions[a * 3 + 2], directions[a * 3]);
+    d = ((d % (2 * Math.PI)) + 3 * Math.PI) % (2 * Math.PI) - Math.PI;
+    return Math.abs(d);
+}

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

@@ -0,0 +1,51 @@
+/**
+ * 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: import("../../../shade/renderer/geometry/Geometry.js").Geometry | null, foliage: import("../../../shade/renderer/geometry/Geometry.js").Geometry | null, atlas: Sampler2D | null, { microhole_radius, pixel_size, frame_count, leaf_transmittance, atlas_alpha_channel }: {
+    microhole_radius: number;
+    pixel_size?: number;
+    frame_count?: number;
+    leaf_transmittance?: number;
+    atlas_alpha_channel?: number;
+}, out?: CrownOpacity): CrownOpacity;
+import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
+import { CrownOpacity } from "./CrownOpacity.js";
+//# sourceMappingURL=crown_opacity_measure.d.ts.map

package/src/generation/foliage/analysis/crown_opacity_measure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crown_opacity_measure.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/analysis/crown_opacity_measure.js"],"names":[],"mappings":"AAmdA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,4CAbW,OAAO,8CAA8C,EAAE,QAAQ,GAAC,IAAI,WACpE,OAAO,8CAA8C,EAAE,QAAQ,GAAC,IAAI,SACpE,SAAS,GAAC,IAAI;IAEE,gBAAgB,EAAhC,MAAM;IACW,UAAU,GAA3B,MAAM;IACW,WAAW,GAA5B,MAAM;IAEW,kBAAkB,GAAnC,MAAM;IACW,mBAAmB,GAApC,MAAM;SACN,YAAY,GACV,YAAY,CA8IxB;0BAjoByB,uDAAuD;6BAEpD,mBAAmB"}