@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/src/kinds/vegetation-impostor.ts

@@ -0,0 +1,118 @@
+// LOD2 stand-ins, < 300 triangles. 'blob': a lathe of the real crown envelope (binned from the
+// full skeleton, so it is THIS tree's silhouette) whose top apex is the trunk's tip — one shared
+// point, so the crown provably touches the trunk. 'cards': a dozen coarse folded frond strips
+// rooted on the trunk's top cap centre (palms). Smooth normals on the blob, flat on the cards.
+
+import { type Mesh, MeshBuilder, type Rng, type Vec3 } from '../core/index.ts';
+import { lathe, sweep, transportFrames } from '../primitives/index.ts';
+import type { TreeParams } from './vegetation-params.ts';
+import type { Stem } from './vegetation-skeleton.ts';
+
+export interface Impostor {
+  readonly trunk: Mesh;
+  readonly leaves: Mesh;
+}
+
+/** Trunk at 4 path points; `apex` extends it straight up to a point (blob's top). */
+function coarseTrunk(trunk: Stem, p: TreeParams, apex: number | null): Mesh {
+  const n = trunk.pts.length - 1;
+  const idx = [...new Set([0, Math.round(n / 3), Math.round((2 * n) / 3), n])];
+  const pts = idx.map((i): Vec3 => trunk.pts[i] ?? [0, 0, 0]);
+  const radii = idx.map((i) => trunk.radii[i] ?? 0.1);
+  const last = pts.length - 1;
+  const tip = pts[last] ?? [0, 0, 1];
+  if (apex !== null && apex > tip[2] + 1e-6) {
+    pts.push([tip[0], tip[1], apex]);
+    radii.push(0);
+  } else radii[last] = 0;
+  return sweep({
+    section: { radius: 1, segments: 5 },
+    path: pts,
+    scale: radii,
+    color: p.bark,
+    strip: 'wood',
+    caps: apex === null ? 'end' : false,
+  });
+}
+
+export function blob(stems: readonly Stem[], p: TreeParams, rng: Rng): Impostor {
+  const trunk = stems[0];
+  if (!trunk) return { trunk: new MeshBuilder().build(), leaves: new MeshBuilder().build() };
+  const tip = trunk.pts[trunk.pts.length - 1] ?? [0, 0, 1];
+  const margin = p.leaves.size * 0.6;
+  let z0 = Infinity;
+  let z1 = tip[2];
+  for (const s of stems)
+    for (const q of s.level > 0 ? s.pts : []) {
+      z0 = Math.min(z0, q[2] - margin * (1 + (p.leaves.hang ?? 0) * 2));
+      z1 = Math.max(z1, q[2] + margin);
+    }
+  if (!Number.isFinite(z0)) z0 = tip[2] * 0.5;
+  const BINS = 6;
+  const r = new Array<number>(BINS).fill(0.2);
+  for (const s of stems)
+    for (const q of s.level > 0 ? s.pts : []) {
+      const b = Math.min(BINS - 1, Math.max(0, Math.floor(((q[2] - z0) / (z1 - z0)) * BINS)));
+      r[b] = Math.max(r[b] ?? 0, Math.hypot(q[0] - tip[0], q[1] - tip[1]) + margin);
+    }
+  const profile: [number, number][] = [[0, z0]];
+  for (let b = 0; b < BINS; b++) profile.push([r[b] ?? 0.2, z0 + ((b + 0.5) / BINS) * (z1 - z0)]);
+  profile.push([0, z1]);
+  const leaves = lathe({ profile, segments: 10, color: p.leaves.color, at: [tip[0], tip[1], 0] });
+  const [cr, cg, cb] = p.leaves.color;
+  for (let i = 0; i < leaves.colors.length / 3; i++) {
+    const t = ((leaves.positions[i * 3 + 2] ?? 0) - z0) / (z1 - z0);
+    const k = (0.55 + 0.5 * t) * (1 + rng.range(-0.08, 0.08));
+    leaves.colors.set([cr * k, cg * k, cb * k], i * 3);
+  }
+  return { trunk: coarseTrunk(trunk, p, z1), leaves };
+}
+
+export function frondCards(stems: readonly Stem[], p: TreeParams, level: number): Impostor {
+  const trunk = stems[0];
+  const mb = new MeshBuilder();
+  if (!trunk) return { trunk: mb.build(), leaves: mb.build() };
+  const top = trunk.pts[trunk.pts.length - 1] ?? [0, 0, 1];
+  const fronds = stems.filter((s) => s.level === level);
+  const every = Math.max(1, Math.ceil(fronds.length / 12));
+  const [cr, cg, cb] = p.leaves.color;
+  for (const [fi, st] of fronds.entries()) {
+    if (fi % every !== 0) continue;
+    const n = st.pts.length - 1;
+    const pts = [top, st.pts[Math.round(n / 2)] ?? top, st.pts[n] ?? top];
+    const fr = transportFrames(pts);
+    const w = [0.25, 1, 0.35].map((k) => k * st.length * p.leaves.width);
+    for (const side of [1, -1]) {
+      const edge = pts.map((c, j): Vec3 => {
+        const f = fr[j];
+        const ww = (w[j] ?? 0) * side;
+        if (!f) return c;
+        return [
+          c[0] + (f.b[0] * 0.85 - f.n[0] * 0.45 * side) * ww,
+          c[1] + (f.b[1] * 0.85 - f.n[1] * 0.45 * side) * ww,
+          c[2] + (f.b[2] * 0.85 - f.n[2] * 0.45 * side) * ww,
+        ];
+      });
+      for (let j = 0; j < 2; j++) {
+        const q = [pts[j], pts[j + 1], edge[j + 1], edge[j]] as Vec3[];
+        const [a, b, c] = [q[0] ?? top, q[1] ?? top, q[2] ?? top];
+        const e1 = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+        const e2 = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
+        const nx = (e1[1] ?? 0) * (e2[2] ?? 0) - (e1[2] ?? 0) * (e2[1] ?? 0);
+        const ny = (e1[2] ?? 0) * (e2[0] ?? 0) - (e1[0] ?? 0) * (e2[2] ?? 0);
+        const nz = (e1[0] ?? 0) * (e2[1] ?? 0) - (e1[1] ?? 0) * (e2[0] ?? 0);
+        const l = Math.hypot(nx, ny, nz) || 1;
+        for (const s of [1, -1]) {
+          const nn: Vec3 = [(nx / l) * s, (ny / l) * s, (nz / l) * s];
+          const ids = q.map((v, k) => {
+            const sh = k < 2 ? 0.7 : 1;
+            return mb.vertex({ p: v, n: nn, uv: [0, 0], color: [cr * sh, cg * sh, cb * sh] });
+          });
+          const [i0 = 0, i1 = 0, i2 = 0, i3 = 0] = s > 0 ? ids : [...ids].reverse();
+          mb.quad(i0, i1, i2, i3);
+        }
+      }
+    }
+  }
+  return { trunk: coarseTrunk(trunk, p, null), leaves: mb.build() };
+}

package/src/kinds/vegetation-leaves.ts

@@ -0,0 +1,168 @@
+// Leaf cards: double-sided `planar` polygons, each standing for a cluster of leaves, with per-vertex
+// colour (darker at the stem, lighter at the tip, darker deep inside the crown). LOD0 roots every
+// card on an exact twig vertex (`transportFrames` = the sweep's own frames); LOD1 replaces each
+// twig by one bigger cluster card rooted on its parent's bark.
+
+import { type Mesh, merge, type Rng, type Vec3 } from '../core/index.ts';
+import { planar, transportFrames } from '../primitives/index.ts';
+import { type LeafParams, OUTLINES } from './vegetation-params.ts';
+import type { Stem } from './vegetation-skeleton.ts';
+
+const unit = (a: Vec3): Vec3 => {
+  const l = Math.hypot(a[0], a[1], a[2]) || 1;
+  return [a[0] / l, a[1] / l, a[2] / l];
+};
+
+/** Crown occlusion: cards deep inside / low in the crown are darker. */
+export interface CrownShade {
+  readonly centre: Vec3;
+  readonly radius: number;
+  readonly zMin: number;
+  readonly zMax: number;
+}
+
+export function crownShade(stems: readonly Stem[], level: number): CrownShade {
+  let r = 0.1;
+  let z0 = Infinity;
+  let z1 = -Infinity;
+  const t = stems[0]?.pts;
+  const c = t?.[t.length - 1] ?? [0, 0, 0];
+  for (const s of stems) {
+    if (s.level < level) continue;
+    for (const p of s.pts) {
+      r = Math.max(r, Math.hypot(p[0] - c[0], p[1] - c[1]));
+      z0 = Math.min(z0, p[2]);
+      z1 = Math.max(z1, p[2]);
+    }
+  }
+  return { centre: c, radius: r, zMin: z0, zMax: Math.max(z1, z0 + 0.1) };
+}
+
+function card(
+  leaf: LeafParams,
+  base: Vec3,
+  dir: Vec3,
+  side: Vec3,
+  len: number,
+  shade: CrownShade,
+  rng: Rng,
+): Mesh {
+  const outline = OUTLINES[leaf.shape === 'frond' ? 'oval' : leaf.shape];
+  const w = len * leaf.width;
+  const points = outline.map(
+    ([u, v]): Vec3 => [
+      base[0] + dir[0] * u * len + side[0] * v * w,
+      base[1] + dir[1] * u * len + side[1] * v * w,
+      base[2] + dir[2] * u * len + side[2] * v * w,
+    ],
+  );
+  const m = planar({ points, color: leaf.color, doubleSided: true });
+  const k = 1 + rng.range(-leaf.colorVar, leaf.colorVar);
+  const hue = rng.range(-leaf.colorVar, leaf.colorVar) * 0.6;
+  const radial = Math.hypot(base[0] - shade.centre[0], base[1] - shade.centre[1]) / shade.radius;
+  const up = (base[2] - shade.zMin) / (shade.zMax - shade.zMin);
+  const ao = 0.5 + 0.35 * Math.min(1, radial) ** 0.8 + 0.2 * Math.max(0, Math.min(1, up));
+  const [r, g, b] = leaf.color;
+  for (let i = 0; i < m.colors.length / 3; i++) {
+    const u = outline[i % outline.length]?.[0] ?? 0;
+    const s = ao * k * (0.7 + 0.4 * u);
+    m.colors[i * 3] = r * s * (1 + hue);
+    m.colors[i * 3 + 1] = g * s;
+    m.colors[i * 3 + 2] = b * s * (1 - hue);
+  }
+  return m;
+}
+
+/** Splay outward from the stem, lift a little, then droop towards the ground by `hang`. */
+function aim(radial: Vec3, along: Vec3, leaf: LeafParams, rng: Rng): { dir: Vec3; side: Vec3 } {
+  const hang = leaf.hang ?? 0;
+  const flat = leaf.flat ?? 0;
+  const lift = rng.range(-0.3, 0.5);
+  const out = unit([
+    radial[0] * 0.9 + along[0] * 0.7,
+    radial[1] * 0.9 + along[1] * 0.7,
+    radial[2] * 0.9 + along[2] * 0.7 + lift,
+  ]);
+  const d0 = unit([out[0] * (1 - hang), out[1] * (1 - hang), out[2] * (1 - hang) - hang]);
+  const dir = unit([d0[0], d0[1], d0[2] * (1 - flat)]);
+  const level = unit([-dir[1], dir[0], 0]);
+  const s1 = unit([
+    dir[1] * radial[2] - dir[2] * radial[1],
+    dir[2] * radial[0] - dir[0] * radial[2],
+    dir[0] * radial[1] - dir[1] * radial[0],
+  ]);
+  const s0 = Math.hypot(...s1) < 0.5 ? level : s1;
+  // Flat cards (pine pads) lie level: side goes horizontal, roll fades out.
+  const side = unit([
+    s0[0] + (level[0] - s0[0]) * flat,
+    s0[1] + (level[1] - s0[1]) * flat,
+    s0[2] + (level[2] - s0[2]) * flat,
+  ]);
+  const roll = rng.range(-0.7, 0.7) * (1 - flat);
+  const t: Vec3 = [
+    dir[1] * side[2] - dir[2] * side[1],
+    dir[2] * side[0] - dir[0] * side[2],
+    dir[0] * side[1] - dir[1] * side[0],
+  ];
+  const c = Math.cos(roll);
+  const s = Math.sin(roll);
+  return { dir, side: [side[0] * c + t[0] * s, side[1] * c + t[1] * s, side[2] * c + t[2] * s] };
+}
+
+/** LOD0: `perStem` cards along the outer 70% of every terminal stem, rooted on a ring vertex. */
+export function leafCards(
+  stems: readonly Stem[],
+  level: number,
+  ringSegments: number,
+  leaf: LeafParams,
+  shade: CrownShade,
+  rng: Rng,
+): Mesh {
+  const out: Mesh[] = [];
+  for (const st of stems) {
+    if (st.level !== level) continue;
+    const frames = transportFrames(st.pts);
+    const res = st.pts.length - 1;
+    for (let i = 0; i < leaf.perStem; i++) {
+      const from = leaf.from ?? 0.3;
+      const t = from + ((1 - from) * (i + 1)) / leaf.perStem;
+      const j = Math.max(1, Math.min(res, Math.round(t * res)));
+      const f = frames[j];
+      const c = st.pts[j];
+      if (!f || !c) continue;
+      const a = (rng.int(0, ringSegments - 1) / ringSegments) * Math.PI * 2;
+      const radial: Vec3 = [
+        Math.cos(a) * f.n[0] + Math.sin(a) * f.b[0],
+        Math.cos(a) * f.n[1] + Math.sin(a) * f.b[1],
+        Math.cos(a) * f.n[2] + Math.sin(a) * f.b[2],
+      ];
+      const r = st.radii[j] ?? 0;
+      const base: Vec3 = [c[0] + radial[0] * r, c[1] + radial[1] * r, c[2] + radial[2] * r];
+      const { dir, side } = aim(radial, f.t, leaf, rng);
+      out.push(card(leaf, base, dir, side, leaf.size * rng.range(0.8, 1.2), shade, rng));
+    }
+  }
+  return merge(out);
+}
+
+/** LOD1: one cluster card per (unemitted) twig, rooted where the twig would leave its parent. */
+export function clusterCards(
+  stems: readonly Stem[],
+  level: number,
+  leaf: LeafParams,
+  shade: CrownShade,
+  rng: Rng,
+): Mesh {
+  const out: Mesh[] = [];
+  for (const st of stems) {
+    if (st.level !== level) continue;
+    const tip = st.pts[st.pts.length - 1] ?? st.surface;
+    const p0 = st.pts[0] ?? st.surface;
+    const along = unit([tip[0] - p0[0], tip[1] - p0[1], tip[2] - p0[2]]);
+    const radial = unit([st.surface[0] - p0[0], st.surface[1] - p0[1], st.surface[2] - p0[2]]);
+    const { dir, side } = aim(radial, along, leaf, rng);
+    const len = st.length * 1.1 + leaf.size;
+    out.push(card(leaf, st.surface, dir, side, len, shade, rng));
+  }
+  return merge(out);
+}

package/src/kinds/vegetation-mesh.ts

@@ -0,0 +1,174 @@
+// Skeleton → wood meshes: stems as tapered sweeps (LOD sets radial and path resolution), the
+// trunk with a bark gradient and marks, the buttressed root flare as a lobed `loft`. Plus the
+// fit that scales the finished tree onto its real height and crown spread.
+
+import { boundsOf, type Mesh, merge, type Rng, type Vec3 } from '../core/index.ts';
+import { loft, ringXY, sweep } from '../primitives/index.ts';
+import type { TreeParams } from './vegetation-params.ts';
+import type { Stem } from './vegetation-skeleton.ts';
+
+/** Radial segments per [level][lod]. The trunk's 8 keeps ring vertices on ±Y (exact DBH). */
+const RADIAL = [
+  [8, 6, 5],
+  [6, 4, 4],
+  [4, 3, 3],
+  [3, 3, 3],
+];
+export const radialSegments = (level: number, lod: number): number =>
+  RADIAL[Math.min(3, level)]?.[lod] ?? 3;
+
+/** Every `step`-th path point (always keeping both ends): LOD1 halves path resolution. */
+export function coarsen(st: Stem, step: number): { pts: Vec3[]; radii: number[] } {
+  const pts: Vec3[] = [];
+  const radii: number[] = [];
+  const last = st.pts.length - 1;
+  for (let i = 0; i <= last; i += step) {
+    pts.push(st.pts[i] ?? [0, 0, 0]);
+    radii.push(st.radii[i] ?? 0);
+  }
+  if (last % step !== 0) {
+    pts.push(st.pts[last] ?? [0, 0, 0]);
+    radii.push(st.radii[last] ?? 0);
+  }
+  return { pts, radii };
+}
+
+/** All stems with level in [lo, hi], merged. */
+export function stemsMesh(
+  stems: readonly Stem[],
+  lo: number,
+  hi: number,
+  lod: number,
+  color: Vec3,
+): Mesh {
+  const out: Mesh[] = [];
+  for (const st of stems) {
+    if (st.level < lo || st.level > hi) continue;
+    const { pts, radii } = coarsen(st, lod === 0 ? 1 : 2);
+    out.push(
+      sweep({
+        section: { radius: 1, segments: radialSegments(st.level, lod) },
+        path: pts,
+        scale: radii,
+        color,
+        strip: 'wood',
+      }),
+    );
+  }
+  return merge(out);
+}
+
+const mix = (a: Vec3, b: Vec3, t: number): [number, number, number] => [
+  a[0] + (b[0] - a[0]) * t,
+  a[1] + (b[1] - a[1]) * t,
+  a[2] + (b[2] - a[2]) * t,
+];
+
+/** Bark colour by height (bark → barkTop) with seeded marks; rewrites the mesh's colours. */
+export function barkTint(m: Mesh, p: TreeParams, top: number, rng: Rng): Mesh {
+  const hi = p.barkTop ?? p.bark;
+  for (let i = 0; i < m.colors.length / 3; i++) {
+    const z = m.positions[i * 3 + 2] ?? 0;
+    const t = Math.min(1, Math.max(0, (z / Math.max(0.1, top) - 0.3) / 0.4));
+    let c = mix(p.bark, hi, t * t * (3 - 2 * t));
+    if (p.barkMarks && rng.next() < p.barkMarks.amount) c = mix(c, p.barkMarks.color, 0.85);
+    const k = 1 + rng.range(-0.06, 0.06);
+    m.colors.set([c[0] * k, c[1] * k, c[2] * k], i * 3);
+  }
+  return m;
+}
+
+/** The trunk, radius scaled by `radiusScale` (the fit's 1/sy keeps DBH exact after scaling). */
+export function trunkMesh(
+  trunk: Stem,
+  p: TreeParams,
+  lod: number,
+  radiusScale: number,
+  rng: Rng,
+): Mesh {
+  const { pts, radii } = coarsen(trunk, lod === 0 ? 1 : 2);
+  const m = sweep({
+    section: { radius: 1, segments: radialSegments(0, lod) },
+    path: pts,
+    scale: radii.map((r) => r * radiusScale),
+    color: p.bark,
+    strip: 'wood',
+    caps: p.impostor === 'cards' ? 'end' : false,
+  });
+  return barkTint(m, p, pts[pts.length - 1]?.[2] ?? 1, rng);
+}
+
+/** Trunk axis point at height z (linear between path points). */
+function axisAt(trunk: Stem, z: number): Vec3 {
+  for (let i = 1; i < trunk.pts.length; i++) {
+    const a = trunk.pts[i - 1] ?? [0, 0, 0];
+    const b = trunk.pts[i] ?? a;
+    if (b[2] >= z || i === trunk.pts.length - 1) {
+      const f = Math.min(1, Math.max(0, (z - a[2]) / (b[2] - a[2] || 1)));
+      return [a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f, z];
+    }
+  }
+  return [0, 0, z];
+}
+
+/** Buttressed flare: `p.roots` lobes, wide at the ground, melting into the trunk by ~2·DBH. */
+export function rootsMesh(
+  trunk: Stem,
+  p: TreeParams,
+  lod: number,
+  radiusScale: number,
+  rng: Rng,
+): Mesh {
+  const r0 = (trunk.radii[0] ?? 0.2) * radiusScale;
+  const lobes = p.roots ?? 0;
+  const phase = rng.range(0, Math.PI * 2);
+  const levels = [
+    { z: -0.1, k: 1.7, amp: 0.7 },
+    { z: 0.5 * r0, k: 1.3, amp: 0.4 },
+    { z: 1.3 * r0, k: 1.04, amp: 0.15 },
+    { z: 2.4 * r0, k: 0.9, amp: 0 },
+  ];
+  const segs = lod === 0 ? 16 : 10;
+  const rings = levels.map(({ z, k, amp }) => {
+    const c = axisAt(trunk, z);
+    const lobe = (a: number): number => 1 + amp * Math.max(0, Math.cos(lobes * (a - phase))) ** 2;
+    return ringXY(c, r0 * k, r0 * k, segs, lobe);
+  });
+  const m = loft({ rings, color: p.bark, strip: 'wood' });
+  return barkTint(m, p, trunk.pts[trunk.pts.length - 1]?.[2] ?? 1, rng);
+}
+
+/** Per-axis factors that bring the union of `meshes` to `target` = [X, Y, Z] spans. */
+export function fitFactors(meshes: readonly Mesh[], target: Vec3): Vec3 {
+  const lo = [Infinity, Infinity, Infinity];
+  const hi = [-Infinity, -Infinity, -Infinity];
+  for (const m of meshes) {
+    if (m.indices.length === 0) continue;
+    const b = boundsOf(m);
+    for (let k = 0; k < 3; k++) {
+      lo[k] = Math.min(lo[k] ?? 0, b.min[k] ?? 0);
+      hi[k] = Math.max(hi[k] ?? 0, b.max[k] ?? 0);
+    }
+  }
+  const f = (k: 0 | 1 | 2): number => target[k] / Math.max(1e-6, (hi[k] ?? 1) - (lo[k] ?? 0));
+  return [f(0), f(1), f(2)];
+}
+
+/** Non-uniform scale about the origin; normals by the inverse transpose, renormalised. */
+export function scaleMesh(m: Mesh, s: Vec3): Mesh {
+  const positions = new Float32Array(m.positions.length);
+  const normals = new Float32Array(m.normals.length);
+  for (let i = 0; i < positions.length; i += 3) {
+    positions[i] = (m.positions[i] ?? 0) * s[0];
+    positions[i + 1] = (m.positions[i + 1] ?? 0) * s[1];
+    positions[i + 2] = (m.positions[i + 2] ?? 0) * s[2];
+    const nx = (m.normals[i] ?? 0) / s[0];
+    const ny = (m.normals[i + 1] ?? 0) / s[1];
+    const nz = (m.normals[i + 2] ?? 0) / s[2];
+    const l = Math.hypot(nx, ny, nz) || 1;
+    normals[i] = nx / l;
+    normals[i + 1] = ny / l;
+    normals[i + 2] = nz / l;
+  }
+  return { ...m, positions, normals };
+}

package/src/kinds/vegetation-params.ts

@@ -0,0 +1,147 @@
+// Tree vocabulary: Weber & Penn 1995 ("Creation and Rendering of Realistic Trees", SIGGRAPH)
+// parameters, trimmed to what a game tree needs. Plain data, so presets are objects a recipe
+// spreads and overrides.
+
+import type { Vec2, Vec3 } from '../core/index.ts';
+
+/** Crown envelope: how level-1 branch length varies up the trunk (Weber–Penn `Shape`). */
+export type CrownShape =
+  | 'conical'
+  | 'spherical'
+  | 'hemispherical'
+  | 'cylindrical'
+  | 'tapered'
+  | 'flame';
+
+/** One recursion level. Level 0 is the trunk; levels 1–3 are branches, sub-branches, twigs. */
+export interface BranchLevel {
+  /** Children per parent (level 1: along the trunk). Ignored for level 0. */
+  readonly branches: number;
+  /** Level 0: fraction of tree height. Level ≥ 1: fraction of the parent's length. */
+  readonly length: number;
+  /** ± relative random length variation. */
+  readonly lengthVar?: number;
+  /** Degrees between child and parent axis at the attachment. */
+  readonly downAngle: number;
+  /** Added to downAngle from the first child (bottom) to the last (top) of the parent's zone. */
+  readonly downAngleV?: number;
+  /** Phyllotaxis step about the parent, degrees (golden angle 137.5° by default). */
+  readonly rotate?: number;
+  /** Total bend over the stem, degrees: + towards the sky, − towards the ground. Trunk: + bends
+   * back against `lean` (towards −X). */
+  readonly curve?: number;
+  /** If set, the second half bends by this instead (S-curves, weeping tips). */
+  readonly curveBack?: number;
+  /** Seeded wobble per path segment, ± degrees. */
+  readonly curveVar?: number;
+  /** Where children start along this stem's parent, as a fraction (level 1 uses `baseSize`). */
+  readonly start?: number;
+  /** Path segments at LOD0 (LOD1 halves them). */
+  readonly segments: number;
+}
+
+export type LeafShape = 'oval' | 'lobed' | 'tuft' | 'strand' | 'frond';
+
+/** Card outlines: u along the card (0 = stem end), v across (±0.5). */
+export const OUTLINES: Record<Exclude<LeafShape, 'frond'>, readonly Vec2[]> = {
+  oval: [
+    [0, 0],
+    [0.25, -0.4],
+    [0.65, -0.5],
+    [1, 0],
+    [0.65, 0.5],
+    [0.25, 0.4],
+  ],
+  lobed: [
+    [0, 0],
+    [0.3, -0.45],
+    [0.5, -0.3],
+    [0.75, -0.5],
+    [1, 0],
+    [0.75, 0.5],
+    [0.5, 0.3],
+    [0.3, 0.45],
+  ],
+  tuft: [
+    [0, 0],
+    [0.35, -0.5],
+    [0.45, -0.15],
+    [0.75, -0.4],
+    [1, 0],
+    [0.75, 0.4],
+    [0.45, 0.15],
+    [0.35, 0.5],
+  ],
+  strand: [
+    [0, 0],
+    [0.1, -0.5],
+    [1, 0],
+    [0.1, 0.5],
+  ],
+};
+
+export interface LeafParams {
+  readonly shape: LeafShape;
+  /** Card length at LOD0, metres. Cards stand for a cluster of leaves, not one leaf. */
+  readonly size: number;
+  /** Card width as a fraction of its length (fronds: leaflet length as a fraction of frond). */
+  readonly width: number;
+  /** Cards per terminal stem (fronds: leaflets per side). */
+  readonly perStem: number;
+  /** Where cards start along a terminal stem, 0–1 (default 0.3; tufts sit near the tip). */
+  readonly from?: number;
+  readonly color: Vec3;
+  /** ± relative colour variation per card. */
+  readonly colorVar: number;
+  /** 0–1: lay cards level, like the horizontal needle pads of a pine. */
+  readonly flat?: number;
+  /** 0 = cards splay outward, 1 = they hang straight down (willow strands). */
+  readonly hang?: number;
+}
+
+export interface TreeParams {
+  readonly shape: CrownShape;
+  /** Fraction of the trunk free of branches (clear bole). */
+  readonly baseSize: number;
+  /** [trunk, level 1, level 2?, level 3?]. */
+  readonly levels: readonly BranchLevel[];
+  /** Child radius = parent radius · (child length / parent length)^ratioPower. */
+  readonly ratioPower: number;
+  /** Trunk radius at the top as a fraction of its radius at breast height. */
+  readonly taper: number;
+  /** Trunk lean from vertical towards +X, degrees. The trunk stays in the XZ plane. */
+  readonly lean?: number;
+  readonly bark: Vec3;
+  /** Bark colour at the top of the trunk (Scots pine's orange upper bark); default `bark`. */
+  readonly barkTop?: Vec3;
+  /** Dark bark marks scattered per vertex (birch lenticels): colour + fraction of vertices. */
+  readonly barkMarks?: { readonly color: Vec3; readonly amount: number };
+  readonly leaves: LeafParams;
+  /** Buttress lobes in the root flare at the base (LOD0/1); 0 or absent = no `roots` part. */
+  readonly roots?: number;
+  /** Fruit hung under the crown (coconuts), merged into `branches`. LOD0 only. */
+  readonly fruit?: { readonly count: number; readonly radius: number; readonly color: Vec3 };
+  /** LOD2 stand-in: a lathe of the crown envelope, or a few coarse frond cards. */
+  readonly impostor: 'blob' | 'cards';
+  /** Typical mature size this preset was tuned on (used when the caller omits spread/dbh). */
+  readonly typical: { readonly height: number; readonly spread: number; readonly dbh: number };
+}
+
+/** Weber–Penn ShapeRatio; `r` is 1 at the crown base and 0 at the trunk tip. */
+export function shapeRatio(shape: CrownShape, r: number): number {
+  const x = Math.min(1, Math.max(0, r));
+  switch (shape) {
+    case 'conical':
+      return 0.2 + 0.8 * x;
+    case 'spherical':
+      return 0.2 + 0.8 * Math.sin(Math.PI * x);
+    case 'hemispherical':
+      return 0.2 + 0.8 * Math.sin((Math.PI / 2) * x);
+    case 'cylindrical':
+      return 1;
+    case 'tapered':
+      return 0.5 + 0.5 * x;
+    case 'flame':
+      return x <= 0.7 ? 0.15 + (0.85 * x) / 0.7 : 0.15 + (0.85 * (1 - x)) / 0.3;
+  }
+}