@woosh/meep-engine 3.55.0 → 3.57.0

package/src/generation/foliage/CROWN_FILLING_BRIEF_2026_10_26.md

@@ -0,0 +1,172 @@
+# Crown Filling by Light
+
+Follows `SHOOT_SYSTEMS_ALL_SPECIES_BRIEF_2026_10_26.md`, which grew every woody species' twigs from sourced shoot
+demography and left the crowns barren.
+
+## Problem
+
+Each carrier grows its twig system alone for a fixed number of years, at a fixed vigour (net shoots a shoot leaves a
+year), with shoots shed by a chosen rank of age, order and length. Nothing in that knows where the crown is empty or
+crowded. Seed 1337, against master's metre-long cards:
+
+| preset | leaf area, master -> now | side opacity, master -> now |
+| :--- | ---: | ---: |
+| birch | 45 -> 2 m^2 | 0.44 -> 0.10 |
+| willow | 241 -> 7 m^2 | 0.67 -> 0.18 |
+| pine | 174 -> 24 m^2 | 0.69 -> 0.33 |
+| spruce | 161 -> 20 m^2 | 0.57 -> 0.34 |
+| maple | 150 -> 63 m^2 | 0.66 -> 0.43 |
+| oak | 164 -> 113 m^2 | 0.64 -> 0.51 |
+
+**The target** is the US Forest Inventory's crown ratings of 15,011 leaf-on trees seen from the side (Randolph 2006,
+USDA GTR SRS-94, Tables 1-4). Healthy crowns block a mean 45% of their outline (oaks, maples, birches 46-51%), and their
+foliated parts let about 15% of skylight through (interquartile 10-20%). From below, open-grown crowns intercept 0.75-0.92
+of light (Nowak 1996, Forest Science 42: 504-507, Table 2).
+
+## Principle
+
+A real crown is full because it grows until it shades itself. Shoots in light make more shoots; shoots in shade make
+fewer, and an axis in deep shade dies. The papers already in hand measure exactly this:
+
+- **Spruce.** Rb, the net shoots a shoot leaves a year, rises with the light a branch receives: about 0.65 at
+  4-5 mol m^-2 d^-1 to about 2.2 at 10-12, against 37.1 under open sky, so 0.12 to 0.30 of full light. Below 1 in deep
+  shade, a branch's foliage shrinks with age (Niinemets & Lukjanova 2003, New Phytol. 158: 75-89, Fig. 5b, Table 1).
+- **Pine.** Branching stops at a relative light of 0.20-0.25 (Ilonen et al. 1979, Silva Fennica 13: 319-321). A shoot
+  with no needles left is dead (Kellomäki & Kurttio 1991, p. 104).
+- **Birch.** The bud population grows 1.52 a year in the top of the crown, 0.999 at its bottom (Maillette 1982, J.
+  Appl. Ecol. 19: 219-238, Table 1).
+- **Red maple.** Shaded branches die, so foliage stays at the crown's periphery (Wilson 1966, Harvard Forest Paper 14,
+  p. 19).
+
+So vigour becomes a function of light, and the crown's leaf area becomes an outcome: growth stops where the crown has
+shaded its own interior to the light at which shoots no longer replace themselves.
+
+## Design
+
+The framework (trunk, boughs and branches from the generator graph) stays as it is. Everything younger grows by light.
+`tree_skeleton_grow_shoots` is rebuilt around one tree-wide simulation:
+
+1. **One season loop for the whole tree.** Every carrier's twig system grows in the same loop, so the systems compete
+   for the same light. `years` and the light response move from the per-carrier `ShootSystemRule` to a species-level
+   `ShootGrowthConfig`. The rules keep what differs by carrier: bud zones, lengths, orders, angles.
+2. **Shoots have geometry as they grow.** Each new unit's start, heading and end are fixed in its season (tropisms,
+   zigzag, insertion and phyllotaxis, as the writer does today), so light can be measured where the leaves are. The
+   writer then only turns the surviving axes into skeleton branches.
+3. **The light field.** Each season, the leaf area of every leaf-bearing unit is deposited in a voxel grid over the
+   crown.
+   - **Light at each voxel:** relative irradiance from the sky by Beer-Lambert, `exp(-G Omega LAD path)`.
+   - **Extinction:** `G = 0.5`, the projection of a spherical leaf angle distribution.
+   - **Clumping:** `Omega` is the species' shoot clumping; Scots pine about 0.58 from its silhouette-to-area ratio of
+     0.146 (Smolander, Stenberg & Linder 1994, Tree Physiol. 14: 971-980), broadleaves 1 for want of data.
+   - **Sky:** a standard overcast sky, radiance `(1 + 2 sin elevation) / 3` (Moon & Spencer 1942), weighted for a
+     horizontal receiver as hemispherical photographs measure it.
+   - **Directions:** lattice directions, so each is one sweep of the grid. The cost is grid cells times directions,
+     whatever the leaf count.
+4. **Vigour follows light.** An axis in relative light `Q` leaves `Rb(Q)` net shoots a year. `Rb` rises linearly from 1
+   at the species' compensation light to its full vigour at its saturation light, flat above, and falls below 1 under
+   compensation. A season's new shoots on an axis survive at `Rb(Q) / yield`, its gross yield of new shoots. The shoots
+   kept are the best lit, with a dithered count so the total is exact on average. This replaces the chosen
+   age/order/length rank.
+5. **Death by shade is not a separate rule.** A terminal that is shed takes its axis with it [BB1998], and in shade the
+   terminal is shed. A shaded branch thins and dies as `Rb < 1` makes it.
+6. **Long enough to fill.** `years` covers the time the periphery takes to reach the light limit, so crown fullness is
+   set by light, not by when the simulation stops. The equilibrium is measured, not assumed.
+7. **Wood.** The [BB2000] Table 7 diameter holds only for current and year-old units, the shoots it was measured on.
+   Older wood is the pipe model plus what its laterals need where they join, for twig and carrier alike.
+8. **Framework avoidance** is tested when a unit grows, as now.
+
+**Per-species light response:**
+
+| preset | compensation `Q` | saturation `Q` | full vigour | source |
+| :--- | ---: | ---: | ---: | :--- |
+| spruce | 0.16 | 0.30 | 2.19 | [NL2003] Fig. 5b line through (0.12, 0.65), (0.30, 2.2); Table 1 max |
+| pine | 0.22 | 0.30 | 1.867 | Ilonen 1979 (0.20-0.25); saturation spruce's; [NL2003] Fig. 2 |
+| birch | 0.22 | 0.30 | 1.52 | top of crown [M1982]; light points pine's |
+| oak, maple, willow, shrub | chosen | chosen | chosen | none found |
+
+**Gaps.** Only spruce has a measured light curve. Pine has its compensation point. The others borrow the curve's
+shape, and that is marked in the code.
+
+## Measuring
+
+- **Fullness:** crown density and foliage transparency against Randolph 2006, and interception from below against Nowak
+  1996, measured with the crown opacity benchmark being built in a sibling session. Until that lands, the scratchpad
+  probe stands in.
+- **Specs, from the principle:**
+  - In a uniform light field, the twig population changes by `Rb(Q)` a year.
+  - Shoots in shade die.
+  - Leaf area stops growing with `years` once the crown is full.
+  - Doubling `years` past equilibrium changes leaf area little.
+  - A crown with more framework does not end up with proportionally more leaf.
+
+## Plan
+
+1. `ShootGrowthConfig`; the rule loses `years` and `vigour`.
+2. `shoot_light_field`: voxel leaf area, sky sweeps, irradiance query. Specs against Beer-Lambert in closed form.
+3. The tree-wide simulation with geometry, light-driven survival, framework avoidance at growth.
+4. The writer and radii on the simulated axes.
+5. Presets: light response per species.
+6. Specs green (including the willow seam and the season order), mutation-tested.
+7. Measure every preset against the targets; look at each in the playground.
+
+## Landed (2026-10-26, uncommitted)
+
+As designed, plus what building it turned up:
+
+- **The simulation:** `shoot_systems_simulate` runs every carrier's twig system in one season loop against a
+  `ShootLightField` (leaf-area voxels of `light_cell`, 17 lattice sweeps of the overcast sky, matches Beer-Lambert in
+  closed form within 0.01). Each season: extension with tropisms, short-shoot survival `short_shoot_survival x
+  min(1, Rb(Q))`, bursts, syllepsis, shedding to `Rb(Q) / yield` (rank: log keep share, age, order, length, jitter),
+  the cascade of a shed mother, then the wood.
+- **Dynamic girth** (Alex's pick over a forecast radius): `ShootGirth` thickens the wood each season with what it
+  carries, never thinning: the pipe model at the species' `pipe_model_exponent` over the shoots' Table 7 radius, Table
+  7 for a unit of its age, and `1 / SHOOT_LATERAL_RADIUS_RATIO` of a lateral where it joins, on twigs, carriers and the
+  framework above them. A shoot grows only where it clears today's wood; a shoot the wood has grown into by the end
+  of a season dies with all it carries. The framework hash (`ShootFrameworkHash`, allocation-free) is rebuilt each
+  season.
+- **Framework ages** come from the leader growth: a branch is born when its parent's tip passed its seat, so a carrier
+  carries `round(age)` units over its whole length.
+- **Cards follow leaves:** a unit carries its leaves (`leaves_per_unit + leaves_per_metre L`, times `leaf_survival` at
+  its age) over the leaves one card draws (`foliage_card_leaf_count`), dithered; short shoots get their own rosette
+  tiles (`foliage_atlas_tiles.js`).
+- **Skinning seats** (found by the willow seam spec once twigs grew on twigs): where more than four joints meet, the
+  four kept are those that leave the seat least far from where all of them would carry it, and a dropped joint folds
+  into the kept one that carries the point most alike. "How far apart" is each joint on the path between them turning
+  by its reference-wind rotation about its pivot (`TreeSkeleton.joint_rotation`, written by
+  `tree_skeleton_assign_skin_joints`). Willow seats over the 1 cm tolerance: 178 by weight-then-hops, 6 by
+  weight-times-hops, 0 now.
+
+**Specs restated from their principle** (each mutation-tested red):
+- interpenetration: a child may meet its mother's wood only in the crotch, the run of its first segments that still
+  lie in her wood, and a child whose tip is in her wood is buried; twigs no longer get a year-old-girth allowance. The
+  spec finds candidate pairs by a grid (it was n^2 and timed out at 90k segments).
+- conifer tiers: they come from the whorls (spiral boughs: empty bands 5.4x fewer on spruce, 3.9x on pine);
+  plagiotropism no longer moves them (0.95x).
+- spire: the leader's top unit, clothed in at least half the needles a unit of `leader_growth` carries.
+- autumn order: the leaves that fell were more exposed and younger than those kept, by a quarter of the summer spread.
+- shoot demography: from `tree_skeleton_grow`'s records (zones, the four-bud whorl, ancestry, light response).
+
+**Measured at seed 1337** with master's `foliage_measure_leaf_area` and `tree_crown_opacity` (copied in for the run):
+
+| preset | leaf m^2 | crown LAI | side density | side transparency | below density | below transparency | generate |
+| :--- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| oak | 90.9 | 3.11 | 0.51 | 0.44 | 0.53 | 0.38 | 0.9 s |
+| pine | 35.0 | 1.60 | 0.38 | 0.60 | 0.41 | 0.53 | 1.0 s |
+| birch | 64.5 | 6.59 | 0.56 | 0.38 | 0.80 | 0.15 | 2.5 s |
+| willow | 136.3 | 3.68 | 0.69 | 0.30 | 0.71 | 0.25 | 2.0 s |
+| maple | 36.3 | 1.42 | 0.33 | 0.55 | 0.32 | 0.43 | 1.1 s |
+| spruce | 117.8 | 4.44 | 0.36 | 0.28 | 0.45 | 0.25 | 3.1 s |
+| shrub | 57.8 | 4.65 | 0.62 | 0.34 | 0.77 | 0.18 | 0.3 s |
+
+(generate: skeleton and cards, `probe_crowns.mjs`.) FIA's targets are density 45-51% and transparency about 15%
+[Randolph 2006].
+
+**Open, measured:**
+- Every preset is far more see-through than FIA's 15%; only oak's density is in range.
+- **The shrub was barren** at a chosen Rb of 1.3 (2.1 m^2, crown LAI 0.18): light did not limit it, the stool's young
+  stems seeded few lineages, and 1.3 of a gross yield of 7.17 kept under one burst shoot in five even in full sun. No
+  net shoot yield was found for hazel (Grisafi et al. 2024 report one season's bud fates; orchard LAI 0.80-2.86,
+  Oeztuerk et al. 2018, is per ground area). Alex's pick: full-sun vigour is the gross yield the rule's Grisafi
+  numbers give (`shoot_expected_yield`, 7.17), so only shade sheds hazel shoots. Light saturates the crown from about
+  2.8 up. The shrub row above is measured at that vigour; master's leaf-area and opacity specs pass on this tree.
+- Engulfment took birch from 115 to 83 m^2 (probe), willow from 167 to 157, spruce from 140 to 121.

package/src/generation/foliage/FOLIAGE_DESIGN.md

@@ -7,7 +7,7 @@ This document specifies a production-grade, State-of-the-Art (SotA) procedural t
 ### Core Design Tenets
 1. **Turn-Key Top Layer, Layered Override API Underneath**:
    - **Top Layer (1-line turn-key)**: `generate_tree({ preset: TreePreset.Oak, seed: 42 })` or `place_tree(scene_context, dataset, { preset: "pine", position: [10, 0, -5] })` produces a complete, multi-LOD, wind-rigged, PBR-materialized tree asset (`TreeAsset` / `SceneBundle` / `Prefab`) with zero external asset files required.
-   - **Mid Layer (Species & Generator Descriptors)**: Declarative `TreeSpeciesConfig`, `BranchLevelConfig`, `CrownConfig`, `FoliageConfig`, `BarkMaterialConfig`, `FoliageMaterialConfig`, and `TreeWindConfig` with `AnimationCurve` profiles and full JSON serialization.
+   - **Mid Layer (Species & Generator Descriptors)**: Declarative `TreeSpeciesConfig`, a branch generator graph (`BranchGeneratorConfig` nodes joined by `BranchSpawnRule` edges, foliage placed by `FoliageSpawnRule`s), `CrownConfig`, `FoliageConfig`, `BarkMaterialConfig`, `FoliageMaterialConfig`, and `TreeWindConfig` with `AnimationCurve` profiles and full JSON serialization.
    - **Low Layer (Pure Pipeline Passes)**: Composable, allocation-conscious pure functions operating on `Graph` skeletons, `Transform64` node frames, Hermite spine buffers, `PointHashGrid3` crown fields, and `Geometry` / `Attribute` buffers.
 2. **Zero Duplicate Adjacent Infrastructure**:
    - **Coordinate System**: Strictly Meep's right-handed **Y-up** convention (`Vector3.up = (0, 1, 0)`, ground plane `X-Z`).
@@ -106,23 +106,58 @@ Evaluating any point or derivative at local parameter $u \in [0, 1]$ along edge
 - `spline3_hermite_derivative(u, p0x, p1x, m0x, m1x)` (for $x, y, z$)
 
 ### 4.2 Hybrid Parametric + Space-Colonization Growth Algorithm
-For each recursion level $l \in \{0, \dots, L_{\max}\}$:
+Branches are grown breadth-first from the trunk (`species.branches[0]`). Every `species.branch_rules` edge
+`source -> target` (always `source < target`, so the graph is acyclic) spawns branches of generator `target` along
+each branch of generator `source`; one generator may spawn several kinds of children (boughs, roots, stubs, sprouts,
+inter-whorl branches) and several generators may spawn the same kind (fan-in). Branching depth $l$ counts lateral
+hops from the trunk; split forks keep their parent's depth and generator.
 1. **Crown Envelope & Space Colonization Field**:
    - The crown volume is defined by a configurable `CrownEnvelopeType` (`Conical`, `Spherical`, `Hemispherical`, `Cylindrical`, `TaperedCylindrical`, `Flame`, `InverseConical`, `TendFlame`, `Weeping`, or custom `AnimationCurve` profile) centered at $(0, H_{\text{crown}}, 0)$.
    - When `space_colonization_weight > 0`, $N_{\text{attract}}$ attraction points are sampled deterministically inside the crown envelope using `seededRandom` and indexed in a `PointHashGrid3` with cell size equal to the attraction radius $d_i$.
 2. **Branch Spawn & Phyllotactic Budding**:
-   - Along each parent branch of level $l - 1$, child branches are spawned above `bare_length_ratio` $t_{\text{bare}} \in [0, 1)$ according to the level's `PhyllotaxisMode` (`SpiralGolden` $137.507764^\circ$, `AlternateDistichous` $180^\circ$, `OppositeDecussate` $180^\circ + 90^\circ$ flip, `Opposite` $180^\circ$, `Whorled` $360^\circ / M$).
-   - Child branch length $L_l(t_p)$ is modulated by the parent's `length_profile: AnimationCurve` and the crown envelope $S_{\text{env}}(h_{\text{norm}})$.
+   - Along each parent branch, each outgoing rule spawns its children inside `[attach_min, attach_max]` according to the rule's `PhyllotaxisMode` (`SpiralGolden` $137.507764^\circ$, `AlternateDistichous` $180^\circ$, `OppositeDecussate` $180^\circ + 90^\circ$ flip, `Opposite` $180^\circ$, `Whorled` $360^\circ / M$, `FlareLobes` on the crests of the parent's basal buttress lobes).
+   - Child branch length $L_l(t_p)$ is modulated by the rule's `length_profile: AnimationCurve` and, for rules with `crown_envelope`, the crown envelope $S_{\text{env}}(h_{\text{norm}})$. Children of a rule without `crown_envelope` (roots, trunk sprouts) are neither shrunk by the envelope nor kept inside it.
+   - Self-pruning: below a crown rule's `attach_min` the rule once grew children too, at the same nodes continued down the stem; they died in the crown's shade. Each keeps `(1 - self_pruning) - age` of its length as a dead stub (age 0 just below the living children, 1 at the stem base; size at death `(1 - age)` of today's), and once that no longer clears the bark it is grown over and becomes a bark scar (knot).
+   - Generators with `root` grow structural surface roots: they descend onto the ground plane $y = 0$ and creep along it, add no pipe-model area to their stem, and never receive a wind joint.
    - Initial child heading $\mathbf{T}_c(0)$ diverges from parent tangent $\mathbf{T}_p(t_p)$ by insertion angle $\alpha_{\text{insert}}(t_p)$ around the azimuth $\phi_k$ in the parent's RMF plane $(\mathbf{R}_p, \mathbf{S}_p)$.
    - The child's initial RMF normal $\mathbf{R}_c(0)$ is aligned with the adaxial (upper crotch) projection of $\mathbf{T}_p$:
      $$\mathbf{R}_c(0) = \text{normalize}\big(\mathbf{T}_p - (\mathbf{T}_p \cdot \mathbf{T}_c(0))\mathbf{T}_c(0)\big)$$
      guaranteeing that $\theta = 0$ on the child's cross-section always lies at the top of the branch collar.
+   - **Dorsiventral parents** (`BranchGeneratorConfig.plagiotropism` $p > 0$, lateral generators only):
+     - **The plane.** A plagiotropic parent bears its buds in the plane of its tangent $\mathbf{T}_p$ and the horizontal
+       $\mathbf{H} = \mathbf{T}_p \times \mathbf{e}_y$ across it. The plane's normal is
+       $\mathbf{N} = \mathbf{H} \times \mathbf{T}_p$, which points up.
+     - **Ventral knockout.** No bud is emitted into the downward cone of half-angle $p\,\pi/2$.
+       - A bud whose own heading points into the cone does not break. That test is about where the bud sits on the
+         bough.
+       - Nor may fanning, or a turn for clearance, carry a bud's emitted heading into the cone. Each such candidate is
+         rejected, and a bud with none left does not break.
+       - Contact projection of a child's first segment can still deflect it in afterwards.
+     - **Fanning.** The surviving buds' radial direction loses $p\,|\mathbf{H}|$ of its component along $\mathbf{N}$,
+       fanning them into the plane. A vertical parent has no such plane, and its children are not fanned.
+     - **Which species.** Plagiotropism follows the species' architectural model (Hallé, Oldeman & Tomlinson's architectural models, as listed by Pfisterer (2000, *Mitt. Biol. Bundesanst.* 370) and Millet, Bouchard & Édelin (1999, *Écoscience* 6: 187–203)):
+       - **Massart's model** (*Picea*, *Abies*): tiers of plagiotropic branches. The spruce preset sets it.
+       - **Rauh's model** (*Pinus*, *Acer*, *Quercus*, *Betula*): branches orthotropic and built like the trunk. Those
+         presets set none.
+       - **Troll's model** (*Fagus*, *Tilia*, *Ulmus*): every axis plagiotropic. Not among the presets.
+       - The knockout is the least sourced part: laterals of a plagiotropic branch lie in its horizontal plane, but no
+         *Picea*-specific source was found for the fate of its ventral buds. On spruce it barely acts, since the buds are
+         already distichous.
+     - **Replaces.** This replaces an undocumented emission rule keyed on the *child's* gravitropism, which biased every
+       lateral's buds upward and off its underside.
+       - **Pads:** its effect was small (oak 0.750 with it, 0.789 without).
+       - **Headings:** its effect was not. Without it, oak has 3.8% of twigs more than 30° below the horizontal against
+         1.4% (mean heading y 0.327 against 0.398), and birch 1.2% against 0.6%.
+       - **No basis:** Rauh-model branches are orthotropic and branch radially, and the positional bias reported for
+         some of them is slight hypotony (lower-side laterals favoured; Millet et al. 1999), not an upward one.
 3. **Stepped Spine Integration with Tropisms, Gnarl, & Splits**:
    - As segment $k \to k+1$ advances by $\Delta s = L_l / N_{\text{seg}}$:
      - **Intrinsic curvature**: Pitch rotation around $\mathbf{S}_k$ by $\Delta \theta_{\text{curve}}(t_k)$ and helical twist around $\mathbf{T}_k$.
      - **Gravitropism (Y-up)**: Bending toward $-\mathbf{e}_y = (0, -1, 0)$ (or $+\mathbf{e}_y$ for negative gravitropism), weighted by mechanical tip compliance $\text{lerp}(0.2, 1.0, t^\gamma)$.
      - **Phototropism**: Steering toward $\text{normalize}(\alpha_{\text{sky}}\mathbf{e}_y + (1-\alpha_{\text{sky}})\mathbf{d}_{\text{radial}})$ to seek sky light and escape interior crown self-shading.
      - **Curl / Simplex Gnarl**: 3D divergence-free `curl_noise_3d` (or `sdnoise3_array`) projected perpendicular to $\mathbf{T}_k$.
+     - **Plagiotropism**: a lateral shoot with `plagiotropism` $p$ is steered by $-p\,T_{k,y}\,\mathbf{e}_y$ towards the horizontal. The apical `tip_upcurl` still turns its tip up, so conifer boughs keep their upturned ends.
+     - **Straightness**: `straightness` $\lambda$ adds $\lambda(\mathbf{T}_0 - \mathbf{T}_k)$, a pull back towards the heading the branch was given, so strong gnarl does not carry a branch out of its sector. $\mathbf{T}_0$ is the bud's heading. For the fork that continues a split it becomes the heading the split deflected it to, as the other forks aim along their own. It resists every deviation from that heading, droop included.
      - **Space Colonization Pull**: Queries `PointHashGrid3.forEachNear` around $\mathbf{p}_k$, pulling $\mathbf{T}_{k+1}$ toward unclaimed attraction points within radius $d_i$ and marking attraction points within kill radius $d_k$ as consumed.
      - **Sympodial / Dichotomous Forking (`split_probability`, `split_angle`, `split_Spread`)**: At segment $k$, a stem can bifurcate or trifurcate into $M \in \{2, 3\}$ daughter branches that diverge symmetrically in azimuth and pitch.
      - **RMF Transport**: Advances $(\mathbf{R}_k, \mathbf{S}_k) \to (\mathbf{R}_{k+1}, \mathbf{S}_{k+1})$ via Wang et al. (2008) **Double Reflection** with fallback to `tube_frame_transport`.
@@ -130,6 +165,26 @@ For each recursion level $l \in \{0, \dots, L_{\max}\}$:
    - After all branch levels are generated in `skeleton.graph`, a bottom-up post-order pass accumulates cross-sectional area using the Da Vinci / Murray Pipe Model law:
      $$R_{\text{pipe}}(v) = \left( R_{\text{tip}}^\alpha + \sum_{e=(v \to u)} R_{\text{pipe}}(u)^\alpha \right)^{1/\alpha}, \quad \alpha \in [2.0, 2.8]$$
    - The final radius at node $v$ blends the artist-controlled parametric taper curve (`radius_profile: AnimationCurve`) with the physical pipe model via `pipe_model_weight` $\in [0, 1]$.
+5. **Annual Shoot Layer** (`skeleton/tree_skeleton_grow_shoots.js`, `skeleton/shoot_systems_simulate.js`; see
+   `CROWN_FILLING_BRIEF_2026_10_26.md`):
+   - **Input.** Each `species.shoot_rules` entry (`ShootSystemRule`, its bud zones `ShootBudZone`) grows the
+     peripheral twig system on every living branch of its `source` generator, after the pipe-model pass. The twigs are
+     branches of generator `target` (short shoots `short_target`), one level below their carrier.
+   - **The carrier's growth.** A framework branch is born when its parent's tip passed its seat, at the species'
+     `shoot_growth.leader_growth`; it carries `round(age)` annual units over its whole length.
+   - **Each season, tree-wide**, under a voxel light field (`ShootLightField`: leaf area, Beer-Lambert from a standard
+     overcast sky):
+     - Every living axis grows a terminal unit; short shoots survive as their light allows.
+     - Last season's units burst their zones' buds (and this season's, sylleptically). Unit lengths are drawn per
+       order.
+     - New shoots are kept to their light's net yield, `shoot_growth.net_yield(Q)` over the rule's gross yield. A shed
+       axis takes everything on it.
+     - The wood thickens with what it carries (`ShootGirth`): Table 7 (`d = 0.27 + 0.13 age + 0.02 l` cm) for a unit
+       of its age, the pipe model at the species' exponent, and 1 / 0.82 of a lateral where it joins, on twigs,
+       carriers and the framework above them.
+   - **Avoidance.** A unit grows only where it clears today's wood; a shoot the wood has grown into dies.
+   - **The record.** Every carrier and twig records where each of its annual units starts
+     (`TreeSkeleton.branch_unit_start_t`), for the foliage pass (§6.1).
 
 ---
 
@@ -167,17 +222,94 @@ For any lateral branch ($l \ge 1$) attached to a parent branch of radius $R_p$ a
 
 ### 6.1 Phyllotactic Attachment Generator
 Generates `FoliageAttachment` transforms along carrier branches of levels $l \in [l_{\text{min}}, L_{\max}]$:
-- Supports `SpiralGolden` ($137.507764^\circ$), `AlternateDistichous` ($180^\circ$), `Tristichous` ($120^\circ$), `Opposite` ($2\times 180^\circ$), `OppositeDecussate` ($2\times 180^\circ$ with $90^\circ$ alternation), and `Whorled` ($M$ organs per node), plus terminal rosette clustering at branch tips ($t \to 1$).
+- Supports `SpiralGolden` ($137.507764^\circ$), `AlternateDistichous` ($180^\circ$), `Tristichous` ($120^\circ$), `Opposite` ($2\times 180^\circ$), `OppositeDecussate` ($2\times 180^\circ$ with $90^\circ$ alternation), and `Whorled` ($M$ organs per node), with nodes spaced evenly over the carrier's leafy span.
+- **Card density is derived, not authored** (`skeleton/foliage_card_density.js`):
+  - **The sleeve.** A card leaves the shoot at insertion angle $\alpha$ and reaches $L$, so the shoot wears a foliage
+    sleeve of radius $R = L \sin\alpha$.
+  - **One leaf per line of sight.** The carrier holds just enough leaf that a line of sight through that sleeve meets
+    one leaf on average. By Cauchy's formula the sleeve's mean projected area is a quarter of its surface ($2\pi R$ per
+    metre), and a flat leaf's is half its area. So the leaf area is $\pi R$ per metre, and
+    $$n = \frac{\pi \sin\alpha \,(1 - v_a)}{S \, s \, \phi \, P}\ \text{cards per metre}.$$
+    The terms:
+    - $S$ is the side of the species' square card, the size its tile draws its leaf at (`foliage_tile_layout`, §6.3),
+      and $s$ the card scale on that shoot.
+    - $\phi$ is the atlas's measured leaf coverage (`FoliageAtlasCutout.coverage`).
+    - $P$ is the number of planes a card stands up (2 for `CrossCard`, 3 for `TriStarCluster`).
+    - $v_a$ is where the tile's leaf attaches (`FoliageTileLayout.anchor_v`): the card's length spans the tile from
+      there.
+  - **Leafy span.** It starts at the rule's `attach_min`, honoured up to 0.92 (`foliage_leafy_span_start`), for the
+    cards and the sail alike.
+  - **Rounding.** The expected count is rounded with a golden-ratio dither per (branch, rule), so it is exact on
+    average.
+  - **Annual units replace the rule.** A branch that records its annual units (`TreeSkeleton.branch_unit_start_t`,
+    written by the annual shoot layer, §4.2) carries, on each unit, its leaves (`leaves_per_unit + leaves_per_metre L`,
+    times `leaf_survival` at the unit's age; a short shoot `leaves_per_short_shoot` at its tip), in place of the
+    density rule (`foliage_unit_card_spans`).
+    - **A card a leaf.** Each leaf is a card at its own node along the unit, leaving the shoot at the rule's insertion
+      angle and turned by its phyllotaxis. A needle-shoot card draws a stretch of shoot with its needles instead, as
+      many as the shoot bears there, and lies along it.
+    - **Maturity.** Each card draws its own maturity from its branch.
+    - **Wind.** The joint mechanics load the same card on that unit.
+  - **Wind.** The joint mechanics take the same $\pi R$ per metre as the foliage's sail. The wind rig and the cards
+    agree within 0–3.5% on every preset (size variance and length floors).
+- **Abscission and wilt** (`skeleton/foliage_senescence.js`):
+  - **Each tile's onset.** The pigment model ages each atlas tile at its own pace: a tile of maturity $\mu$ is at stage
+    $\sigma_k = \sigma(0.80 + 0.36|\mu - 0.35|) + 0.12\sigma^2$ (`foliage_variant_senescence`), and retains
+    $1 - \sigma_k(1.36 - \text{shielding})$ of its chlorophyll. Its exposed lamina is bare once $\sigma_k = 1/1.36$.
+    `foliage_variant_abscission_onset` solves that for the tree's senescence, $\sigma_0(\mu)$: 0.66 for mature tiles,
+    0.73 for juvenile ones and 0.82 at $\mu = 0.35$. No leaf falls or dries before its own tile's onset.
+  - **Each card's threshold.** After that, exposure orders the fall. A card's threshold
+    $\theta \in [\sigma_0(\mu), 1]$ comes from the mean of its sun exposure ($0.62\,\rho_{\text{shell}} + 0.38\,h_{\text{norm}}$)
+    and its position along its shoot. Outer and apical leaves fall first, and the crown is bare at $\sigma = 1$.
+  - **Dryness.** Between its onset and its fall the card dries: $d = (\sigma - \sigma_0)/(\theta - \sigma_0)$.
+    - The mesh builder takes a folding card (`FoldedVCard`, `RibbedFrond`, `CutoutHull`) towards a leaf with no turgor:
+      the fold closes towards $\pi/2$, the arch goes to 0, and the droop goes to 1. `CrossCard` and `TriStarCluster`
+      have no fold and do not wilt.
+    - A card just before its fall is nearly shut, a valid sliver.
+  - **Wind.** The joint mechanics shed the same leaves from their sail. They judge the expected leaf (no jitter) at each
+    segment's middle.
 - **Heliotropic & Gravitropic Orientation**:
   - Reorients each leaf/frond basis $(\mathbf{F}, \mathbf{U}, \mathbf{W})$ so its adaxial normal $\mathbf{U}$ tilts toward the sky + canopy-outward light vector (`phototropism` $\in [0, 1]$) while its forward tip $\mathbf{F}$ droops under `gravitropism` $\in [-1, 1]$, with seeded angular jitter to prevent specular aliasing.
 
 ### 6.2 Foliage Topologies
 Supports 5 production real-time foliage card/mesh archetypes:
-1. **`FoldedVCard` (Default Broadleaf Cluster)**: $2 \times 2$ or $2 \times 3$ grid with transverse V-fold angle $\beta_{\text{fold}}$, longitudinal midrib arch $h_{\text{arch}} \sin(\pi v)$, and tip camber $-h_{\text{camber}} v^2$. Never appears razor-flat at grazing view angles.
-2. **`CrossCard` (Conifer Needle Tuft / Dense Shrub Cluster)**: Two orthogonal intersecting V-cards rotated by $90^\circ$ around the petiole axis $\mathbf{F}$.
-3. **`TriStarCluster` (Volumetric Bush / Pine Shoot)**: Three cards arranged at $60^\circ$ star angles with radial offset.
+1. **`FoldedVCard`**: $2 \times 2$ or $2 \times 3$ grid with transverse V-fold angle $\beta_{\text{fold}}$, longitudinal midrib arch $h_{\text{arch}} \sin(\pi v)$, and tip camber $-h_{\text{camber}} v^2$. Never appears razor-flat at grazing view angles.
+2. **`CrossCard` (needle shoot)**: Two orthogonal intersecting V-cards rotated by $90^\circ$ around the shoot axis $\mathbf{F}$; each plane draws the needles in its sector round the shoot (§6.3).
+3. **`TriStarCluster` (needle shoot)**: Three cards arranged at $60^\circ$ star angles, each drawing its sector's needles.
 4. **`RibbedFrond` (Palms, Ferns, Cycads, Weeping Boughs)**: Multi-segment curved Cubic Hermite frond spine with RMF transport, longitudinal V-fold variation, and width profile $W(t) = W_{\max} \sin(\pi t^{p_w})$.
-5. **`OctagonalCutoutHull` (Tight Alpha-Bound Card)**: 6-vertex diamond/hexagonal hull trimming empty corner texels to cut alpha-test quad overdraw by ~35%.
+5. **`CutoutHull` (Fitted Alpha-Bound Card, the broadleaves' leaf)**: the convex hull of everything its atlas tile
+   draws, reduced to 6 vertices and fanned around a midrib vertex.
+   - **Shape.** Each half turns about the midrib by `fold_angle`, and the card arches and droops along its length like
+     a frond spine.
+   - **Fitting.** `make_foliage_material` fits the hulls while it synthesizes the atlas (`FoliageAtlasCutout`):
+     - Each covered texel row contributes the outer corners of its first and last texel that has any alpha.
+     - `convex_hull_monotone_2d` hulls those points.
+     - `convex_hull_fixed_count_2d_relaxation` reduces the hull to 6 vertices inside the tile, inset by half a texel
+       (its `bounds`), so no corner reaches the atlas neighbour.
+     - When no edge can be removed without leaving the tile, the unbounded fit is clipped to the tile
+       (`polygon2_clip_axis_halfplane`) and relaxed again.
+     - If that stalls too, the hull is the silhouette's bounding box as a hexagon. It is looser, but it holds every drawn
+       texel. Clamping the unbounded fit's corners instead would cut the leaf.
+   - **Result.** A willow's lanceolate leaf is cut far tighter than a hazel's broad one (`foliage_atlas_cutout.spec`).
+   - **Custom material.** With a caller's own material, the cards cover whole tiles.
+
+### 6.3 Leaf Architecture and the Atlas Tile
+Every tile draws the species' own leaf at its true size (`material/leaf_geometry.js`, `material/foliage_tile.js`;
+`LEAF_ARCHITECTURE_BRIEF_2026_10_26.md`):
+- **The leaf, as floras describe it** (`LeafArchitecture`, in the terms of Ellis et al. 2009, *Manual of Leaf
+  Architecture*): blade length and length/width ratio, where it is widest, apex and base angles and shapes, pinnate or
+  palmate lobes with their sinus depth, teeth a centimetre and their depth and order, secondary veins and their
+  angle, petiole length; a compound leaf's leaflets and rachis. Each preset cites its flora.
+- **The outline** is a monotone cubic Hermite envelope through the base, the base angle's point a quarter of the way up,
+  the widest point, the apex angle's point and the apex; rounded ends are arcs, acuminate ones concave. A pinnately
+  lobed blade is a body out to the sinus floors plus a rounded lobe along each secondary vein; a palmate one is a lobe
+  per primary vein over a body; teeth are offset along the outline's normal. All contours wind the same way, so
+  `polygon2_rasterize_coverage` fills their union by the nonzero rule with exact coverage across each row.
+- **The tile** draws the mature leaf filling it within a 2% margin, attached at the bottom middle; younger leaves are
+  smaller. The card is that tile at that scale: its size is the leaf's. The resolution draws the leaf's finest feature
+  (a tooth, a sinus) four texels across and its stems two, so they survive the alpha test.
+- **Needle shoots** draw a stretch of shoot as long as a needle, its needles shared among the card's planes, each
+  plane showing those in its sector round the shoot, foreshortened by their azimuth.
 
 ---
 
@@ -187,6 +319,11 @@ Supports 5 production real-time foliage card/mesh archetypes:
 - **Per-Vertex Canopy AO (`StandardAttributes.Color`)**:
   - Combines macro crown ellipsoid depth $AO_{\text{crown}}(\mathbf{v}) \in [AO_{\text{core}}, 1.0]$ with local hierarchy depth $AO_{\text{local}}(v) \in [0.7, 1.0]$ (darkening inner branch crotches and petiole bases while brightening outer sun-exposed tips).
   - Multiplied with optional per-cluster hue/value jitter in `StandardAttributes.Color` (`vec3<f32>`), which `StandardShadeMaterial` automatically multiplies with `texture_albedo` in the G-buffer pass.
+  - **Tint headroom.** Vertex colours are encoded as `unorm8`, so on their own they can only darken. Each card's tint
+    (`FoliageAttachmentSet.tints`) is free to exceed 1. The builder writes `tint / tint_scale`, where `tint_scale` is
+    the largest tint channel, and the foliage material's `diffuse_color` (the shader's `albedo_color`) carries
+    `tint_scale` back. The product is exactly `albedo · tint · AO`. Across the presets `tint_scale` is about 1.1, and
+    about half of all tint channels exceed 1.
 - **Spherized / Puffed Foliage Normals (`StandardAttributes.Normal`)**:
   - Blends the geometric card normal $\mathbf{n}_{\text{card}}$ with the canopy-outward normal $\text{normalize}(\mathbf{v} - \mathbf{C}_{\text{crown}})$ by `normal_puffiness` $\in [0, 0.85]$ before running `geometry.ensureTangents()`, giving leaf clusters soft volumetric canopy lighting.
 
@@ -212,8 +349,8 @@ Meep's visibility-buffer renderer (`Shade`) deforms `MeshletGeometry` on the GPU
 When the caller does not pass custom `bark_material` or `foliage_material`, the system synthesizes studio-quality procedural PBR textures using `Sampler2D` $\to$ `ShadeImage.fromSampler2D` $\to$ `ShadeTexture.from`:
 1. **`make_bark_material(config)`**:
    - Generates tileable (`TextureWrapType.Repeat`) bark **Albedo** (fissured ridges, lenticels/stripes for birch, warm heartwood/moss undertones), **Tangent-Space Normal Map** (derived analytically from height gradients), and **ORM Map** (`R`: fissure occlusion, `G`: micro-roughness, `B`: 0 metalness) on a `StandardShadeMaterial` (`TransparencyMode.Opaque`, `ShadeDrawSide.Front`).
-2. **`make_foliage_material(config)`**:
-   - Generates a botanical twig/leaf or conifer-needle cluster **Albedo + Alpha Cutout** texture (serrated/lobed/ovate/palmate/needle silhouettes, midrib & lateral venation, premultiplied RGBA compatible with Shade's `albedo_unpremultiply` and hashed alpha test), **Tangent-Space Normal Map** (vein relief), and **ORM Map** on a `StandardShadeMaterial` (`TransparencyMode.AlphaTested`, `ShadeDrawSide.Double`, `transmission_factor: 0.25`).
+2. **`make_foliage_material(species)`**:
+   - Generates the species' leaf (or needle shoot) **Albedo + Alpha Cutout** texture from its `LeafArchitecture` (§6.3: outline coverage, midvein and secondary veins, petiole, premultiplied RGBA compatible with Shade's `albedo_unpremultiply` and hashed alpha test), **Tangent-Space Normal Map** (camber, vein relief, bullation), and **ORM Map** on a `StandardShadeMaterial` (`TransparencyMode.AlphaTested`, `ShadeDrawSide.Double`, `transmission_factor: 0`).
 
 ### 7.4 Multi-LOD Chain with Area-Compensated Foliage Decimation
 Generates a configurable $N$-level LOD chain (default 4 levels: `LOD0`, `LOD1`, `LOD2`, `LOD3`):
@@ -239,10 +376,13 @@ src/generation/foliage/
   config/
     CrownEnvelopeType.js
     PhyllotaxisMode.js
-    FoliageCardType.js
+    FoliageCardType.js
     FoliageBarkType.js
     TreePreset.js
-    BranchLevelConfig.js
+    BranchGeneratorConfig.js
+    BranchSpawnRule.js
+    FoliageSpawnRule.js
+    ShootSystemRule.js
     CrownConfig.js
     FoliageConfig.js
     BarkMaterialConfig.js
@@ -258,17 +398,27 @@ src/generation/foliage/
     spine_frame_double_reflection.js (+ .spec.js)
     tree_skeleton_grow.js (+ .spec.js)
     tree_skeleton_compute_pipe_radii.js (+ .spec.js)
+    shoot_demography.js (+ .spec.js)
+    tree_skeleton_grow_shoots.js (+ .spec.js)
     tree_skeleton_assign_skin_joints.js (+ .spec.js)
+    tree_skeleton_grow_growth_modifiers.spec.js
+    foliage_card_density.js
+    foliage_senescence.js
   mesh/
     branch_collar_project.js (+ .spec.js)
     branch_ring_triangulate.js (+ .spec.js)
     tree_mesh_build_bark.js (+ .spec.js)
-    foliage_collect_attachments.js (+ .spec.js)
-    tree_mesh_build_foliage.js (+ .spec.js)
+    foliage_collect_attachments.js (+ .spec.js, _density.spec.js)
+    foliage_seasons.spec.js
+    tree_mesh_build_foliage.js (+ .spec.js, _cutout.spec.js)
     tree_mesh_apply_canopy_ao.js (+ .spec.js)
   material/
     make_bark_material.js (+ .spec.js)
     make_foliage_material.js (+ .spec.js)
+    compute_foliage_variant_atlas_layout.js
+    foliage_leaf_silhouette.js
+    FoliageAtlasCutout.js
+    foliage_atlas_cutout.js (+ .spec.js)
   animation/
     build_tree_wind_rig.js (+ .spec.js)
   asset/

package/src/generation/foliage/LEAF_ARCHITECTURE_BRIEF_2026_10_26.md

@@ -0,0 +1,158 @@
+# Leaf Architecture
+
+## Problem
+
+The oak's cards did not look like oak leaves (Alex, 2026-10-26: "What the fuck is that?"). Two causes, both hacks:
+
+- **The leaf outline was code, not botany.** `foliage_leaf_silhouette.js` switched on a string, `"lobed"` (a ±28% sine
+  ripple, "oak-like"), `"serrated"` (a sawtooth), `"palmate"` (a cosine), each with hand-picked constants. The oak's
+  `"lobed"` blade was widest near its base, with shallow wavy edges: a Christmas tree.
+- **A whole shoot was painted flat into one texture.** The `"rosette"` arrangement drew 11 leaves from one point,
+  fanned over ±83°, each three-quarters as wide as long. They merged into one blob with 11 tips. A `TriStarCluster`
+  stood three of those on crossing planes, which is the star in the screenshot. Meanwhile the simulation grows the
+  real shoots, so the tile duplicated the shoot geometry and contradicted it.
+
+Fixing the oak's outline alone would have kept both hacks.
+
+## Principle
+
+- **A leaf is data, described as floras describe it.** Ellis et al. (2009), *Manual of Leaf Architecture*, gives the
+  vocabulary; each preset cites its flora.
+- **A card is one leaf, on its shoot.** Each leaf is a card at its own node, leaving the shoot at the rule's insertion
+  angle and turned by its phyllotaxis.
+- **Needles stay shoot cards.** Pine bears 1,560 needles per metre and spruce 2,450 (sourced in the presets). A card
+  per needle is out of reach, and the needle shoot is the unit those papers measure.
+
+## Design
+
+- **`LeafArchitecture`** (`FoliageMaterialConfig.leaf`):
+  - blade length, length/width ratio, where it is widest;
+  - apex and base angle and shape (`LeafApexShape`, `LeafBaseShape`; the angles measured as Ellis et al. define them,
+    a quarter of the blade's length from the tip or the base);
+  - lobation (`LeafLobation`), lobes, sinus depth, palmate spread and lateral lobe length;
+  - teeth per cm, tooth depth and order;
+  - secondary veins and their angle;
+  - petiole length;
+  - a compound leaf's leaflets and rachis.
+- **`leaf_geometry`** turns that into outline contours, veins and stems in metres:
+  - **Envelope:** a monotone cubic Hermite (Fritsch-Carlson) through the base, the base angle's point, the widest point,
+    the apex angle's point and the apex. The shapes set the end slopes. A rounded end is an elliptic arc; an acuminate
+    one is shallow, so the margin is concave near the tip.
+  - **Pinnate lobes:** the blade reaches only to the sinus floor, `1 - sinus_depth` of the outline's width. Each lateral
+    lobe is a rounded blade of its own along its secondary vein (so it leans by the vein's angle), out to the outline.
+    The veins leave the midvein evenly spaced.
+  - **Palmate lobes:** a blade per primary lobe, radiating across `lobe_spread`, over a body to the sinus floors.
+  - **Base lobes:** cordate and lobate bases are a cubic Bezier from the petiole sinus round the basal lobe, solved to
+    reach exactly `base_lobe_depth` below the petiole.
+  - **Teeth:** offset along the outline's normal, spaced along the untoothed margin, with a second order a third the
+    size.
+  - **Union:** every contour winds the same way, so the union of lobes, leaflets and petiole is filled by the nonzero
+    rule (`polygon2_rasterize_coverage`, exact across each row, 4 samples down it).
+- **`foliage_tile_layout`** (one place for every consumer):
+  - The mature leaf fills the tile within a 2% margin, attached at the bottom middle. Every tile draws at that scale,
+    so the card's size in metres is the leaf's (`card_size`).
+  - **Resolution:** the finest feature (a tooth, a sinus) is drawn 4 texels across. The narrowest stem is drawn 2
+    texels across, so wherever it falls it covers a whole texel and survives the alpha test.
+  - **Needle shoots:** a stretch of shoot as long as a needle, with the needles the shoot bears there
+    (`leaves_per_metre`), shared among the card's planes. Each plane draws the needles in its sector round the shoot,
+    foreshortened by their azimuth.
+- **`foliage_tile_raster`:**
+  - Coverage, veins stamped near each segment, distance to the margin and to the midvein by chamfer, camber,
+    bullation, and the petiole.
+  - The pigment, senescence and normal code of `make_foliage_material` is unchanged. It now skips the texels the leaf
+    leaves empty, which keep the dilated fill.
+- **Cards:**
+  - **Broadleaves:** a card per leaf. A short shoot's `leaves_per_short_shoot` sit at its tip. The presets draw
+    `CutoutHull` cards.
+  - **Needle cards** lie along the shoot.
+  - **Density path:** branches not grown by annual units keep it, on the layout's card size and anchor.
+
+## Sources per species
+
+| preset | leaf | sources | estimated, not found |
+| :--- | :--- | :--- | :--- |
+| oak (*Quercus robur*) | mean blade 10.6 and 12.0 cm; L/W 1.8, 1.64; width 0.81-0.85 of max at 0.5 L, 0.47-0.50 at 0.9 L; petiole 7.4-8.0% of blade | Boratyński et al. 2008, *Silva Fennica* 42: 115-124, Table 4. Fitted: widest at 0.675, apex angle 1.2, base 0.8 rad (both widths within 0.01) | auricle size, secondary angle |
+| | obovate; apex broadly rounded; sinuses 1/3-7/8 to midrib; entire; 5-7 secondaries | FNA vol. 3 | |
+| | 5-7 lobes a side | Flora of China | |
+| | up to 5 pairs; auricles usually strong | BSBI Plant Crib | |
+| birch (*Betula pendula*) | 3-7 × 2.5-5 cm, ovate-rhombic, acuminate, cuneate, doubly serrate | FNA | apex and base angles, teeth (1.3 a cm, 1.5 mm), widest point |
+| | 6-8 lateral veins; petiole 2-3 cm | FoC | |
+| | 2 leaves a short shoot | Maillette 1982 | |
+| willow (*Salix babylonica*) | 90-160 × 5-20 mm, L/W 5.5-10.5, acuminate, cuneate, serrulate; petiole 7-9 mm | FNA vol. 7 | angles, teeth (5 a cm, 0.3 mm), veins |
+| maple (*Acer rubrum*) | 6.8 cm, 39 cm² | Wilson 1966 | lobe outline, lateral lobe length 0.85, teeth (3 a cm, 1.5 mm) |
+| | 3 lobes; lateral axes 73-86° apart; midlobe 46-56% of blade; petiole 60-114% of blade; 2 leaf pairs a short shoot | Critchfield 1971 | |
+| | doubly serrate | Gleason & Cronquist | |
+| | base truncate to cordate | Trees and Shrubs Online | |
+| shrub (*Corylus avellana*) | 5-12 × 4-12 cm, abruptly acuminate, narrowly cordate, doubly serrate, ≤ 8 vein pairs | FNA | angles, base lobe depth, teeth (0.7 a cm, 2.5 mm) |
+| | petiole 6-12 mm | Trees and Shrubs Online | |
+| | 8 cm gives the 41 cm² of a sun leaf | Catoni et al. 2015 | |
+| pine, spruce needles | 52 mm [Niinemets & Lukjanova 2003]; spruce's 18 mm was already chosen | | widths 1.6 and 1 mm; needle angle 0.6 rad |
+| palm, fern | no species named: the old frond's sizes are kept | | everything |
+
+The botanical data was gathered by a research subagent from efloras.org (FNA, FoC), BSBI, VicFlora, Go Botany, Trees
+and Shrubs Online, SEINet and the papers above. Its quotes and URLs are in the session's scratchpad (`leaf/`).
+floranorthamerica.org refused access, and HAL (Kremer et al. 2002) is behind a bot check.
+
+## Measured
+
+*Seed 1337 unless noted; the "before" figures are from 49845ff00.*
+
+**Atlas, from the drawn tiles:**
+
+| preset | resolution | card | coverage | one leaf |
+| :--- | ---: | ---: | ---: | ---: |
+| oak | 128 | 12.7 cm | 0.208 | 33 cm² |
+| birch | 256 | 7.8 cm | 0.174 | 10.6 cm² |
+| willow | 512 | 13.9 cm | 0.073 | 14 cm² |
+| maple | 512 | 13.2 cm | 0.213 | 37 cm² |
+| shrub | 128 | 9.3 cm | 0.522 | 45 cm² |
+| pine | 256 | 9.8 cm (81 needles) | | |
+| spruce | 256 | 3.4 cm (44 needles) | | |
+| palm | 128 | | | |
+| fern | 128 | | | |
+
+Leaf areas against the sources:
+- maple: 37 cm² against Wilson's 39;
+- hazel: 45 cm² against Catoni's 41;
+- birch: 10.6 cm² against about 11 from FNA's sizes.
+
+**Cost:** cards, LOD0 triangles, and `generate_tree` time with the LOD0 meshes.
+
+| preset | cards | foliage tris | bark tris | generate + LOD0 |
+| :--- | ---: | ---: | ---: | ---: |
+| oak | 25,622 | 153,732 | 81,587 | 0.77 + 0.06 s |
+| pine | 3,554 | 21,324 | 39,817 | 0.71 + 0.03 s |
+| birch | 63,909 | 383,454 | 454,735 | 1.73 + 0.56 s |
+| willow | 113,001 | 678,006 | 410,091 | 1.81 + 0.46 s |
+| maple | 13,008 | 78,048 | 37,774 | 1.16 + 0.05 s |
+| spruce | 176,311 | 705,244 | 1,085,114 | 3.12 + 1.23 s |
+| shrub | 16,976 | 101,856 | 62,817 | 0.52 + 0.05 s |
+
+**Crowns,** measured with `foliage_measure_leaf_area` and `tree_crown_opacity`; "before" is 49845ff00:
+
+| preset | leaf m² (before) | crown LAI | side density | side transparency | below density | below transparency |
+| :--- | ---: | ---: | ---: | ---: | ---: | ---: |
+| oak | 89.4 (90.9) | 3.11 | 0.50 | 0.42 | 0.58 | 0.27 |
+| pine | 15.7 (35.0) | 0.74 | 0.34 | 0.64 | 0.35 | 0.62 |
+| birch | 70.4 (64.5) | 6.77 | 0.56 | 0.33 | 0.75 | 0.12 |
+| willow | 232.6 (136.3) | 6.43 | 0.75 | 0.18 | 0.74 | 0.19 |
+| maple | 50.7 (36.3) | 1.97 | 0.41 | 0.42 | 0.42 | 0.32 |
+| spruce | 78.4 (117.8) | 3.03 | 0.33 | 0.31 | 0.42 | 0.29 |
+| shrub | 62.5 (57.8) | 4.52 | 0.63 | 0.22 | 0.64 | 0.16 |
+
+- **Pine and spruce lost leaf area** because their old tiles overdrew. Every plane of a card drew all of its needles,
+  three times over on pine, and wider than the needles are. Now each needle is drawn once at its width.
+- **Willow gained,** its lanceolate leaves replacing a frond drawing. Its transparency, 0.18, is near FIA's 15%.
+
+## Open (measured, not argued)
+
+- **Card counts rose where a card used to hold several leaves:** birch 5×, willow 9×, oak 11×. Pine and spruce rose
+  2.4×, because a needle card now covers one needle length of shoot, not 2.4. That stretch is chosen, not sourced.
+- **Estimates:** the angles, tooth sizes and widest points the floras do not give are marked in each preset.
+- **Palm and fern** name no species, so their leaves are not sourced.
+- **Wind sail:**
+  - `TreeWindConfig.elastic_modulus` is fitted to the oak, whose leaf area moved by 2% (90.9 to 89.4 m²); it was not
+    refit.
+  - Pine's and spruce's sails fell with their leaf area (to 0.45 and 0.67), so they will sway less. That sway is not
+    measured.
+- **Transparency:** every crown but willow's is still far above FIA's 15% transparency.