@woosh/meep-engine 3.52.0 → 3.54.0

package/src/generation/foliage/config/FoliageConfig.js

@@ -0,0 +1,283 @@
+import { assert } from "../../../core/assert.js";
+import { hash_mix2 } from "../../../core/math/hash/hash_mix2.js";
+import { computeHashFloat } from "../../../core/primitives/numbers/computeHashFloat.js";
+import { FoliageCardType } from "./FoliageCardType.js";
+import { PhyllotaxisMode } from "./PhyllotaxisMode.js";
+
+/**
+ * Configuration for phyllotactic leaf/frond placement, card topology, heliotropism, and canopy AO.
+ */
+export class FoliageConfig {
+    /**
+     * Whether foliage geometry is generated.
+     * @type {boolean}
+     */
+    enabled = true;
+
+    /**
+     * Leaf cluster card or frond mesh topology.
+     * @type {FoliageCardType|number}
+     */
+    card_type = FoliageCardType.FoldedVCard;
+
+    /**
+     * Minimum branch recursion level that carries foliage cards.
+     * @type {number}
+     */
+    attach_min_level = 2;
+
+    /**
+     * Number of phyllotactic nodes along each qualifying carrier branch.
+     * @type {number}
+     */
+    cards_per_branch = 10;
+
+    /**
+     * Number of terminal rosette cards clustered at the branch tip (t = 1).
+     * @type {number}
+     */
+    terminal_rosette_count = 3;
+
+    /**
+     * Bare fraction [0, 0.9] at the base of a carrier branch without leaves.
+     * @type {number}
+     */
+    bare_ratio = 0.2;
+
+    /**
+     * Phyllotactic arrangement mode for leaf attachments.
+     * @type {PhyllotaxisMode|number}
+     */
+    phyllotaxis_mode = PhyllotaxisMode.SpiralGolden;
+
+    /**
+     * Organs per node when `phyllotaxis_mode === PhyllotaxisMode.Whorled`.
+     * @type {number}
+     */
+    whorl_count = 3;
+
+    /**
+     * Petiole insertion angle (radians) relative to carrier branch tangent.
+     * @type {number}
+     */
+    insertion_angle = 0.85;
+
+    /**
+     * Base width of a leaf cluster card or frond (meters).
+     * @type {number}
+     */
+    card_width = 0.85;
+
+    /**
+     * Base length of a leaf cluster card or frond from petiole pivot to tip (meters).
+     * @type {number}
+     */
+    card_length = 0.95;
+
+    /**
+     * Relative random variance in card dimensions [0, 0.8].
+     * @type {number}
+     */
+    size_variance = 0.2;
+
+    /**
+     * Transverse V-fold dihedral angle (radians) across the midrib.
+     * @type {number}
+     */
+    fold_angle = 0.28;
+
+    /**
+     * Midrib arch elevation (meters) at mid-span.
+     * @type {number}
+     */
+    arch_height = 0.08;
+
+    /**
+     * Longitudinal tip droop displacement (meters).
+     * @type {number}
+     */
+    camber_droop = 0.1;
+
+    /**
+     * Number of longitudinal segments when `card_type === FoliageCardType.RibbedFrond`.
+     * @type {number}
+     */
+    frond_segments = 5;
+
+    /**
+     * Heliotropic reorientation weight [0, 1] aligning adaxial leaf normals toward sky/canopy exterior.
+     * @type {number}
+     */
+    phototropism = 0.6;
+
+    /**
+     * Gravitropic petiole droop weight [-1, 1].
+     * @type {number}
+     */
+    gravitropism = 0.25;
+
+    /**
+     * Per-card random angular jitter (radians) to break specular aliasing.
+     * @type {number}
+     */
+    angular_jitter = 0.25;
+
+    /**
+     * Hemisphere-safe normal puffing factor [0, 0.45] blending card normals toward canopy exterior.
+     * @type {number}
+     */
+    normal_puffiness = 0.32;
+
+    /**
+     * Minimum ambient occlusion brightness in deep crown core [0.1, 1.0].
+     * @type {number}
+     */
+    ao_core_darkening = 0.35;
+
+    /**
+     * Per-cluster brightness/tint variation amplitude in vertex colors [0, 0.3].
+     * @type {number}
+     */
+    color_variation = 0.08;
+
+    /**
+     * @param {Partial<FoliageConfig>} [options]
+     * @returns {FoliageConfig}
+     */
+    static from(options = {}) {
+        const r = new FoliageConfig();
+        r.applyOverrides(options);
+        return r;
+    }
+
+    /**
+     * @param {Partial<FoliageConfig>|boolean} [overrides]
+     * @returns {this}
+     */
+    applyOverrides(overrides = {}) {
+        if (overrides === null || overrides === undefined) {
+            return this;
+        }
+        if (typeof overrides === "boolean") {
+            this.enabled = overrides;
+            return this;
+        }
+        if (overrides.enabled !== undefined) this.enabled = Boolean(overrides.enabled);
+        if (overrides.card_type !== undefined) this.card_type = overrides.card_type;
+        if (overrides.attach_min_level !== undefined) this.attach_min_level = Math.max(0, overrides.attach_min_level | 0);
+        if (overrides.cards_per_branch !== undefined) this.cards_per_branch = Math.max(0, overrides.cards_per_branch | 0);
+        if (overrides.terminal_rosette_count !== undefined) this.terminal_rosette_count = Math.max(0, overrides.terminal_rosette_count | 0);
+        if (overrides.bare_ratio !== undefined) this.bare_ratio = overrides.bare_ratio;
+        if (overrides.phyllotaxis_mode !== undefined) this.phyllotaxis_mode = overrides.phyllotaxis_mode;
+        if (overrides.whorl_count !== undefined) this.whorl_count = Math.max(1, overrides.whorl_count | 0);
+        if (overrides.insertion_angle !== undefined) this.insertion_angle = overrides.insertion_angle;
+        if (overrides.card_width !== undefined) this.card_width = overrides.card_width;
+        if (overrides.card_length !== undefined) this.card_length = overrides.card_length;
+        if (overrides.size_variance !== undefined) this.size_variance = overrides.size_variance;
+        if (overrides.fold_angle !== undefined) this.fold_angle = overrides.fold_angle;
+        if (overrides.arch_height !== undefined) this.arch_height = overrides.arch_height;
+        if (overrides.camber_droop !== undefined) this.camber_droop = overrides.camber_droop;
+        if (overrides.frond_segments !== undefined) this.frond_segments = Math.max(2, overrides.frond_segments | 0);
+        if (overrides.phototropism !== undefined) this.phototropism = overrides.phototropism;
+        if (overrides.gravitropism !== undefined) this.gravitropism = overrides.gravitropism;
+        if (overrides.angular_jitter !== undefined) this.angular_jitter = overrides.angular_jitter;
+        if (overrides.normal_puffiness !== undefined) this.normal_puffiness = overrides.normal_puffiness;
+        if (overrides.ao_core_darkening !== undefined) this.ao_core_darkening = overrides.ao_core_darkening;
+        if (overrides.color_variation !== undefined) this.color_variation = overrides.color_variation;
+        return this;
+    }
+
+    /**
+     * @param {FoliageConfig} other
+     * @returns {this}
+     */
+    copy(other) {
+        assert.defined(other, 'other');
+        this.enabled = other.enabled;
+        this.card_type = other.card_type;
+        this.attach_min_level = other.attach_min_level;
+        this.cards_per_branch = other.cards_per_branch;
+        this.terminal_rosette_count = other.terminal_rosette_count;
+        this.bare_ratio = other.bare_ratio;
+        this.phyllotaxis_mode = other.phyllotaxis_mode;
+        this.whorl_count = other.whorl_count;
+        this.insertion_angle = other.insertion_angle;
+        this.card_width = other.card_width;
+        this.card_length = other.card_length;
+        this.size_variance = other.size_variance;
+        this.fold_angle = other.fold_angle;
+        this.arch_height = other.arch_height;
+        this.camber_droop = other.camber_droop;
+        this.frond_segments = other.frond_segments;
+        this.phototropism = other.phototropism;
+        this.gravitropism = other.gravitropism;
+        this.angular_jitter = other.angular_jitter;
+        this.normal_puffiness = other.normal_puffiness;
+        this.ao_core_darkening = other.ao_core_darkening;
+        this.color_variation = other.color_variation;
+        return this;
+    }
+
+    /**
+     * @returns {FoliageConfig}
+     */
+    clone() {
+        const r = new FoliageConfig();
+        r.copy(this);
+        return r;
+    }
+
+    /**
+     * @param {FoliageConfig} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (this === other) return true;
+        if (!other || !other.isFoliageConfig) return false;
+        return this.enabled === other.enabled
+            && this.card_type === other.card_type
+            && this.attach_min_level === other.attach_min_level
+            && this.cards_per_branch === other.cards_per_branch
+            && this.terminal_rosette_count === other.terminal_rosette_count
+            && this.bare_ratio === other.bare_ratio
+            && this.phyllotaxis_mode === other.phyllotaxis_mode
+            && this.whorl_count === other.whorl_count
+            && this.insertion_angle === other.insertion_angle
+            && this.card_width === other.card_width
+            && this.card_length === other.card_length
+            && this.size_variance === other.size_variance
+            && this.fold_angle === other.fold_angle
+            && this.arch_height === other.arch_height
+            && this.camber_droop === other.camber_droop
+            && this.frond_segments === other.frond_segments
+            && this.phototropism === other.phototropism
+            && this.gravitropism === other.gravitropism
+            && this.angular_jitter === other.angular_jitter
+            && this.normal_puffiness === other.normal_puffiness
+            && this.ao_core_darkening === other.ao_core_darkening
+            && this.color_variation === other.color_variation;
+    }
+
+    /**
+     * @returns {number}
+     */
+    hash() {
+        let h = hash_mix2(this.enabled ? 1 : 0, this.card_type);
+        h = hash_mix2(h, this.attach_min_level);
+        h = hash_mix2(h, this.cards_per_branch);
+        h = hash_mix2(h, this.terminal_rosette_count);
+        h = hash_mix2(h, this.phyllotaxis_mode);
+        h = hash_mix2(h, computeHashFloat(this.card_width));
+        h = hash_mix2(h, computeHashFloat(this.card_length));
+        h = hash_mix2(h, computeHashFloat(this.fold_angle));
+        h = hash_mix2(h, computeHashFloat(this.phototropism));
+        h = hash_mix2(h, computeHashFloat(this.gravitropism));
+        return h;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+FoliageConfig.prototype.isFoliageConfig = true;

package/src/generation/foliage/config/FoliageMaterialConfig.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Procedural foliage cluster PBR material, ontogenetic variant atlas, & biochemical senescence configuration.
+ */
+export class FoliageMaterialConfig {
+    /**
+     * @param {Partial<FoliageMaterialConfig>} [options]
+     * @returns {FoliageMaterialConfig}
+     */
+    static from(options?: Partial<FoliageMaterialConfig>): FoliageMaterialConfig;
+    /**
+     * Procedural per-variant tile resolution (pixels, power of two).
+     * @type {number}
+     */
+    resolution: number;
+    /**
+     * Mature sun-facing leaf lamina color (sRGB).
+     * @type {Color}
+     */
+    primary_color: Color;
+    /**
+     * Vein / secondary leaf color (sRGB).
+     * @type {Color}
+     */
+    secondary_color: Color;
+    /**
+     * Legacy / convenience autumn shift factor [0, 1].
+     * Acts as a lower bound on `senescence` when non-zero for backwards compatibility.
+     * @type {number}
+     */
+    autumn_tint: number;
+    /**
+     * Leaf cluster silhouette style: `"ovate" | "lobed" | "serrated" | "palmate" | "needle" | "frond"`.
+     * @type {string}
+     */
+    leaf_shape: string;
+    /**
+     * Number of leaflets arranged on the twig cluster card.
+     * @type {number}
+     */
+    leaflets_per_cluster: number;
+    /**
+     * Base PBR roughness [0, 1].
+     * @type {number}
+     */
+    roughness: number;
+    /**
+     * Venation normal-map relief strength [0, 1].
+     * @type {number}
+     */
+    vein_strength: number;
+    /**
+     * Horizontal UV coordinate [0, 1] on the foliage card where the drawn woody stem/petiole attaches to the branch.
+     * @type {number}
+     */
+    stem_anchor_u: number;
+    /**
+     * Vertical UV coordinate [0, 1] on the foliage card where the drawn woody stem/petiole attaches to the branch.
+     * @type {number}
+     */
+    stem_anchor_v: number;
+    /**
+     * Number of ontogenetic foliage card variants packed into the material atlas [1, 16].
+     * Variant 0 represents newly flushed juvenile apical leaves; Variant `variant_count - 1`
+     * represents fully mature (or most senescent) basal/interior leaves.
+     * @type {number}
+     */
+    variant_count: number;
+    /**
+     * Juvenile-to-mature chlorophyll-lag lightening & yellow-green/chartreuse shift [0, 1].
+     * @type {number}
+     */
+    juvenile_color_shift: number;
+    /**
+     * Transient epidermal anthocyanin bronze/reddish margin flush on newly emerging juvenile leaves [0, 1].
+     * @type {number}
+     */
+    juvenile_anthocyanin: number;
+    /**
+     * Juvenile-to-mature leaflet aspect ratio, lobe/tooth incision depth, and lateral spread progression [0, 1].
+     * @type {number}
+     */
+    ontogeny_shape_variation: number;
+    /**
+     * Juvenile-to-mature vascular venation relief, interveinal bullation, stem lignification, and cuticle roughness progression [0, 1].
+     * @type {number}
+     */
+    ontogeny_vein_contrast: number;
+    /**
+     * Seasonal chlorophyll catabolism (autumn senescence) stage [0, 1].
+     * Governed by photoperiod/temperature breakdown of chlorophyll a/b, which unmasks plastid carotenoids,
+     * triggers photoprotective vacuolar anthocyanin synthesis in sunlit leaves, and oxidizes foliar tannins.
+     * @type {number}
+     */
+    senescence: number;
+    /**
+     * Foliar xanthophyll & beta-carotene concentration [0, 1] unmasked as chlorophyll degrades
+     * (drives vivid golden-yellow autumn coloration in Birch, Willow, Aspen, Ginkgo, Maple).
+     * @type {number}
+     */
+    carotenoid_density: number;
+    /**
+     * Species genetic potential [0, 1] for de novo vacuolar anthocyanin synthesis under high solar
+     * irradiance and carbohydrate accumulation during senescence (drives scarlet/crimson in Maple & Oak).
+     * @type {number}
+     */
+    anthocyanin_potential: number;
+    /**
+     * Foliar condensed tannin / polyphenol oxidation rate [0, 1] into russet/copper-brown during late senescence
+     * (high in Oak, low in Birch/Maple).
+     * @type {number}
+     */
+    tannin_oxidation: number;
+    /**
+     * @param {Partial<FoliageMaterialConfig>} [overrides]
+     * @returns {this}
+     */
+    applyOverrides(overrides?: Partial<FoliageMaterialConfig>): this;
+    /**
+     * @param {FoliageMaterialConfig} other
+     * @returns {this}
+     */
+    copy(other: FoliageMaterialConfig): this;
+    /**
+     * @returns {FoliageMaterialConfig}
+     */
+    clone(): FoliageMaterialConfig;
+    /**
+     * @param {FoliageMaterialConfig} other
+     * @returns {boolean}
+     */
+    equals(other: FoliageMaterialConfig): boolean;
+    /**
+     * @returns {number}
+     */
+    hash(): number;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isFoliageMaterialConfig: boolean;
+}
+import { Color } from "../../../core/color/Color.js";
+//# sourceMappingURL=FoliageMaterialConfig.d.ts.map

package/src/generation/foliage/config/FoliageMaterialConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FoliageMaterialConfig.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/config/FoliageMaterialConfig.js"],"names":[],"mappings":"AAMA;;GAEG;AACH;IA2HC;;;OAGG;IACH,sBAHW,QAAQ,qBAAqB,CAAC,GAC5B,qBAAqB,CAMjC;IAlID;;;OAGG;IACH,YAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,eAFU,KAAK,CAEkC;IAEjD;;;OAGG;IACH,iBAFU,KAAK,CAEoC;IAEnD;;;;OAIG;IACH,aAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,YAFU,MAAM,CAEK;IAErB;;;OAGG;IACH,sBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,WAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,eAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,eAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,eAFU,MAAM,CAEI;IAEpB;;;;;OAKG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,sBAFU,MAAM,CAEY;IAE5B;;;OAGG;IACH,sBAFU,MAAM,CAEY;IAE5B;;;OAGG;IACH,0BAFU,MAAM,CAEgB;IAEhC;;;OAGG;IACH,wBAFU,MAAM,CAEc;IAE9B;;;;;OAKG;IACH,YAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,oBAFU,MAAM,CAEU;IAE1B;;;;OAIG;IACH,uBAFU,MAAM,CAEa;IAE7B;;;;OAIG;IACH,kBAFU,MAAM,CAEQ;IAYxB;;;OAGG;IACH,2BAHW,QAAQ,qBAAqB,CAAC,GAC5B,IAAI,CAsChB;IAED;;;OAGG;IACH,YAHW,qBAAqB,GACnB,IAAI,CAwBhB;IAED;;OAEG;IACH,SAFa,qBAAqB,CAMjC;IAED;;;OAGG;IACH,cAHW,qBAAqB,GACnB,OAAO,CAwBnB;IAED;;OAEG;IACH,QAFa,MAAM,CAqBlB;IAGF;;;OAGG;IACH,kCAFU,OAAO,CAEsC;CANtD;sBA/QqB,8BAA8B"}