@woosh/meep-engine 3.52.0 → 3.54.0

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

@@ -0,0 +1,157 @@
+import { assert } from "../../../core/assert.js";
+import { hash_mix2 } from "../../../core/math/hash/hash_mix2.js";
+import { computeHashFloat } from "../../../core/primitives/numbers/computeHashFloat.js";
+
+/**
+ * Configuration for GPU fluid-driven skeletal wind animation (`Skin` + `FoliageWindRig`)
+ * and per-vertex wind attributes.
+ *
+ * Foliage bones are driven directly on the GPU by sampling Meep's 3D fluid dynamics
+ * wind field (`GPUSceneWind`: `GlobalFluidEffector` far-field + 3D MAC `GPUFluidCascadeStack`
+ * wakes/vortices/impulses) and stepping a 2nd-order damped spring-damper oscillator per joint.
+ */
+export class TreeWindConfig {
+    /**
+     * Whether GPU fluid-driven skeletal wind rig and joint attributes are generated.
+     * @type {boolean}
+     */
+    enabled = true;
+
+    /**
+     * Maximum number of structural skeleton joints extracted for `Skin` and `FoliageWindRig` (>= 1).
+     * @type {number}
+     */
+    max_joints = 32;
+
+    /**
+     * Baseline aerodynamic compliance (rad / (m/s)^2) for level-0 trunk joints.
+     * @type {number}
+     */
+    trunk_compliance = 0.012;
+
+    /**
+     * Baseline aerodynamic compliance (rad / (m/s)^2) for primary and secondary branch joints.
+     * @type {number}
+     */
+    branch_compliance = 0.045;
+
+    /**
+     * Baseline natural angular frequency omega_0 (rad/s) for structural branches.
+     * @type {number}
+     */
+    natural_frequency = 2.8;
+
+    /**
+     * Dimensionless viscous + structural damping ratio zeta (0 < zeta < 1 is underdamped).
+     * @type {number}
+     */
+    damping_ratio = 0.32;
+
+    /**
+     * Cross-wind vortex-shedding & turbulent flutter amplitude ratio [0..1].
+     * @type {number}
+     */
+    turbulence = 0.28;
+
+    /**
+     * Asymptotic elastic bend saturation limit (radians).
+     * @type {number}
+     */
+    max_bend_angle = 0.65;
+
+    /**
+     * @param {Partial<TreeWindConfig>|boolean} [options]
+     * @returns {TreeWindConfig}
+     */
+    static from(options = {}) {
+        const r = new TreeWindConfig();
+        r.applyOverrides(options);
+        return r;
+    }
+
+    /**
+     * @param {Partial<TreeWindConfig>|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.max_joints !== undefined) this.max_joints = Math.max(1, overrides.max_joints | 0);
+        if (overrides.trunk_compliance !== undefined) this.trunk_compliance = Math.max(0, overrides.trunk_compliance);
+        if (overrides.branch_compliance !== undefined) this.branch_compliance = Math.max(0, overrides.branch_compliance);
+        if (overrides.natural_frequency !== undefined) this.natural_frequency = Math.max(0.1, overrides.natural_frequency);
+        if (overrides.damping_ratio !== undefined) this.damping_ratio = Math.max(0.01, overrides.damping_ratio);
+        if (overrides.turbulence !== undefined) this.turbulence = Math.max(0, overrides.turbulence);
+        if (overrides.max_bend_angle !== undefined) this.max_bend_angle = Math.max(0.01, overrides.max_bend_angle);
+        return this;
+    }
+
+    /**
+     * @param {TreeWindConfig} other
+     * @returns {this}
+     */
+    copy(other) {
+        assert.defined(other, 'other');
+        this.enabled = other.enabled;
+        this.max_joints = other.max_joints;
+        this.trunk_compliance = other.trunk_compliance;
+        this.branch_compliance = other.branch_compliance;
+        this.natural_frequency = other.natural_frequency;
+        this.damping_ratio = other.damping_ratio;
+        this.turbulence = other.turbulence;
+        this.max_bend_angle = other.max_bend_angle;
+        return this;
+    }
+
+    /**
+     * @returns {TreeWindConfig}
+     */
+    clone() {
+        const r = new TreeWindConfig();
+        r.copy(this);
+        return r;
+    }
+
+    /**
+     * @param {TreeWindConfig} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (this === other) return true;
+        if (!other || !other.isTreeWindConfig) return false;
+        return this.enabled === other.enabled
+            && this.max_joints === other.max_joints
+            && this.trunk_compliance === other.trunk_compliance
+            && this.branch_compliance === other.branch_compliance
+            && this.natural_frequency === other.natural_frequency
+            && this.damping_ratio === other.damping_ratio
+            && this.turbulence === other.turbulence
+            && this.max_bend_angle === other.max_bend_angle;
+    }
+
+    /**
+     * @returns {number}
+     */
+    hash() {
+        let h = hash_mix2(this.enabled ? 1 : 0, this.max_joints);
+        h = hash_mix2(h, computeHashFloat(this.trunk_compliance));
+        h = hash_mix2(h, computeHashFloat(this.branch_compliance));
+        h = hash_mix2(h, computeHashFloat(this.natural_frequency));
+        h = hash_mix2(h, computeHashFloat(this.damping_ratio));
+        h = hash_mix2(h, computeHashFloat(this.turbulence));
+        h = hash_mix2(h, computeHashFloat(this.max_bend_angle));
+        return h;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+TreeWindConfig.prototype.isTreeWindConfig = true;

package/src/generation/foliage/index.d.ts

@@ -0,0 +1,39 @@
+export { CrownEnvelopeType } from "./config/CrownEnvelopeType.js";
+export { PhyllotaxisMode } from "./config/PhyllotaxisMode.js";
+export { FoliageCardType } from "./config/FoliageCardType.js";
+export { FoliageBarkType } from "./config/FoliageBarkType.js";
+export { TreePreset } from "./config/TreePreset.js";
+export { BranchLevelConfig } from "./config/BranchLevelConfig.js";
+export { CrownConfig } from "./config/CrownConfig.js";
+export { FoliageConfig } from "./config/FoliageConfig.js";
+export { BarkMaterialConfig } from "./config/BarkMaterialConfig.js";
+export { FoliageMaterialConfig } from "./config/FoliageMaterialConfig.js";
+export { TreeWindConfig } from "./config/TreeWindConfig.js";
+export { TreeLODConfig } from "./config/TreeLODConfig.js";
+export { TreeSpeciesConfig } from "./config/TreeSpeciesConfig.js";
+export { make_tree_species_preset } from "./presets/make_tree_species_preset.js";
+export { TreeSkeleton } from "./skeleton/TreeSkeleton.js";
+export { spine_frame_double_reflection } from "./skeleton/spine_frame_double_reflection.js";
+export { tree_skeleton_grow } from "./skeleton/tree_skeleton_grow.js";
+export { tree_skeleton_compute_pipe_radii } from "./skeleton/tree_skeleton_compute_pipe_radii.js";
+export { tree_skeleton_assign_skin_joints } from "./skeleton/tree_skeleton_assign_skin_joints.js";
+export { branch_collar_project } from "./mesh/branch_collar_project.js";
+export { foliage_collect_attachments } from "./mesh/foliage_collect_attachments.js";
+export { tree_mesh_build_foliage } from "./mesh/tree_mesh_build_foliage.js";
+export { tree_mesh_apply_canopy_ao } from "./mesh/tree_mesh_apply_canopy_ao.js";
+export { make_bark_material } from "./material/make_bark_material.js";
+export { build_tree_wind_rig } from "./animation/build_tree_wind_rig.js";
+export { FoliageWindJoint } from "../../shade/renderer/animation/foliage/FoliageWindJoint.js";
+export { FoliageWindRig } from "../../shade/renderer/animation/foliage/FoliageWindRig.js";
+export { chunk_foliage_wind_step } from "../../shade/renderer/animation/foliage/chunk_foliage_wind_step.js";
+export { FoliageWindRigs } from "../../engine/graphics3/animation/FoliageWindRigs.js";
+export { FoliageWindSystem } from "../../engine/graphics3/FoliageWindSystem.js";
+export { TreeLODAsset } from "./asset/TreeLODAsset.js";
+export { TreeAsset } from "./asset/TreeAsset.js";
+export { generate_tree } from "./asset/generate_tree.js";
+export { crown_envelope_evaluate, crown_envelope_sdf } from "./skeleton/crown_envelope_evaluate.js";
+export { branch_ring_triangulate, branch_apex_triangulate } from "./mesh/branch_ring_triangulate.js";
+export { tree_mesh_build_bark, geometry_obtain_joints_attribute } from "./mesh/tree_mesh_build_bark.js";
+export { make_foliage_material, compute_foliage_variant_atlas_layout } from "./material/make_foliage_material.js";
+export { place_tree, unplace_tree } from "./asset/place_tree.js";
+//# sourceMappingURL=index.d.ts.map

package/src/generation/foliage/index.d.ts.map

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

package/src/generation/foliage/index.js

@@ -0,0 +1,44 @@
+export { CrownEnvelopeType } from "./config/CrownEnvelopeType.js";
+export { PhyllotaxisMode } from "./config/PhyllotaxisMode.js";
+export { FoliageCardType } from "./config/FoliageCardType.js";
+export { FoliageBarkType } from "./config/FoliageBarkType.js";
+export { TreePreset } from "./config/TreePreset.js";
+export { BranchLevelConfig } from "./config/BranchLevelConfig.js";
+export { CrownConfig } from "./config/CrownConfig.js";
+export { FoliageConfig } from "./config/FoliageConfig.js";
+export { BarkMaterialConfig } from "./config/BarkMaterialConfig.js";
+export { FoliageMaterialConfig } from "./config/FoliageMaterialConfig.js";
+export { TreeWindConfig } from "./config/TreeWindConfig.js";
+export { TreeLODConfig } from "./config/TreeLODConfig.js";
+export { TreeSpeciesConfig } from "./config/TreeSpeciesConfig.js";
+
+export { make_tree_species_preset } from "./presets/make_tree_species_preset.js";
+
+export { TreeSkeleton } from "./skeleton/TreeSkeleton.js";
+export { crown_envelope_evaluate, crown_envelope_sdf } from "./skeleton/crown_envelope_evaluate.js";
+export { spine_frame_double_reflection } from "./skeleton/spine_frame_double_reflection.js";
+export { tree_skeleton_grow } from "./skeleton/tree_skeleton_grow.js";
+export { tree_skeleton_compute_pipe_radii } from "./skeleton/tree_skeleton_compute_pipe_radii.js";
+export { tree_skeleton_assign_skin_joints } from "./skeleton/tree_skeleton_assign_skin_joints.js";
+
+export { branch_collar_project } from "./mesh/branch_collar_project.js";
+export { branch_ring_triangulate, branch_apex_triangulate } from "./mesh/branch_ring_triangulate.js";
+export { tree_mesh_build_bark, geometry_obtain_joints_attribute } from "./mesh/tree_mesh_build_bark.js";
+export { foliage_collect_attachments } from "./mesh/foliage_collect_attachments.js";
+export { tree_mesh_build_foliage } from "./mesh/tree_mesh_build_foliage.js";
+export { tree_mesh_apply_canopy_ao } from "./mesh/tree_mesh_apply_canopy_ao.js";
+
+export { make_bark_material } from "./material/make_bark_material.js";
+export { make_foliage_material, compute_foliage_variant_atlas_layout } from "./material/make_foliage_material.js";
+
+export { build_tree_wind_rig } from "./animation/build_tree_wind_rig.js";
+export { FoliageWindJoint } from "../../shade/renderer/animation/foliage/FoliageWindJoint.js";
+export { FoliageWindRig } from "../../shade/renderer/animation/foliage/FoliageWindRig.js";
+export { chunk_foliage_wind_step } from "../../shade/renderer/animation/foliage/chunk_foliage_wind_step.js";
+export { FoliageWindRigs } from "../../engine/graphics3/animation/FoliageWindRigs.js";
+export { FoliageWindSystem } from "../../engine/graphics3/FoliageWindSystem.js";
+
+export { TreeLODAsset } from "./asset/TreeLODAsset.js";
+export { TreeAsset } from "./asset/TreeAsset.js";
+export { generate_tree } from "./asset/generate_tree.js";
+export { place_tree, unplace_tree } from "./asset/place_tree.js";

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

@@ -0,0 +1,37 @@
+/**
+ * Evaluates the low-frequency 3D macro-relief heightfield and smooth UV grain flow at `(u, v)`.
+ * Used by `tree_mesh_build_bark` for 3D cross-sectional undulation (strictly band-limited to
+ * low circumferential frequencies `<= 3` so polygon rings never suffer Nyquist aliasing creases!).
+ *
+ * Writes `[height, dh_du, u_flow_warp, knot_mask]` to `out`.
+ *
+ * @param {Float32Array|number[]} out
+ * @param {number} u
+ * @param {number} v
+ * @param {BarkMaterialConfig} cfg
+ * @param {number} [seed=1]
+ */
+export function evaluate_bark_relief(out: Float32Array | number[], u: number, v: number, cfg: BarkMaterialConfig, seed?: number): void;
+/**
+ * Synthesizes a turn-key procedural PBR `StandardShadeMaterial` for tree bark, including
+ * Albedo (`ColorSpace.SRGB`), 2-channel Tangent-Space Normal (`ColorSpace.LinearSRGB`,
+ * `TextureFilterType.LinearNormal`), and ORM (`R=Occlusion, G=Roughness, B=Metalness=0`) textures.
+ *
+ * The horizontal axis `U in [0, 1)` tiles seamlessly around branch circumferences (`wrapS = Repeat`),
+ * while the vertical axis `V in [0, 1]` (`wrapT = ClampToEdge`) encodes continuous ontogenetic bark
+ * evolution from old ruptured basal trunk bark (`V ~ 0`) through mature trunk/bough bark (`V ~ 0.35`)
+ * to smooth young upper shoot/twig bark (`V ~ 0.9`).
+ *
+ * Because `V in [0, 1]` spans the full ontogenetic height of the tree (~8x longer in world space than
+ * a single circumference wrap `U in [0, 1)`), vertical texture resolution (`height = width * 4`) and
+ * vertical cellular/noise frequencies are scaled by the world-space aspect ratio so bark plates,
+ * fissures, and lenticels have crisp, isotropic world-space proportions without vertical stretching.
+ *
+ * @param {BarkMaterialConfig|Object} [config]
+ * @param {number} [seed=1]
+ * @returns {StandardShadeMaterial}
+ */
+export function make_bark_material(config?: BarkMaterialConfig | any, seed?: number): StandardShadeMaterial;
+import { BarkMaterialConfig } from "../config/BarkMaterialConfig.js";
+import { StandardShadeMaterial } from "../../../shade/renderer/material/StandardShadeMaterial.js";
+//# sourceMappingURL=make_bark_material.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"make_bark_material.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/material/make_bark_material.js"],"names":[],"mappings":"AA6GA;;;;;;;;;;;;GAYG;AACH,0CANW,YAAY,GAAC,MAAM,EAAE,KACrB,MAAM,KACN,MAAM,OACN,kBAAkB,SAClB,MAAM,QAsEhB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,4CAJW,kBAAkB,MAAO,SACzB,MAAM,GACJ,qBAAqB,CAwgBjC;mCAzsBkC,iCAAiC;sCAR9B,2DAA2D"}