Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

5.6 KB
Raw Blame
// Raster image formats the image engine can hand to FirePDF for OCR: the
// formats FirePDF opens as a one-page image document (PNG, JPEG, JPEG 2000,
// TIFF, GIF, BMP), plus WebP and AVIF, which FirePDF transcodes to PNG before
// opening them. SVG and HEIC are deliberately absent: FirePDF cannot open
// them, so they keep failing fast as unsupported files instead of burning a
// round trip.

export const IMAGE_CONTENT_TYPE_TO_EXTENSION: ReadonlyMap<string, string> =
  new Map<string, string>([
    ["image/png", ".png"],
    ["image/jpeg", ".jpg"],
    // Non-standard but common in the wild.
    ["image/jpg", ".jpg"],
    ["image/pjpeg", ".jpg"],
    ["image/tiff", ".tif"],
    ["image/x-tiff", ".tif"],
    ["image/gif", ".gif"],
    ["image/bmp", ".bmp"],
    ["image/x-ms-bmp", ".bmp"],
    // JPEG 2000: the JP2 container digitized book scans and IIIF tile sources
    // are served in, and its extended JPX sibling. Raw codestreams (.j2k,
    // .j2c) share the type: FirePDF opens them the same way.
    ["image/jp2", ".jp2"],
    ["image/jpx", ".jp2"],
    // Raw codestreams have no registered type; these are the labels servers
    // use for them.
    ["image/j2k", ".jp2"],
    ["image/j2c", ".jp2"],
    ["image/x-j2c", ".jp2"],
    // WebP and AVIF: what CDNs serve to a browser that advertises them in
    // Accept, whatever the URL's extension says. FirePDF transcodes both.
    ["image/webp", ".webp"],
    ["image/avif", ".avif"],
  ]);

export const IMAGE_EXTENSION_ALIASES: ReadonlyMap<string, string> = new Map<
  string,
  string
>([
  [".jpeg", ".jpg"],
  [".tiff", ".tif"],
  [".jpx", ".jp2"],
  [".jpf", ".jp2"],
  [".j2k", ".jp2"],
  [".j2c", ".jp2"],
]);

export const IMAGE_EXTENSIONS = new Set([
  ...IMAGE_CONTENT_TYPE_TO_EXTENSION.values(),
  ...IMAGE_EXTENSION_ALIASES.keys(),
]);

export function imageExtensionFromContentType(
  contentType: string | null | undefined,
): string | null {
  if (!contentType) return null;
  const mediaType = contentType.split(";")[0].trim().toLowerCase();
  return IMAGE_CONTENT_TYPE_TO_EXTENSION.get(mediaType) ?? null;
}

export function imageContentTypeFromExtension(
  extension: string,
): string | null {
  const lower = extension.toLowerCase();
  const ext = IMAGE_EXTENSION_ALIASES.get(lower) ?? lower;
  for (const [contentType, mapped] of IMAGE_CONTENT_TYPE_TO_EXTENSION) {
    if (mapped === ext) return contentType;
  }
  return null;
}

// Only matches at the end of the path: image URLs do not carry the
// mid-path `file.xlsx/hash` shape that document URLs sometimes do.
export function imageExtensionFromUrlPath(urlPath: string): string | null {
  const lowerPath = urlPath.toLowerCase();
  for (const ext of IMAGE_EXTENSIONS) {
    if (lowerPath.endsWith(ext)) return ext;
  }
  return null;
}

// Magic-byte signatures for the supported formats. Servers mislabel freely
// (`image/png;charset=UTF-8`, HTML error pages served as `image/jpeg`), so
// the bytes are the source of truth for whether OCR can open the file. A
// `null` position matches any byte: container formats carry a length field
// ahead of their tag.
const MAGIC_SIGNATURES: Array<{
  contentType: string;
  bytes: Array<number | null>;
}> = [
  {
    contentType: "image/png",
    bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
  },
  { contentType: "image/jpeg", bytes: [0xff, 0xd8, 0xff] },
  { contentType: "image/gif", bytes: [0x47, 0x49, 0x46, 0x38] },
  { contentType: "image/tiff", bytes: [0x49, 0x49, 0x2a, 0x00] },
  { contentType: "image/tiff", bytes: [0x4d, 0x4d, 0x00, 0x2a] },
  { contentType: "image/bmp", bytes: [0x42, 0x4d] },
  // JPEG 2000: the JP2/JPX container's 12-byte signature box, and a raw
  // codestream (SOC then SIZ marker). FirePDF opens both through the same
  // loader, so both report the container type.
  {
    contentType: "image/jp2",
    bytes: [
      0x00, 0x00, 0x00, 0x0c, 0x6a, 0x50, 0x20, 0x20, 0x0d, 0x0a, 0x87, 0x0a,
    ],
  },
  { contentType: "image/jp2", bytes: [0xff, 0x4f, 0xff, 0x51] },
  // WebP: RIFF header, 4-byte chunk size, then the WEBP form type.
  {
    contentType: "image/webp",
    bytes: [
      0x52,
      0x49,
      0x46,
      0x46,
      null,
      null,
      null,
      null,
      0x57,
      0x45,
      0x42,
      0x50,
    ],
  },
  // AVIF: an ISO media file whose first box is `ftyp` with the `avif` brand
  // (still image) or `avis` (image sequence; the first frame is OCR'd).
  {
    contentType: "image/avif",
    bytes: [
      null,
      null,
      null,
      null,
      0x66,
      0x74,
      0x79,
      0x70,
      0x61,
      0x76,
      0x69,
      0x66,
    ],
  },
  {
    contentType: "image/avif",
    bytes: [
      null,
      null,
      null,
      null,
      0x66,
      0x74,
      0x79,
      0x70,
      0x61,
      0x76,
      0x69,
      0x73,
    ],
  },
];

const SNIFF_WINDOW = Math.max(...MAGIC_SIGNATURES.map(s => s.bytes.length));

export function sniffImageContentType(bytes: Uint8Array): string | null {
  for (const { contentType, bytes: magic } of MAGIC_SIGNATURES) {
    if (bytes.length < magic.length) continue;
    let matches = true;
    for (let i = 0; i < magic.length; i++) {
      if (magic[i] !== null && bytes[i] !== magic[i]) {
        matches = false;
        break;
      }
    }
    if (matches) return contentType;
  }
  return null;
}

// Sniffs a base64 payload without decoding all of it: 4 base64 characters
// encode 3 bytes, so a short prefix covers the longest signature.
export function sniffImageContentTypeFromBase64(base64: string): string | null {
  const chars = Math.ceil(SNIFF_WINDOW / 3) * 4;
  return sniffImageContentType(Buffer.from(base64.slice(0, chars), "base64"));
}