1Using OpenCV.js {#tutorial_js_usage}
2===============================
3
4Steps
5-----
6
7In 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](https://github.com/opencv/opencv/releases), 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/3.4.0/opencv.js](https://docs.opencv.org/3.4.0/opencv.js). Use `master` if you want the latest build). You can also build your own copy by following the tutorial on Build Opencv.js.
8
9### Create a web page
10
11First, let's create a simple web page that is able to upload an image.
12
13@code{.js}
14<!DOCTYPE html>
15<html>
16<head>
17<meta charset="utf-8">
18<title>Hello OpenCV.js</title>
19</head>
20<body>
21<h2>Hello OpenCV.js</h2>
22<div>
23  <div class="inputoutput">
24    <img id="imageSrc" alt="No Image" />
25    <div class="caption">imageSrc <input type="file" id="fileInput" name="file" /></div>
26  </div>
27</div>
28<script type="text/javascript">
29let imgElement = document.getElementById("imageSrc")
30let inputElement = document.getElementById("fileInput");
31inputElement.addEventListener("change", (e) => {
32  imgElement.src = URL.createObjectURL(e.target.files[0]);
33}, false);
34</script>
35</body>
36</html>
37@endcode
38
39To 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.
40
41@note It is a better practice to use a local web server to host the index.html.
42
43### Include OpenCV.js
44
45Set the URL of `opencv.js` to `src` attribute of \<script\> tag.
46
47@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.
48
49Example for synchronous loading:
50@code{.js}
51<script src="opencv.js" type="text/javascript"></script>
52@endcode
53
54You 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.
55
56Example for asynchronous loading
57@code{.js}
58<script async src="opencv.js" onload="onOpenCvReady();" type="text/javascript"></script>
59@endcode
60
61### Use OpenCV.js
62
63Once `opencv.js` is ready, you can access OpenCV objects and functions through `cv` object.
64
65For example, you can create a cv.Mat from an image by cv.imread.
66
67@note Because image loading is asynchronous, you need to put cv.Mat creation inside the `onload` callback.
68
69@code{.js}
70imgElement.onload = function() {
71  let mat = cv.imread(imgElement);
72}
73@endcode
74
75Many 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.
76
77In this tutorial, we just show a cv.Mat on screen. To show a cv.Mat, you need a canvas element.
78
79@code{.js}
80<canvas id="outputCanvas"></canvas>
81@endcode
82
83You can use cv.imshow to show cv.Mat on the canvas.
84@code{.js}
85cv.imshow("outputCanvas", mat);
86@endcode
87
88Putting all of the steps together, the final index.html is shown below.
89
90@code{.js}
91<!DOCTYPE html>
92<html>
93<head>
94<meta charset="utf-8">
95<title>Hello OpenCV.js</title>
96</head>
97<body>
98<h2>Hello OpenCV.js</h2>
99<p id="status">OpenCV.js is loading...</p>
100<div>
101  <div class="inputoutput">
102    <img id="imageSrc" alt="No Image" />
103    <div class="caption">imageSrc <input type="file" id="fileInput" name="file" /></div>
104  </div>
105  <div class="inputoutput">
106    <canvas id="canvasOutput" ></canvas>
107    <div class="caption">canvasOutput</div>
108  </div>
109</div>
110<script type="text/javascript">
111let imgElement = document.getElementById('imageSrc');
112let inputElement = document.getElementById('fileInput');
113inputElement.addEventListener('change', (e) => {
114  imgElement.src = URL.createObjectURL(e.target.files[0]);
115}, false);
116
117imgElement.onload = function() {
118  let mat = cv.imread(imgElement);
119  cv.imshow('canvasOutput', mat);
120  mat.delete();
121};
122
123function onOpenCvReady() {
124  document.getElementById('status').innerHTML = 'OpenCV.js is ready.';
125}
126</script>
127<script async src="opencv.js" onload="onOpenCvReady();" type="text/javascript"></script>
128</body>
129</html>
130@endcode
131
132@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](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/embind.html#memory-management) for details.
133
134Try it
135------
136\htmlonly
137<iframe src="../../js_setup_usage.html" width="100%"
138        onload="this.style.height=this.contentDocument.body.scrollHeight +'px';">
139</iframe>
140\endhtmlonly
141