jscanify

You can install jscanify using npm for Node.js/bundler environments, or include it via a CDN for direct browser usage.

Important: If using the CDN, you must also include opencv.js and load it asynchronously, as jscanify is powered by OpenCV.js.

// npm
$ npm i jscanify
import jscanify from 'jscanify'

<!-- cdn -->
<script src="https://docs.opencv.org/4.7.0/opencv.js" async></script>
<!-- warning: loading OpenCV can take some time. Load asynchronously -->
<script src="https://cdn.jsdelivr.net/gh/ColonelParrot/jscanify@master/src/jscanify.min.js"></script>

To ensure optimal results with jscanify:

• Environment: Place the paper on a flat surface with a solid background color.
• Initialization: Wrap your code in a window load event listener to ensure opencv.js is fully loaded before attempting to instantiate jscanify.
• Node.js: Note that usage on NodeJS differs from the browser implementation.

To use jscanify in a Node.js environment, you must instantiate the jscanify class and then call loadOpenCV to asynchronously load the OpenCV runtime. The loadOpenCV method accepts a callback that is executed once the OpenCV runtime is fully initialized.

Note that the constructor automatically sets up a simulated DOM environment using jsdom and canvas to ensure compatibility with OpenCV's expectations.

To implement real-time paper detection, capture frames from a <video> element using getUserMedia, draw them to a hidden <canvas>, and pass that canvas to scanner.highlightPaper(). Use setInterval to create a continuous loop for the highlighting effect.

<video id="video"></video> <canvas id="canvas"></canvas>
<!-- original video -->
<canvas id="result"></canvas>
<!-- highlighted video -->

const scanner = new jscanify();
const canvasCtx = canvas.getContext("2d");
const resultCtx = result.getContext("2d");
navigator.mediaDevices.getUserMedia({ video: true }).then((stream) => {
  video.srcObject = stream;
  video.onloadedmetadata = () => {
    video.play();

    setInterval(() => {
      canvasCtx.drawImage(video, 0, 0);
      const resultCanvas = scanner.highlightPaper(canvas);
      resultCtx.drawImage(resultCanvas, 0, 0);
    }, 10);
  };
});

Use the extractPaper method to detect a piece of paper and perform distortion correction (scanning) to produce a rectified rectangular image. You must provide the desired paperWidth and paperHeight for the output.

const scanner = new jscanify();
const paperWidth = 500;
const paperHeight = 1000;
image.onload = function () {
  const resultCanvas = scanner.extractPaper(image, paperWidth, paperHeight);
  document.body.appendChild(resultCanvas);
};

Use the highlightPaper method to detect a piece of paper within an image and return a canvas with the paper's edges highlighted. This is useful for visual feedback to the user.

const scanner = new jscanify();
image.onload = function () {
  const highlightedCanvas = scanner.highlightPaper(image);
  document.body.appendChild(highlightedCanvas);
};

Use highlightPaper(image, options) to return an HTMLCanvasElement that displays the original image with a colored outline drawn around the detected paper contour. This is useful for providing visual feedback to users about what the library has detected.

Options:

• color (string): The stroke color (e.g., `

The findPaperContour method uses Canny edge detection, Gaussian blurring, and Otsu thresholding to locate the largest contour in an image, which is assumed to be the paper.

Parameters:

• img: The input image to process (must be a cv.Mat).

Returns: The largest cv.Mat representing the contour, or null if no contour is found.

The findPaperContour(img) method uses OpenCV.js to find the largest contour in a provided cv.Mat object, which is assumed to be the paper. It performs Canny edge detection, Gaussian blurring, and Otsu thresholding to isolate the contour.

Note: This method requires cv (OpenCV.js) to be available in the global scope.

The getCornerPoints method calculates the four extreme corners (top-left, top-right, bottom-left, and bottom-right) of a given contour based on its bounding box and center point.

Parameters:

• contour: The contour to process (must be a cv.Mat).

Returns: An object containing four points, each with x and y properties:

• topLeftCorner
• topRightCorner
• bottomLeftCorner
• bottomRightCorner