@woosh/meep-engine 3.52.0 → 3.54.0

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

@@ -0,0 +1,186 @@
+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 { CrownEnvelopeType } from "./CrownEnvelopeType.js";
+
+/**
+ * Macro crown silhouette, space colonization competition, and pipe-model parameters.
+ */
+export class CrownConfig {
+    /**
+     * Silhouette envelope shape.
+     * @type {CrownEnvelopeType|number}
+     */
+    envelope_type = CrownEnvelopeType.Spherical;
+
+    /**
+     * Total crown vertical extent (meters).
+     * @type {number}
+     */
+    height = 8.4;
+
+    /**
+     * Maximum crown horizontal radius (meters).
+     * @type {number}
+     */
+    radius = 5.4;
+
+    /**
+     * Height above ground (Y=0) where the crown envelope begins (meters).
+     * @type {number}
+     */
+    base_height = 2.4;
+
+    /**
+     * Strength [0, 1] of envelope pruning / length clamping on lateral branches.
+     * @type {number}
+     */
+    prune_ratio = 0.35;
+
+    /**
+     * Weight [0, 1] of Runions space-colonization attraction steering on growing branch tips.
+     * @type {number}
+     */
+    space_colonization_weight = 0.25;
+
+    /**
+     * Number of attraction points distributed inside the crown envelope.
+     * @type {number}
+     */
+    attraction_point_count = 160;
+
+    /**
+     * Radius of influence (meters) within which an attraction point pulls growing tips.
+     * @type {number}
+     */
+    attraction_radius = 2.5;
+
+    /**
+     * Kill distance (meters) within which an attraction point is consumed by a growing tip.
+     * @type {number}
+     */
+    kill_radius = 0.65;
+
+    /**
+     * Da Vinci / Murray pipe-model exponent alpha in r_parent^alpha = sum(r_child^alpha).
+     * @type {number}
+     */
+    pipe_model_exponent = 2.3;
+
+    /**
+     * Blend weight [0, 1] between parametric taper and bottom-up pipe-model radius accumulation.
+     * @type {number}
+     */
+    pipe_model_weight = 0.6;
+
+    /**
+     * Mix [0, 1] between zenith (+Y) and radial crown-outward vector for phototropism.
+     * @type {number}
+     */
+    sky_phototropism_mix = 0.6;
+
+    /**
+     * @param {Partial<CrownConfig>} [options]
+     * @returns {CrownConfig}
+     */
+    static from(options = {}) {
+        const r = new CrownConfig();
+        r.applyOverrides(options);
+        return r;
+    }
+
+    /**
+     * @param {Partial<CrownConfig>} [overrides]
+     * @returns {this}
+     */
+    applyOverrides(overrides = {}) {
+        if (overrides === null || overrides === undefined) {
+            return this;
+        }
+        if (overrides.envelope_type !== undefined) this.envelope_type = overrides.envelope_type;
+        if (overrides.height !== undefined) this.height = overrides.height;
+        if (overrides.radius !== undefined) this.radius = overrides.radius;
+        if (overrides.base_height !== undefined) this.base_height = overrides.base_height;
+        if (overrides.prune_ratio !== undefined) this.prune_ratio = overrides.prune_ratio;
+        if (overrides.space_colonization_weight !== undefined) this.space_colonization_weight = overrides.space_colonization_weight;
+        if (overrides.attraction_point_count !== undefined) this.attraction_point_count = Math.max(0, overrides.attraction_point_count | 0);
+        if (overrides.attraction_radius !== undefined) this.attraction_radius = overrides.attraction_radius;
+        if (overrides.kill_radius !== undefined) this.kill_radius = overrides.kill_radius;
+        if (overrides.pipe_model_exponent !== undefined) this.pipe_model_exponent = overrides.pipe_model_exponent;
+        if (overrides.pipe_model_weight !== undefined) this.pipe_model_weight = overrides.pipe_model_weight;
+        if (overrides.sky_phototropism_mix !== undefined) this.sky_phototropism_mix = overrides.sky_phototropism_mix;
+        return this;
+    }
+
+    /**
+     * @param {CrownConfig} other
+     * @returns {this}
+     */
+    copy(other) {
+        assert.defined(other, 'other');
+        this.envelope_type = other.envelope_type;
+        this.height = other.height;
+        this.radius = other.radius;
+        this.base_height = other.base_height;
+        this.prune_ratio = other.prune_ratio;
+        this.space_colonization_weight = other.space_colonization_weight;
+        this.attraction_point_count = other.attraction_point_count;
+        this.attraction_radius = other.attraction_radius;
+        this.kill_radius = other.kill_radius;
+        this.pipe_model_exponent = other.pipe_model_exponent;
+        this.pipe_model_weight = other.pipe_model_weight;
+        this.sky_phototropism_mix = other.sky_phototropism_mix;
+        return this;
+    }
+
+    /**
+     * @returns {CrownConfig}
+     */
+    clone() {
+        const r = new CrownConfig();
+        r.copy(this);
+        return r;
+    }
+
+    /**
+     * @param {CrownConfig} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (this === other) return true;
+        if (!other || !other.isCrownConfig) return false;
+        return this.envelope_type === other.envelope_type
+            && this.height === other.height
+            && this.radius === other.radius
+            && this.base_height === other.base_height
+            && this.prune_ratio === other.prune_ratio
+            && this.space_colonization_weight === other.space_colonization_weight
+            && this.attraction_point_count === other.attraction_point_count
+            && this.attraction_radius === other.attraction_radius
+            && this.kill_radius === other.kill_radius
+            && this.pipe_model_exponent === other.pipe_model_exponent
+            && this.pipe_model_weight === other.pipe_model_weight
+            && this.sky_phototropism_mix === other.sky_phototropism_mix;
+    }
+
+    /**
+     * @returns {number}
+     */
+    hash() {
+        let h = hash_mix2(this.envelope_type, computeHashFloat(this.height));
+        h = hash_mix2(h, computeHashFloat(this.radius));
+        h = hash_mix2(h, computeHashFloat(this.base_height));
+        h = hash_mix2(h, computeHashFloat(this.prune_ratio));
+        h = hash_mix2(h, computeHashFloat(this.space_colonization_weight));
+        h = hash_mix2(h, this.attraction_point_count);
+        h = hash_mix2(h, computeHashFloat(this.pipe_model_exponent));
+        h = hash_mix2(h, computeHashFloat(this.pipe_model_weight));
+        return h;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+CrownConfig.prototype.isCrownConfig = true;

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

@@ -0,0 +1,16 @@
+/**
+ * Botanical crown silhouette envelope shapes (Weber & Penn 1995 + weeping extension).
+ */
+export type CrownEnvelopeType = number;
+export namespace CrownEnvelopeType {
+    let Conical: number;
+    let Spherical: number;
+    let Hemispherical: number;
+    let Cylindrical: number;
+    let TaperedCylindrical: number;
+    let Flame: number;
+    let InverseConical: number;
+    let TendFlame: number;
+    let Weeping: number;
+}
+//# sourceMappingURL=CrownEnvelopeType.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CrownEnvelopeType.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/config/CrownEnvelopeType.js"],"names":[],"mappings":";;;gCAIU,MAAM"}

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

@@ -0,0 +1,17 @@
+/**
+ * Botanical crown silhouette envelope shapes (Weber & Penn 1995 + weeping extension).
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const CrownEnvelopeType = {
+    Conical: 0,
+    Spherical: 1,
+    Hemispherical: 2,
+    Cylindrical: 3,
+    TaperedCylindrical: 4,
+    Flame: 5,
+    InverseConical: 6,
+    TendFlame: 7,
+    Weeping: 8,
+};

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

@@ -0,0 +1,11 @@
+/**
+ * Botanical bark surface pattern archetypes for procedural bark synthesis and relief.
+ */
+export type FoliageBarkType = number;
+export namespace FoliageBarkType {
+    let Fissured: number;
+    let Birch: number;
+    let Plated: number;
+    let Ringed: number;
+}
+//# sourceMappingURL=FoliageBarkType.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FoliageBarkType.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/config/FoliageBarkType.js"],"names":[],"mappings":";;;8BAIU,MAAM"}

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

@@ -0,0 +1,16 @@
+/**
+ * Botanical bark surface pattern archetypes for procedural bark synthesis and relief.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const FoliageBarkType = {
+    /** Braided vertical ridges and cellular fissures (oak, willow, maple default) */
+    Fissured: 0,
+    /** Chalk-white periderm with horizontal lenticel dashes, peeling strips, and basal rupture skirt (birch) */
+    Birch: 1,
+    /** Ragged exfoliating stepped conifer scale plates (pine, spruce) */
+    Plated: 2,
+    /** Horizontal leaf-scar rings and fibrous trunk weave (palm, shrub, fern) */
+    Ringed: 3,
+};

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

@@ -0,0 +1,12 @@
+/**
+ * Real-time foliage cluster card and frond mesh archetypes.
+ */
+export type FoliageCardType = number;
+export namespace FoliageCardType {
+    let FoldedVCard: number;
+    let CrossCard: number;
+    let TriStarCluster: number;
+    let RibbedFrond: number;
+    let OctagonalCutoutHull: number;
+}
+//# sourceMappingURL=FoliageCardType.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FoliageCardType.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/config/FoliageCardType.js"],"names":[],"mappings":";;;8BAIU,MAAM"}

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

@@ -0,0 +1,18 @@
+/**
+ * Real-time foliage cluster card and frond mesh archetypes.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const FoliageCardType = {
+    /** Folded V-card with longitudinal arch and tip camber (broadleaf default) */
+    FoldedVCard: 0,
+    /** Two intersecting orthogonal V-cards (conifer needle tufts & dense shrubs) */
+    CrossCard: 1,
+    /** Three cards arranged at 60-degree star angles (volumetric pine/spruce clusters) */
+    TriStarCluster: 2,
+    /** Multi-segment curved Cubic Hermite ribbed frond (palms, ferns, weeping boughs) */
+    RibbedFrond: 3,
+    /** Tight hexagonal/octagonal alpha-bound hull trimming empty corners */
+    OctagonalCutoutHull: 4,
+};

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"FoliageConfig.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/config/FoliageConfig.js"],"names":[],"mappings":"AAMA;;GAEG;AACH;IAqII;;;OAGG;IACH,sBAHW,QAAQ,aAAa,CAAC,GACpB,aAAa,CAMzB;IA5ID;;;OAGG;IACH,SAFU,OAAO,CAEF;IAEf;;;OAGG;IACH,WAFU,eAAe,GAAC,MAAM,CAEQ;IAExC;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;OAGG;IACH,kBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;OAGG;IACH,YAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,kBAFU,eAAe,GAAC,MAAM,CAEgB;IAEhD;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,iBAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,YAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,aAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,eAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,YAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,aAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,cAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,cAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,cAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,gBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,kBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,mBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,iBAFU,MAAM,CAEO;IAYvB;;;OAGG;IACH,2BAHW,QAAQ,aAAa,CAAC,GAAC,OAAO,GAC5B,IAAI,CAiChB;IAED;;;OAGG;IACH,YAHW,aAAa,GACX,IAAI,CA2BhB;IAED;;OAEG;IACH,SAFa,aAAa,CAMzB;IAED;;;OAGG;IACH,cAHW,aAAa,GACX,OAAO,CA2BnB;IAED;;OAEG;IACH,QAFa,MAAM,CAclB;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;CANtC;gCAjR+B,sBAAsB;gCACtB,sBAAsB"}