js_usage.markdown



Using OpenCV.js {#tutorial_js_usage}

Steps
In this tutorial, you will learn how to include and start to use opencv.js inside a web page.

Create a web page
First, let's create a simple web page that is able to upload an image.
@code{.js}


Hello OpenCV.js


Hello OpenCV.js

  
    imageSrc 
  

@endcode
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.
Example for synchronous loading:
@code{.js}

@endcode
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
@code{.js}

@endcode

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.
@code{.js}
imgElement.onload = function() {
let mat = cv.imread(imgElement);
}
@endcode
Many OpenCV functions can be used to process cv.Mat. You can refer to other tutorials, such as @ref tutorial_js_table_of_contents_imgproc, for details.
In this tutorial, we just show a cv.Mat on screen. To show a cv.Mat, you need a canvas element.
@code{.js}

@endcode
You can use cv.imshow to show cv.Mat on the canvas.
@code{.js}
cv.imshow(mat, "outputCanvas");
@endcode
Putting all of the steps together, the final index.html is shown below.
@code{.js}


Hello OpenCV.js


Hello OpenCV.js
OpenCV.js is loading...

  
    imageSrc 
  
  
    canvasOutput
  

@endcode
@note You have to call delete method of cv.Mat to free memory allocated in Emscripten's heap. Please refer to Memeory management of Emscripten for details.

Try it
\htmlonly


\endhtmlonly