Steps

In this tutorial, you will learn how to include and start to use opencv.js inside a web page. You can get a copy of opencv.js from opencv-{VERSION_NUMBER}-docs.zip in each release, or simply download the prebuilt script from the online documentations at "https://docs.opencv.org/{VERSION_NUMBER}/opencv.js" (For example, https://docs.opencv.org/4.5.0/opencv.js. Use 4.x if you want the latest build). You can also build your own copy by following the tutorial Build OpenCV.js.

Create a web page

First, let's create a simple web page that is able to upload an image.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Hello OpenCV.js</title>
</head>
<body>
<h2>Hello OpenCV.js</h2>
<div>
  <div class="inputoutput">
    <img id="imageSrc" alt="No Image" />
    <div class="caption">imageSrc <input type="file" id="fileInput" name="file" /></div>
  </div>
</div>
<script type="text/javascript">
let imgElement = document.getElementById("imageSrc")
let inputElement = document.getElementById("fileInput");
inputElement.addEventListener("change", (e) => {
  imgElement.src = URL.createObjectURL(e.target.files[0]);
}, false);
</script>
</body>
</html>

To run this web page, copy the content above and save to a local index.html file. To run it, open it using your web browser.

Note: It is a better practice to use a local web server to host the index.html.

Include OpenCV.js

Set the URL of opencv.js to src attribute of <script> tag.

Note: For this tutorial, we host opencv.js at same folder as index.html. You can also choose to use the URL of the prebuilt opencv.js in our online documentation.

Example for synchronous loading:

You may want to load opencv.js asynchronously by async attribute in <script> tag. To be notified when opencv.js is ready, you can register a callback to onload attribute.

Example for asynchronous loading

Use OpenCV.js

Once opencv.js is ready, you can access OpenCV objects and functions through cv object.

For example, you can create a cv.Mat from an image by cv.imread.

Note: Because image loading is asynchronous, you need to put cv.Mat creation inside the onload callback.

imgElement.onload = function() {
  let mat = cv.imread(imgElement);
}

Many OpenCV functions can be used to process cv.Mat. You can refer to other tutorials, such as Image Processing, for details.

In this tutorial, we just show a cv.Mat on screen. To show a cv.Mat, you need a canvas element.

You can use cv.imshow to show cv.Mat on the canvas.

cv.imshow("outputCanvas", mat);

Putting all of the steps together, the final index.html is shown below.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Hello OpenCV.js</title>
</head>
<body>
<h2>Hello OpenCV.js</h2>
<p id="status">OpenCV.js is loading...</p>
<div>
  <div class="inputoutput">
    <img id="imageSrc" alt="No Image" />
    <div class="caption">imageSrc <input type="file" id="fileInput" name="file" /></div>
  </div>
  <div class="inputoutput">
    <canvas id="canvasOutput" ></canvas>
    <div class="caption">canvasOutput</div>
  </div>
</div>
<script type="text/javascript">
let imgElement = document.getElementById('imageSrc');
let inputElement = document.getElementById('fileInput');
inputElement.addEventListener('change', (e) => {
  imgElement.src = URL.createObjectURL(e.target.files[0]);
}, false);
 
imgElement.onload = function() {
  let mat = cv.imread(imgElement);
  cv.imshow('canvasOutput', mat);
  mat.delete();
};
 
var Module = {
  // https://emscripten.org/docs/api_reference/module.html#Module.onRuntimeInitialized
  onRuntimeInitialized() {
    document.getElementById('status').innerHTML = 'OpenCV.js is ready.';
  }
};
</script>
<script async src="opencv.js" type="text/javascript"></script>
</body>
</html>

Note: You have to call delete method of cv.Mat to free memory allocated in Emscripten's heap. Please refer to Memory management of Emscripten for details.

Steps

Create a web page

Include OpenCV.js

Use OpenCV.js

Try it