@salama/image-finder/PACKAGE.md

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

# Template Matcher - NPM Package

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

## Installation

```bash
npm install template-matcher
```

## Quick Start

### CommonJS (Node.js)
```javascript
const TemplateMatcher = require('template-matcher');

async function findButtons() {
    const matches = await TemplateMatcher.findMatches(
        'screenshot.png',
        'button.png',
        { threshold: 0.8 }
    );
    
    console.log(`Found ${matches.length} buttons`);
    matches.forEach(match => {
        console.log(`Button at [${match.x}, ${match.y}] with ${(match.confidence * 100).toFixed(1)}% confidence`);
    });
}
```

### ES Modules
```javascript
import TemplateMatcher from 'template-matcher';
// or
import { TemplateMatcher, Matcher } from 'template-matcher';

const matches = await TemplateMatcher.findMatches('screenshot.png', 'template.png');
```

### TypeScript
```typescript
import TemplateMatcher, { MatchResult, MatcherOptions } from 'template-matcher';

const options: MatcherOptions = {
    threshold: 0.8,
    multiscale: true,
    useHSV: true,
    useDualScoring: true
};

const matches: MatchResult[] = await TemplateMatcher.findMatches(
    'screenshot.png',
    'template.png',
    options
);

// Full IDE autocomplete and type checking
matches.forEach((match: MatchResult) => {
    console.log(`Match at [${match.x}, ${match.y}] with confidence ${match.confidence}`);
});
```

## Features

- 🚀 **High Performance**: Input scaling for up to 89% faster processing
- 🎨 **Color Sensitivity**: Advanced HSV color space matching with dual RGB+HSV scoring
- 📱 **Multi-Template**: Batch processing with cross-template non-maximum suppression
- 🔄 **Variant Detection**: Automatic detection of numbered template variants
- ⚡ **Parallel Safe**: Unique annotation filenames for concurrent execution
- 🎯 **Precision Control**: Configurable thresholds, preprocessing, and matching methods
- 📝 **TypeScript Support**: Full type definitions with IDE autocomplete
- 🔧 **ES Modules & CommonJS**: Works with both module systems

## API Reference

### Core Methods

#### `findMatches(screenshotPath, templatePath, options?)`
Find all instances of a template in a screenshot.

```javascript
const matches = await TemplateMatcher.findMatches(
    'screenshot.png',
    'template.png',
    {
        threshold: 0.8,
        multiscale: true,
        useHSV: true,
        debug: false
    }
);
```

#### `findMatchesBatch(screenshotPath, templatePaths, options?)`
Process multiple templates against one screenshot with parallel processing.

```javascript
const matches = await TemplateMatcher.findMatchesBatch(
    'screenshot.png',
    ['button1.png', 'button2.png', 'icon.png'],
    {
        threshold: 0.7,
        crossTemplateNMS: true,
        inputScaling: 0.5
    }
);
```

#### `findTemplateVariants(templatePath, debug?)`
Automatically detect numbered template variants.

```javascript
const variants = await TemplateMatcher.findTemplateVariants('button.png');
// Returns: ['button.png', 'button1.png', 'button2.png', ...]
```

### Configuration Methods

#### `getAvailableMethods()`
Get all available OpenCV matching methods.

```javascript
const methods = TemplateMatcher.getAvailableMethods();
// Returns: ['CCOEFF', 'CCOEFF_NORMED', 'CCORR', 'CCORR_NORMED', 'SQDIFF', 'SQDIFF_NORMED']
```

#### `getDefaultOptions()`
Get the current default options configuration.

```javascript
const defaults = TemplateMatcher.getDefaultOptions();
console.log(defaults.threshold); // 0.8
console.log(defaults.useHSV);    // true
```

## TypeScript Types

### MatchResult
```typescript
interface MatchResult {
    x: number;              // Top-left X coordinate
    y: number;              // Top-left Y coordinate
    width: number;          // Template width
    height: number;         // Template height
    confidence: number;     // Match confidence (0.0-1.0)
    centerX: number;        // Center X coordinate
    centerY: number;        // Center Y coordinate
    templatePath?: string;  // Template path (batch mode)
}
```

### MatcherOptions
```typescript
interface MatcherOptions {
    threshold?: number;                    // 0.0-1.0, default: 0.8
    multiscale?: boolean;                 // default: false
    useHSV?: boolean;                     // default: true
    useDualScoring?: boolean;             // default: true
    inputScaling?: number;                // 0.1-1.0, default: 1.0
    enableVariantDetection?: boolean;     // default: false
    annotationDir?: string;               // default: './tmp/annotations'
    debug?: boolean;                      // default: false
    // ... many more options
}
```

## Advanced Examples

### Color-Sensitive Matching
```javascript
// For matching colored UI elements with high precision
const matches = await TemplateMatcher.findMatches(
    'screenshot.png',
    'red_button.png',
    {
        threshold: 0.7,
        useHSV: true,
        useDualScoring: true,
        hsvWeights: [3.0, 2.0, 0.5],  // Emphasize hue and saturation
        rgbWeight: 0.6,
        hsvWeight: 0.4
    }
);
```

### High-Performance Batch Processing
```javascript
// Process multiple templates with 75% faster performance
const matches = await TemplateMatcher.findMatchesBatch(
    'large_screenshot.png',
    ['button1.png', 'button2.png', 'icon1.png', 'icon2.png'],
    {
        threshold: 0.8,
        inputScaling: 0.5,        // 75% faster
        crossTemplateNMS: true,   // Remove overlapping matches
        overlapThreshold: 0.7,
        annotationDir: './results'
    }
);

console.log(`Found ${matches.length} matches across all templates`);
```

### Template Variant Detection
```javascript
// Automatically detect and process template variants
const matches = await TemplateMatcher.findMatches(
    'screenshot.png',
    'button.png',  // Will auto-detect button1.png, button2.png, etc.
    {
        enableVariantDetection: true,
        threshold: 0.8,
        debug: true
    }
);

// This automatically switches to batch mode if variants are found
```

### Automation Integration
```javascript
// Example for automated testing
async function clickButton(screenshotPath, buttonTemplate) {
    const matches = await TemplateMatcher.findMatches(
        screenshotPath,
        buttonTemplate,
        {
            threshold: 0.9,      // High precision for UI automation
            multiscale: true,    // Handle different screen resolutions
            annotationDir: './test_results'  // Save results for debugging
        }
    );
    
    if (matches.length > 0) {
        const button = matches[0];  // Get the best match
        console.log(`Clicking button at [${button.centerX}, ${button.centerY}]`);
        // Integrate with your automation tool here
        return { success: true, position: [button.centerX, button.centerY] };
    } else {
        console.log('Button not found');
        return { success: false };
    }
}
```

## Dependencies

- `@techstark/opencv-js`: OpenCV.js for computer vision operations
- `sharp`: High-performance image processing

## License

MIT

## Support

For issues and feature requests, visit the [GitHub repository](https://github.com/your-username/template-matcher).

---

**Note**: This package requires Node.js 14+ and is optimized for server-side image processing and automation tasks.