lecodes-assets 0.2.0 → 0.2.1

package/src/terrainPack.ts

@@ -0,0 +1,169 @@
+// `lecodes assets terrain-pack` — a terrain's splat layers (up to four) → what `Terrain.create`'s
+// `layers`/`normals` read (docs/terrain-plan.md §1.5):
+//
+//   <name>.ktx2        one per layer: the albedo, sRGB, square, mipmapped
+//   normals01.ktx2     layer 0's normal XY in RG + layer 1's in BA   (linear)
+//   normals23.ktx2     layers 2 + 3 likewise (only when there are more than two layers)
+//
+// The packing exists because terrain.mat runs at Filament feature level 1 (nine samplers): four
+// albedos + four separate normal maps + the control map + the lightmap would be ten. Z is
+// reconstructed in the shader, so only XY ship. A layer without a normal map gets a flat (128,128).
+//
+// Inputs: an albedo file per layer (PNG/JPEG/WebP/TIFF via sharp, TGA/BMP decoded here) with the
+// normal map given by `--normals`, guessed from the albedo's name (`<x>_Albedo.png` → `<x>_Normal.png`),
+// or — the Unity-pack shape — a FOLDER per layer holding `*_Albedo.*` + `*_Normal.*`.
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs"
+import { basename, extname, join, resolve } from "node:path"
+import { spawnSync } from "node:child_process"
+import { decodeBmp, decodeTga, encodePng, sniffMime } from "./textures/resolveImage"
+import { findToktx, checkToktx } from "./doctor/transcodeKtx2"
+
+export type TerrainPackLayer = { name: string, albedo: string, normal?: string }
+
+export type TerrainPackOptions = {
+  /** Where the files land. */
+  outDir: string
+  /** Output edge in pixels — every texture is resampled square (default 1024). */
+  size?: number
+  /** Write PNGs instead of KTX2 (no toktx needed; larger, uncompressed on the GPU). */
+  png?: boolean
+  /** Invert the normal maps' green channel (DirectX-style sources; Unity's are OpenGL-style, the default). */
+  flipY?: boolean
+  /** toktx UASTC quality 0–4 (default 1). */
+  quality?: number
+  log?: (msg: string) => void
+}
+
+export type TerrainPackResult = {
+  layers: { name: string, file: string, albedo: string, normal: string | null, sourceSize: [number, number] }[]
+  normals: string[]
+  /** The matching `Terrain.create` fragment. */
+  snippet: string
+}
+
+const IMAGE_EXT = /\.(png|jpe?g|webp|tiff?|tga|bmp)$/i
+
+/** A layer from a file (+ optional normal) or a folder (`*Albedo*` + `*Normal*` inside). */
+export const resolveTerrainLayer = (input: string, normal?: string, name?: string): TerrainPackLayer => {
+  const p = resolve(input)
+  if (!existsSync(p)) throw new Error(`not found: ${input}`)
+  if (statSync(p).isDirectory()) {
+    const files = readdirSync(p).filter((f) => IMAGE_EXT.test(f))
+    // plain "_Albedo" over "_AlbedoSmoothness" (Unity packs ship both; the smoothness alpha is dropped anyway)
+    const albedo = files.find((f) => /albedo/i.test(f) && !/smooth/i.test(f)) ?? files.find((f) => /albedo|basecolor|base_color|diffuse|_d\./i.test(f))
+    if (!albedo) throw new Error(`${input}: no albedo image (a file named *Albedo* / *BaseColor* / *Diffuse*)`)
+    const nrm = normal ?? files.find((f) => /normal|_n\./i.test(f) && !/normalmap_?dx/i.test(f))
+    return { name: name ?? cleanName(basename(p)), albedo: join(p, albedo), normal: nrm ? (normal ? resolve(normal) : join(p, nrm)) : undefined }
+  }
+  if (!IMAGE_EXT.test(p)) throw new Error(`${input}: not an image (png/jpg/webp/tiff/tga/bmp)`)
+  let nrm: string | undefined = normal ? resolve(normal) : undefined
+  if (!nrm) {
+    const stem = p.slice(0, -extname(p).length)
+    for (const cand of [ stem.replace(/albedo/i, "Normal"), stem.replace(/albedo/i, "normal"), `${stem}_Normal`, `${stem}_normal`, stem.replace(/_?(basecolor|diffuse|_d)$/i, "_Normal") ]) {
+      if (cand === stem) continue
+      const hit = [ ".png", ".jpg", ".jpeg", ".tga", ".webp", ".tif", ".tiff", ".bmp" ].map((e) => cand + e).find((f) => existsSync(f))
+      if (hit) { nrm = hit; break }
+    }
+  }
+  return { name: name ?? cleanName(basename(p, extname(p)).replace(/[_-]?(albedo|basecolor|base_color|diffuse)$/i, "")), albedo: p, normal: nrm }
+}
+
+const cleanName = (s: string): string => s.trim().replace(/\s+/g, "_").replace(/[^A-Za-z0-9_-]/g, "").toLowerCase() || "layer"
+
+type Raw = { data: Buffer, width: number, height: number }
+
+/** Any supported image → RGBA at `size`² (TGA/BMP through the in-house decoders, the rest via sharp). */
+const loadRgba = async (path: string, size: number): Promise<Raw & { sourceSize: [number, number] }> => {
+  const sharp = (await import("sharp")).default
+  let bytes: Uint8Array = new Uint8Array(readFileSync(path))
+  const mime = sniffMime(bytes, path)
+  if (mime === "image/x-tga" || mime === "image/bmp") {
+    const rgba = mime === "image/x-tga" ? decodeTga(bytes) : decodeBmp(bytes)
+    if (!rgba) throw new Error(`${path}: could not decode the ${mime === "image/bmp" ? "BMP" : "TGA"}`)
+    bytes = encodePng(rgba)
+  }
+  const img = sharp(Buffer.from(bytes))
+  const meta = await img.metadata()
+  const { data, info } = await img.resize(size, size, { fit: "fill", kernel: "lanczos3" }).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+  return { data, width: info.width, height: info.height, sourceSize: [ meta.width ?? 0, meta.height ?? 0 ] }
+}
+
+const encodeKtx2 = (toktx: string, png: string, ktx2: string, srgb: boolean, quality: number): void => {
+  const args = [ "--t2", "--encode", "uastc", "--uastc_quality", String(quality), "--zcmp", "18", "--genmipmap", "--assign_oetf", srgb ? "srgb" : "linear", ktx2, png ]
+  const p = spawnSync(toktx, args, { encoding: "utf8" })
+  if (p.status !== 0) throw new Error(`toktx failed (${p.status ?? p.error?.message ?? "?"}) on ${basename(png)}:\n${(p.stderr || p.stdout || "").trim()}`)
+}
+
+export const packTerrainTextures = async (layers: TerrainPackLayer[], opts: TerrainPackOptions): Promise<TerrainPackResult> => {
+  if (layers.length === 0) throw new Error("no layers")
+  if (layers.length > 4) throw new Error(`${layers.length} layers — a terrain material takes at most four`)
+  const size = opts.size ?? 1024
+  if (!(size >= 16 && size <= 8192) || (size & (size - 1)) !== 0) throw new Error(`--size wants a power of two in 16..8192, got ${size}`)
+  const log = opts.log ?? (() => {})
+  const sharp = (await import("sharp")).default
+  const toktx = opts.png ? null : findToktx()
+  if (toktx && !checkToktx(toktx)) {
+    throw new Error("KTX-Software's toktx is needed for KTX2 output — install it (https://github.com/KhronosGroup/KTX-Software/releases, on PATH or KTX_TOKTX=<path>) or pass --png")
+  }
+  const seen = new Set<string>()
+  for (const l of layers) {
+    if (seen.has(l.name)) throw new Error(`two layers named "${l.name}" — pass --names`)
+    seen.add(l.name)
+  }
+  mkdirSync(opts.outDir, { recursive: true })
+  const ext = opts.png ? ".png" : ".ktx2"
+
+  const writeImage = async (raw: Raw, channels: 3 | 4, out: string, srgb: boolean): Promise<void> => {
+    let pipe = sharp(raw.data, { raw: { width: raw.width, height: raw.height, channels: 4 } })
+    if (channels === 3) pipe = pipe.removeAlpha()
+    const png = opts.png ? out : out.slice(0, -ext.length) + ".png"
+    await pipe.png({ compressionLevel: opts.png ? 9 : 1 }).toFile(png)
+    if (toktx) {
+      encodeKtx2(toktx, png, out, srgb, opts.quality ?? 1)
+      unlinkSync(png)
+    }
+  }
+
+  const result: TerrainPackResult = { layers: [], normals: [], snippet: "" }
+  const normalRaws: (Raw | null)[] = []
+  for (const l of layers) {
+    const alb = await loadRgba(l.albedo, size)
+    const file = join(opts.outDir, l.name + ext)
+    await writeImage(alb, 3, file, true)
+    let nrm: (Raw & { sourceSize: [number, number] }) | null = null
+    if (l.normal) {
+      if (!existsSync(l.normal)) throw new Error(`${l.name}: normal map not found: ${l.normal}`)
+      nrm = await loadRgba(l.normal, size)
+    }
+    normalRaws.push(nrm)
+    result.layers.push({ name: l.name, file, albedo: l.albedo, normal: l.normal ?? null, sourceSize: alb.sourceSize })
+    log(`   ${l.name.padEnd(16)} ${alb.sourceSize[0]}×${alb.sourceSize[1]} → ${size}²  ${nrm ? `+ normal ${nrm.sourceSize[0]}×${nrm.sourceSize[1]}` : "(flat normal)"}`)
+  }
+
+  // the packs: RG = layer 2k's XY, BA = layer 2k+1's; a missing map is flat
+  const packCount = layers.length > 2 ? 2 : 1
+  for (let k = 0; k < packCount; k++) {
+    const a = normalRaws[k * 2] ?? null, b = normalRaws[k * 2 + 1] ?? null
+    const n = size * size
+    const out = Buffer.alloc(n * 4)
+    for (let i = 0; i < n; i++) {
+      const o = i * 4
+      out[o] = a ? a.data[o] : 128
+      out[o + 1] = a ? (opts.flipY ? 255 - a.data[o + 1] : a.data[o + 1]) : 128
+      out[o + 2] = b ? b.data[o] : 128
+      out[o + 3] = b ? (opts.flipY ? 255 - b.data[o + 1] : b.data[o + 1]) : 128
+    }
+    const file = join(opts.outDir, `normals${k * 2}${k * 2 + 1}${ext}`)
+    await writeImage({ data: out, width: size, height: size }, 4, file, false)
+    result.normals.push(file)
+    log(`   normals${k * 2}${k * 2 + 1}${"".padEnd(7)} ${a ? layers[k * 2].name : "flat"} + ${b ? layers[k * 2 + 1].name : layers[k * 2 + 1] ? "flat" : "—"}`)
+  }
+
+  const rel = (f: string): string => "./" + basename(f)
+  result.snippet = [
+    "layers: [",
+    ...result.layers.map((l, i) => `  { albedo: asset('${rel(l.file)}'), tiling: 4${normalRaws[i] ? ", normalScale: 1" : ""} },`),
+    `], normals: [ ${result.normals.map((f) => `asset('${rel(f)}')`).join(", ")} ]`,
+  ].join("\n")
+  return result
+}

package/src/textures/resolveImage.ts

@@ -0,0 +1,202 @@
+// Turn an FBX texture reference (embedded bytes or a filename) into GLB-embeddable image bytes.
+// PNG/JPEG pass through; TGA/BMP are decoded here and re-encoded as PNG (no native deps); anything
+// else goes through `sharp` when it's installed, otherwise the texture is skipped with a warning.
+
+import { existsSync, readFileSync } from "node:fs"
+import { basename, dirname, join, isAbsolute } from "node:path"
+import { deflateSync } from "node:zlib"
+import { createHash } from "node:crypto"
+import type { FbxTexture } from "../fbx/read"
+
+export type ResolvedImage = { data: Uint8Array, mimeType: "image/png" | "image/jpeg", hash: string, converted: boolean, source: string }
+type Warn = (w: { level: "warn" | "info", message: string }) => void
+
+export const sniffMime = (b: Uint8Array, hintName = ""): string => {
+  if (b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) return "image/png"
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return "image/jpeg"
+  if (b.length >= 12 && b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 && b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50) return "image/webp"
+  if (b.length >= 2 && b[0] === 0x42 && b[1] === 0x4d) return "image/bmp"
+  if (b.length >= 4 && b[0] === 0x44 && b[1] === 0x44 && b[2] === 0x53 && b[3] === 0x20) return "image/vnd-ms.dds"
+  if (b.length >= 4 && b[0] === 0x38 && b[1] === 0x42 && b[2] === 0x50 && b[3] === 0x53) return "image/vnd.adobe.photoshop"
+  if (b.length >= 4 && ((b[0] === 0x49 && b[1] === 0x49 && b[2] === 0x2a) || (b[0] === 0x4d && b[1] === 0x4d && b[2] === 0x00))) return "image/tiff"
+  if (b.length >= 12 && b[0] === 0xab && b[1] === 0x4b && b[2] === 0x54 && b[3] === 0x58) return "image/ktx2"
+  const ext = hintName.toLowerCase().split(".").pop() ?? ""
+  if (ext === "tga" || ext === "targa") return "image/x-tga"
+  // TGA has no magic; accept the footer or a plausible header when the extension says so
+  if (b.length > 26) {
+    const foot = new TextDecoder().decode(b.subarray(b.length - 18, b.length - 2))
+    if (foot === "TRUEVISION-XFILE") return "image/x-tga"
+  }
+  return "application/octet-stream"
+}
+
+const hashOf = (b: Uint8Array): string => createHash("sha1").update(b).digest("hex")
+
+/** Resolve an FBX texture to PNG/JPEG bytes (null = unusable, warned). */
+export const resolveTextureImage = async (t: FbxTexture, embedded: Uint8Array | null, baseDir: string | undefined, warn: Warn): Promise<ResolvedImage | null> => {
+  let data: Uint8Array | null = embedded && embedded.length > 0 ? embedded : null
+  let source = "embedded"
+  const hint = t.relative || t.filename || t.absolute || t.name
+  if (!data) {
+    const found = findExternal(t, baseDir)
+    if (!found) { warn({ level: "warn", message: `texture '${hint}': not embedded and not found next to the FBX — skipped` }); return null }
+    data = new Uint8Array(readFileSync(found))
+    source = found
+  }
+  const mime = sniffMime(data, hint)
+  if (mime === "image/png" || mime === "image/jpeg") return { data, mimeType: mime, hash: hashOf(data), converted: false, source }
+  if (mime === "image/x-tga") {
+    const rgba = decodeTga(data)
+    if (rgba) { const png = encodePng(rgba); return { data: png, mimeType: "image/png", hash: hashOf(png), converted: true, source } }
+  }
+  if (mime === "image/bmp") {
+    const rgba = decodeBmp(data)
+    if (rgba) { const png = encodePng(rgba); return { data: png, mimeType: "image/png", hash: hashOf(png), converted: true, source } }
+  }
+  // last resort: sharp (optional dependency)
+  try {
+    const sharp = (await import("sharp")).default
+    const png = new Uint8Array(await sharp(Buffer.from(data)).png().toBuffer())
+    return { data: png, mimeType: "image/png", hash: hashOf(png), converted: true, source }
+  } catch (e) {
+    warn({ level: "warn", message: `texture '${hint}': ${mime} is not supported without 'sharp' (bun add sharp) — skipped` })
+    return null
+  }
+}
+
+const findExternal = (t: FbxTexture, baseDir: string | undefined): string | null => {
+  const candidates: string[] = []
+  const names = [ t.absolute, t.filename, t.relative ].filter(Boolean)
+  for (const n of names) {
+    if (isAbsolute(n) && existsSync(n)) return n
+    if (baseDir) {
+      candidates.push(join(baseDir, n))
+      const b = basename(n.replace(/\\/g, "/"))
+      candidates.push(join(baseDir, b), join(baseDir, "textures", b), join(baseDir, "Textures", b))
+    }
+  }
+  for (const c of candidates) if (existsSync(c)) return c
+  return null
+}
+
+// ---- TGA --------------------------------------------------------------------------------------
+
+export type Rgba = { width: number, height: number, data: Uint8Array }
+
+export const decodeTga = (b: Uint8Array): Rgba | null => {
+  if (b.length < 18) return null
+  const idLen = b[0], cmapType = b[1], imgType = b[2]
+  const cmapStart = b[3] | (b[4] << 8), cmapLen = b[5] | (b[6] << 8), cmapBits = b[7]
+  const width = b[12] | (b[13] << 8), height = b[14] | (b[15] << 8)
+  const bpp = b[16], desc = b[17]
+  const topDown = (desc & 0x20) !== 0
+  const rle = imgType === 9 || imgType === 10 || imgType === 11
+  const kind = imgType & 7 // 1 = colormapped, 2 = truecolor, 3 = grayscale
+  if (width === 0 || height === 0 || ![ 1, 2, 3 ].includes(kind)) return null
+  let p = 18 + idLen
+  let cmap: Uint8Array | null = null
+  const cmapBytes = (cmapBits + 7) >> 3
+  if (cmapType === 1) { cmap = b.subarray(p, p + cmapLen * cmapBytes); p += cmapLen * cmapBytes }
+  const bytesPP = bpp >> 3
+  const out = new Uint8Array(width * height * 4)
+  const px = new Uint8Array(4)
+  const readPixel = (at: number): void => {
+    if (kind === 3) { const g = b[at]; px[0] = g; px[1] = g; px[2] = g; px[3] = bytesPP > 1 ? b[at + 1] : 255; return }
+    if (kind === 1 && cmap) {
+      const idx = (bytesPP === 2 ? b[at] | (b[at + 1] << 8) : b[at]) - cmapStart
+      const c = idx * cmapBytes
+      if (cmapBytes >= 3) { px[0] = cmap[c + 2]; px[1] = cmap[c + 1]; px[2] = cmap[c]; px[3] = cmapBytes === 4 ? cmap[c + 3] : 255 }
+      else { const v = cmap[c] | (cmap[c + 1] << 8); px[0] = ((v >> 10) & 31) * 8; px[1] = ((v >> 5) & 31) * 8; px[2] = (v & 31) * 8; px[3] = 255 }
+      return
+    }
+    if (bytesPP === 4) { px[0] = b[at + 2]; px[1] = b[at + 1]; px[2] = b[at]; px[3] = b[at + 3]; return }
+    if (bytesPP === 3) { px[0] = b[at + 2]; px[1] = b[at + 1]; px[2] = b[at]; px[3] = 255; return }
+    if (bytesPP === 2) { const v = b[at] | (b[at + 1] << 8); px[0] = ((v >> 10) & 31) * 8; px[1] = ((v >> 5) & 31) * 8; px[2] = (v & 31) * 8; px[3] = 255; return }
+    px[0] = px[1] = px[2] = b[at]; px[3] = 255
+  }
+  const total = width * height
+  let i = 0
+  const put = (): void => {
+    const y = topDown ? Math.floor(i / width) : height - 1 - Math.floor(i / width)
+    const o = (y * width + (i % width)) * 4
+    out[o] = px[0]; out[o + 1] = px[1]; out[o + 2] = px[2]; out[o + 3] = px[3]
+    i++
+  }
+  if (!rle) {
+    for (; i < total && p + bytesPP <= b.length;) { readPixel(p); p += bytesPP; put() }
+  } else {
+    while (i < total && p < b.length) {
+      const head = b[p++]
+      const count = (head & 0x7f) + 1
+      if (head & 0x80) { readPixel(p); p += bytesPP; for (let k = 0; k < count && i < total; k++) put() }
+      else for (let k = 0; k < count && i < total && p + bytesPP <= b.length; k++) { readPixel(p); p += bytesPP; put() }
+    }
+  }
+  return { width, height, data: out }
+}
+
+// ---- BMP (uncompressed 24/32-bit) --------------------------------------------------------------
+
+export const decodeBmp = (b: Uint8Array): Rgba | null => {
+  if (b.length < 54 || b[0] !== 0x42 || b[1] !== 0x4d) return null
+  const dv = new DataView(b.buffer, b.byteOffset, b.byteLength)
+  const offset = dv.getUint32(10, true)
+  const width = dv.getInt32(18, true)
+  const rawHeight = dv.getInt32(22, true)
+  const bpp = dv.getUint16(28, true)
+  const compression = dv.getUint32(30, true)
+  if ((bpp !== 24 && bpp !== 32) || (compression !== 0 && compression !== 3)) return null
+  const height = Math.abs(rawHeight)
+  const topDown = rawHeight < 0
+  const stride = ((width * bpp / 8) + 3) & ~3
+  const out = new Uint8Array(width * height * 4)
+  for (let y = 0; y < height; y++) {
+    const srcY = topDown ? y : height - 1 - y
+    let s = offset + srcY * stride
+    for (let x = 0; x < width; x++) {
+      const o = (y * width + x) * 4
+      out[o] = b[s + 2]; out[o + 1] = b[s + 1]; out[o + 2] = b[s]; out[o + 3] = bpp === 32 ? b[s + 3] : 255
+      s += bpp / 8
+    }
+  }
+  return { width, height, data: out }
+}
+
+// ---- PNG encoder (RGBA8, filter 0, zlib) -----------------------------------------------------------
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256)
+  for (let n = 0; n < 256; n++) { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; t[n] = c >>> 0 }
+  return t
+})()
+const crc32 = (parts: Uint8Array[]): number => {
+  let c = 0xffffffff
+  for (const p of parts) for (let i = 0; i < p.length; i++) c = CRC_TABLE[(c ^ p[i]) & 0xff] ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+const chunk = (type: string, data: Uint8Array): Uint8Array => {
+  const t = new TextEncoder().encode(type)
+  const out = new Uint8Array(12 + data.length)
+  const dv = new DataView(out.buffer)
+  dv.setUint32(0, data.length)
+  out.set(t, 4); out.set(data, 8)
+  dv.setUint32(8 + data.length, crc32([ t, data ]))
+  return out
+}
+
+export const encodePng = (img: Rgba): Uint8Array => {
+  const { width, height, data } = img
+  const raw = new Uint8Array((width * 4 + 1) * height)
+  for (let y = 0; y < height; y++) { raw[y * (width * 4 + 1)] = 0; raw.set(data.subarray(y * width * 4, (y + 1) * width * 4), y * (width * 4 + 1) + 1) }
+  const ihdr = new Uint8Array(13)
+  const dv = new DataView(ihdr.buffer)
+  dv.setUint32(0, width); dv.setUint32(4, height)
+  ihdr[8] = 8; ihdr[9] = 6; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0
+  const idat = new Uint8Array(deflateSync(raw, { level: 6 }))
+  const sig = new Uint8Array([ 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a ])
+  const parts = [ sig, chunk("IHDR", ihdr), chunk("IDAT", idat), chunk("IEND", new Uint8Array(0)) ]
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0))
+  let o = 0
+  for (const p of parts) { out.set(p, o); o += p.length }
+  return out
+}