@repeato/native-cv 0.1.2 → 0.1.4

package/README.internal.md

@@ -34,8 +34,8 @@ const sof = new native.SiftObjectFinder({
   clusterSearchRadius: 50  // Cluster search radius in pixels
 });
 
-// TemplateMatcherWorker can be instantiated without parameters
-const tmw = new native.TemplateMatcherWorker();
+// TemplateMatcher can be instantiated without parameters
+const tmw = new native.TemplateMatcher();
 ```
 
 ### Electron Integration

package/index.d.ts

@@ -0,0 +1,348 @@
+// TypeScript definitions for @repeato/native-cv
+
+/**
+ * Represents a rectangle with position and dimensions
+ */
+export class Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+
+  constructor(x?: number, y?: number, width?: number, height?: number);
+
+  /** The area of the rectangle (width * height) */
+  readonly area: number;
+
+  /** The center point of the rectangle */
+  readonly center: { x: number; y: number };
+
+  /** Check if a point is inside the rectangle */
+  contains(x: number, y: number): boolean;
+
+  toString(): string;
+}
+
+/**
+ * Represents a 3D vector
+ */
+export class Vec3 {
+  x: number;
+  y: number;
+  z: number;
+
+  constructor(x?: number, y?: number, z?: number);
+
+  /** The length (magnitude) of the vector */
+  readonly length: number;
+
+  /** Returns a normalized copy of this vector */
+  normalize(): Vec3;
+
+  /** Add another vector to this one */
+  add(other: Vec3): Vec3;
+
+  /** Compute dot product with another vector */
+  dot(other: Vec3): number;
+
+  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;
+
+  /**
+   * Save debug image to file
+   * @param filePath Path to save the image
+   */
+  saveDebugImage(filePath: string): void;
+
+  /**
+   * 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;
+
+  /**
+   * 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[];
+
+  /**
+   * Get the best match
+   * @returns Best match result or null if no match found
+   */
+  getMatch(): MatchResult | null;
+
+  /**
+   * Convert pixel coordinates to percentage coordinates
+   * @param match Match with pixel coordinates
+   * @returns Match with percentage coordinates (0-1)
+   */
+  toPercentageCoordinates(match: MatchResult): MatchResult;
+
+  /**
+   * Match only non-empty regions
+   */
+  matchNonEmpty(minMatches?: number): MatchResult[];
+
+  /**
+   * Get probabilities for all pyramid levels
+   * @returns Map of pyramid level to probability
+   */
+  getProbabilities(): Record<number, number>;
+
+  /** Probabilities getter (alias for getProbabilities) */
+  readonly probabilities: Record<number, number>;
+}
+
+/**
+ * Object detection result from SIFT/ORB matching
+ */
+export interface ObjectResult {
+  /** X coordinate of the detected object */
+  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;
+}
+
+/**
+ * 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[];
+}
+
+/**
+ * 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

@@ -5,7 +5,7 @@ const nativeCV = require('node-gyp-build')(__dirname);
 
 // Export the native functions directly
 module.exports = {
-  TemplateMatcher: nativeCV.TemplateMatcherWorker,
+  TemplateMatcher: nativeCV.TemplateMatcher,
   SiftObjectFinder: nativeCV.SiftObjectFinder,
   
   // JavaScript wrapper classes

package/native.js

@@ -32,12 +32,12 @@ if (!native) {
   const makeMissing = (name) => function () { throw new Error(errorMessage + `\nRequested native class: ${name}`) }
 
   native = {
-    TemplateMatcherWorker: makeMissing('TemplateMatcherWorker'),
+    TemplateMatcher: makeMissing('TemplateMatcher'),
     SiftObjectFinder: makeMissing('SiftObjectFinder')
   }
 } else {
   // Ensure both expected classes are present; if not, provide explicit error placeholders.
-  const expected = ['TemplateMatcherWorker', 'SiftObjectFinder']
+  const expected = ['TemplateMatcher', 'SiftObjectFinder']
   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?`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repeato/native-cv",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Native OpenCV-based template matching module for Node.js, replacing opencv4nodejs-m1.",
   "main": "index.js",
   "types": "index.d.ts",