@forgeax/engine-image 0.1.2

package/dist/decode-image-from-file.mjs

@@ -0,0 +1,590 @@
+import { stat, readFile } from 'fs/promises';
+import { extname, dirname, join } from 'path';
+import { validateMeta } from '@forgeax/engine-pack';
+import { err, ok, IMAGE_ERROR_HINTS } from '@forgeax/engine-types';
+import * as jpeg from 'jpeg-js';
+import * as UPNG from 'upng-js';
+
+// src/decode-image-from-file.ts
+var IMAGE_ERROR_EXPECTED = {
+  "image-decode-failed": "PNG / JPG byte stream decodes successfully",
+  "image-format-unsupported": "mime is one of ['image/png', 'image/jpeg', 'image/x-tga']; uploadTexture format <-> colorSpace family agrees",
+  "image-dimension-out-of-bounds": "width and height fall under device caps maxTextureDimension2D (or 16384 hard cap)",
+  "image-meta-missing": "<source>.meta.json sidecar (importer: 'image') exists in the same directory",
+  "image-hdr-decode-failed": "Radiance RGBE header is valid and pixel data decodes successfully",
+  // feat-20260521-sprite-atlas-animation M1 T-03 — vite-plugin-image atlas
+  // hook .expected literals (plan-strategy section 2 D-2 + AC-10 a/b/c).
+  // ImageErrorImpl construction path is unchanged: the new atlas-* errors
+  // flow through `new ImageErrorImpl({ code: 'atlas-...', ...detail })` and
+  // pick the .expected string up from this Record at construction time
+  // (charter P3 explicit failure SSOT — AI users surface .expected next to
+  // .hint after switch (err.code) without parsing the message).
+  "atlas-empty-input": "images.length >= 1",
+  "atlas-size-exceeded": "image width x height <= maxAtlasSize^2 and each image fits in the atlas footprint",
+  "atlas-region-mismatch": "sum(regions[i].w x regions[i].h) <= atlasWidth x atlasHeight"
+};
+var ImageErrorImpl = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(detail) {
+    const code = detail.code;
+    const expected = IMAGE_ERROR_EXPECTED[code];
+    const hint = IMAGE_ERROR_HINTS[code];
+    super(`[ImageError ${code}] expected: ${expected}; hint: ${hint}`);
+    this.name = "ImageError";
+    this.code = code;
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = detail;
+  }
+};
+function imageError(detail) {
+  return new ImageErrorImpl(detail);
+}
+
+// src/hdr-decoder.ts
+var LF = 10;
+function decodeHdr(bytes) {
+  let pos = 0;
+  if (bytes.length < 11) {
+    return err(hdrDecodeError("file too short for Radiance HDR header"));
+  }
+  const magic = String.fromCharCode(...bytes.subarray(0, 11));
+  if (magic !== "#?RADIANCE\n" && magic !== "#?RGBE\n") {
+    return err(
+      hdrDecodeError("missing or invalid Radiance HDR magic; expected #?RADIANCE or #?RGBE")
+    );
+  }
+  pos = 11;
+  let formatFound = false;
+  while (pos < bytes.length) {
+    const lineEnd = findByte(bytes, LF, pos);
+    if (lineEnd === -1) return err(hdrDecodeError("header truncated before empty line"));
+    const line = asciiSubstring(bytes, pos, lineEnd);
+    pos = lineEnd + 1;
+    if (line === "") break;
+    if (line.startsWith("FORMAT=")) {
+      const val = line.slice(7);
+      if (val === "32-bit_rle_rgbe") {
+        formatFound = true;
+      }
+    }
+  }
+  if (!formatFound) {
+    return err(hdrDecodeError("missing or unsupported FORMAT; expected FORMAT=32-bit_rle_rgbe"));
+  }
+  if (pos >= bytes.length) return err(hdrDecodeError("missing resolution line"));
+  const resLineEnd = findByte(bytes, LF, pos);
+  if (resLineEnd === -1) return err(hdrDecodeError("resolution line truncated"));
+  const resLine = asciiSubstring(bytes, pos, resLineEnd);
+  pos = resLineEnd + 1;
+  const resMatch = /^-Y\s+(\d+)\s+\+X\s+(\d+)\s*$/.exec(resLine);
+  if (resMatch === null) {
+    return err(
+      hdrDecodeError(`unexpected resolution line format: "${resLine}"; expected "-Y H +X W"`)
+    );
+  }
+  const height = Number(resMatch[1]);
+  const width = Number(resMatch[2]);
+  if (height === void 0 || width === void 0 || height <= 0 || width <= 0) {
+    return err(hdrDecodeError(`invalid dimensions: ${width}x${height}`));
+  }
+  const pixelCount = width * height;
+  const rgbe = new Uint8Array(pixelCount * 4);
+  const scanlineBytes = width * 4;
+  for (let y = 0; y < height; y++) {
+    if (pos + 4 > bytes.length) {
+      return err(hdrDecodeError(`truncated at scanline ${y}: expected 4-byte prefix`));
+    }
+    const p0 = bytes[pos];
+    const p1 = bytes[pos + 1];
+    const pHi = bytes[pos + 2];
+    const pLo = bytes[pos + 3];
+    if (p0 === void 0 || p1 === void 0 || pHi === void 0 || pLo === void 0) {
+      return err(hdrDecodeError(`truncated at scanline ${y}`));
+    }
+    const prefixWidth = pHi << 8 | pLo;
+    if (p0 === 2 && p1 === 2 && prefixWidth === width && width >= 8 && width <= 32767) {
+      const decoded = decodeNewRleScanline(bytes, pos + 4, width);
+      if (decoded === null) {
+        return err(hdrDecodeError(`RLE decode failed at scanline ${y}`));
+      }
+      const base = y * scanlineBytes;
+      const channels = [decoded[0], decoded[1], decoded[2], decoded[3]];
+      for (let x = 0; x < width; x++) {
+        for (let ch = 0; ch < 4; ch++) {
+          rgbe[base + x * 4 + ch] = channels[ch][x];
+        }
+      }
+      pos += 4 + decoded.totalBytes;
+    } else {
+      return err(
+        hdrDecodeError(
+          "old-RLE format is not supported; only new-RLE (32-bit_rle_rgbe) is accepted"
+        )
+      );
+    }
+  }
+  const out = new Float32Array(pixelCount * 4);
+  for (let i = 0; i < pixelCount; i++) {
+    const base = i * 4;
+    const r = rgbe[base];
+    const g = rgbe[base + 1];
+    const b = rgbe[base + 2];
+    const e = rgbe[base + 3];
+    out[base + 3] = 1;
+    if (e === 0) {
+      out[base] = 0;
+      out[base + 1] = 0;
+      out[base + 2] = 0;
+    } else {
+      const f = 2 ** (e - 136);
+      out[base] = (r + 0.5) * f;
+      out[base + 1] = (g + 0.5) * f;
+      out[base + 2] = (b + 0.5) * f;
+    }
+  }
+  return ok({ width, height, data: out });
+}
+function decodeNewRleScanline(bytes, start, width) {
+  const channels = [];
+  let cursor = start;
+  for (let ch = 0; ch < 4; ch++) {
+    const data = new Uint8Array(width);
+    let x = 0;
+    while (x < width) {
+      if (cursor >= bytes.length) return null;
+      const code = bytes[cursor];
+      cursor++;
+      if (code > 128) {
+        const count = code - 128;
+        if (cursor >= bytes.length || x + count > width) return null;
+        const val = bytes[cursor];
+        cursor++;
+        data.fill(val, x, x + count);
+        x += count;
+      } else {
+        if (code === 0) continue;
+        if (cursor + code > bytes.length || x + code > width) return null;
+        for (let k = 0; k < code; k++) {
+          data[x + k] = bytes[cursor + k];
+        }
+        cursor += code;
+        x += code;
+      }
+    }
+    channels.push(data);
+  }
+  const ch0 = channels[0];
+  const ch1 = channels[1];
+  const ch2 = channels[2];
+  const ch3 = channels[3];
+  if (ch0 === void 0 || ch1 === void 0 || ch2 === void 0 || ch3 === void 0) {
+    return null;
+  }
+  return {
+    0: ch0,
+    1: ch1,
+    2: ch2,
+    3: ch3,
+    totalBytes: cursor - start
+  };
+}
+function findByte(bytes, target, start) {
+  for (let i = start; i < bytes.length; i++) {
+    if (bytes[i] === target) return i;
+  }
+  return -1;
+}
+function asciiSubstring(bytes, start, end) {
+  let s = "";
+  for (let i = start; i < end; i++) {
+    s += String.fromCharCode(bytes[i]);
+  }
+  return s;
+}
+function hdrDecodeError(reason) {
+  return imageError({
+    code: "image-hdr-decode-failed",
+    reason
+  });
+}
+
+// src/resize-image.ts
+function downscaleRgba(bytes, width, height, maxDimension) {
+  if (width <= maxDimension && height <= maxDimension) {
+    return { bytes, width, height };
+  }
+  const scale = maxDimension / Math.max(width, height);
+  const targetWidth = Math.max(1, Math.round(width * scale));
+  const targetHeight = Math.max(1, Math.round(height * scale));
+  const output = new Uint8Array(targetWidth * targetHeight * 4);
+  const source = (x, y, channel) => bytes[(y * width + x) * 4 + channel] ?? 0;
+  for (let y = 0; y < targetHeight; y += 1) {
+    const sourceY = (y + 0.5) * height / targetHeight - 0.5;
+    const y0 = Math.max(0, Math.floor(sourceY));
+    const y1 = Math.min(height - 1, y0 + 1);
+    const yWeight = Math.max(0, Math.min(1, sourceY - y0));
+    for (let x = 0; x < targetWidth; x += 1) {
+      const sourceX = (x + 0.5) * width / targetWidth - 0.5;
+      const x0 = Math.max(0, Math.floor(sourceX));
+      const x1 = Math.min(width - 1, x0 + 1);
+      const xWeight = Math.max(0, Math.min(1, sourceX - x0));
+      const outputOffset = (y * targetWidth + x) * 4;
+      for (let channel = 0; channel < 4; channel += 1) {
+        const top = source(x0, y0, channel) * (1 - xWeight) + source(x1, y0, channel) * xWeight;
+        const bottom = source(x0, y1, channel) * (1 - xWeight) + source(x1, y1, channel) * xWeight;
+        output[outputOffset + channel] = Math.round(top * (1 - yWeight) + bottom * yWeight);
+      }
+    }
+  }
+  return { bytes: output, width: targetWidth, height: targetHeight };
+}
+
+// src/parse-image.ts
+var DEFAULT_MAX_DIMENSION = 16384;
+var SUPPORTED_MIMES = ["image/png", "image/jpeg", "image/x-tga"];
+function parseImage(bytes, mime, opts = {}) {
+  if (!SUPPORTED_MIMES.includes(mime)) {
+    return err(
+      imageError({
+        code: "image-format-unsupported",
+        actualMime: mime,
+        ...opts.path !== void 0 ? { path: opts.path } : {}
+      })
+    );
+  }
+  let width = 0;
+  let height = 0;
+  let rgba;
+  try {
+    if (mime === "image/png") {
+      const upngMod = UPNG.default ?? UPNG;
+      const decoded = upngMod.decode(bytes);
+      width = decoded.width;
+      height = decoded.height;
+      const frames = upngMod.toRGBA8(decoded);
+      const first = frames[0];
+      if (first === void 0) {
+        return err(
+          imageError({
+            code: "image-decode-failed",
+            reason: "UPNG.toRGBA8 returned no frames",
+            ...opts.path !== void 0 ? { path: opts.path } : {}
+          })
+        );
+      }
+      rgba = new Uint8Array(first);
+    } else if (mime === "image/jpeg") {
+      const jpegMod = jpeg.default ?? jpeg;
+      const decoded = jpegMod.decode(bytes, { useTArray: true, formatAsRGBA: true });
+      width = decoded.width;
+      height = decoded.height;
+      rgba = decoded.data;
+    } else {
+      const decoded = decodeTga(bytes);
+      width = decoded.width;
+      height = decoded.height;
+      rgba = decoded.bytes;
+    }
+  } catch (e) {
+    return err(
+      imageError({
+        code: "image-decode-failed",
+        reason: e instanceof Error ? e.message : String(e),
+        ...opts.path !== void 0 ? { path: opts.path } : {}
+      })
+    );
+  }
+  const downscaleLimit = opts.downscaleMaxDimension;
+  if (downscaleLimit !== void 0 && Number.isInteger(downscaleLimit) && downscaleLimit > 0) {
+    const downscaled = downscaleRgba(rgba, width, height, downscaleLimit);
+    rgba = downscaled.bytes;
+    width = downscaled.width;
+    height = downscaled.height;
+  }
+  const limit = opts.maxDimension ?? DEFAULT_MAX_DIMENSION;
+  if (width > limit || height > limit) {
+    return err(
+      imageError({
+        code: "image-dimension-out-of-bounds",
+        requested: { width, height },
+        limit
+      })
+    );
+  }
+  return ok({
+    bytes: rgba,
+    width,
+    height,
+    mime,
+    colorSpace: opts.colorSpace ?? "srgb",
+    mipmap: opts.mipmap ?? true
+  });
+}
+function decodeTga(bytes) {
+  if (bytes.length < 18) throw new Error("TGA header is truncated");
+  const colorMapType = bytes[1];
+  const imageType = bytes[2];
+  const idLength = bytes[0] ?? 0;
+  const width = (bytes[12] ?? 0) | (bytes[13] ?? 0) << 8;
+  const height = (bytes[14] ?? 0) | (bytes[15] ?? 0) << 8;
+  const pixelDepth = bytes[16] ?? 0;
+  const descriptor = bytes[17] ?? 0;
+  if (colorMapType !== 0) throw new Error("color-mapped TGA is unsupported");
+  if (width < 1 || height < 1) throw new Error("TGA dimensions must be positive");
+  const isTrueColor = imageType === 2 || imageType === 10;
+  const isGray = imageType === 3 || imageType === 11;
+  if (!isTrueColor && !isGray) throw new Error(`TGA image type ${imageType} is unsupported`);
+  if (isTrueColor && pixelDepth !== 24 && pixelDepth !== 32) {
+    throw new Error(`TGA true-color depth ${pixelDepth} is unsupported`);
+  }
+  if (isGray && pixelDepth !== 8)
+    throw new Error(`TGA grayscale depth ${pixelDepth} is unsupported`);
+  const bytesPerPixel = pixelDepth / 8;
+  let offset = 18 + idLength;
+  const pixelCount = width * height;
+  const out = new Uint8Array(pixelCount * 4);
+  const topOrigin = (descriptor & 32) !== 0;
+  const rightOrigin = (descriptor & 16) !== 0;
+  let filePixel = 0;
+  const writePixel = (pixel) => {
+    if (filePixel >= pixelCount) throw new Error("TGA pixel data has too many pixels");
+    const fileX = filePixel % width;
+    const fileY = Math.floor(filePixel / width);
+    const x = rightOrigin ? width - 1 - fileX : fileX;
+    const y = topOrigin ? fileY : height - 1 - fileY;
+    const destination = (y * width + x) * 4;
+    if (isGray) {
+      const value = pixel[0] ?? 0;
+      out[destination] = value;
+      out[destination + 1] = value;
+      out[destination + 2] = value;
+      out[destination + 3] = 255;
+    } else {
+      out[destination] = pixel[2] ?? 0;
+      out[destination + 1] = pixel[1] ?? 0;
+      out[destination + 2] = pixel[0] ?? 0;
+      out[destination + 3] = bytesPerPixel === 4 ? pixel[3] ?? 255 : 255;
+    }
+    filePixel += 1;
+  };
+  const readPixel = () => {
+    if (offset + bytesPerPixel > bytes.length) throw new Error("TGA pixel data is truncated");
+    const pixel = bytes.slice(offset, offset + bytesPerPixel);
+    offset += bytesPerPixel;
+    return pixel;
+  };
+  if (imageType === 2 || imageType === 3) {
+    while (filePixel < pixelCount) writePixel(readPixel());
+  } else {
+    while (filePixel < pixelCount) {
+      if (offset >= bytes.length) throw new Error("TGA RLE packet header is truncated");
+      const packet = bytes[offset++] ?? 0;
+      const count = (packet & 127) + 1;
+      if (filePixel + count > pixelCount) throw new Error("TGA RLE packet exceeds image bounds");
+      if ((packet & 128) !== 0) {
+        const pixel = readPixel();
+        for (let i = 0; i < count; i++) writePixel(pixel);
+      } else {
+        for (let i = 0; i < count; i++) writePixel(readPixel());
+      }
+    }
+  }
+  if (filePixel !== pixelCount) throw new Error("TGA pixel count mismatch");
+  return { width, height, bytes: out };
+}
+
+// src/decode-image-from-file.ts
+var EXT_TO_MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".tga": "image/x-tga",
+  ".hdr": "image/vnd.radiance"
+};
+function deriveSidecarPath(sourcePath) {
+  const dir = dirname(sourcePath);
+  const base = sourcePath.slice(dir.length + 1);
+  return join(dir, `${base}.meta.json`);
+}
+function sidecarSchemaFailureReason() {
+  const firstError = validateMeta.errors?.[0];
+  if (firstError === void 0) return "sidecar schema validation failed";
+  const location = firstError.instancePath === "" ? "/" : firstError.instancePath;
+  return `sidecar schema validation failed: ${firstError.keyword} at ${location}`.slice(0, 256);
+}
+function imageSidecarFailureReason(sidecar, mime) {
+  const subAsset = sidecar.subAssets[0];
+  const settings = sidecar.importSettings;
+  const expectedKind = mime === "image/vnd.radiance" ? "equirect" : "texture";
+  if (sidecar.importer !== "image") return "image sidecar importer must be image";
+  if (sidecar.subAssets.length !== 1 || subAsset === void 0) {
+    return "image sidecar must declare one sub-asset";
+  }
+  if (subAsset.kind !== expectedKind || subAsset.sourceIndex !== 0) {
+    return `image sidecar sub-asset must be ${expectedKind} at sourceIndex 0`;
+  }
+  if (settings.colorSpace !== void 0 && !["srgb", "linear"].includes(settings.colorSpace)) {
+    return "image sidecar colorSpace must be srgb or linear";
+  }
+  if (settings.mipmap !== void 0 && !["auto", "none"].includes(settings.mipmap)) {
+    return "image sidecar mipmap must be auto or none";
+  }
+  if (settings.addressMode !== void 0 && !["repeat", "clamp-to-edge", "mirror-repeat"].includes(settings.addressMode)) {
+    return "image sidecar addressMode is unsupported";
+  }
+  if (settings.filterMode !== void 0 && !["nearest", "linear"].includes(settings.filterMode)) {
+    return "image sidecar filterMode is unsupported";
+  }
+  return void 0;
+}
+async function decodeImageFromFile(sourcePath) {
+  const ext = extname(sourcePath).toLowerCase();
+  const mime = EXT_TO_MIME[ext];
+  if (mime === void 0) {
+    return err(
+      imageError({
+        code: "image-format-unsupported",
+        actualMime: `extension '${ext || "<none>"}'`,
+        path: sourcePath
+      })
+    );
+  }
+  const sidecarPath = deriveSidecarPath(sourcePath);
+  try {
+    await stat(sourcePath);
+  } catch (e) {
+    return err(
+      imageError({
+        code: "image-decode-failed",
+        reason: `failed to read source: ${e instanceof Error ? e.message : String(e)}`,
+        path: sourcePath
+      })
+    );
+  }
+  try {
+    await stat(sidecarPath);
+  } catch {
+    return err(
+      imageError({
+        code: "image-meta-missing",
+        sourcePath,
+        expectedSidecarPath: sidecarPath
+      })
+    );
+  }
+  let sidecarText;
+  try {
+    sidecarText = (await readFile(sidecarPath)).toString("utf8");
+  } catch (e) {
+    return err(
+      imageError({
+        code: "image-decode-failed",
+        reason: `failed to read sidecar: ${e instanceof Error ? e.message : String(e)}`,
+        path: sidecarPath
+      })
+    );
+  }
+  let parsedSidecar;
+  try {
+    parsedSidecar = JSON.parse(sidecarText);
+  } catch (e) {
+    return err(
+      imageError({
+        code: "image-decode-failed",
+        reason: `sidecar JSON parse failed: ${e instanceof Error ? e.message : String(e)}`,
+        path: sidecarPath
+      })
+    );
+  }
+  if (!validateMeta(parsedSidecar)) {
+    return err(
+      imageError({
+        code: "image-decode-failed",
+        reason: sidecarSchemaFailureReason(),
+        path: sidecarPath
+      })
+    );
+  }
+  const sidecar = parsedSidecar;
+  const imageSidecarFailure = imageSidecarFailureReason(sidecar, mime);
+  if (imageSidecarFailure !== void 0) {
+    return err(
+      imageError({
+        code: "image-decode-failed",
+        reason: imageSidecarFailure,
+        path: sidecarPath
+      })
+    );
+  }
+  const settings = sidecar.importSettings ?? {};
+  const colorSpace = settings.colorSpace ?? "srgb";
+  const mipmap = settings.mipmap ?? "auto";
+  const addressMode = settings.addressMode ?? "repeat";
+  const filterMode = settings.filterMode ?? "linear";
+  const guid = sidecar.subAssets[0]?.guid ?? "";
+  const meta = {
+    guid,
+    colorSpace,
+    mipmap,
+    addressMode,
+    filterMode
+  };
+  let bytes;
+  try {
+    const buf = await readFile(sourcePath);
+    bytes = new Uint8Array(buf);
+  } catch (e) {
+    return err(
+      imageError({
+        code: "image-decode-failed",
+        reason: `failed to read source: ${e instanceof Error ? e.message : String(e)}`,
+        path: sourcePath
+      })
+    );
+  }
+  if (mime === "image/vnd.radiance") {
+    if (colorSpace !== "linear") {
+      return err(
+        imageError({
+          code: "image-format-unsupported",
+          actualMime: `colorSpace conflict: HDR requires linear, got ${colorSpace}`,
+          path: sourcePath
+        })
+      );
+    }
+    const hdrRes = decodeHdr(bytes);
+    if (!hdrRes.ok) return err(hdrRes.error);
+    const rgba8 = new Uint8Array(hdrRes.value.width * hdrRes.value.height * 4);
+    for (let i = 0; i < hdrRes.value.data.length; i++) {
+      const v = hdrRes.value.data[i];
+      const clamped = v !== void 0 ? Math.max(0, Math.min(1, v)) : 0;
+      rgba8[i] = Math.round(clamped * 255);
+    }
+    const decoded = {
+      bytes: rgba8,
+      width: hdrRes.value.width,
+      height: hdrRes.value.height,
+      mime: "image/jpeg",
+      colorSpace: "linear",
+      mipmap: false
+    };
+    return ok({ decoded, meta });
+  }
+  const r = parseImage(bytes, mime, {
+    colorSpace,
+    mipmap: mipmap === "auto",
+    path: sourcePath
+  });
+  if (!r.ok) {
+    return err(r.error);
+  }
+  return ok({ decoded: r.value, meta });
+}
+
+export { decodeImageFromFile };
+//# sourceMappingURL=decode-image-from-file.mjs.map
+//# sourceMappingURL=decode-image-from-file.mjs.map