# repeato-native-cv

Native OpenCV-based template matching module for Node.js with static linking for Electron distribution.

## Features

- **Static Linking**: All OpenCV dependencies are statically linked, no need for users to install OpenCV
- **Electron Ready**: Pre-built for Electron applications
- **Cross-Platform**: Supports macOS, Windows, and Linux
- **Template Matching**: High-performance template matching using OpenCV
- **ORB Features**: Advanced feature detection and matching

## Installation

```bash
npm install
npm run build:static
```

For Electron apps:
```bash
npm run build:electron
```

## Usage

```javascript
const native = require('./build/Release/repeato-native-cv.node');

// OrbObjectFinder requires parameters
const sof = new native.OrbObjectFinder({
  kMinMatches: 10,        // Minimum matches required
  goodMatchTh: 0.75,      // Good match threshold (0.0-1.0)
  clusterSearchRadius: 50  // Cluster search radius in pixels
});

// TemplateMatcher can be instantiated without parameters
const tmw = new native.TemplateMatcher();
```

### Electron Integration

```javascript
const path = require('path');
const native = require(path.join(__dirname, 'native', 'repeato-native-cv.node'));

const sof = new native.OrbObjectFinder({
  kMinMatches: 10,
  goodMatchTh: 0.75,
  clusterSearchRadius: 50
});
```

## Build Scripts

| Script | Description |
|--------|-------------|
| `npm run build:static` | Build with statically linked OpenCV (recommended) |
| `npm run build:electron` | Build specifically for Electron |
| `npm run build:all` | Cross-platform build for distribution |
| `npm run clean` | Clean all build artifacts |
| `npm run rebuild` | Clean and rebuild from scratch |
| `npm test` | Run test suite |

## Static Build

The static build downloads OpenCV source and compiles it with static libraries. All OpenCV code is bundled into the final `.node` file.

**Pros**:
- No external dependencies
- Perfect for Electron distribution
- Users don't need to install OpenCV

**Cons**:
- Long build time (20+ minutes)
- Larger module size

**Verify no external dependencies**:
```bash
otool -L build/Release/repeato-native-cv.node
# Should only show: /usr/lib/libc++.1.dylib, /usr/lib/libSystem.B.dylib
```

## System Requirements

### All Platforms
- Node.js 16+
- Python 3.9-3.12 (for node-gyp, see note below)
- CMake 3.15+
- C++14 compatible compiler

### macOS
- Xcode Command Line Tools
- macOS 10.15+

### Windows
- Visual Studio Build Tools 2019+
- Windows 10+

### Linux
- GCC 7+ or Clang 6+
- Build essentials (cmake, git, pkg-config)

## Troubleshooting

### Python Version Issues
```
Error: ModuleNotFoundError: No module named 'distutils'
```
**Solution**: Python 3.13+ removed `distutils`. Use Python 3.9-3.12:
```bash
npm config set python /opt/homebrew/opt/python@3.9/bin/python3.9
```

### Corrupted Downloads
```
Error: Failed to extract file
```
**Solution**: Delete `deps/` folder and retry:
```bash
rm -rf deps/ build/
npm run build:static
```

## File Structure

```
repeato-native-cv/
├── src/
│   ├── module.cc              # Main N-API module
│   ├── template_matcher.cc    # Template matching implementation
│   └── orb_object_finder.cc   # ORB object detection
├── scripts/
│   ├── download-opencv.js     # OpenCV download/build
│   ├── build-electron.js      # Electron build script
│   └── build-all.js           # Full build orchestrator
├── binding.gyp                # Node.js build configuration
└── build/Release/
    └── repeato-native-cv.node # Built module
```

## License

MIT
