lecodes-assets 0.1.2 → 0.2.1

package/src/doctor/transcodeTextures.ts

@@ -0,0 +1,101 @@
+// Texture normalization for creator-gl (filament providers = png/jpeg/ktx2 only) + size budget.
+// Split into PLAN (analysis, no mutation) and APPLY (sharp re-encode).
+//
+// Policy (format chosen purely by alpha — PNG only when alpha is needed, else JPG, to keep size
+// small; webp→png for a 2048 image is ~5–10× larger than webp, so we avoid PNG unless required):
+//   - alpha present               -> PNG (jpeg has no alpha channel)
+//   - no alpha                    -> JPG  (normals/metalRough use quality 92 + 4:4:4 chroma)
+//   - webp                        -> re-encode per the rule above (filament has no webp provider)
+//   - max dim > 2048              -> downscale to fit 2048 + re-encode
+//   - opaque PNG (>=1024px)       -> JPG (heavy opaque PNGs are wasteful)
+//   - ktx2                        -> left untouched (supported; sharp can't handle it)
+import sharp from 'sharp'
+import type { Root, Texture } from '@gltf-transform/core'
+
+export const DEFAULT_MAX_SIZE = 2048
+const HEAVY_PNG_MIN_DIM = 1024
+
+export interface TexturePlan {
+  tex: Texture
+  name: string
+  roles: string
+  fromFmt: string
+  toFmt: 'jpeg' | 'png' | null // null = leave unchanged
+  resize: boolean
+  width: number
+  height: number
+  hasAlpha: boolean
+  isNormal: boolean
+  isData: boolean
+  category: 'lossless' | 'lossy' | null
+  reason: string
+  beforeBytes: number
+  afterBytes?: number
+}
+
+export function getTextureRoles(tex: Texture, root: Root) {
+  const set = new Set<string>()
+  for (const m of root.listMaterials()) {
+    if (m.getBaseColorTexture() === tex) set.add('base')
+    if (m.getEmissiveTexture() === tex) set.add('emissive')
+    if (m.getNormalTexture() === tex) set.add('normal')
+    if (m.getMetallicRoughnessTexture() === tex) set.add('metalRough')
+    if (m.getOcclusionTexture() === tex) set.add('occlusion')
+  }
+  return { roles: [...set].join('+') || 'unused', isNormal: set.has('normal'), isData: set.has('metalRough') || set.has('occlusion') }
+}
+
+export async function planTexture(tex: Texture, root: Root, maxSize = DEFAULT_MAX_SIZE, forceFmt?: 'jpeg' | 'png'): Promise<TexturePlan | null> {
+  const img = tex.getImage()
+  const mime = tex.getMimeType() || ''
+  const fromFmt = mime.replace('image/', '') || '?'
+  if (!img) return null
+  if (fromFmt.includes('ktx')) return null
+
+  const { roles, isNormal, isData } = getTextureRoles(tex, root)
+  let width = 0, height = 0, hasAlpha = false
+  try {
+    const buf = Buffer.from(img)
+    const meta = await sharp(buf).metadata()
+    width = meta.width || 0; height = meta.height || 0
+    hasAlpha = !(await sharp(buf).stats()).isOpaque
+  } catch {
+    return null // undecodable by sharp — leave it
+  }
+
+  const resize = Math.max(width, height) > maxSize
+  let desired: 'jpeg' | 'png' = forceFmt ?? (hasAlpha ? 'png' : 'jpeg') // PNG only when alpha is needed
+  if (desired === 'jpeg' && hasAlpha) desired = 'png' // never drop a real alpha channel
+
+  let act = false, reason = 'ok'
+  if (forceFmt) {
+    if ((fromFmt as string) !== desired || resize || (fromFmt as string) === 'webp') { act = true; reason = `${fromFmt} → ${desired}${resize ? ` (≤${maxSize}px)` : ''}` }
+  }
+  else if (fromFmt === 'webp') { act = true; reason = `webp → ${desired}` }
+  else if (resize) { act = true; reason = `${width}×${height} → ≤${maxSize}px, ${desired}` }
+  else if (fromFmt === 'png' && desired === 'jpeg' && Math.max(width, height) >= HEAVY_PNG_MIN_DIM) { act = true; reason = `heavy opaque png → jpeg` }
+
+  const base = { tex, name: tex.getName() || '?', roles, fromFmt, resize, width, height, hasAlpha, isNormal, isData, beforeBytes: img.length }
+  if (!act) return { ...base, toFmt: null, category: null, reason }
+
+  // lossless only when staying/becoming PNG without a resize (no further pixel loss)
+  const category: 'lossless' | 'lossy' = desired === 'png' && !resize ? 'lossless' : 'lossy'
+  return { ...base, toFmt: desired, category, reason }
+}
+
+export async function applyTexturePlan(plan: TexturePlan, maxSize = DEFAULT_MAX_SIZE): Promise<void> {
+  if (!plan.toFmt) return
+  let pipe = sharp(Buffer.from(plan.tex.getImage()!))
+  if (plan.resize) pipe = pipe.resize({ width: maxSize, height: maxSize, fit: 'inside', withoutEnlargement: true })
+  if (plan.toFmt === 'jpeg') {
+    // normals / metal-rough / occlusion carry data, not colour: higher quality, no chroma subsampling
+    const dataLike = plan.isNormal || plan.isData
+    const out = await pipe.jpeg({ quality: dataLike ? 92 : 85, mozjpeg: true, chromaSubsampling: dataLike ? '4:4:4' : '4:2:0' }).toBuffer()
+    plan.tex.setImage(new Uint8Array(out)).setMimeType('image/jpeg')
+    plan.afterBytes = out.length
+  } else {
+    const out = await pipe.png({ compressionLevel: 9 }).toBuffer()
+    plan.tex.setImage(new Uint8Array(out)).setMimeType('image/png')
+    plan.afterBytes = out.length
+  }
+}

package/src/doctor/validateGlb.ts

@@ -0,0 +1,264 @@
+// MIRROR of packages/viewer/src/viewer/validateGlb.ts (kept in sync by hand — the viewer copy is the source of truth;
+// duplicated so lecodes-assets stays publishable without a cross-package import).
+// Pre-flight GLB validator — runs in the browser and in Bun (no Node/DOM APIs, no deps).
+//
+// Why this exists: the creator-gl wasm is shipped WITHOUT emscripten assertions, so when a
+// model violates a filament hard-limit the C++ code calls abort() with no usable message
+// (e.g. "bone count > 256", or a missing texture-decoder for webp). Validate the bytes here,
+// BEFORE handing them to module._loadGlb(), and reject with a clear, actionable error instead.
+//
+// Mirrors the exact constraints filament/gltfio enforce at load time:
+//   - filament CONFIG_MAX_BONE_COUNT        = 256  (skin.joints per renderable)
+//   - filament CONFIG_MAX_MORPH_TARGET_COUNT = 256  (morph targets per primitive)
+//   - gltfio texture providers registered in glb.cpp: image/png, image/jpeg, image/ktx2 only
+//     (webp / EXT_texture_webp has no provider -> load fails).
+
+// ---- filament limits (keep in sync with EngineEnums.h) ----------------------------------------
+export const MAX_BONE_COUNT = 256
+export const MAX_MORPH_TARGET_COUNT = 256
+
+// Texture formats with a provider registered in creator-gl (see packages/creator-gl/src/glb.cpp).
+export const SUPPORTED_IMAGE_FORMATS = ['png', 'jpeg', 'ktx2'] as const
+export type ImageFormat = (typeof SUPPORTED_IMAGE_FORMATS)[number] | 'webp' | 'unknown'
+
+export interface GlbIssue {
+  level: 'error' | 'warning'
+  code: 'CONTAINER' | 'BONE_COUNT' | 'MORPH_COUNT' | 'TEXTURE_FORMAT'
+  message: string
+  detail?: Record<string, unknown>
+}
+
+export interface GlbValidationResult {
+  ok: boolean
+  errors: GlbIssue[]
+  warnings: GlbIssue[]
+  summary: {
+    skins: number
+    maxJointCount: number
+    images: number
+    formats: Record<string, number>
+  }
+}
+
+const GLB_MAGIC = 0x46546c67 // "glTF"
+const CHUNK_JSON = 0x4e4f534a // "JSON"
+const CHUNK_BIN = 0x004e4942 // "BIN\0"
+
+class GlbParseError extends Error {}
+
+export interface ParsedGlb {
+  json: any
+  bin: Uint8Array | null
+}
+
+function toBytes(data: ArrayBuffer | Uint8Array): Uint8Array {
+  return data instanceof Uint8Array ? data : new Uint8Array(data)
+}
+
+/** Container parse only (JSON chunk + BIN chunk); also accepts raw .gltf JSON bytes.
+ *  Exported for reuse (backend asset-metadata extraction) — throws GlbParseError on bad input. */
+export function parseGlb(bytes: Uint8Array): ParsedGlb {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+
+  // Accept a raw .gltf (JSON) too — useful for editor/CI paths. No BIN chunk in that case,
+  // so byte-sniffing of embedded images is skipped (uri/mimeType still validated).
+  if (bytes.byteLength < 12 || dv.getUint32(0, true) !== GLB_MAGIC) {
+    try {
+      return { json: JSON.parse(new TextDecoder().decode(bytes)), bin: null }
+    } catch {
+      throw new GlbParseError('Not a GLB (bad magic) and not parseable as glTF JSON')
+    }
+  }
+
+  const version = dv.getUint32(4, true)
+  if (version !== 2) throw new GlbParseError(`Unsupported GLB container version ${version} (expected 2)`)
+
+  let offset = 12
+  let json: any = null
+  let bin: Uint8Array | null = null
+  while (offset + 8 <= bytes.byteLength) {
+    const chunkLen = dv.getUint32(offset, true)
+    const chunkType = dv.getUint32(offset + 4, true)
+    const start = offset + 8
+    const end = start + chunkLen
+    if (end > bytes.byteLength) throw new GlbParseError(`Chunk at ${offset} overruns the file`)
+    if (chunkType === CHUNK_JSON) {
+      json = JSON.parse(new TextDecoder().decode(bytes.subarray(start, end)))
+    } else if (chunkType === CHUNK_BIN) {
+      bin = bytes.subarray(start, end)
+    }
+    offset = end // chunkLength already includes the 4-byte alignment padding (glTF spec)
+  }
+
+  if (!json) throw new GlbParseError('GLB has no JSON chunk')
+  return { json, bin }
+}
+
+// ---- image format detection -------------------------------------------------------------------
+
+function mimeToFormat(mime: string): ImageFormat {
+  switch (mime) {
+    case 'image/png': return 'png'
+    case 'image/jpeg': return 'jpeg'
+    case 'image/ktx2': return 'ktx2'
+    case 'image/webp': return 'webp'
+    default: return 'unknown'
+  }
+}
+
+function extToFormat(ext: string): ImageFormat {
+  switch (ext) {
+    case 'png': return 'png'
+    case 'jpg':
+    case 'jpeg': return 'jpeg'
+    case 'ktx2': return 'ktx2'
+    case 'webp': return 'webp'
+    default: return 'unknown'
+  }
+}
+
+function sniffMagic(b: Uint8Array): ImageFormat {
+  if (b.length >= 4 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) return 'png'
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return 'jpeg'
+  // RIFF....WEBP
+  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 'webp'
+  // KTX2: 0xAB 'KTX 20' 0xBB 0x0D 0x0A 0x1A 0x0A
+  if (b.length >= 8 && b[0] === 0xab && b[1] === 0x4b && b[2] === 0x54 && b[3] === 0x58 &&
+      b[4] === 0x20 && b[5] === 0x32 && b[6] === 0x30 && b[7] === 0xbb) return 'ktx2'
+  return 'unknown'
+}
+
+function detectFormat(image: any, json: any, bin: Uint8Array | null): { format: ImageFormat; via: string } {
+  if (typeof image?.uri === 'string') {
+    const uri: string = image.uri
+    if (uri.startsWith('data:')) {
+      const m = /^data:([^;,]+)[;,]/.exec(uri)
+      const mime = (m?.[1] ?? '').toLowerCase()
+      return { format: mimeToFormat(mime), via: `data-uri "${mime || '?'}"` }
+    }
+    const ext = (uri.split('?')[0].split('#')[0].split('.').pop() ?? '').toLowerCase()
+    return { format: extToFormat(ext), via: `uri ".${ext}"` }
+  }
+  if (typeof image?.mimeType === 'string') {
+    const mime = image.mimeType.toLowerCase()
+    return { format: mimeToFormat(mime), via: `mimeType "${image.mimeType}"` }
+  }
+  if (typeof image?.bufferView === 'number' && bin) {
+    const bv = json.bufferViews?.[image.bufferView]
+    // embedded images live in buffer 0 (the BIN chunk) for GLB
+    if (bv && (bv.buffer ?? 0) === 0) {
+      const start = bv.byteOffset ?? 0
+      return { format: sniffMagic(bin.subarray(start, start + 16)), via: 'magic-bytes' }
+    }
+  }
+  return { format: 'unknown', via: 'undetermined' }
+}
+
+// Image indices actually referenced by a texture (standard source + ktx2/webp extension sources).
+function collectUsedImages(json: any): Set<number> {
+  const used = new Set<number>()
+  for (const t of json.textures ?? []) {
+    if (typeof t.source === 'number') used.add(t.source)
+    const basisu = t.extensions?.KHR_texture_basisu
+    if (typeof basisu?.source === 'number') used.add(basisu.source)
+    const webp = t.extensions?.EXT_texture_webp
+    if (typeof webp?.source === 'number') used.add(webp.source)
+  }
+  return used
+}
+
+// ---- main entry -------------------------------------------------------------------------------
+
+export function validateGlb(data: ArrayBuffer | Uint8Array): GlbValidationResult {
+  const errors: GlbIssue[] = []
+  const warnings: GlbIssue[] = []
+  const formats: Record<string, number> = {}
+
+  let parsed: ParsedGlb
+  try {
+    parsed = parseGlb(toBytes(data))
+  } catch (e) {
+    return {
+      ok: false,
+      errors: [{ level: 'error', code: 'CONTAINER', message: (e as Error).message }],
+      warnings: [],
+      summary: { skins: 0, maxJointCount: 0, images: 0, formats: {} },
+    }
+  }
+  const { json, bin } = parsed
+
+  // --- skins: joints per skin == filament mSkinningBoneCount, capped at CONFIG_MAX_BONE_COUNT ---
+  const skins: any[] = json.skins ?? []
+  let maxJointCount = 0
+  for (let i = 0; i < skins.length; i++) {
+    const n = skins[i]?.joints?.length ?? 0
+    maxJointCount = Math.max(maxJointCount, n)
+    if (n > MAX_BONE_COUNT) {
+      errors.push({
+        level: 'error',
+        code: 'BONE_COUNT',
+        message: `skin[${i}]${skins[i].name ? ` "${skins[i].name}"` : ''} has ${n} joints, exceeds filament limit of ${MAX_BONE_COUNT}`,
+        detail: { skin: i, name: skins[i].name, joints: n, limit: MAX_BONE_COUNT },
+      })
+    }
+  }
+
+  // --- morph targets per primitive, capped at CONFIG_MAX_MORPH_TARGET_COUNT --------------------
+  for (let mi = 0; mi < (json.meshes?.length ?? 0); mi++) {
+    const mesh = json.meshes[mi]
+    for (let pi = 0; pi < (mesh.primitives?.length ?? 0); pi++) {
+      const n = mesh.primitives[pi]?.targets?.length ?? 0
+      if (n > MAX_MORPH_TARGET_COUNT) {
+        errors.push({
+          level: 'error',
+          code: 'MORPH_COUNT',
+          message: `mesh[${mi}]${mesh.name ? ` "${mesh.name}"` : ''} primitive ${pi} has ${n} morph targets, exceeds filament limit of ${MAX_MORPH_TARGET_COUNT}`,
+          detail: { mesh: mi, primitive: pi, targets: n, limit: MAX_MORPH_TARGET_COUNT },
+        })
+      }
+    }
+  }
+
+  // --- textures: every image must decode with a registered provider (png/jpeg/ktx2) -----------
+  const images: any[] = json.images ?? []
+  const used = collectUsedImages(json)
+  for (let i = 0; i < images.length; i++) {
+    const { format, via } = detectFormat(images[i], json, bin)
+    formats[format] = (formats[format] ?? 0) + 1
+    const supported = (SUPPORTED_IMAGE_FORMATS as readonly string[]).includes(format)
+    if (supported) continue
+
+    const referenced = used.has(i)
+    const issue: GlbIssue = {
+      level: referenced ? 'error' : 'warning',
+      code: 'TEXTURE_FORMAT',
+      message:
+        `image[${i}]${images[i].name ? ` "${images[i].name}"` : ''} is ${format.toUpperCase()} ` +
+        `(${via})${referenced ? '' : ' [unreferenced]'} — only ${SUPPORTED_IMAGE_FORMATS.join('/')} are supported`,
+      detail: { image: i, format, via, referenced },
+    }
+    ;(referenced ? errors : warnings).push(issue)
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    summary: { skins: skins.length, maxJointCount, images: images.length, formats },
+  }
+}
+
+// Human-readable report (string, so it works identically in browser console and Bun stdout).
+export function formatReport(result: GlbValidationResult, label = 'GLB'): string {
+  const lines: string[] = []
+  const s = result.summary
+  lines.push(`${result.ok ? '✅ VALID' : '❌ INVALID'}  ${label}`)
+  lines.push(
+    `  skins=${s.skins} (max joints=${s.maxJointCount}/${MAX_BONE_COUNT})  ` +
+    `images=${s.images} [${Object.entries(s.formats).map(([k, v]) => `${k}:${v}`).join(', ') || 'none'}]`,
+  )
+  for (const e of result.errors) lines.push(`  ✗ ${e.code}: ${e.message}`)
+  for (const w of result.warnings) lines.push(`  ⚠ ${w.code}: ${w.message}`)
+  return lines.join('\n')
+}