lecodes-assets 0.2.1 → 2.5.0

package/src/unwrap/index.ts

@@ -0,0 +1,167 @@
+// The lightmap unwrap of whole GLB files — `lecodes assets unwrap` (commands/unwrap.ts) and `lecodes lightmap bake`'s
+// pre-step (the CLI reaches it through `unwrapGlbFiles` in src/cli.ts). The geometry work is ./lightmapUv.ts.
+//
+// IN PLACE, not `<name>.fixed.glb` like the doctor's passes: scenes reference the original file, so a fixed copy next
+// to it was one the owner copied over the original by hand (and the copies stayed). A file whose every primitive the
+// unwrap would lay out already carries TEXCOORD_1 is left alone (`force` re-unwraps it). The write is atomic: a temp
+// file beside the target, renamed over it — a failed or killed run leaves the original as it was.
+
+import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+import type { Document, Material, TextureInfo } from "@gltf-transform/core"
+import { ensureCodecs, makeIO } from "../doctor/reduceGlbBones"
+import { applyUnwrap, planNeedsUnwrap, planUnwrap, type UnwrapOptions, type UnwrapPlan, type UnwrapResult } from "./lightmapUv"
+
+export { applyUnwrap, planNeedsUnwrap, planUnwrap, DEFAULT_UNWRAP_TEXEL, UNWRAP_PADDING } from "./lightmapUv"
+export type { UnwrapGroup, UnwrapOptions, UnwrapPlan, UnwrapResult } from "./lightmapUv"
+
+export interface UnwrapFileOptions extends UnwrapOptions {
+  /** unwrap again even when every primitive already carries TEXCOORD_1 */
+  force?: boolean
+  /** write here instead of over the input */
+  output?: string
+}
+
+export interface UnwrapFileReport {
+  input: string
+  /** where the unwrapped file went; null when nothing was written */
+  output: string | null
+  status: "unwrapped" | "skipped" | "failed"
+  /** why it was skipped or failed */
+  reason?: string
+  /** one line: what the unwrap made of the file (describeUnwrap) */
+  summary: string
+  result?: UnwrapResult
+  /** primitives the unwrap leaves as they are (skinned, not a triangle list, …) */
+  kept: { name: string, reason: string }[]
+  /** TEXCOORD_1 sets the unwrap replaced (`force`, or a file that had them on some primitives only) */
+  replaced: number
+  warnings: string[]
+  ms: number
+  bytesBefore: number
+  bytesAfter: number
+}
+
+const message = (e: unknown): string => (e instanceof Error ? e.message : String(e))
+
+/** Materials of the planned primitives with a texture on TEXCOORD_1 (an AO map on the second set): they would sample the
+ *  lightmap layout once the set is replaced. */
+const uv1Samplers = (plan: UnwrapPlan): string[] => {
+  const names = new Set<string>()
+  const infos = (m: Material): (TextureInfo | null)[] => [
+    m.getBaseColorTextureInfo(), m.getNormalTextureInfo(), m.getOcclusionTextureInfo(), m.getEmissiveTextureInfo(), m.getMetallicRoughnessTextureInfo(),
+  ]
+  for (const p of [ ...plan.prims, ...plan.lods ]) {
+    const m = p.prim.getMaterial()
+    if (m && infos(m).some((i) => i?.getTexCoord() === 1)) names.add(m.getName() || "material")
+  }
+  return [ ...names ]
+}
+
+/** Write `bytes` to `target` through a temp file beside it, renamed over it. */
+const writeAtomic = (target: string, bytes: Uint8Array): void => {
+  const dir = dirname(target)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  const tmp = join(dir, `.${basename(target)}.unwrap-${process.pid}.tmp`)
+  try {
+    writeFileSync(tmp, bytes)
+    renameSync(tmp, target)
+  } catch (e) {
+    try { unlinkSync(tmp) } catch { /* never written */ }
+    throw e
+  }
+}
+
+/** Unwrap one document in memory (no file): the plan's verdict, and the result when it did. */
+export async function unwrapDocument(doc: Document, opts: UnwrapFileOptions = {}): Promise<Omit<UnwrapFileReport, "input" | "output" | "summary" | "ms" | "bytesBefore" | "bytesAfter">> {
+  const plan = planUnwrap(doc, opts)
+  const kept = plan.skipped
+  if (plan.prims.length === 0) return { status: "skipped", reason: kept.length ? "nothing to unwrap" : "no meshes", kept, replaced: 0, warnings: [] }
+  if (!opts.force && !planNeedsUnwrap(plan)) {
+    return { status: "skipped", reason: `has TEXCOORD_1 on its ${plan.prims.length + plan.lods.length} primitive(s)`, kept, replaced: 0, warnings: [] }
+  }
+  const replaced = plan.prims.filter((p) => p.hasUv1).length + plan.lods.filter((l) => l.hasUv1).length
+  const warnings: string[] = []
+  const samplers = replaced ? uv1Samplers(plan) : []
+  if (samplers.length) warnings.push(`${samplers.join(", ")} sample${samplers.length === 1 ? "s" : ""} a texture on TEXCOORD_1 — it now reads the lightmap layout`)
+  const result = await applyUnwrap(doc, plan)
+  // glTF's top-level `scene` is optional and glTF-Transform only writes it when set; strict loaders then load no roots.
+  const root = doc.getRoot()
+  if (!root.getDefaultScene() && root.listScenes().length > 0) root.setDefaultScene(root.listScenes()[0])
+  return { status: "unwrapped", result, kept, replaced, warnings }
+}
+
+/** Unwrap one GLB file: in place unless `output` names another file. Never throws for the file's sake — a failure is the
+ *  report's status. */
+export async function unwrapGlbFile(input: string, opts: UnwrapFileOptions = {}): Promise<UnwrapFileReport> {
+  const t0 = performance.now()
+  const rep: UnwrapFileReport = { input, output: null, status: "failed", summary: "", kept: [], replaced: 0, warnings: [], ms: 0, bytesBefore: 0, bytesAfter: 0 }
+  const done = (): UnwrapFileReport => { rep.ms = performance.now() - t0; rep.summary = describeUnwrap(rep); return rep }
+  if (!existsSync(input)) { rep.reason = "not found"; return done() }
+  rep.bytesBefore = statSync(input).size
+  await ensureCodecs()
+  const io = makeIO()
+  let doc: Document
+  try { doc = await io.read(input) } catch (e) { rep.reason = `unreadable: ${message(e)}`; return done() }
+  try {
+    Object.assign(rep, await unwrapDocument(doc, opts))
+  } catch (e) {
+    rep.status = "failed"
+    rep.reason = message(e)
+    return done()
+  }
+  if (rep.status !== "unwrapped") return done()
+  const output = opts.output ?? input
+  try {
+    const bytes = await io.writeBinary(doc)
+    writeAtomic(output, bytes)
+    rep.output = output
+    rep.bytesAfter = bytes.byteLength
+  } catch (e) {
+    rep.status = "failed"
+    rep.reason = `not written: ${message(e)}`
+  }
+  return done()
+}
+
+/** Where `-o` sends an input: none = in place; one input and a path that is not a folder = that file; else the folder. */
+export const unwrapOutputFor = (input: string, out: string | undefined, batch: boolean): string | undefined => {
+  if (!out) return undefined
+  const norm = out.replace(/\\/g, "/")
+  const asDir = batch || norm.endsWith("/") || (existsSync(norm) && statSync(norm).isDirectory())
+  return asDir ? join(norm, basename(input)).replace(/\\/g, "/") : out
+}
+
+/** Unwrap several GLB files one after the other (xatlas is single-threaded wasm; memory stays one file's). `out` as `-o`;
+ *  `onFile` hears each report as it lands. */
+export async function unwrapGlbFiles(files: string[], opts: UnwrapFileOptions & { out?: string, onFile?: (r: UnwrapFileReport) => void } = {}): Promise<UnwrapFileReport[]> {
+  const { out, onFile, ...rest } = opts
+  const reports: UnwrapFileReport[] = []
+  for (const input of files) {
+    const r = await unwrapGlbFile(input, { ...rest, output: unwrapOutputFor(input, out, files.length > 1) ?? rest.output })
+    reports.push(r)
+    onFile?.(r)
+  }
+  return reports
+}
+
+const kb = (n: number): string => `${Math.round(n / 1024)} KB`
+
+/** One line per file: what the unwrap made of it. */
+export const describeUnwrap = (r: UnwrapFileReport): string => {
+  if (r.status !== "unwrapped" || !r.result) return `${r.status === "failed" ? "failed" : "skipped"}: ${r.reason ?? "?"}`
+  const res = r.result
+  const lod = res.lodPrimitives ? `; ${res.lodPrimitives} LOD primitive(s) by projection` : ""
+  const groups = res.groups.length ? `, ${res.groups.length} groups${res.splitNodes ? ` (${res.splitNodes} node(s) cut)` : ""}` : ""
+  return `${res.charts} charts over ${res.primitives} primitive(s)${groups}, vertices ${res.verticesBefore} → ${res.verticesAfter} (+${res.verticesAfter - res.verticesBefore} on seams)${lod}${r.replaced ? `; ${r.replaced} TEXCOORD_1 set(s) replaced` : ""}, ${(r.ms / 1000).toFixed(1)} s`
+}
+
+/** The detail lines under a file's line: groups, what was left as it was, warnings, where it went. */
+export const detailUnwrap = (r: UnwrapFileReport): string[] => {
+  const lines: string[] = []
+  r.result?.groups.forEach((g, k) => lines.push(`group ${k}: ${g.primitives} primitive(s), ${g.area.toFixed(0)} m², ${g.charts} charts${g.texelScale > 1 ? `, texel ×${g.texelScale}` : ""}`))
+  if (r.kept.length) lines.push(`left as is: ${r.kept.slice(0, 6).map((s) => `${s.name} (${s.reason})`).join(", ")}${r.kept.length > 6 ? ` … ${r.kept.length - 6} more` : ""}`)
+  for (const w of r.warnings) lines.push(`⚠ ${w}`)
+  if (r.output) lines.push(`${r.output === r.input ? "written in place" : `written to ${r.output}`} (${kb(r.bytesBefore)} → ${kb(r.bytesAfter)})`)
+  return lines
+}