npm package: @kt-solutions/jscanify
Description: Enhanced document scanner with multi-strategy detection. Fork of jscanify with improved accuracy for challenging backgrounds.
Author: KT Solutions
Latest version: 1.6.0

# @kt-solutions/jscanify

Enhanced JavaScript document scanner with multi-strategy detection for improved accuracy.

[![npm version](https://badge.fury.io/js/%40kt-solutions%2Fjscanify.svg)](https://www.npmjs.com/package/@kt-solutions/jscanify)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Credits

This is an enhanced fork of [jscanify](https://github.com/ColonelParrot/jscanify) by **ColonelParrot**. Full credit to the original author for creating this excellent document scanning library.

## What's Enhanced? (v1.6.0)

This fork implements a **Phase 10 Combined Detection Strategy** that dramatically improves detection accuracy on challenging backgrounds:

| Original | This Fork |
|----------|-----------|
| Works well on solid backgrounds | Works on wood, stone, carpet, textured surfaces |
| Single detection strategy | 6 parallel detection strategies |
| Can detect internal elements (QR codes, text) as document edges | Geometric validation rejects non-rectangular shapes |

### Detection Strategies

1. **Line-based** (Hough Transform) - Best for documents with clear edges
2. **Contour-based** (3 variants) - Standard, heavy blur, morphological gradient
3. **LAB Luminance** - Color-space based edge detection
4. **Texture Contrast** - Excellent for gray stone and textured surfaces
5. **Brightness Segmentation** - Optimal for white paper detection
6. **Multi-scale Edge Detection** - Tries multiple blur/threshold combinations

### Geometric Validation

All detected shapes are validated with strict geometric constraints:
- **Width consistency**: top edge ≈ bottom edge (max 30% difference)
- **Height consistency**: left edge ≈ right edge (max 30% difference)
- Rejects impossible/garbage shapes - prefers NO detection over BAD detection

### Accuracy

Tested on 27 images across various backgrounds:
- **93% detection rate** (25/27 images)
- Only fails on extreme white-on-white cases (physically limited contrast)

## Installation

```bash
npm install @kt-solutions/jscanify
```

## Usage

### Node.js

```javascript
const JScanify = require('@kt-solutions/jscanify');
const { loadImage } = require('canvas');

const scanner = new JScanify();

scanner.loadOpenCV(async (cv) => {
  const image = await loadImage('document.jpg');

  // Extract the document (perspective corrected)
  const result = scanner.extractPaper(image, 800, 1000);

  // Or just highlight the detected document
  const highlighted = scanner.highlightPaper(image);
});
```

### Browser

```html
<script src="https://docs.opencv.org/4.7.0/opencv.js" async></script>
<script src="node_modules/@kt-solutions/jscanify/src/jscanify.js"></script>

<script>
  const scanner = new jscanify();

  // Wait for OpenCV to load
  cv['onRuntimeInitialized'] = () => {
    const image = document.getElementById('myImage');
    const result = scanner.extractPaper(image, 800, 1000);
    document.body.appendChild(result);
  };
</script>
```

### Configuration

```javascript
const scanner = new JScanify({
  maxWidthDiff: 0.30,    // Max top/bottom width difference (30%)
  maxHeightDiff: 0.30,   // Max left/right height difference (30%)
  minAreaRatio: 0.08,    // Minimum document area (8% of image)
  maxAreaRatio: 0.95,    // Maximum document area (95% of image)
});
```

## API

### `findPaperContour(img)`
Finds the document contour in an image. Returns the contour with metadata about which strategy was used.

### `highlightPaper(image, options)`
Highlights the detected document with a colored border.
- `options.color` - Border color (default: "orange")
- `options.thickness` - Border thickness (default: 10)

### `extractPaper(image, width, height, cornerPoints?)`
Extracts and perspective-corrects the detected document.
- `width` - Output width in pixels
- `height` - Output height in pixels
- `cornerPoints` - Optional custom corner points

### `getCornerPoints(contour)`
Returns the four corner points of a detected contour:
- `topLeftCorner`, `topRightCorner`, `bottomLeftCorner`, `bottomRightCorner`

## Original jscanify

For the original library, visit:
- GitHub: [ColonelParrot/jscanify](https://github.com/ColonelParrot/jscanify)
- npm: [jscanify](https://www.npmjs.com/package/jscanify)
- Documentation: [jscanify Wiki](https://github.com/ColonelParrot/jscanify/wiki)

## License

MIT License - Same as original jscanify

Copyright (c) ColonelParrot (original), KT Solutions (enhancements)