@arcships/light-ocr-runtime 0.1.0

package/src/exif.cjs

@@ -0,0 +1,241 @@
+'use strict';
+
+// Minimal JPEG EXIF orientation parser (D106, D-N1-5).
+// Reads the orientation tag from the JPEG APP1 segment and applies the
+// corresponding pixel transform. Zero-dependency, stb-style.
+//
+// Only orientation (tag 0x0112) is read. Other EXIF fields are skipped.
+// PNG eXIf is not handled here; PNG has no EXIF orientation in v1.
+//
+// References:
+// - JEITA CP-3451C (Exif 2.3) section 4.6.4 (APP1 structure)
+// - TIFF tag 0x0112 Orientation
+
+// Parse the EXIF orientation value from a JPEG buffer.
+// Returns 1..8 if found, or 1 (normal) if not present / not a JPEG.
+function parseExifOrientation(buffer) {
+  if (!buffer || buffer.length < 4) return 1;
+  // JPEG must start with SOI marker 0xFFD8
+  if (buffer[0] !== 0xff || buffer[1] !== 0xd8) return 1;
+
+  let offset = 2;
+  while (offset + 1 < buffer.length) {
+    // Each marker: 0xFF then marker code
+    if (buffer[offset] !== 0xff) return 1;
+    const marker = buffer[offset + 1];
+    offset += 2;
+
+    // SOI (D8), EOI (D9), RSTn (D0-D7), TEM (01): no payload
+    if (marker === 0xd8 || marker === 0xd9) return 1;
+    if (marker >= 0xd0 && marker <= 0xd7) continue;
+    if (marker === 0x01) continue;
+
+    // SOS (DA): start of scan — EXIF would be before this
+    if (marker === 0xda) return 1;
+
+    // All other markers have a 2-byte length (including the length bytes)
+    if (offset + 1 >= buffer.length) return 1;
+    const length = (buffer[offset] << 8) | buffer[offset + 1];
+    if (length < 2 || offset + length > buffer.length) return 1;
+
+    // APP1 marker is 0xFFE1
+    if (marker === 0xe1) {
+      const orientation = tryParseApp1(buffer, offset, length);
+      if (orientation) return orientation;
+    }
+
+    offset += length;
+  }
+  return 1;
+}
+
+// Try to parse APP1 as EXIF. Returns orientation 1..8 or 0 if not EXIF.
+function tryParseApp1(buffer, dataOffset, segmentLength) {
+  // APP1 data starts after the 2-byte length field
+  // EXIF header: "Exif\0\0" (6 bytes)
+  const exifHeader = dataOffset + 2;
+  if (exifHeader + 6 > dataOffset + segmentLength) return 0;
+  if (buffer[exifHeader] !== 0x45 || buffer[exifHeader + 1] !== 0x78 ||
+      buffer[exifHeader + 2] !== 0x69 || buffer[exifHeader + 3] !== 0x66 ||
+      buffer[exifHeader + 4] !== 0x00 || buffer[exifHeader + 5] !== 0x00) {
+    return 0; // not EXIF (could be XMP)
+  }
+
+  // TIFF header starts here
+  const tiffStart = exifHeader + 6;
+  if (tiffStart + 8 > dataOffset + segmentLength) return 0;
+
+  // Byte order: II (little-endian) or MM (big-endian)
+  const littleEndian = buffer[tiffStart] === 0x49 && buffer[tiffStart + 1] === 0x49;
+  const bigEndian = buffer[tiffStart] === 0x4d && buffer[tiffStart + 1] === 0x4d;
+  if (!littleEndian && !bigEndian) return 0;
+  const le = littleEndian;
+
+  // Magic number 42 (0x002A)
+  const magic = readU16(buffer, tiffStart + 2, le);
+  if (magic !== 0x002a) return 0;
+
+  // Offset to IFD0 from TIFF start
+  const ifdOffset = tiffStart + readU32(buffer, tiffStart + 4, le);
+  if (ifdOffset + 2 > dataOffset + segmentLength) return 0;
+
+  const entryCount = readU16(buffer, ifdOffset, le);
+  for (let i = 0; i < entryCount; i++) {
+    const entryOffset = ifdOffset + 2 + i * 12;
+    if (entryOffset + 12 > dataOffset + segmentLength) break;
+    const tag = readU16(buffer, entryOffset, le);
+    if (tag === 0x0112) { // Orientation
+      const type = readU16(buffer, entryOffset + 2, le);
+      const count = readU32(buffer, entryOffset + 4, le);
+      if (type === 3 && count === 1) { // SHORT
+        const value = readU16(buffer, entryOffset + 8, le);
+        if (value >= 1 && value <= 8) return value;
+      }
+      return 0;
+    }
+  }
+  return 0;
+}
+
+function readU16(buffer, offset, littleEndian) {
+  if (littleEndian) return buffer[offset] | (buffer[offset + 1] << 8);
+  return (buffer[offset] << 8) | buffer[offset + 1];
+}
+
+function readU32(buffer, offset, littleEndian) {
+  if (littleEndian) {
+    return (buffer[offset]) |
+           (buffer[offset + 1] << 8) |
+           (buffer[offset + 2] << 16) |
+           (buffer[offset + 3] << 24);
+  }
+  return (buffer[offset] << 24) |
+         (buffer[offset + 1] << 16) |
+         (buffer[offset + 2] << 8) |
+         (buffer[offset + 3]);
+}
+
+// Apply EXIF orientation to RGB pixel data.
+// input: { data: Uint8Array (RGB), width, height }
+// orientation: 1..8
+// Returns { data, width, height } in pageSpace (orientation-corrected).
+function applyOrientation(pixels, orientation) {
+  if (orientation === 1) return pixels; // normal, no transform
+
+  const { data, width: w, height: h } = pixels;
+  const channels = 3;
+
+  switch (orientation) {
+    case 2: // flip horizontal
+      return flipHorizontal(data, w, h, channels);
+    case 3: // rotate 180
+      return rotate180(data, w, h, channels);
+    case 4: // flip vertical
+      return flipVertical(data, w, h, channels);
+    case 5: // transpose (flip horizontal + rotate 270 CW)
+      return transpose(data, w, h, channels);
+    case 6: // rotate 90 CW
+      return rotate90CW(data, w, h, channels);
+    case 7: // transverse (flip horizontal + rotate 90 CW)
+      return transverse(data, w, h, channels);
+    case 8: // rotate 90 CCW (= 270 CW)
+      return rotate90CCW(data, w, h, channels);
+    default:
+      return pixels;
+  }
+}
+
+function alloc(w, h, channels) {
+  return { data: new Uint8Array(w * h * channels), width: w, height: h };
+}
+
+function flipHorizontal(data, w, h, c) {
+  const out = alloc(w, h, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      const dst = (y * w + (w - 1 - x)) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+function flipVertical(data, w, h, c) {
+  const out = alloc(w, h, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      const dst = ((h - 1 - y) * w + x) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+function rotate180(data, w, h, c) {
+  const out = alloc(w, h, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      const dst = ((h - 1 - y) * w + (w - 1 - x)) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+function rotate90CW(data, w, h, c) {
+  // new dimensions: h x w
+  const out = alloc(h, w, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      // (x, y) -> (h-1-y, x) in the new w'=h, h'=w grid
+      const dst = (x * h + (h - 1 - y)) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+function rotate90CCW(data, w, h, c) {
+  const out = alloc(h, w, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      // (x, y) -> (y, w-1-x)
+      const dst = ((w - 1 - x) * h + y) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+function transpose(data, w, h, c) {
+  // transpose: (x,y) -> (y,x)
+  const out = alloc(h, w, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      const dst = (x * h + y) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+function transverse(data, w, h, c) {
+  // transverse: (x,y) -> (h-1-y, w-1-x)
+  const out = alloc(h, w, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      const dst = ((h - 1 - y) * h + (w - 1 - x)) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+module.exports = { parseExifOrientation, applyOrientation };

package/src/facade.cjs

@@ -0,0 +1,119 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const runtime = require('./index.cjs');
+
+function createModelFacade(config) {
+  if (!config || typeof config !== 'object') {
+    throw new TypeError('model facade config must be an object');
+  }
+  const {
+    model,
+    modelPackage,
+    compatibleBundleIds,
+    appleBundleIds = compatibleBundleIds,
+    developmentBundlePath,
+    profile,
+  } = config;
+  if (typeof model !== 'string' || model === '') {
+    throw new TypeError('model facade config requires model');
+  }
+  if (typeof modelPackage !== 'string' || modelPackage === '') {
+    throw new TypeError('model facade config requires modelPackage');
+  }
+  if (!Array.isArray(compatibleBundleIds) || compatibleBundleIds.length === 0) {
+    throw new TypeError('model facade config requires compatibleBundleIds');
+  }
+  if (!profile || typeof profile !== 'object' || profile.model !== model) {
+    throw new TypeError('model facade config requires a matching profile');
+  }
+
+  function resolveBuiltInBundle(selectedModel, requireApple) {
+    if (selectedModel !== model) {
+      throw new runtime.OcrError(
+        'invalid_argument',
+        `model must be ${JSON.stringify(model)}`,
+      );
+    }
+
+    let manifestPath;
+    if (developmentBundlePath) {
+      const candidate = path.resolve(developmentBundlePath, 'manifest.json');
+      if (fs.existsSync(candidate)) manifestPath = candidate;
+    }
+    if (!manifestPath) {
+      try {
+        manifestPath = require.resolve(`${modelPackage}/bundle/manifest.json`);
+      } catch (cause) {
+        throw new runtime.OcrError(
+          'package_load_failed',
+          `Unable to locate the built-in ${model} model`,
+          `Reinstall ${modelPackage}; ${cause instanceof Error ? cause.message : String(cause)}`,
+        );
+      }
+    }
+
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch (cause) {
+      throw new runtime.OcrError(
+        'package_load_failed',
+        'Unable to read the built-in model manifest',
+        cause instanceof Error ? cause.message : String(cause),
+      );
+    }
+    const accepted = requireApple ? appleBundleIds : compatibleBundleIds;
+    if (!accepted.includes(manifest.bundleId)) {
+      throw new runtime.OcrError(
+        'package_load_failed',
+        `The installed model package is incompatible with the ${model} facade`,
+        `expected ${accepted.join(' or ')}, received ${String(manifest.bundleId)}`,
+      );
+    }
+    return path.dirname(manifestPath);
+  }
+
+  function resolveCreateOptions(options) {
+    if (options === undefined) options = {};
+    if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+      throw new runtime.OcrError('invalid_argument', 'createEngine options must be an object');
+    }
+    const hasModel = Object.prototype.hasOwnProperty.call(options, 'model');
+    const hasBundlePath = Object.prototype.hasOwnProperty.call(options, 'bundlePath');
+    if (hasModel && hasBundlePath) {
+      throw new runtime.OcrError(
+        'invalid_argument',
+        'model and bundlePath cannot be used together',
+      );
+    }
+    if (hasBundlePath) return options;
+    const selectedModel = hasModel ? options.model : model;
+    const requireApple = options.execution?.provider === 'apple';
+    const resolved = {
+      ...options,
+      bundlePath: resolveBuiltInBundle(selectedModel, requireApple),
+    };
+    delete resolved.model;
+    return resolved;
+  }
+
+  async function createEngine(options) {
+    return runtime.createEngine(resolveCreateOptions(options));
+  }
+
+  const modelProfile = Object.freeze({
+    ...profile,
+    excludedLanguages: Object.freeze([...(profile?.excludedLanguages || [])]),
+  });
+
+  return Object.freeze({
+    createEngine,
+    OcrError: runtime.OcrError,
+    modelProfile,
+  });
+}
+
+module.exports = { createModelFacade };

package/src/index.cjs

@@ -0,0 +1,177 @@
+'use strict';
+
+const { loadNative } = require('./load-native.cjs');
+
+class OcrError extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.name = 'OcrError';
+    this.code = code;
+    if (detail !== undefined && detail !== '') this.detail = detail;
+  }
+}
+
+function normalizeNativeError(error) {
+  if (error && error.name === 'OcrError') {
+    Object.setPrototypeOf(error, OcrError.prototype);
+  }
+  return error;
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+function validateSignal(signal) {
+  if (
+    signal === null ||
+    typeof signal !== 'object' ||
+    typeof signal.aborted !== 'boolean' ||
+    typeof signal.addEventListener !== 'function' ||
+    typeof signal.removeEventListener !== 'function'
+  ) {
+    throw new OcrError('invalid_argument', 'signal must be an AbortSignal');
+  }
+}
+
+function abortReason(signal) {
+  return signal.reason === undefined
+    ? new DOMException('The operation was aborted', 'AbortError')
+    : signal.reason;
+}
+
+function resolveCreateOptions(options) {
+  if (options === undefined) options = {};
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw new OcrError('invalid_argument', 'createEngine options must be an object');
+  }
+  const hasModel = Object.prototype.hasOwnProperty.call(options, 'model');
+  const hasBundlePath = Object.prototype.hasOwnProperty.call(options, 'bundlePath');
+  if (hasModel) {
+    throw new OcrError(
+      'invalid_argument',
+      '@arcships/light-ocr-runtime is model-free; pass bundlePath or use a model facade',
+    );
+  }
+  if (!hasBundlePath || typeof options.bundlePath !== 'string' || options.bundlePath === '') {
+    throw new OcrError(
+      'invalid_argument',
+      '@arcships/light-ocr-runtime requires a non-empty bundlePath',
+    );
+  }
+  return options;
+}
+
+class OcrEngineImpl {
+  #native;
+  #closePromise;
+
+  constructor(nativeEngine) {
+    this.#native = nativeEngine;
+    this.info = deepFreeze(nativeEngine.info);
+    Object.defineProperty(this, 'info', { writable: false, configurable: false });
+  }
+
+  recognize(image, options = {}) {
+    return this.#recognize('recognize', image, options);
+  }
+
+  recognizeEncoded(data, options = {}) {
+    return this.#recognize('recognizeEncoded', data, options);
+  }
+
+  detect(data, options = {}) {
+    return this.#recognize('detect', data, options);
+  }
+
+  #recognize(nativeMethod, image, options) {
+    let signal;
+    let nativeOptions;
+    try {
+      if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+        throw new OcrError('invalid_argument', 'recognize options must be an object');
+      }
+      signal = options.signal;
+      if (signal !== undefined) {
+        validateSignal(signal);
+        if (signal.aborted) return Promise.reject(abortReason(signal));
+      }
+      nativeOptions = { ...options };
+      delete nativeOptions.signal;
+    } catch (error) {
+      return Promise.reject(normalizeNativeError(error));
+    }
+
+    let operation;
+    try {
+      operation = this.#native[nativeMethod](image, nativeOptions);
+    } catch (error) {
+      return Promise.reject(normalizeNativeError(error));
+    }
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const cleanup = () => {
+        if (signal !== undefined) signal.removeEventListener('abort', onAbort);
+      };
+      const settle = (callback, value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        callback(value);
+      };
+      const onAbort = () => {
+        if (settled) return;
+        try {
+          this.#native.cancel(operation.requestId);
+        } catch {
+          // Public cancellation still wins. Native teardown owns any remaining work.
+        }
+        settle(reject, abortReason(signal));
+      };
+
+      operation.promise.then(
+        (value) => settle(resolve, value),
+        (error) => settle(reject, normalizeNativeError(error)),
+      );
+
+      if (signal !== undefined) {
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted) onAbort();
+      }
+    });
+  }
+
+  close() {
+    if (this.#closePromise === undefined) {
+      try {
+        this.#closePromise = Promise.resolve(this.#native.close()).catch((error) => {
+          throw normalizeNativeError(error);
+        });
+      } catch (error) {
+        this.#closePromise = Promise.reject(normalizeNativeError(error));
+      }
+    }
+    return this.#closePromise;
+  }
+}
+
+let nativeRuntime;
+
+async function createEngine(options) {
+  try {
+    const resolvedOptions = resolveCreateOptions(options);
+    if (!nativeRuntime) nativeRuntime = loadNative();
+    const nativeEngine = await nativeRuntime.binding.createEngine(
+      resolvedOptions,
+      nativeRuntime.runtimePolicy,
+    );
+    return new OcrEngineImpl(nativeEngine);
+  } catch (error) {
+    throw normalizeNativeError(error);
+  }
+}
+
+module.exports = { createEngine, OcrError };