opencv-featurematch-js is a JavaScript library for feature-based image alignment in the browser, built on OpenCV.js. Given two images, it finds matching features, computes a homography between them, returning a transform used to warp one image onto the other.
Useful anywhere two overlapping images need to be lined up automatically - panorama/mosaic stitching, burst-sequence or time-lapse alignment, augmented reality overlays, document/whiteboard scanning, object tracking, or motion tracking across frames.
Originally adapted from Scott Suhy's Image Alignment (Feature Based) in OpenCV.js tutorial.
This example is written for p5.js and can be run in the browser.
let bastoncini, bastoncini_in_scene;
let result;
function preload() {
bastoncini = loadImage('images/bastoncini.png');
bastoncini_in_scene = loadImage('images/bastoncini_in_scene.png');
}
async function setup() {
createCanvas(800, 400, WEBGL);
await featurematchReady();
const options = {};
result = alignImages(bastoncini.canvas, bastoncini_in_scene.canvas, options);
console.log(result);
}
function draw() {
background(220);
translate(-width/2, -height/2);
image(bastoncini, 0, 0);
push();
translate(bastoncini.width, 0);
image(bastoncini_in_scene, 0, 0);
if (result && result.valid) {
applyMatrix(result.transform);
noFill();
strokeWeight(3);
stroke('green');
rect(0, 0, bastoncini.width, bastoncini.height);
}
pop();
}await featurematchReady() waits until the feature-matching is ready, this also requires both the OpenCv and Shimage libraries to be loaded succesfully.
alignImages(imageA, imageB, options) computes the alignment of the images, a 3D transform that will map imageA's own coordinate space into imageB's directly. Internally, the OpenCV pipeline detects KAZE features in both images, matches them with a kNN matcher, keeps the confident matches, and fits a homography between them with cv.findHomography (RANSAC).
The returned result object:
valid- whether the fitted homography passed the thresholds set byoptionsbelowtransform- a flat 16-element column-major 4x4 matrix (the same layout WebGL/OpenGL use natively). Populated as soon as any homography is found at all, even on an otherwise-invalid result - onlynullif no homography was foundinlierMatches/outlierMatches- the underlying point correspondences, each an array of[[xA, yA], [xB, yB]]pairs in that image's own pixel coordinates;inlierMatchesare the ones RANSAC kept,outlierMatchesthe ones it rejectedreason- why an invalid result was rejected (or'OK')
options assed to alignImages:
maxRotationDeg- max allowed rotation in degrees (default: unbounded)maxScale- max allowed scale factor, n - the homography can be up to nx bigger or nx smaller (default3)maxShear- max allowed shear (default0.5)maxPerspective- max allowed perspective distortion (default0.01)precision- decimal places to roundinlierMatches/outlierMatchescoordinates to (default0, i.e. whole pixels)
<!DOCTYPE html>
<html lang="en">
<head>
<script src="https://cdn.jsdelivr.net/npm/p5@1.11.13/lib/p5.js"></script>
<script src="https://cdn.jsdelivr.net/npm/p5@1.11.13/lib/addons/p5.sound.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/davidchatting/shimage@latest/shimage.js"></script>
<script src="https://cdn.jsdelivr.net/gh/davidchatting/cdn/opencv/4.5.1/opencv.js"></script>
<script src="https://cdn.jsdelivr.net/gh/davidchatting/opencv-featurematch-js@latest/opencv-featurematch-js.min.js"></script>
<link rel="stylesheet" type="text/css" href="style.css">
<meta charset="utf-8" />
</head>
<body>
<main>
</main>
<script src="sketch.js"></script>
</body>
</html>A minimised version of opencv-featurematch-js, built automatically via build.yml, is distributed via CDN:
https://cdn.jsdelivr.net/gh/davidchatting/opencv-featurematch-js@latest/opencv-featurematch-js.min.js
opencv-featurematch-js depends on both opencv.js and shimage.js, and the example requires p5.js.
This repository automatically synchronises with the p5.js editor, where the example code in the p5js/ folder is maintained. Using the github workflows, build.yml automatically downloads the sketch's files via the editor's export API, commit them into the repo, and insert the content into the code blocks in this README. The reference for the p5.js sketch is held in the package.json homepage field.
MIT - see LICENSE.