lecodes-assets 2.5.1 → 2.8.0

package/src/doctor/impostor.ts

@@ -31,9 +31,12 @@
 //               elevation 0 at the top of the image). A point p lands at uv ((i + a) / C, (k + 1 - b) / R),
 //               a = 0.5 + 0.5·dot(p-c, right)/r, b = the same on up (a right, b UP).
 //   textures    PNG RGBA8, the doctor's KTX2 pass encodes them afterwards like any map - but never resized by its
-//               --max-size (both carry the texture extras `lecodes.impostor = true`; a 12 × 256 = 3072 px strip stays):
+//               --max-size (all three carry the texture extras `lecodes.impostor = true`; a 12 × 256 = 3072 px strip stays):
 //               baseColorTexture          rgb = albedo (sRGB; source × baseColorFactor, averaged in LINEAR), a = coverage
-//               metallicRoughnessTexture  r, g = the hull normal in OBJECT space (no frame basis), packed with the
+//                                         (FRACTIONAL: covered samples / S²)
+//               metallicRoughnessTexture  r, g = the shading normal in OBJECT space (no frame basis): a card sample's
+//                                         the crown's HULL normal, a bark sample's the MESH normal (the interpolated
+//                                         vertex NORMAL, sign-corrected, turned toward the frame's viewer); packed with the
 //                                         FULL-sphere octahedral map normalEncode / normalDecode below (the far side's
 //                                         and the crown's underside normals included) - not the frames' hemi octEncode;
 //                                         the map's seam pole (its four corners) is object -Y, a direction no frame looks
@@ -43,8 +46,18 @@
 //                                         point nearest this frame's viewer, 0.5 = the quad plane through c, 0 = the
 //                                         farthest) - the shader self-shadows the quad from the frame nearest the sun
 //                                         with it (and parallax may read it later); a = AO (COLOR_0.r, else 1).
-//               2×2 supersamples a texel (coverage = covered / 4, data = mean of the covered ones: the normal averaged
-//               as a vector then encoded, the depth averaged), then the colour and data are DILATED into the empty
+//               occlusionTexture          r = the BARK fraction (bark samples / covered samples: an OPAQUE slot is bark,
+//                                         a MASK slot a card), g = 0, b = the BARK's OCCLUSION (the mean over the texel's
+//                                         bark samples of what foliage.mat darkens the bark's ambient by beyond the sky
+//                                         visibility: the baked cavity COLOR_0.g x the material's occlusion map at its
+//                                         strength x the normal map's own cavity ½ + ½·clamp(n.z); never 0 - 1/255 at
+//                                         least - so b = 0 says "an atlas before this channel" and the shader reads 1),
+//                                         a = 1 - linear data, not occlusion. g = 0 marks the map as present: the
+//                                         engine's default for a missing map is white (g = 1) and the shader reads
+//                                         bark = r·(1 - g), so an older atlas reads no bark.
+//               S×S supersamples a texel (S = `samples`, default 8: coverage = covered / S², data = mean of the covered
+//               ones: the normal averaged as a vector then encoded, the depth averaged), then the colour, data and bark
+//               are DILATED into the empty
 //               texels of the same frame so bilinear / mips never pull black in (a depth read just outside a
 //               silhouette continues the surface; the albedo's alpha there says "no occluder").
 //   quad        node `<level-0 root name>_LOD<k>`, k = min(2, highest existing level + 1); every `_LOD<n>` n ≥ k goes
@@ -76,16 +89,19 @@ export type ImpostorOptions = {
   px?: number
   /** The LOD level the quad takes (default min(2, highest existing + 1)). */
   level?: number
+  /** Supersamples a texel's SIDE (S: S×S samples, default IMPOSTOR_SAMPLES = 8): the coverage is covered / S² — a porous
+   *  crown keeps its holes as a fraction (foliage-impostor.mat cuts it at the mask; alphaToCoverage takes it under MSAA). */
+  samples?: number
   log?: (s: string) => void
 }
 export type ImpostorResult = {
   cols: number, rows: number, px: number, width: number, height: number
-  radius: number, center: [number, number, number], level: number, triangles: number, ms: number, node: string
+  radius: number, center: [number, number, number], level: number, triangles: number, ms: number, node: string, samples: number
 }
 
 /** "12×3 frames · 256 px (3072×768)" / "oct 8×8 frames · 128 px (1024×1024)" — the import's and the doctor's log. */
 export const impostorLabel = (r: ImpostorResult): string =>
-  `${r.rows ? `${r.cols}×${r.rows}` : `oct ${r.cols}×${r.cols}`} frames · ${r.px} px (${r.width}×${r.height})`
+  `${r.rows ? `${r.cols}×${r.rows}` : `oct ${r.cols}×${r.cols}`} frames · ${r.px} px (${r.width}×${r.height}) · ${r.samples}×${r.samples} samples`
 
 const LOD_RE = /_LOD([1-9]\d*)$/i
 const REPEAT = 10497, CLAMP = 33071, MIRROR = 33648
@@ -131,6 +147,45 @@ export const normalDecode = (u: number, v: number): Vec3 => {
   return [ x / l, z / l, y / l ]
 }
 
+/** THE DATA MAP'S MIPS (transcodeKtx2.ts hands them to the encoder as explicit levels): a box mip of the ENCODED
+ *  octahedral normal is wrong - the map's seam pole is -Y at the corners and +Y its centre, so averaging two
+ *  downward normals' coordinates lands near the centre, i.e. UP. Measured on a Chernobyl aspen (2026-11-04): the
+ *  lower crown's normals read n.y -0.40 at level 0, -0.20 after a 4x4 box of the map, -0.11 after 8x8 - and the
+ *  quad, reading that mip under an overcast sky, lit its crown 22 % brighter than the cards. Here every level's r, g
+ *  is the encoded mean of the DECODED normals of its source texels (normalised), b (depth) and a (AO) the plain mean.
+ *  Level 0 is the source; the levels halve to 1x1 (an odd edge takes its last texel into the previous block). */
+export type DataLevel = { data: Uint8Array, width: number, height: number }
+export const impostorDataMipChain = (src: Uint8Array, sw: number, sh: number): DataLevel[] => {
+  const levels: DataLevel[] = [ { data: src, width: sw, height: sh } ]
+  let cur = levels[0]
+  while (cur.width > 1 || cur.height > 1) {
+    const w = Math.max(1, cur.width >> 1), h = Math.max(1, cur.height >> 1)
+    const out = new Uint8Array(w * h * 4)
+    const fx = cur.width / w, fy = cur.height / h
+    for (let y = 0; y < h; y++) {
+      const y0 = Math.floor(y * fy), y1 = y === h - 1 ? cur.height : Math.floor((y + 1) * fy)
+      for (let x = 0; x < w; x++) {
+        const x0 = Math.floor(x * fx), x1 = x === w - 1 ? cur.width : Math.floor((x + 1) * fx)
+        let nx = 0, ny = 0, nz = 0, b = 0, a = 0, n = 0
+        for (let yy = y0; yy < y1; yy++) for (let xx = x0; xx < x1; xx++) {
+          const o = (yy * cur.width + xx) * 4
+          const v = normalDecode(cur.data[o] / 255, cur.data[o + 1] / 255)
+          nx += v[0]; ny += v[1]; nz += v[2]; b += cur.data[o + 2]; a += cur.data[o + 3]; n++
+        }
+        const l = Math.hypot(nx, ny, nz)
+        const [ eu, ev ] = l > 1e-9 ? normalEncode([ nx / l, ny / l, nz / l ]) : [ 0.5, 0.5 ]
+        const o = (y * w + x) * 4
+        out[o] = Math.round(Math.min(Math.max(eu, 0), 1) * 255)
+        out[o + 1] = Math.round(Math.min(Math.max(ev, 0), 1) * 255)
+        out[o + 2] = Math.round(b / n); out[o + 3] = Math.round(a / n)
+      }
+    }
+    cur = { data: out, width: w, height: h }
+    levels.push(cur)
+  }
+  return levels
+}
+
 /** Screen right / up of the frame that looks along -d. */
 export const frameBasis = (d: Vec3): { right: Vec3, up: Vec3 } => {
   const ref: Vec3 = Math.abs(d[1]) < 0.999 ? [ 0, 1, 0 ] : [ 0, 0, -1 ]
@@ -178,9 +233,12 @@ export const octLayout = (N: number, P: number): ImpostorLayout => {
 
 // ---- level-0 geometry ------------------------------------------------------------------------------------
 
-type Slot = { mask: boolean, cull: boolean, cutoff: number, f: [number, number, number, number], img: Uint8Array | null, w: number, h: number, wrapS: number, wrapT: number, set: number }
+type Sampler = { w: number, h: number, wrapS: number, wrapT: number }
+/** A bark slot's extra maps (RGBA8, sampled through `taps`): the glTF occlusion map (r, linear) at its strength, the normal map (b = n.z). */
+type Tex = Sampler & { img: Uint8Array, set: number }
+type Slot = { mask: boolean, cull: boolean, cutoff: number, f: [number, number, number, number], img: Uint8Array | null, w: number, h: number, wrapS: number, wrapT: number, set: number, occ: Tex | null, occStrength: number, nmap: Tex | null }
 type Level0 = {
-  pos: Float32Array, nrm: Float32Array, uv: Float32Array, ao: Float32Array
+  pos: Float32Array, nrm: Float32Array, uv: Float32Array, ao: Float32Array, cav: Float32Array
   tri: Uint32Array, triSlot: Uint16Array, face: Float32Array, slots: Slot[]
   min: Vec3, max: Vec3, root: GltfNode
 }
@@ -208,17 +266,8 @@ export const impostorBounds = (doc: Document): { min: Vec3, max: Vec3 } | null =
   return min[0] <= max[0] ? { min, max } : null
 }
 
-const makeSlot = async (mat: Material | null, images: Map<Texture, Promise<{ img: Uint8Array, w: number, h: number } | null>>, log: (s: string) => void): Promise<Slot> => {
-  const f = (mat?.getBaseColorFactor() ?? [ 1, 1, 1, 1 ]) as [number, number, number, number]
-  const mask = mat?.getAlphaMode() === "MASK"
-  const slot: Slot = { mask, cull: !mask && !mat?.getDoubleSided(), cutoff: mat ? mat.getAlphaCutoff() : 0.5, f: [ f[0], f[1], f[2], f[3] ], img: null, w: 0, h: 0, wrapS: REPEAT, wrapT: REPEAT, set: 0 }
-  const tex = mat?.getBaseColorTexture()
-  if (!mat || !tex) return slot
-  if ((tex.getMimeType() || "").includes("ktx2")) throw new Error(`impostor: the base colour of material "${mat.getName()}" is already KTX2 — bake impostors before the KTX2 encode (from the source textures)`)
-  const info = mat.getBaseColorTextureInfo()
-  slot.set = info?.getTexCoord() ?? 0
-  slot.wrapS = info?.getWrapS() ?? REPEAT
-  slot.wrapT = info?.getWrapT() ?? REPEAT
+type Images = Map<Texture, Promise<{ img: Uint8Array, w: number, h: number } | null>>
+const decodeTex = (tex: Texture, images: Images): Promise<{ img: Uint8Array, w: number, h: number } | null> => {
   let job = images.get(tex)
   if (!job) {
     job = (async () => {
@@ -228,17 +277,45 @@ const makeSlot = async (mat: Material | null, images: Map<Texture, Promise<{ img
     })()
     images.set(tex, job)
   }
-  const img = await job
+  return job
+}
+
+const makeSlot = async (mat: Material | null, images: Images, log: (s: string) => void): Promise<Slot> => {
+  const f = (mat?.getBaseColorFactor() ?? [ 1, 1, 1, 1 ]) as [number, number, number, number]
+  const mask = mat?.getAlphaMode() === "MASK"
+  const slot: Slot = { mask, cull: !mask && !mat?.getDoubleSided(), cutoff: mat ? mat.getAlphaCutoff() : 0.5, f: [ f[0], f[1], f[2], f[3] ], img: null, w: 0, h: 0, wrapS: REPEAT, wrapT: REPEAT, set: 0, occ: null, occStrength: 1, nmap: null }
+  if (!mat) return slot
+  // the BARK's extra maps (an opaque slot): what foliage.mat darkens the bark's ambient by - its occlusion map at the
+  // material's strength and its normal map's cavity - go into the bark map's b (the header). A KTX2 one is skipped
+  // with a line (the base colour below is the one that must be source bytes).
+  if (!mask) {
+    for (const [ what, tex, info ] of [ [ "occ", mat.getOcclusionTexture(), mat.getOcclusionTextureInfo() ], [ "nmap", mat.getNormalTexture(), mat.getNormalTextureInfo() ] ] as const) {
+      if (!tex) continue
+      if ((tex.getMimeType() || "").includes("ktx2")) { log(`   ⚠ impostor: the ${what === "occ" ? "occlusion" : "normal"} map of "${mat.getName()}" is KTX2 - the bark's atlas occlusion goes without it`); continue }
+      const im = await decodeTex(tex, images)
+      if (!im) continue
+      const t: Tex = { img: im.img, w: im.w, h: im.h, wrapS: info?.getWrapS() ?? REPEAT, wrapT: info?.getWrapT() ?? REPEAT, set: info?.getTexCoord() ?? 0 }
+      if (what === "occ") { slot.occ = t; slot.occStrength = mat.getOcclusionStrength() } else slot.nmap = t
+    }
+  }
+  const tex = mat.getBaseColorTexture()
+  if (!tex) return slot
+  if ((tex.getMimeType() || "").includes("ktx2")) throw new Error(`impostor: the base colour of material "${mat.getName()}" is already KTX2 — bake impostors before the KTX2 encode (from the source textures)`)
+  const info = mat.getBaseColorTextureInfo()
+  slot.set = info?.getTexCoord() ?? 0
+  slot.wrapS = info?.getWrapS() ?? REPEAT
+  slot.wrapT = info?.getWrapT() ?? REPEAT
+  const img = await decodeTex(tex, images)
   if (!img) { log(`   ⚠ impostor: the base colour of "${mat.getName()}" could not be decoded — drawn as its factor, opaque`); slot.mask = false; return slot }
   slot.img = img.img; slot.w = img.w; slot.h = img.h
   return slot
 }
 
 const collectLevel0 = async (doc: Document, log: (s: string) => void): Promise<Level0 | null> => {
-  const pos: number[] = [], nrm: number[] = [], uv: number[] = [], ao: number[] = []
+  const pos: number[] = [], nrm: number[] = [], uv: number[] = [], ao: number[] = [], cav: number[] = []
   const tri: number[] = [], triSlot: number[] = [], face: number[] = []
   const slots: Slot[] = [], slotOf = new Map<Material | null, number>()
-  const images = new Map<Texture, Promise<{ img: Uint8Array, w: number, h: number } | null>>()
+  const images: Images = new Map()
   const min: Vec3 = [ Infinity, Infinity, Infinity ], max: Vec3 = [ -Infinity, -Infinity, -Infinity ]
   const trisOfNode = new Map<GltfNode, number>()
   const v: number[] = []
@@ -277,7 +354,7 @@ const collectLevel0 = async (doc: Document, log: (s: string) => void): Promise<L
           nrm.push(nx / l, ny / l, nz / l)
         } else nrm.push(0, 0, 0)          // no normals: the face normal stands in at shading
         if (T) { T.getElement(i, v); uv.push(v[0], v[1]) } else uv.push(0, 0)
-        if (C) { C.getElement(i, v); ao.push(v[0]) } else ao.push(1)
+        if (C) { C.getElement(i, v); ao.push(v[0]); cav.push(v[1]) } else { ao.push(1); cav.push(1) }
       }
       const idx = p.getIndices()
       const n = idx ? idx.getCount() : count
@@ -303,7 +380,7 @@ const collectLevel0 = async (doc: Document, log: (s: string) => void): Promise<L
     if (!nested && n > best) { best = n; root = node }
   }
   return {
-    pos: Float32Array.from(pos), nrm: Float32Array.from(nrm), uv: Float32Array.from(uv), ao: Float32Array.from(ao),
+    pos: Float32Array.from(pos), nrm: Float32Array.from(nrm), uv: Float32Array.from(uv), ao: Float32Array.from(ao), cav: Float32Array.from(cav),
     tri: Uint32Array.from(tri), triSlot: Uint16Array.from(triSlot), face: Float32Array.from(face), slots, min, max, root: root!,
   }
 }
@@ -322,7 +399,7 @@ const wrapI = (i: number, n: number, mode: number): number => {
 }
 // bilinear taps of the last `taps` call: byte offsets + weights (module scratch: the bake is synchronous per sample)
 const tapI = new Int32Array(4), tapW = new Float32Array(4)
-const taps = (s: Slot, u: number, v: number): void => {
+const taps = (s: Sampler, u: number, v: number): void => {
   const fx = u * s.w - 0.5, fy = v * s.h - 0.5
   const x0 = Math.floor(fx), y0 = Math.floor(fy), tx = fx - x0, ty = fy - y0
   const xa = wrapI(x0, s.w, s.wrapS), xb = wrapI(x0 + 1, s.w, s.wrapS), ya = wrapI(y0, s.h, s.wrapT), yb = wrapI(y0 + 1, s.h, s.wrapT)
@@ -335,6 +412,20 @@ const alphaAt = (s: Slot, u: number, v: number): number => {
   const d = s.img
   return (d[tapI[0] + 3] * tapW[0] + d[tapI[1] + 3] * tapW[1] + d[tapI[2] + 3] * tapW[2] + d[tapI[3] + 3] * tapW[3]) / 255 * s.f[3]
 }
+// one channel of a bark map at (u, v), bilinear, 0..1
+const chanAt = (t: Tex, ch: number, u: number, v: number): number => {
+  taps(t, u, v)
+  const d = t.img
+  return (d[tapI[0] + ch] * tapW[0] + d[tapI[1] + ch] * tapW[1] + d[tapI[2] + ch] * tapW[2] + d[tapI[3] + ch] * tapW[3]) / 255
+}
+// what foliage.mat darkens the bark's ambient by beyond the sky visibility: the material's occlusion map at its strength
+// x the normal map's cavity (½ + ½·clamp(n.z, 0, 1): a texel whose normal leans hard off the surface sits in a groove)
+const barkOccAt = (s: Slot, u: number, v: number): number => {
+  let o = 1
+  if (s.occ) o *= 1 + s.occStrength * (chanAt(s.occ, 0, u, v) - 1)
+  if (s.nmap) o *= 0.5 + 0.5 * Math.min(Math.max(chanAt(s.nmap, 2, u, v) * 2 - 1, 0), 1)
+  return o
+}
 
 // ---- dilation ------------------------------------------------------------------------------------------------
 
@@ -342,7 +433,7 @@ const DILATE_PASSES = 16
 
 /** Fill the empty texels' colour (base rgb) and data (all four) from their filled 8-neighbours in the same frame,
  *  pass by pass; whatever is still empty after the passes takes its frame's mean (the mips' last levels). */
-const dilate = (base: Uint8Array, data: Uint8Array, covered: Uint8Array, W: number, H: number, frameOf: Int32Array, nFrames: number): void => {
+const dilate = (base: Uint8Array, data: Uint8Array, bark: Uint8Array, covered: Uint8Array, W: number, H: number, frameOf: Int32Array, nFrames: number): void => {
   let cur = covered.slice()
   for (let pass = 0; pass < DILATE_PASSES; pass++) {
     const next = cur.slice()
@@ -352,7 +443,7 @@ const dilate = (base: Uint8Array, data: Uint8Array, covered: Uint8Array, W: numb
         const i = y * W + x
         if (cur[i]) continue
         const f = frameOf[i]
-        let n = 0, r = 0, g = 0, b = 0, d0 = 0, d1 = 0, d2 = 0, d3 = 0
+        let n = 0, r = 0, g = 0, b = 0, d0 = 0, d1 = 0, d2 = 0, d3 = 0, k0 = 0, k2 = 0
         for (let oy = -1; oy <= 1; oy++) {
           const yy = y + oy
           if (yy < 0 || yy >= H) continue
@@ -364,6 +455,7 @@ const dilate = (base: Uint8Array, data: Uint8Array, covered: Uint8Array, W: numb
             const o = k * 4
             r += base[o]; g += base[o + 1]; b += base[o + 2]
             d0 += data[o]; d1 += data[o + 1]; d2 += data[o + 2]; d3 += data[o + 3]
+            k0 += bark[o]; k2 += bark[o + 2]
             n++
           }
         }
@@ -371,6 +463,7 @@ const dilate = (base: Uint8Array, data: Uint8Array, covered: Uint8Array, W: numb
         const o = i * 4
         base[o] = Math.round(r / n); base[o + 1] = Math.round(g / n); base[o + 2] = Math.round(b / n)
         data[o] = Math.round(d0 / n); data[o + 1] = Math.round(d1 / n); data[o + 2] = Math.round(d2 / n); data[o + 3] = Math.round(d3 / n)
+        bark[o] = Math.round(k0 / n); bark[o + 2] = Math.round(k2 / n)
         next[i] = 1
         changed++
       }
@@ -380,24 +473,26 @@ const dilate = (base: Uint8Array, data: Uint8Array, covered: Uint8Array, W: numb
   }
   // the rest: the frame's mean over its covered texels (the whole atlas' when the frame saw nothing)
   // (slot nFrames = the whole atlas; a texel outside every frame - none in today's layouts - takes the atlas' mean)
-  const sums = new Float64Array((nFrames + 1) * 8)
-  const all = nFrames * 8
+  const sums = new Float64Array((nFrames + 1) * 10)
+  const all = nFrames * 10
   for (let i = 0; i < W * H; i++) {
     if (!covered[i]) continue
     const o = i * 4
-    for (const s of frameOf[i] >= 0 ? [ frameOf[i] * 8, all ] : [ all ]) {
+    for (const s of frameOf[i] >= 0 ? [ frameOf[i] * 10, all ] : [ all ]) {
       sums[s] += base[o]; sums[s + 1] += base[o + 1]; sums[s + 2] += base[o + 2]
       sums[s + 3] += data[o]; sums[s + 4] += data[o + 1]; sums[s + 5] += data[o + 2]; sums[s + 6] += data[o + 3]; sums[s + 7]++
+      sums[s + 8] += bark[o]; sums[s + 9] += bark[o + 2]
     }
   }
   for (let i = 0; i < W * H; i++) {
     if (cur[i]) continue
-    let s = frameOf[i] >= 0 ? frameOf[i] * 8 : all
+    let s = frameOf[i] >= 0 ? frameOf[i] * 10 : all
     if (!sums[s + 7]) s = all
     const n = sums[s + 7], o = i * 4
-    if (!n) { base[o] = base[o + 1] = base[o + 2] = 128; data[o] = data[o + 1] = data[o + 2] = 128; data[o + 3] = 255; continue }
+    if (!n) { base[o] = base[o + 1] = base[o + 2] = 128; data[o] = data[o + 1] = data[o + 2] = 128; data[o + 3] = 255; bark[o] = 0; bark[o + 2] = 0; continue }
     base[o] = Math.round(sums[s] / n); base[o + 1] = Math.round(sums[s + 1] / n); base[o + 2] = Math.round(sums[s + 2] / n)
     data[o] = Math.round(sums[s + 3] / n); data[o + 1] = Math.round(sums[s + 4] / n); data[o + 2] = Math.round(sums[s + 5] / n); data[o + 3] = Math.round(sums[s + 6] / n)
+    bark[o] = Math.round(sums[s + 8] / n); bark[o + 2] = Math.round(sums[s + 9] / n)
   }
 }
 
@@ -419,6 +514,9 @@ const invert4 = (m: ArrayLike<number>): number[] | null => {
   ]
 }
 
+/** The default supersampling (S×S a texel) — `--impostor-samples` overrides it. */
+export const IMPOSTOR_SAMPLES = 8
+
 const encodePng = async (rgba: Uint8Array, w: number, h: number): Promise<Uint8Array> => {
   const sharp = (await import("sharp")).default
   return new Uint8Array(await sharp(Buffer.from(rgba.buffer, rgba.byteOffset, rgba.byteLength), { raw: { width: w, height: h, channels: 4 } }).png().toBuffer())
@@ -434,7 +532,7 @@ export const bakeImpostor = async (doc: Document, opts: ImpostorOptions): Promis
   const log = opts.log ?? ((s: string) => console.log(s))
   const g = await collectLevel0(doc, log)
   if (!g) return null
-  const { pos, nrm, uv, ao, tri, triSlot, face, slots } = g
+  const { pos, nrm, uv, ao, cav, tri, triSlot, face, slots } = g
   const nv = pos.length / 3, nt = tri.length / 3
   const c: Vec3 = [ (g.min[0] + g.max[0]) / 2, (g.min[1] + g.max[1]) / 2, (g.min[2] + g.max[2]) / 2 ]
   let r2 = 0
@@ -461,8 +559,11 @@ export const bakeImpostor = async (doc: Document, opts: ImpostorOptions): Promis
     for (let y = f.y0; y < f.y1; y++) frameOf.fill(fi, y * AW + f.x0, y * AW + f.x1)
   })
 
-  const base = new Uint8Array(AW * AH * 4), data = new Uint8Array(AW * AH * 4), covered = new Uint8Array(AW * AH)
-  const samples = span * span * 4
+  // the BARK map (the material's occlusionTexture): r = the texel's bark fraction, g = b = 0, a = 255 (the header)
+  const base = new Uint8Array(AW * AH * 4), data = new Uint8Array(AW * AH * 4), bark = new Uint8Array(AW * AH * 4), covered = new Uint8Array(AW * AH)
+  const S = Math.max(1, Math.min(16, Math.round(opts.samples ?? IMPOSTOR_SAMPLES))), S2 = S * S
+  for (let i = 3; i < bark.length; i += 4) bark[i] = 255
+  const samples = span * span * S2
   const zb = new Float32Array(samples), tb = new Int32Array(samples), l1b = new Float32Array(samples), l2b = new Float32Array(samples)
   const qx = new Float32Array(nv), qy = new Float32Array(nv), qz = new Float32Array(nv)
 
@@ -470,7 +571,7 @@ export const bakeImpostor = async (doc: Document, opts: ImpostorOptions): Promis
     const d = fr.d
     const { right, up } = frameBasis(d)
     const X0 = fr.x0, X1 = fr.x1, Y0 = fr.y0, Y1 = fr.y1
-    const W = (X1 - X0) * 2, H = (Y1 - Y0) * 2
+    const W = (X1 - X0) * S, H = (Y1 - Y0) * S
     // every vertex into this frame's sample grid (sample k centred at k + 0.5), qz = toward the camera; the frame's
     // local (a, b) spans its rect: x = x0 + a·(x1 - x0), y = y0 + (1 - b)·(y1 - y0)
     const k = 0.5 / r
@@ -515,24 +616,39 @@ export const bakeImpostor = async (doc: Document, opts: ImpostorOptions): Promis
         }
       }
     }
-    // resolve: each texel's four samples shaded from their triangle + barycentrics
+    // resolve: each texel's S×S samples shaded from their triangle + barycentrics
     for (let y = Y0; y < Y1; y++) {
       for (let x = X0; x < X1; x++) {
-        let n = 0, cr = 0, cg = 0, cb = 0, nx = 0, ny = 0, nz = 0, aoSum = 0, zSum = 0
-        for (let q = 0; q < 4; q++) {
-          const s = ((y - Y0) * 2 + (q >> 1)) * W + (x - X0) * 2 + (q & 1)
+        let n = 0, nBark = 0, cr = 0, cg = 0, cb = 0, nx = 0, ny = 0, nz = 0, aoSum = 0, zSum = 0, occSum = 0
+        for (let q = 0; q < S2; q++) {
+          const s = ((y - Y0) * S + Math.floor(q / S)) * W + (x - X0) * S + (q % S)
           const t = tb[s]
           if (t < 0) continue
           zSum += zb[s]                   // dot(p - c, d) of the surviving sample's surface point
           const l1 = l1b[s], l2 = l2b[s], l0 = 1 - l1 - l2
           const ia = tri[t * 3], ib = tri[t * 3 + 1], ic = tri[t * 3 + 2]
-          // the hull normal at the surface point (the cards' shading normal, see the header), never flipped
-          const mx = pos[ia * 3] * l0 + pos[ib * 3] * l1 + pos[ic * 3] * l2 - crown[0]
-          const my = pos[ia * 3 + 1] * l0 + pos[ib * 3 + 1] * l1 + pos[ic * 3 + 1] * l2 - crown[1]
-          const mz = pos[ia * 3 + 2] * l0 + pos[ib * 3 + 2] * l1 + pos[ic * 3 + 2] * l2 - crown[2]
-          const ml = Math.hypot(mx, my, mz) || 1
-          nx += mx / ml; ny += my / ml; nz += mz / ml
           const slot = slots[triSlot[t]]
+          if (!slot.mask) {
+            // BARK (an opaque slot): the MESH normal - the vertices' interpolated NORMAL (the face's where the mesh has
+            // none) - turned toward this frame's viewer: what the bark is lit by (foliage.mat), not the crown's hull
+            let mx = nrm[ia * 3] * l0 + nrm[ib * 3] * l1 + nrm[ic * 3] * l2
+            let my = nrm[ia * 3 + 1] * l0 + nrm[ib * 3 + 1] * l1 + nrm[ic * 3 + 1] * l2
+            let mz = nrm[ia * 3 + 2] * l0 + nrm[ib * 3 + 2] * l1 + nrm[ic * 3 + 2] * l2
+            let ml = Math.hypot(mx, my, mz)
+            if (ml < 1e-6) { mx = face[t * 3]; my = face[t * 3 + 1]; mz = face[t * 3 + 2]; ml = 1 }
+            const flip = mx * d[0] + my * d[1] + mz * d[2] < 0 ? -1 : 1
+            nx += flip * mx / ml; ny += flip * my / ml; nz += flip * mz / ml
+            nBark++
+            // the bark's occlusion (the header): the baked cavity x the material's maps at the sample's uv
+            occSum += (cav[ia] * l0 + cav[ib] * l1 + cav[ic] * l2) * (slot.occ || slot.nmap ? barkOccAt(slot, uv[ia * 2] * l0 + uv[ib * 2] * l1 + uv[ic * 2] * l2, uv[ia * 2 + 1] * l0 + uv[ib * 2 + 1] * l1 + uv[ic * 2 + 1] * l2) : 1)
+          } else {
+            // a card: the hull normal at the surface point (the cards' shading normal, see the header), never flipped
+            const mx = pos[ia * 3] * l0 + pos[ib * 3] * l1 + pos[ic * 3] * l2 - crown[0]
+            const my = pos[ia * 3 + 1] * l0 + pos[ib * 3 + 1] * l1 + pos[ic * 3 + 1] * l2 - crown[1]
+            const mz = pos[ia * 3 + 2] * l0 + pos[ib * 3 + 2] * l1 + pos[ic * 3 + 2] * l2 - crown[2]
+            const ml = Math.hypot(mx, my, mz) || 1
+            nx += mx / ml; ny += my / ml; nz += mz / ml
+          }
           if (slot.img) {
             taps(slot, uv[ia * 2] * l0 + uv[ib * 2] * l1 + uv[ic * 2] * l2, uv[ia * 2 + 1] * l0 + uv[ib * 2 + 1] * l1 + uv[ic * 2 + 1] * l2)
             const im = slot.img
@@ -546,7 +662,9 @@ export const bakeImpostor = async (doc: Document, opts: ImpostorOptions): Promis
         if (!n) continue
         const o = (y * AW + x) * 4
         covered[y * AW + x] = 1
-        base[o] = toSrgb8(cr / n); base[o + 1] = toSrgb8(cg / n); base[o + 2] = toSrgb8(cb / n); base[o + 3] = Math.round(n / 4 * 255)
+        base[o] = toSrgb8(cr / n); base[o + 1] = toSrgb8(cg / n); base[o + 2] = toSrgb8(cb / n); base[o + 3] = Math.round(n / S2 * 255)
+        bark[o] = Math.round(nBark / n * 255)
+        bark[o + 2] = nBark ? Math.max(1, Math.round(Math.min(Math.max(occSum / nBark, 0), 1) * 255)) : 0   // 0 = no bark here (and an older atlas)
         // r, g = the mean hull normal in OBJECT space, full-sphere octahedral; b = the mean depth dot(p - c, d) / r
         const nl = Math.hypot(nx, ny, nz) || 1
         const [ eu, ev ] = normalEncode([ nx / nl, ny / nl, nz / nl ])
@@ -558,7 +676,7 @@ export const bakeImpostor = async (doc: Document, opts: ImpostorOptions): Promis
       }
     }
   }
-  dilate(base, data, covered, AW, AH, frameOf, frames.length)
+  dilate(base, data, bark, covered, AW, AH, frameOf, frames.length)
 
   // ---- the quad: the levels it replaces go, then the node --------------------------------------------------
   const root = g.root
@@ -568,20 +686,20 @@ export const bakeImpostor = async (doc: Document, opts: ImpostorOptions): Promis
   // `level` (--impostor-level) picks the slot - and so the LOD pass's threshold (0.30 / 0.12 / 0.05 for 1 / 2 / 3) the quad
   // shows at - never past the first gap: the pass hides every level at an index nothing fills
   const level = Math.min(Math.max(1, Math.round(opts.level ?? 2)), highest + 1)
-  const drop = (n: GltfNode): void => { for (const ch of n.listChildren()) drop(ch); n.dispose() }
-  for (const n of doc.getRoot().listNodes()) { const m = LOD_RE.exec(n.getName()); if (m && Number(m[1]) >= level && !n.isDisposed()) drop(n) }
+  for (const n of doc.getRoot().listNodes()) { const m = LOD_RE.exec(n.getName()); if (m && Number(m[1]) >= level && !n.isDisposed()) dropNode(n) }
 
   const buffer = doc.getRoot().listBuffers()[0] ?? doc.createBuffer()
   // tagged: transcodeKtx2.ts planKtx2 never resizes them by --max-size (a 3072 px strip squashed is a broken layout)
   const tag = () => ({ lecodes: { impostor: true } })
   const albedo = doc.createTexture(`${rootName}_impostor_albedo`).setMimeType("image/png").setImage(await encodePng(base, AW, AH)).setExtras(tag())
   const normalDepth = doc.createTexture(`${rootName}_impostor_data`).setMimeType("image/png").setImage(await encodePng(data, AW, AH)).setExtras(tag())
+  const barkMap = doc.createTexture(`${rootName}_impostor_bark`).setMimeType("image/png").setImage(await encodePng(bark, AW, AH)).setExtras(tag())
   const material = doc.createMaterial(`${rootName}_impostor`)
     .setAlphaMode("MASK").setAlphaCutoff(0.5).setDoubleSided(true).setMetallicFactor(0).setRoughnessFactor(1).setBaseColorFactor([ 1, 1, 1, 1 ])
-    .setBaseColorTexture(albedo).setMetallicRoughnessTexture(normalDepth)
+    .setBaseColorTexture(albedo).setMetallicRoughnessTexture(normalDepth).setOcclusionTexture(barkMap)
     .setExtras({ lecodes: { impostor: [ layout.cols, c[0], c[1], c[2], r, layout.rows ] } })
   // clamped: a frame on the atlas border must not wrap into the opposite one
-  for (const info of [ material.getBaseColorTextureInfo(), material.getMetallicRoughnessTextureInfo() ]) info?.setWrapS(CLAMP).setWrapT(CLAMP)
+  for (const info of [ material.getBaseColorTextureInfo(), material.getMetallicRoughnessTextureInfo(), material.getOcclusionTextureInfo() ]) info?.setWrapS(CLAMP).setWrapT(CLAMP)
   const acc = (type: "VEC2" | "VEC3" | "VEC4" | "SCALAR", arr: Float32Array<ArrayBuffer> | Uint16Array<ArrayBuffer>) => doc.createAccessor().setType(type).setArray(arr).setBuffer(buffer)
   const corners = new Float32Array([ -1, -1, -1, 1, -1, 1, 1, 1, -1, -1, 1, 1 ]).map((s, k) => c[k % 3] + s * r)
   const prim = doc.createPrimitive().setMaterial(material)
@@ -602,7 +720,14 @@ export const bakeImpostor = async (doc: Document, opts: ImpostorOptions): Promis
   } else {
     for (const s of doc.getRoot().listScenes()) if (s.listChildren().includes(root)) s.addChild(node)
   }
-  // quiet: prune logs every removal at INFO, once per kind of an import
+  await pruneQuiet(doc)
+  return { cols: layout.cols, rows: layout.rows, px: P, width: AW, height: AH, radius: r, center: c, level, triangles: nt, ms: Math.round(performance.now() - t0), node: node.getName(), samples: S }
+}
+
+const dropNode = (n: GltfNode): void => { for (const ch of n.listChildren()) dropNode(ch); n.dispose() }
+
+/** prune what the dropped nodes used — quietly: prune logs every removal at INFO, once per kind of an import */
+const pruneQuiet = async (doc: Document): Promise<void> => {
   const logger = doc.getLogger()
   doc.setLogger(new Logger(Logger.Verbosity.SILENT))
   await doc.transform(prune({
@@ -610,5 +735,25 @@ export const bakeImpostor = async (doc: Document, opts: ImpostorOptions): Promis
     keepLeaves: true, keepAttributes: true, keepIndices: true, keepSolidTextures: true, keepExtras: false,
   }))
   doc.setLogger(logger)
-  return { cols: layout.cols, rows: layout.rows, px: P, width: AW, height: AH, radius: r, center: c, level, triangles: nt, ms: Math.round(performance.now() - t0), node: node.getName() }
+}
+
+/**
+ * Drop the pack's own BILLBOARD level: Unity's tree exporter writes the last level as `Billboard_<Tree>` — two crossed
+ * cards over a pre-rendered sheet under a Standard-shader material, which the importer keeps as `<Tree>_LOD<n>`
+ * (kindGlb.ts) and which, drawn by the crown cards' shader, is a flat pale cross (Chernobyl, 2026-11-04: every far
+ * tree). Under `--impostor` the quad IS the billboard, so the level goes for every vegetation kind — the ones too small
+ * for a quad simply end at their last mesh level. A node whose every primitive wears a `Billboard_*` material. Returns
+ * how many nodes went.
+ */
+export const dropBillboards = async (doc: Document): Promise<number> => {
+  let n = 0
+  for (const node of doc.getRoot().listNodes()) {
+    if (node.isDisposed()) continue
+    const prims = node.getMesh()?.listPrimitives() ?? []
+    if (!prims.length || !prims.every((p) => /^Billboard_/i.test(p.getMaterial()?.getName() ?? ""))) continue
+    dropNode(node)
+    n++
+  }
+  if (n) await pruneQuiet(doc)
+  return n
 }