@woosh/meep-engine 3.56.0 → 3.57.0

package/src/generation/foliage/material/foliage_tile.js

@@ -0,0 +1,286 @@
+import { polygon2_rasterize_coverage } from "../../../core/geom/2d/polygon/polygon2_rasterize_coverage.js";
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { smoothStep } from "../../../core/math/smoothStep.js";
+import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
+import { computeUnsignedDistanceField_Chamfer } from "../../../engine/graphics/texture/sampler/distance/computeUnsignedDistanceField_Chamfer.js";
+import { FoliageTileContent } from "../config/FoliageTileContent.js";
+import { foliage_card_plane_count } from "../skeleton/foliage_card_density.js";
+import { foliage_variant_maturity } from "../skeleton/foliage_senescence.js";
+import { leaf_geometry, needle_shoot_geometry } from "./leaf_geometry.js";
+
+/**
+ * Most tiles an atlas packs (`compute_foliage_variant_atlas_layout`).
+ * @type {number}
+ */
+const MAX_TILES = 16;
+
+/**
+ * Texels across the finest feature a tile draws (a tooth, a sinus, a needle's width) at full resolution: enough to
+ * draw its point, not only its presence.
+ * @type {number}
+ */
+const FEATURE_TEXELS = 4;
+
+/**
+ * Texels across the narrowest stem a tile draws: wherever it falls it covers a whole texel, which the alpha test keeps.
+ * @type {number}
+ */
+const STEM_TEXELS = 2;
+
+/**
+ * Tile resolution bounds (texels). The upper one is a safety net against a feature too fine to draw.
+ * @type {number}
+ */
+const MIN_RESOLUTION = 32;
+const MAX_RESOLUTION = 1024;
+
+/**
+ * Empty border around the organ, as a share of the tile, so filtering never reads a neighbouring tile.
+ * @type {number}
+ */
+const TILE_MARGIN = 0.02;
+
+/**
+ * Sample rows per texel row when rasterizing an outline's coverage.
+ * @type {number}
+ */
+const COVERAGE_ROWS = 4;
+
+/**
+ * @typedef {Object} FoliageTileLayout
+ * @property {number} variant_count maturity variants, one tile each
+ * @property {number} resolution texels across a tile
+ * @property {number} scale tile units per metre: every tile draws its organ at its true size at this scale
+ * @property {number} card_size the side of the square card a tile covers (m)
+ * @property {number} anchor_u where the organ attaches to its shoot, in tile units
+ * @property {number} anchor_v
+ * @property {number} leaves_per_card leaves one card draws: one leaf, or a needle shoot's needles
+ * @property {number} needles needles a needle-shoot tile draws, its plane's share of the card's; 0 for a leaf
+ * @property {number} shoot_length length of shoot a needle-shoot tile draws (m), 0 for a leaf
+ */
+
+/**
+ * Maturity variants of a species' foliage atlas.
+ * @param {import("../config/FoliageMaterialConfig.js").FoliageMaterialConfig} material
+ * @returns {number}
+ */
+export function foliage_atlas_variant_count(material) {
+    return clamp((material.variant_count ?? 4) | 0, 1, MAX_TILES);
+}
+
+/**
+ * Geometry a species' tile draws at maturity `maturity`, in metres.
+ *
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {number} maturity
+ * @param {number} needles
+ * @param {number} shoot_length
+ * @returns {import("./leaf_geometry.js").LeafGeometry}
+ */
+function tile_organ(species, maturity, needles, shoot_length) {
+    const material = species.foliage_material;
+    const shape_var = clamp(material.ontogeny_shape_variation ?? 0.35, 0, 1);
+    return material.tile_content === FoliageTileContent.NeedleShoot
+        ? needle_shoot_geometry(material.leaf, needles, shoot_length, material.needle_angle, foliage_card_plane_count(species.foliage.card_type), maturity, shape_var)
+        : leaf_geometry(material.leaf, maturity, shape_var);
+}
+
+/**
+ * How a species' foliage atlas lays out its tiles: every tile draws its organ (a leaf, or a stretch of needle shoot)
+ * at the same scale, its true size, so a card's size in metres is the tile's at that scale. The mature organ fills the
+ * tile within its margin, attached at the bottom middle; younger, smaller ones fit inside.
+ *
+ * A needle-shoot card draws a stretch of shoot as long as a needle, with as many needles as the shoot bears there
+ * (`FoliageConfig.leaves_per_metre`), shared among the planes it stands up: each plane's tile draws the needles in
+ * its sector round the shoot.
+ *
+ * The resolution draws the organ's finest feature `FEATURE_TEXELS` texels across, and its narrowest stem `STEM_TEXELS`.
+ *
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @returns {FoliageTileLayout}
+ */
+export function foliage_tile_layout(species) {
+    const material = species.foliage_material;
+    const needle_shoot = material.tile_content === FoliageTileContent.NeedleShoot;
+    const shoot_length = needle_shoot ? material.leaf.blade_length : 0;
+    const card_needles = needle_shoot ? Math.max(1, Math.round(species.foliage.leaves_per_metre * shoot_length)) : 0;
+    const needles = needle_shoot ? Math.max(1, Math.round(card_needles / foliage_card_plane_count(species.foliage.card_type))) : 0;
+    const g = tile_organ(species, 1, needles, shoot_length);
+
+    let half_width = 0, min_y = g.attach_y, max_y = g.attach_y;
+    for (let i = 0; i < g.points.length; i += 2) {
+        half_width = Math.max(half_width, Math.abs(g.points[i]));
+        min_y = Math.min(min_y, g.points[i + 1]);
+        max_y = Math.max(max_y, g.points[i + 1]);
+    }
+    const scale = (1 - 2 * TILE_MARGIN) / Math.max(max_y - min_y, 2 * half_width, 1e-6);
+    const card_size = 1 / scale;
+    let stem = Infinity;
+    for (let s = 0; s < g.stems.length; s += 5) stem = Math.min(stem, 2 * g.stems[s + 4]);
+    const wanted = Math.max(FEATURE_TEXELS * card_size / Math.max(1e-6, g.finest), STEM_TEXELS * card_size / Math.max(1e-6, stem));
+    const resolution = clamp(Math.pow(2, Math.ceil(Math.log2(wanted))), MIN_RESOLUTION, MAX_RESOLUTION);
+
+    return {
+        variant_count: foliage_atlas_variant_count(material),
+        resolution,
+        scale,
+        card_size,
+        anchor_u: 0.5,
+        anchor_v: TILE_MARGIN + (g.attach_y - min_y) * scale,
+        leaves_per_card: needle_shoot ? card_needles : 1,
+        needles,
+        shoot_length
+    };
+}
+
+/**
+ * @typedef {Object} FoliageTileRaster
+ * @property {number} maturity of the tile's organ
+ * @property {Float32Array} alpha leaf coverage of each texel, row-major from the tile's bottom (`v` 0) up
+ * @property {Float32Array} vein how strongly a vein shows, `[0, 1]`
+ * @property {Float32Array} edge_norm `0` at the margin, `1` on the midvein (or a primary vein, a rachis)
+ * @property {Float32Array} tip where along the organ, `0` at its foot, `1` at its tip
+ * @property {Float32Array} height lamina relief: camber, bullation, raised veins
+ * @property {Float32Array} stem coverage of the woody stem: petiole, rachis, shoot
+ */
+
+/**
+ * Distance from `(px, py)` to the segment `(x0, y0)`-`(x1, y1)`.
+ */
+function segment_distance(px, py, x0, y0, x1, y1) {
+    const dx = x1 - x0, dy = y1 - y0;
+    const len2 = dx * dx + dy * dy;
+    const t = len2 > 0 ? clamp(((px - x0) * dx + (py - y0) * dy) / len2, 0, 1) : 0;
+    return Math.hypot(px - x0 - dx * t, py - y0 - dy * t);
+}
+
+/**
+ * Rasterizes tile `variant` of a species' atlas: the organ's exact coverage of each texel, and the fields the
+ * material shades it with.
+ *
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {FoliageTileLayout} layout
+ * @param {number} variant
+ * @param {boolean} [coverage_only] skip everything but `alpha`
+ * @returns {FoliageTileRaster}
+ */
+export function foliage_tile_raster(species, layout, variant, coverage_only = false) {
+    const material = species.foliage_material;
+    const res = layout.resolution;
+    const maturity = foliage_variant_maturity(variant, layout.variant_count);
+    const g = tile_organ(species, maturity, layout.needles, layout.shoot_length);
+    const scale = layout.scale;
+
+    // the organ in texels: x across from the anchor, y up from the bottom of the tile
+    const pts = new Float64Array(g.points.length);
+    for (let i = 0; i < g.points.length; i += 2) {
+        pts[i] = (layout.anchor_u + g.points[i] * scale) * res;
+        pts[i + 1] = (layout.anchor_v + (g.points[i + 1] - g.attach_y) * scale) * res;
+    }
+    const n = res * res;
+    const alpha = new Float32Array(n);
+    polygon2_rasterize_coverage(alpha, res, res, pts, g.contours, g.contours.length / 2, COVERAGE_ROWS);
+
+    const out = {
+        maturity,
+        alpha,
+        vein: null,
+        edge_norm: null,
+        tip: null,
+        height: null,
+        stem: null
+    };
+    if (coverage_only) {
+        return out;
+    }
+
+    // distance from each texel inside to the nearest texel outside: how far it lies from the margin
+    const outside = new Uint8Array(n);
+    for (let i = 0; i < n; i++) outside[i] = alpha[i] < 0.5 ? 1 : 0;
+    const edge_texels = new Float32Array(n);
+    computeUnsignedDistanceField_Chamfer(new Sampler2D(outside, 1, res, res), new Sampler2D(edge_texels, 1, res, res), 0, 1, Math.SQRT2, 2 * res);
+
+    const vein = new Float32Array(n);
+    const edge_norm = new Float32Array(n);
+    const tip = new Float32Array(n);
+    const height = new Float32Array(n);
+    const stem = new Float32Array(n);
+    const texels_per_metre = res * scale;
+    const metres_per_texel = 1 / texels_per_metre;
+    const veins = g.veins;
+    const vein_contrast = clamp(material.ontogeny_vein_contrast ?? 0.55, 0, 1);
+    const camber_amp = lerp(0.45, 0.68, maturity);
+    const bullation_amp = lerp(0.02, 0.26, maturity) * vein_contrast;
+    const length = Math.max(1e-6, g.tip_y - g.attach_y);
+    // texels on a midvein, from which the lamina's distance to its midvein is measured
+    const on_midvein = new Uint8Array(n);
+
+    /**
+     * Visits every texel within `reach` (m) of segment `s` of `list`, with its distance to the segment (m).
+     */
+    const near_segment = (list, s, reach, visit) => {
+        const x0 = list[s], y0 = list[s + 1], x1 = list[s + 2], y1 = list[s + 3];
+        const to_x = (mx) => (layout.anchor_u + mx * scale) * res;
+        const to_y = (my) => (layout.anchor_v + (my - g.attach_y) * scale) * res;
+        const r = reach * texels_per_metre;
+        const tx0 = Math.max(0, Math.floor(Math.min(to_x(x0), to_x(x1)) - r));
+        const tx1 = Math.min(res - 1, Math.ceil(Math.max(to_x(x0), to_x(x1)) + r));
+        const ty0 = Math.max(0, Math.floor(Math.min(to_y(y0), to_y(y1)) - r));
+        const ty1 = Math.min(res - 1, Math.ceil(Math.max(to_y(y0), to_y(y1)) + r));
+        for (let y = ty0; y <= ty1; y++) {
+            const my = ((y + 0.5) / res - layout.anchor_v) / scale + g.attach_y;
+            for (let x = tx0; x <= tx1; x++) {
+                const mx = ((x + 0.5) / res - layout.anchor_u) / scale;
+                const d = segment_distance(mx, my, x0, y0, x1, y1);
+                if (d <= reach) visit(y * res + x, d);
+            }
+        }
+    };
+
+    // the woody stem: petiole, rachis, shoot
+    for (let s = 0; s < g.stems.length; s += 5) {
+        const hw = g.stems[s + 4];
+        near_segment(g.stems, s, hw + metres_per_texel, (k, d) => {
+            stem[k] = Math.max(stem[k], smoothStep(-metres_per_texel, metres_per_texel, hw - d));
+        });
+    }
+    // veins stand out within three of their half-widths
+    for (let s = 0; s < veins.length; s += 5) {
+        const hw = Math.max(veins[s + 4], 0.5 * metres_per_texel);
+        const midvein = s / 5 < g.midvein_count;
+        near_segment(veins, s, 3 * hw, (k, d) => {
+            if (alpha[k] <= 0) return;
+            vein[k] = Math.max(vein[k], Math.exp(-(d / hw) * (d / hw)));
+            if (midvein && d <= Math.max(hw, metres_per_texel)) on_midvein[k] = 1;
+        });
+    }
+    const mid_texels = new Float32Array(n);
+    computeUnsignedDistanceField_Chamfer(new Sampler2D(on_midvein, 1, res, res), new Sampler2D(mid_texels, 1, res, res), 0, 1, Math.SQRT2, 2 * res);
+    const has_midvein = g.midvein_count > 0;
+
+    for (let y = 0; y < res; y++) {
+        const my = ((y + 0.5) / res - layout.anchor_v) / scale + g.attach_y;
+        const t = clamp((my - g.attach_y) / length, 0, 1);
+        for (let x = 0; x < res; x++) {
+            const k = y * res + x;
+            if (alpha[k] <= 0) continue;
+            // 0 at the margin, 1 on the midvein
+            const e = has_midvein ? edge_texels[k] / Math.max(1e-6, edge_texels[k] + mid_texels[k]) : 1;
+            edge_norm[k] = e;
+            tip[k] = t;
+            // the lamina cambers up from its margin to its midvein, swells between the veins, and its veins stand out
+            const v = vein[k];
+            const camber = Math.sqrt(Math.max(0, 1 - (1 - e) * (1 - e))) * camber_amp;
+            const bullation = (1 - v) * smoothStep(0, 0.65, e) * bullation_amp;
+            height[k] = (camber + bullation + v * 0.4) * alpha[k];
+        }
+    }
+
+    out.vein = vein;
+    out.edge_norm = edge_norm;
+    out.tip = tip;
+    out.height = height;
+    out.stem = stem;
+    return out;
+}

package/src/generation/foliage/material/leaf_geometry.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @typedef {Object} LeafGeometry
+ * @property {number[]} points flat `(x, y)` (m) in the leaf's frame: `y` along the midvein or rachis, the top of the
+ *           petiole at the origin, `x` across
+ * @property {number[]} contours `(first point, count)` pairs, each counter-clockwise; together they fill the leaf by
+ *           the nonzero rule, so lobes and leaflets overlap freely
+ * @property {number[]} veins `(x0, y0, x1, y1, half_width)` segments (m): midveins and primaries first, then
+ *           secondaries
+ * @property {number} midvein_count how many of `veins` are midveins, primaries or the rachis, from which the blade
+ *           cambers
+ * @property {number[]} stems `(x0, y0, x1, y1, half_width)` segments (m) drawn as woody stem: the petiole, a rachis,
+ *           a needle shoot
+ * @property {number} attach_y where the organ attaches to its shoot along `y` (m): the foot of the petiole, or the
+ *           start of a needle shoot's stretch
+ * @property {number} tip_y where the organ ends along `y` (m), for the shading that runs base to tip
+ * @property {number} finest smallest feature of the outline (m): a tooth, a sinus, the blade's width
+ */
+/**
+ * Size, width and lobe depth of a leaf at ontogenetic maturity `maturity` (0 juvenile, 1 mature) against the mature
+ * leaf the architecture describes: juvenile blades are smaller, narrower and less deeply cut, by `shape_var`.
+ *
+ * @param {number} maturity
+ * @param {number} shape_var
+ * @returns {{length: number, width: number, depth: number}}
+ */
+export function leaf_ontogeny(maturity: number, shape_var: number): {
+    length: number;
+    width: number;
+    depth: number;
+};
+/**
+ * Geometry of a leaf at ontogenetic `maturity`: its outline as contours, its veins, its petiole (and rachis).
+ *
+ * - **Simple:** one blade, its petiole below the origin.
+ * - **Palmately lobed:** a primary lobe per `lobes`, each a blade of the architecture's outline radiating from the
+ *   top of the petiole across `lobe_spread`, the outer ones `lateral_lobe_length` as long, over a body that fills the
+ *   sinuses to `1 - sinus_depth` of the way out.
+ * - **Compound:** `leaflets` blades in pairs along a rachis of `rachis_length`, a terminal one at its end when odd;
+ *   leaflets shorten towards the tip.
+ *
+ * @param {import("../config/LeafArchitecture.js").LeafArchitecture} arch
+ * @param {number} maturity `[0, 1]`
+ * @param {number} shape_var how far juvenile leaves differ, `[0, 1]`
+ * @returns {LeafGeometry}
+ */
+export function leaf_geometry(arch: import("../config/LeafArchitecture.js").LeafArchitecture, maturity: number, shape_var: number): LeafGeometry;
+/**
+ * Geometry of a stretch of needle shoot `shoot_length` long as one of `planes` card planes through it shows it: the
+ * shoot up `y` from the origin and the `needles` needles whose azimuth round the shoot lies within the plane's sector,
+ * `pi / planes` wide either side of the shoot, evenly along it. Each leaves the shoot at `needle_angle`; turned
+ * out of the plane by its azimuth, it shows at a shallower angle and foreshortened.
+ *
+ * @param {import("../config/LeafArchitecture.js").LeafArchitecture} arch the needle
+ * @param {number} needles drawn on this plane
+ * @param {number} shoot_length m
+ * @param {number} needle_angle radians from the shoot
+ * @param {number} planes card planes the shoot's needles are shared among
+ * @param {number} maturity
+ * @param {number} shape_var
+ * @returns {LeafGeometry}
+ */
+export function needle_shoot_geometry(arch: import("../config/LeafArchitecture.js").LeafArchitecture, needles: number, shoot_length: number, needle_angle: number, planes: number, maturity: number, shape_var: number): LeafGeometry;
+export type LeafGeometry = {
+    /**
+     * flat `(x, y)` (m) in the leaf's frame: `y` along the midvein or rachis, the top of the
+     * petiole at the origin, `x` across
+     */
+    points: number[];
+    /**
+     * `(first point, count)` pairs, each counter-clockwise; together they fill the leaf by
+     * the nonzero rule, so lobes and leaflets overlap freely
+     */
+    contours: number[];
+    /**
+     * `(x0, y0, x1, y1, half_width)` segments (m): midveins and primaries first, then
+     * secondaries
+     */
+    veins: number[];
+    /**
+     * how many of `veins` are midveins, primaries or the rachis, from which the blade
+     * cambers
+     */
+    midvein_count: number;
+    /**
+     * `(x0, y0, x1, y1, half_width)` segments (m) drawn as woody stem: the petiole, a rachis,
+     * a needle shoot
+     */
+    stems: number[];
+    /**
+     * where the organ attaches to its shoot along `y` (m): the foot of the petiole, or the
+     * start of a needle shoot's stretch
+     */
+    attach_y: number;
+    /**
+     * where the organ ends along `y` (m), for the shading that runs base to tip
+     */
+    tip_y: number;
+    /**
+     * smallest feature of the outline (m): a tooth, a sinus, the blade's width
+     */
+    finest: number;
+};
+//# sourceMappingURL=leaf_geometry.d.ts.map

package/src/generation/foliage/material/leaf_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaf_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/material/leaf_geometry.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;GAOG;AACH,wCAJW,MAAM,aACN,MAAM,GACJ;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAQ1D;AA8TD;;;;;;;;;;;;;;GAcG;AACH,oCALW,OAAO,+BAA+B,EAAE,gBAAgB,YACxD,MAAM,aACN,MAAM,GACJ,YAAY,CAkFxB;AAED;;;;;;;;;;;;;;GAcG;AACH,4CATW,OAAO,+BAA+B,EAAE,gBAAgB,WACxD,MAAM,gBACN,MAAM,gBACN,MAAM,UACN,MAAM,YACN,MAAM,aACN,MAAM,GACJ,YAAY,CAkCxB;;;;;;YA5ea,MAAM,EAAE;;;;;cAER,MAAM,EAAE;;;;;WAER,MAAM,EAAE;;;;;mBAER,MAAM;;;;;WAEN,MAAM,EAAE;;;;;cAER,MAAM;;;;WAEN,MAAM;;;;YACN,MAAM"}