@kt-solutions/jscanify

Enhanced JavaScript document scanner with multi-strategy detection for improved accuracy.

Credits

This is an enhanced fork of 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

npm install @kt-solutions/jscanify

Usage

Node.js

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

<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

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
• npm: jscanify
• Documentation: jscanify Wiki

License

MIT License - Same as original jscanify

Copyright (c) ColonelParrot (original), KT Solutions (enhancements)