@repeato/native-cv 0.1.4 → 0.2.0

package/README.md

@@ -2,4 +2,13 @@
 
 Native OpenCV-based computer vision module for Node.js with static linking for Electron distribution.
 
-Used in Repeato-CLI and Repeato-Studio. Learn more at https://www.repeato.app
+Used in Repeato-CLI and Repeato-Studio. Learn more at https://www.repeato.app
+
+## Electron + Webpack
+
+If you bundle your renderer with webpack, native modules must be resolvable from disk at runtime.
+
+- Ensure `@repeato/native-cv` is treated as an external (do not bundle it).
+- Ensure `.node` binaries are unpacked from asar (e.g. `asarUnpack: ["**/*.node"]`).
+
+If these are misconfigured, you may see `node-gyp-build` errors like “No native build was found … loaded from: …electron.asar/renderer”.

package/index.d.ts

@@ -48,301 +48,68 @@ export class Vec3 {
   toString(): string;
 }
 
-/**
- * Match result from template matching
- */
-export interface MatchResult {
-  /** X coordinate of the match (top-left corner) */
-  x: number;
-  /** Y coordinate of the match (top-left corner) */
-  y: number;
-  /** Width of the matched region */
-  width: number;
-  /** Height of the matched region */
-  height: number;
-  /** Match probability/confidence (0-1) */
-  probability: number;
-  /** Scale factor if scale-invariant matching was used */
-  scale?: number;
-  /** Pyramid level where match was found */
-  pyrLevel?: number;
-}
-
-/**
- * Options for template matching
- */
-export interface MatchOptions {
-  /** Minimum number of matches required */
-  minMatches?: number;
-  /** Optimal number of matches to find */
-  optimalMatches?: number;
-  /** Timeout in milliseconds */
-  timeout?: number;
-  /** Whether to use scale-invariant matching */
-  scaleInvariant?: boolean;
-  /** Accuracy level (0-1) */
-  accuracy?: number;
-}
-
-/**
- * Native template matcher using OpenCV
- * Provides fast, accurate template matching with pyramid-based search
- */
-export class TemplateMatcher {
-  constructor();
-
-  /** Set test case ID for debugging */
-  setID(id: string): void;
-
-  /** Enable/disable debug mode */
-  setDebug(debug: boolean): void;
-
-  /** Set title for debug output */
-  setTitle(title: string): void;
-
-  /** Get the current title */
-  getTitle(): string;
-
-  /**
-   * Set the template image to search for
-   * @param imageBuffer Buffer containing the image data (PNG, JPEG, etc.)
-   */
-  setTemplateImage(imageBuffer: Buffer): void;
-
-  /**
-   * Set a scale factor for the template
-   * @param scale Scale factor (1.0 = original size)
-   */
-  setScale(scale: number): void;
-
-  /**
-   * Set the image to search in
-   * @param imageBuffer Buffer containing the image data (PNG, JPEG, etc.)
-   */
-  setImage(imageBuffer: Buffer): void;
-
-  /**
-   * Create image pyramids for multi-scale matching
-   * @param levels Number of pyramid levels
-   */
-  createPyramid(levels: number): void;
-
-  /**
-   * Find matches of the template in the image
-   * @param minMatches Minimum number of matches to find
-   * @param optimalMatches Optimal number of matches
-   * @param timeout Timeout in milliseconds
-   * @returns Array of match results
-   */
-  findMatch(minMatches?: number, optimalMatches?: number, timeout?: number): MatchResult[];
-
-  /** Get the aspect ratio of the template */
-  getAspectRatio(): number;
-
-  /**
-   * Perform scale-invariant template matching
-   * @param minMatches Minimum matches required
-   * @param optimalMatches Optimal number of matches
-   * @param timeout Timeout in milliseconds
-   * @returns Array of match results
-   */
-  matchScaleInvariant(minMatches?: number, optimalMatches?: number, timeout?: number): MatchResult[];
-
-  /**
-   * Match using image pyramid
-   * @param minMatches Minimum matches required
-   * @param optimalMatches Optimal number of matches  
-   * @param timeout Timeout in milliseconds
-   * @param resolutionFixScale Resolution fix scale factor
-   * @param scaleInvariant Whether to use scale-invariant matching
-   * @param accuracy Accuracy level (0-1)
-   * @returns Array of match results
-   */
-  matchPyramid(
-    minMatches?: number,
-    optimalMatches?: number,
-    timeout?: number,
-    resolutionFixScale?: number,
-    scaleInvariant?: boolean,
-    accuracy?: number
-  ): MatchResult[];
-
-  /**
-   * Add matches to existing results without duplicates
-   * @param allMatches Existing matches
-   * @param moreMatches New matches to add
-   * @returns Combined array without duplicates
-   */
-  addMatchesWithoutDuplicates(allMatches: MatchResult[], moreMatches: MatchResult[]): MatchResult[];
-
-  /**
-   * Check if two matches are similar (overlapping)
-   * @param match1 First match
-   * @param match2 Second match
-   * @returns True if matches are similar
-   */
-  similar(match1: MatchResult, match2: MatchResult): boolean;
 
-  /**
-   * Generate linearly spaced values
-   * @param start Start value
-   * @param end End value
-   * @param count Number of values
-   * @returns Array of linearly spaced values
-   */
-  linspace(start: number, end: number, count: number): number[];
-
-  /**
-   * Verify subpixel matches at full resolution
-   */
-  checkSubpixelMatchesAtFullResolution(
-    matches: MatchResult[],
-    pyrLevel: number,
-    resolutionFixScale: number,
-    scaleInvariant: boolean,
-    accuracy: number
-  ): MatchResult[];
-
-  /**
-   * Match at full resolution
-   */
-  matchFullRes(
-    minMatches?: number,
-    optimalMatches?: number,
-    timeout?: number
-  ): MatchResult[];
-
-  /** Show debug image (if debug mode enabled) */
-  showDebugImage(): void;
+/** Direct access to the native module */
+export const native: NativeModule;
 
-  /**
-   * Save debug image to file
-   * @param filePath Path to save the image
-   */
-  saveDebugImage(filePath: string): void;
+/** Calculate sum of per-channel standard deviations for an image buffer. */
+export function getMeanStdDev(imageBuffer: Buffer): Promise<number>;
 
-  /**
-   * Draw a rectangle on the debug image
-   * @param x X coordinate
-   * @param y Y coordinate
-   * @param width Width
-   * @param height Height
-   */
-  drawDebugRect(x: number, y: number, width: number, height: number): void;
+/** Decode an image buffer and return its size. */
+export function getImageSize(imageBuffer: Buffer): Promise<{ width: number; height: number }>;
 
-  /**
-   * Match using OpenCV Mat directly (internal use)
-   */
-  matchCvImage(
-    image: Buffer,
-    template: Buffer,
-    pyrLevel: number,
-    minMatches: number,
-    searchRegion?: { x: number; y: number; width: number; height: number }
-  ): MatchResult[];
+/** Calculate bounding box of differences between two images. */
+export function calcImageDiffBoundingBox(options: CalcImageDiffBoundingBoxOptions): Promise<DiffBoundingBox | null>;
 
-  /**
-   * Get the best match
-   * @returns Best match result or null if no match found
-   */
-  getMatch(): MatchResult | null;
+/** Calculate difference percentage between two images. */
+export function calcImageDiffPercentage(options: CalcImageDiffPercentageOptions): Promise<number>;
 
-  /**
-   * Convert pixel coordinates to percentage coordinates
-   * @param match Match with pixel coordinates
-   * @returns Match with percentage coordinates (0-1)
-   */
-  toPercentageCoordinates(match: MatchResult): MatchResult;
+/** Thread-safe template matching using per-call native instances. */
+export function findObjectViaTemplate(options: FindObjectViaTemplateOptions): Promise<MatchResult[]>;
 
-  /**
-   * Match only non-empty regions
-   */
-  matchNonEmpty(minMatches?: number): MatchResult[];
+/** Thread-safe SIFT/ORB matching using per-call native instances. */
+export function findObjectViaSift(options: FindObjectViaSiftOptions): Promise<ObjectResult[]>;
 
-  /**
-   * Get probabilities for all pyramid levels
-   * @returns Map of pyramid level to probability
-   */
-  getProbabilities(): Record<number, number>;
+export interface FindObjectViaTemplateOptions {
+  templateBuffer: Buffer;
+  frameBuffer: Buffer;
+  minMatches: number;
+  optimalMatches: number;
+  timeout: number;
+  resolutionFixScale?: number;
+  scaleInvariant?: boolean;
+  accuracy?: number;
+  roi?: { x: number; y: number; width: number; height: number };
+  debug?: boolean;
+}
 
-  /** Probabilities getter (alias for getProbabilities) */
-  readonly probabilities: Record<number, number>;
+export interface FindObjectViaSiftOptions {
+  templateBuffer: Buffer;
+  frameBuffer: Buffer;
+  minMatches: number;
+  optimalMatches: number;
+  timeout: number;
+  kMinMatches?: number;
+  goodMatchTh?: number;
+  clusterSearchRadius?: number;
+  roi?: { x: number; y: number; width: number; height: number };
+  debug?: boolean;
 }
 
-/**
- * Object detection result from SIFT/ORB matching
- */
-export interface ObjectResult {
-  /** X coordinate of the detected object */
+export interface DiffBoundingBox {
   x: number;
-  /** Y coordinate of the detected object */
   y: number;
-  /** Width of the detected object */
   width: number;
-  /** Height of the detected object */
   height: number;
-  /** Detection confidence/probability */
-  probability: number;
-  /** Number of feature matches in this cluster */
-  matchCount: number;
-  /** Cluster index */
-  clusterIndex: number;
 }
 
-/**
- * Options for SIFT/ORB object detection
- */
-export interface FindObjectsOptions {
-  /** Minimum number of feature matches required */
-  minMatches?: number;
-  /** Good matches threshold (lower = stricter) */
-  goodMatchesThreshold?: number;
-  /** Cluster search radius in pixels */
-  clusterSearchRadius?: number;
+export interface CalcImageDiffBoundingBoxOptions {
+  bufferA: Buffer;
+  bufferB: Buffer;
+  region?: { x: number; y: number; width: number; height: number } | null;
 }
 
-/**
- * Feature-based object finder using ORB descriptors
- * Good for finding objects with distinctive features
- */
-export class SiftObjectFinder {
-  constructor(options?: FindObjectsOptions);
-
-  /** Set test case ID for debugging */
-  setId(id: string): void;
-
-  /** Set title for debug output */
-  setTitle(title: string): void;
-
-  /** Enable/disable debug mode */
-  setDebug(debug: boolean): void;
-
-  /**
-   * Set the template image to search for
-   * @param imageBuffer Buffer containing the image data
-   */
-  setTemplateImage(imageBuffer: Buffer): void;
-
-  /**
-   * Set the image to search in
-   * @param imageBuffer Buffer containing the image data
-   */
-  setImage(imageBuffer: Buffer): void;
-
-  /**
-   * Find objects matching the template
-   * @returns Array of detected objects
-   */
-  findObjects(): ObjectResult[];
+export interface CalcImageDiffPercentageOptions {
+  bufferA: Buffer;
+  bufferB: Buffer;
 }
-
-/**
- * Native OpenCV module (low-level access)
- */
-export interface NativeModule {
-  TemplateMatcherWorker: typeof TemplateMatcher;
-  SiftObjectFinder: typeof SiftObjectFinder;
-}
-
-/** Direct access to the native module */
-export const native: NativeModule;

package/index.js

@@ -1,17 +1,390 @@
 // Main entry point for repeato-native-cv module
-// Uses node-gyp-build to load prebuilt binaries
+// Runs native operations in a bounded child-process pool for true parallelism in Electron 12
 
-const nativeCV = require('node-gyp-build')(__dirname);
+const os = require('os')
+const path = require('path')
+const { fork } = require('child_process')
+const nativeCV = require('node-gyp-build')(__dirname)
+
+const WorkerScriptPath = path.join(__dirname, 'worker', 'native-cv-process-worker.js')
+const MaxConcurrencyFallback = 4
+const ParsedConcurrency = Number.parseInt(process.env.NATIVE_CV_CONCURRENCY ?? '', 10)
+const HardwareConcurrency = typeof os.availableParallelism === 'function' ? os.availableParallelism() : os.cpus().length
+const DefaultConcurrency = Math.max(1, Math.min(MaxConcurrencyFallback, HardwareConcurrency))
+const NativeCvConcurrency = Math.max(1, Number.isFinite(ParsedConcurrency) ? ParsedConcurrency : DefaultConcurrency)
+
+const toBuffer = (value, label) => {
+  if (Buffer.isBuffer(value)) {
+    return value
+  }
+
+  if (ArrayBuffer.isView(value)) {
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+  }
+
+  if (value instanceof ArrayBuffer) {
+    return Buffer.from(value)
+  }
+
+  if (value && typeof value === 'object' && value.type === 'Buffer' && value.data != null) {
+    return Buffer.from(value.data)
+  }
+
+  throw new Error(`${label} must be a Buffer`)
+}
+
+/**
+ * @typedef {{
+ * id: number,
+ * method: string,
+ * args: any[],
+ * resolve: (value: any) => void,
+ * reject: (reason?: any) => void
+ * }} NativeTask
+ */
+
+/**
+ * @typedef {{
+ * child: import('child_process').ChildProcess,
+ * busy: boolean,
+ * currentTaskId: number | null
+ * }} WorkerState
+ */
+
+class NativeCvProcessPool {
+  /**
+   * @param {number} size
+   */
+  constructor(size) {
+    this.size = Math.max(1, size)
+    /** @type {WorkerState[]} */
+    this.workers = []
+    /** @type {NativeTask[]} */
+    this.queue = []
+    /** @type {Map<number, NativeTask>} */
+    this.inFlightTasks = new Map()
+    this.taskCounter = 0
+    this.isShuttingDown = false
+
+    for (let index = 0; index < this.size; index += 1) {
+      this.workers.push(this.createWorkerState())
+    }
+  }
+
+  /**
+   * @param {string} method
+   * @param {any[]} args
+   */
+  execute(method, args) {
+    return new Promise((resolve, reject) => {
+      if (this.isShuttingDown) {
+        reject(new Error('Native CV worker pool is shutting down'))
+        return
+      }
+      this.taskCounter += 1
+      this.queue.push({ id: this.taskCounter, method, args, resolve, reject })
+      this.processQueue()
+    })
+  }
+
+  createWorkerState() {
+    const child = fork(WorkerScriptPath, [], {
+      stdio: ['ignore', 'inherit', 'inherit', 'ipc']
+    })
+    /** @type {WorkerState} */
+    const state = { child, busy: false, currentTaskId: null }
+
+    child.on('message', message => {
+      const { id, result, error } = message || {}
+      if (typeof id !== 'number') {
+        return
+      }
+      const task = this.inFlightTasks.get(id)
+      if (!task) {
+        return
+      }
+
+      this.inFlightTasks.delete(id)
+      state.busy = false
+      state.currentTaskId = null
+
+      if (error) {
+        const workerError = new Error(error.message || 'Native worker execution failed')
+        if (error.stack) {
+          workerError.stack = error.stack
+        }
+        if (error.name) {
+          workerError.name = error.name
+        }
+        task.reject(workerError)
+      } else {
+        task.resolve(result)
+      }
+
+      this.processQueue()
+    })
+
+    child.on('error', err => {
+      this.failWorkerTask(state, err)
+    })
+
+    child.on('exit', code => {
+      if (code !== 0) {
+        this.failWorkerTask(state, new Error(`Native CV process stopped with exit code ${code}`))
+      }
+      if (!this.isShuttingDown) {
+        this.replaceWorker(state)
+      }
+      this.processQueue()
+    })
+
+    return state
+  }
+
+  /**
+   * @param {WorkerState} state
+   * @param {Error} err
+   */
+  failWorkerTask(state, err) {
+    if (state.currentTaskId == null) {
+      return
+    }
+    const task = this.inFlightTasks.get(state.currentTaskId)
+    if (!task) {
+      return
+    }
+
+    this.inFlightTasks.delete(task.id)
+    state.busy = false
+    state.currentTaskId = null
+    task.reject(err)
+  }
+
+  /**
+   * @param {WorkerState} previousState
+   */
+  replaceWorker(previousState) {
+    const workerIndex = this.workers.indexOf(previousState)
+    if (workerIndex < 0) {
+      return
+    }
+    this.workers[workerIndex] = this.createWorkerState()
+  }
+
+  processQueue() {
+    if (this.isShuttingDown) {
+      return
+    }
+
+    if (this.queue.length === 0) {
+      return
+    }
+
+    for (const workerState of this.workers) {
+      if (workerState.busy || this.queue.length === 0) {
+        continue
+      }
+
+      const nextTask = this.queue.shift()
+      if (!nextTask) {
+        return
+      }
+
+      workerState.busy = true
+      workerState.currentTaskId = nextTask.id
+      this.inFlightTasks.set(nextTask.id, nextTask)
+
+      workerState.child.send({
+        id: nextTask.id,
+        method: nextTask.method,
+        args: nextTask.args
+      })
+    }
+  }
+
+  async shutdown() {
+    this.isShuttingDown = true
+
+    while (this.queue.length > 0) {
+      const task = this.queue.shift()
+      if (task) {
+        task.reject(new Error('Native CV worker pool shutdown'))
+      }
+    }
+
+    const terminatePromises = this.workers.map(async workerState => {
+      try {
+        workerState.child.kill('SIGTERM')
+      } catch (_) {
+        // ignore terminate errors during shutdown
+      }
+    })
+
+    await Promise.all(terminatePromises)
+    this.workers = []
+  }
+}
+
+const runInProcessAsync = (method, args) =>
+  new Promise((resolve, reject) => {
+    setImmediate(() => {
+      try {
+        const fn = nativeCV[method]
+        if (typeof fn !== 'function') {
+          throw new Error(`Unknown native method: ${method}`)
+        }
+        resolve(fn(...args))
+      } catch (error) {
+        reject(error)
+      }
+    })
+  })
+
+let nativeCvPool = null
+let processPoolUnavailableReason = null
+
+const initProcessPool = () => {
+  try {
+    nativeCvPool = new NativeCvProcessPool(NativeCvConcurrency)
+  } catch (error) {
+    processPoolUnavailableReason = error?.message || 'process pool initialization failed'
+    nativeCvPool = null
+  }
+}
+
+initProcessPool()
+
+/**
+ * @param {string} method
+ * @param {any[]} args
+ */
+const runNativeAsync = async (method, args) => nativeCvPool.execute(method, args)
+const runNative = async (method, args) => {
+  if (nativeCvPool) {
+    return runNativeAsync(method, args)
+  }
+
+  if (processPoolUnavailableReason && process.env.NODE_ENV !== 'production') {
+    console.warn('[native-cv] process pool unavailable, falling back to in-process async:', processPoolUnavailableReason)
+  }
+
+  return runInProcessAsync(method, args)
+}
+
+const getMeanStdDev = async imageBuffer => runNative('getMeanStdDev', [toBuffer(imageBuffer, 'imageBuffer')])
+
+const getImageSize = async imageBuffer => runNative('getImageSize', [toBuffer(imageBuffer, 'imageBuffer')])
+
+const assertOptionsObject = (options, functionName) => {
+  if (!options || typeof options !== 'object' || Buffer.isBuffer(options)) {
+    throw new Error(`${functionName} expects a single options object.`)
+  }
+}
+
+const calcImageDiffBoundingBox = async options => {
+  assertOptionsObject(options, 'calcImageDiffBoundingBox')
+  const { bufferA, bufferB, region } = options
+  return runNative('calcImageDiffBoundingBox', [{
+    bufferA: toBuffer(bufferA, 'bufferA'),
+    bufferB: toBuffer(bufferB, 'bufferB'),
+    region
+  }])
+}
+
+const calcImageDiffPercentage = async options => {
+  assertOptionsObject(options, 'calcImageDiffPercentage')
+  const { bufferA, bufferB } = options
+  return runNative('calcImageDiffPercentage', [{
+    bufferA: toBuffer(bufferA, 'bufferA'),
+    bufferB: toBuffer(bufferB, 'bufferB')
+  }])
+}
+
+const findObjectViaTemplate = async options => {
+  assertOptionsObject(options, 'findObjectViaTemplate')
+  const {
+    templateBuffer,
+    frameBuffer,
+    minMatches,
+    optimalMatches,
+    timeout,
+    resolutionFixScale = 1,
+    scaleInvariant = false,
+    accuracy = 1,
+    roi,
+    debug = false
+  } = options
+  return runNative('findObjectViaTemplate', [{
+    templateBuffer: toBuffer(templateBuffer, 'templateBuffer'),
+    frameBuffer: toBuffer(frameBuffer, 'frameBuffer'),
+    minMatches,
+    optimalMatches,
+    timeout,
+    resolutionFixScale,
+    scaleInvariant,
+    accuracy,
+    roi,
+    debug
+  }])
+}
+
+const findObjectViaSift = async options => {
+  assertOptionsObject(options, 'findObjectViaSift')
+  const {
+    templateBuffer,
+    frameBuffer,
+    minMatches,
+    optimalMatches,
+    timeout,
+    kMinMatches = 10,
+    goodMatchTh = 0.75,
+    clusterSearchRadius = 50,
+    roi,
+    debug = false
+  } = options
+  return runNative('findObjectViaSift', [{
+    templateBuffer: toBuffer(templateBuffer, 'templateBuffer'),
+    frameBuffer: toBuffer(frameBuffer, 'frameBuffer'),
+    minMatches,
+    optimalMatches,
+    timeout,
+    kMinMatches,
+    goodMatchTh,
+    clusterSearchRadius,
+    roi,
+    debug
+  }])
+}
+
+const shutdown = async () => {
+  if (nativeCvPool) {
+    await nativeCvPool.shutdown()
+    nativeCvPool = null
+  }
+}
 
 // Export the native functions directly
 module.exports = {
-  TemplateMatcher: nativeCV.TemplateMatcher,
-  SiftObjectFinder: nativeCV.SiftObjectFinder,
-  
+  getMeanStdDev,
+  getImageSize,
+  calcImageDiffBoundingBox,
+  calcImageDiffPercentage,
+  findObjectViaTemplate,
+  findObjectViaSift,
+  shutdown,
+
   // JavaScript wrapper classes
-  Rect: require('./Rect.js'), 
+  Rect: require('./Rect.js'),
   Vec3: require('./Vec3.js'),
-  
-  // Native module for direct access
-  native: nativeCV
+
+  // Native module for direct access (no class access)
+  native: {
+    getMeanStdDev,
+    getImageSize,
+    calcImageDiffBoundingBox,
+    calcImageDiffPercentage,
+    findObjectViaTemplate,
+    findObjectViaSift,
+    shutdown
+  }
 };

package/native.js

@@ -29,18 +29,22 @@ if (!native) {
   console.error('[native-cv] Last error:', lastError?.message)
 
   const errorMessage = `Native OpenCV module not found. Build it first:\n  cd repeato-native-cv && npm run build\nTried paths:\n${tryPaths.map(p=>`  - ${p}`).join('\n')}\nLast error: ${lastError?.message}`
-  const makeMissing = (name) => function () { throw new Error(errorMessage + `\nRequested native class: ${name}`) }
+  const makeMissing = name => function () { throw new Error(errorMessage + `\nRequested native export: ${name}`) }
 
   native = {
-    TemplateMatcher: makeMissing('TemplateMatcher'),
-    SiftObjectFinder: makeMissing('SiftObjectFinder')
+    getMeanStdDev: makeMissing('getMeanStdDev'),
+    getImageSize: makeMissing('getImageSize'),
+    calcImageDiffBoundingBox: makeMissing('calcImageDiffBoundingBox'),
+    calcImageDiffPercentage: makeMissing('calcImageDiffPercentage'),
+    findObjectViaTemplate: makeMissing('findObjectViaTemplate'),
+    findObjectViaSift: makeMissing('findObjectViaSift')
   }
 } else {
-  // Ensure both expected classes are present; if not, provide explicit error placeholders.
-  const expected = ['TemplateMatcher', 'SiftObjectFinder']
+  // Ensure expected helper exports are present; if not, provide explicit error placeholders.
+  const expected = ['getMeanStdDev', 'getImageSize', 'calcImageDiffBoundingBox', 'calcImageDiffPercentage', 'findObjectViaTemplate', 'findObjectViaSift']
   for (const key of expected) {
     if (!Object.prototype.hasOwnProperty.call(native, key)) {
-      const msg = `Native build missing expected export '${key}'. Did you forget to call ${key}::Init in module.cc?`
+      const msg = `Native build missing expected export '${key}'.`
       console.warn('[native-cv] ' + msg)
       native[key] = () => { throw new Error(msg) }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repeato/native-cv",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Native OpenCV-based template matching module for Node.js, replacing opencv4nodejs-m1.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -16,6 +16,7 @@
     "clean": "rm -rf build/ deps/ prebuilds/ && npm install",
     "rebuild": "npm run clean && npm run build:static",
     "test": "node test-runner.js",
+    "test:concurrency": "node test-concurrency.js",
     "test:debug": "node test-runner.js --debug",
     "test:verbose": "node test-runner.js --verbose",
     "test:scale-invariant": "node test-runner.js --only-scale-invariant"
@@ -46,7 +47,7 @@
     "prebuildify": "^6.0.1"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=14.0.0"
   },
   "files": [
     "index.js",
@@ -54,6 +55,7 @@
     "native.js",
     "Vec3.js",
     "Rect.js",
+    "worker/",
     "prebuilds/",
     "LICENSE"
   ],

package/worker/native-cv-process-worker.js

@@ -0,0 +1,100 @@
+const path = require('path')
+
+const NativeCv = require('node-gyp-build')(path.join(__dirname, '..'))
+
+let isIpcConnected = true
+
+process.on('disconnect', () => {
+  isIpcConnected = false
+  process.exit(0)
+})
+
+process.on('error', error => {
+  if (error?.code === 'EPIPE') {
+    return
+  }
+  console.error('[native-cv-process-worker] process error:', error?.message || error)
+})
+
+const reviveBuffers = value => {
+  if (!value) {
+    return value
+  }
+
+  if (Buffer.isBuffer(value)) {
+    return value
+  }
+
+  if (ArrayBuffer.isView(value)) {
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+  }
+
+  if (value instanceof ArrayBuffer) {
+    return Buffer.from(value)
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(reviveBuffers)
+  }
+
+  if (typeof value === 'object') {
+    if (value.type === 'Buffer' && value.data != null) {
+      return Buffer.from(value.data)
+    }
+
+    const output = {}
+    for (const [key, entry] of Object.entries(value)) {
+      output[key] = reviveBuffers(entry)
+    }
+    return output
+  }
+
+  return value
+}
+
+process.on('message', message => {
+  if (!isIpcConnected) {
+    return
+  }
+
+  const { id, method, args } = message || {}
+
+  if (typeof id !== 'number') {
+    return
+  }
+
+  try {
+    const fn = NativeCv[method]
+    if (typeof fn !== 'function') {
+      throw new Error(`Unknown native method: ${method}`)
+    }
+
+    const normalizedArgs = Array.isArray(args) ? args.map(reviveBuffers) : []
+    const result = fn(...normalizedArgs)
+    if (isIpcConnected && process.connected) {
+      process.send?.({ id, result }, error => {
+        if (error && error.code !== 'EPIPE') {
+          console.error('[native-cv-process-worker] send error:', error.message)
+        }
+      })
+    }
+  } catch (error) {
+    if (isIpcConnected && process.connected) {
+      process.send?.(
+        {
+          id,
+          error: {
+            message: error?.message || 'Unknown native process worker error',
+            stack: error?.stack,
+            name: error?.name
+          }
+        },
+        sendError => {
+          if (sendError && sendError.code !== 'EPIPE') {
+            console.error('[native-cv-process-worker] send error:', sendError.message)
+          }
+        }
+      )
+    }
+  }
+})

package/worker/native-cv-worker.js

@@ -0,0 +1,35 @@
+const path = require('path')
+const { parentPort } = require('worker_threads')
+
+const NativeCv = require('node-gyp-build')(path.join(__dirname, '..'))
+
+if (!parentPort) {
+  throw new Error('native-cv-worker must run in a worker thread')
+}
+
+parentPort.on('message', message => {
+  const { id, method, args } = message || {}
+
+  if (typeof id !== 'number') {
+    return
+  }
+
+  try {
+    const fn = NativeCv[method]
+    if (typeof fn !== 'function') {
+      throw new Error(`Unknown native method: ${method}`)
+    }
+
+    const result = fn(...(Array.isArray(args) ? args : []))
+    parentPort.postMessage({ id, result })
+  } catch (error) {
+    parentPort.postMessage({
+      id,
+      error: {
+        message: error?.message || 'Unknown native worker error',
+        stack: error?.stack,
+        name: error?.name
+      }
+    })
+  }
+})