@salama/image-finder/types.d.ts

Advanced template matching tool with OpenCV.js featuring color sensitivity, batch processing, and performance optimization

/**
 * Template Matcher - TypeScript Definitions
 * Advanced template matching with OpenCV.js
 */

export interface MatchResult {
  /** Top-left X coordinate of the match */
  x: number;
  /** Top-left Y coordinate of the match */
  y: number;
  /** Width of the matched template */
  width: number;
  /** Height of the matched template */
  height: number;
  /** Match confidence score (0.0 to 1.0) */
  confidence: number;
  /** Center X coordinate of the match */
  centerX: number;
  /** Center Y coordinate of the match */
  centerY: number;
  /** Template file path (only in batch mode) */
  templatePath?: string;
  /** RGB matching score (only in dual scoring mode) */
  rgbScore?: number;
  /** HSV matching score (only in dual scoring mode) */
  hsvScore?: number;
  /** Scoring method used ('RGB-only' | 'HSV-only' | 'RGB+HSV') */
  scoringMethod?: string;
}

export interface AnnotationColor {
  /** Red component (0-255) */
  r: number;
  /** Green component (0-255) */
  g: number;
  /** Blue component (0-255) */
  b: number;
  /** Alpha component (0-255) */
  a: number;
}

export type MatchingMethod = 
  | 'CCOEFF'
  | 'CCOEFF_NORMED'
  | 'CCORR'
  | 'CCORR_NORMED'
  | 'SQDIFF'
  | 'SQDIFF_NORMED';

export interface MatcherOptions {
  /** Matching confidence threshold (0.0 to 1.0) */
  threshold?: number;
  
  /** Enable multi-scale template matching */
  multiscale?: boolean;
  
  /** Scale factors for multi-scale matching */
  scales?: number[];
  
  /** Convert images to grayscale */
  grayscale?: boolean;
  
  /** Enable edge detection preprocessing */
  useEdges?: boolean;
  
  /** Apply Gaussian blur preprocessing */
  useBlur?: boolean;
  
  /** Use color inversion */
  useInvert?: boolean;
  
  /** Use specific color channel ('red' | 'green' | 'blue' | null) */
  useChannel?: string | null;
  
  /** Color for annotation rectangles */
  annotationColor?: AnnotationColor;
  
  /** Line thickness for annotations */
  lineThickness?: number;
  
  /** Force specific matching method */
  method?: MatchingMethod | null;
  
  /** Maximum number of matches to return */
  maxMatches?: number;
  
  /** Specific output file path for annotations */
  outputPath?: string | null;
  
  /** Directory for auto-generated annotation files */
  annotationDir?: string | null;
  
  /** Enable detailed debug logging */
  debug?: boolean;
  
  /** Enable HSV color space for better color sensitivity */
  useHSV?: boolean;
  
  /** HSV channel weights [Hue, Saturation, Value] */
  hsvWeights?: [number, number, number];
  
  /** Enable dual RGB+HSV scoring system */
  useDualScoring?: boolean;
  
  /** Weight for RGB matching score in dual scoring */
  rgbWeight?: number;
  
  /** Weight for HSV matching score in dual scoring */
  hsvWeight?: number;
  
  /** Pixel tolerance for matching RGB/HSV results */
  spatialTolerance?: number;
  
  /** Scale input images for performance (0.1 to 1.0) */
  inputScaling?: number;
  
  /** Auto-detect template variants (template1.png, template2.png, etc.) */
  enableVariantDetection?: boolean;
}

export interface BatchMatcherOptions extends MatcherOptions {
  /** Enable cross-template non-maximum suppression */
  crossTemplateNMS?: boolean;
  
  /** IoU threshold for cross-template NMS (0.0 to 1.0) */
  overlapThreshold?: number;
}

export interface PerformanceStats {
  /** Total processing time in milliseconds */
  totalTime: number;
  
  /** Number of templates processed */
  templateCount: number;
  
  /** Average time per template in milliseconds */
  averageTimePerTemplate: number;
  
  /** Input scaling factor used */
  inputScaling: number;
  
  /** Performance boost percentage from scaling */
  performanceBoost: string;
}

/**
 * Advanced template matching class with OpenCV.js
 */
export declare class TemplateMatcher {
  /**
   * Find template matches in a screenshot image (unified method supporting single or multiple templates)
   * @param screenshotPath Path to the screenshot image
   * @param templatePathOrPaths Single template path or array of template paths
   * @param options Matching options (extends BatchMatcherOptions for full feature support)
   * @returns Promise resolving to array of match results
   */
  static findMatches(
    screenshotPath: string,
    templatePathOrPaths: string | string[],
    options?: BatchMatcherOptions
  ): Promise<MatchResult[]>;

  /**
   * Find template matches for multiple templates (batch processing)
   * @deprecated Use findMatches() instead - it handles both single and multiple templates
   * @param screenshotPath Path to the screenshot image
   * @param templatePaths Array of template image paths
   * @param options Batch matching options
   * @returns Promise resolving to array of match results
   */
  static findMatchesBatch(
    screenshotPath: string,
    templatePaths: string[],
    options?: BatchMatcherOptions
  ): Promise<MatchResult[]>;

  /**
   * Find template variants automatically
   * @param templatePath Base template path
   * @param debug Enable debug logging
   * @returns Promise resolving to array of template paths including variants
   */
  static findTemplateVariants(
    templatePath: string,
    debug?: boolean
  ): Promise<string[]>;

  /**
   * Get all available OpenCV matching methods
   * @returns Array of available method names
   */
  static getAvailableMethods(): MatchingMethod[];

  /**
   * Get default options object with current defaults
   * @returns Default options configuration
   */
  static getDefaultOptions(): Required<MatcherOptions>;

  /**
   * Generate unique annotation path with timestamp and random component
   * @param baseDir Base directory for annotations
   * @param prefix Filename prefix
   * @param screenshotPath Original screenshot path for context
   * @returns Promise resolving to unique annotation file path
   */
  static generateAnnotationPath(
    baseDir: string,
    prefix: string,
    screenshotPath: string
  ): Promise<string>;
}

/**
 * Default export for the template matcher
 */
declare const templateMatcher: typeof TemplateMatcher;
export default templateMatcher;