OpenCV
4.9.0
Open Source Computer Vision
|
Emscripten is an LLVM-to-JavaScript compiler. We will use Emscripten to build OpenCV.js.
To Install Emscripten, follow instructions of Emscripten SDK.
For example:
After install, ensure the EMSDK
environment is setup correctly.
For example:
Modern versions of Emscripten requires to use emcmake
/ emmake
launchers:
The version 2.0.10 of emscripten is verified for latest WebAssembly. Please check the version of Emscripten to use the newest features of WebAssembly.
For example:
You can use the latest stable OpenCV version or you can grab the latest snapshot from our Git repository.
Launch Git client and clone OpenCV repository.
For example:
git
installed in your development environment.To build opencv.js
, execute python script <opencv_src_dir>/platforms/js/build_js.py <build_dir>
.
For example, to build in build_js
directory:
python
and cmake
installed in your development environment.The build script builds asm.js version by default. To build WebAssembly version, append --build_wasm
switch. By default everything is bundled into one JavaScript file by base64
encoding the WebAssembly code. For production builds you can add --disable_single_file
which will reduce total size by writing the WebAssembly code to a dedicated .wasm
file which the generated JavaScript file will automatically load.
For example, to build wasm version in build_wasm
directory:
[Optional] To build the OpenCV.js loader, append --build_loader
.
For example:
<opencv_js_dir>/bin/loader.js
. The loader utilizes the WebAssembly Feature Detection to detect the features of the browser and load corresponding OpenCV.js automatically. To use it, you need to use the UMD version of WebAssembly Feature Detection and introduce the loader.js
in your Web application.Example Code:
[optional] To build documents, append --build_doc
option.
For example:
doxygen
installed in your development environment.[optional] To build tests, append --build_test
option.
For example:
[optional] To enable OpenCV contrib modules append --cmake_option="-DOPENCV_EXTRA_MODULES_PATH=/path/to/opencv_contrib/modules/"
For example:
[optional] To enable WebNN backend, append --webnn
option.
For example:
Remember to launch the build command passing --build_test
as mentioned previously. This will generate test source code ready to run together with opencv.js
file in build_js/bin
To run tests, launch a local web server in \<build_dir\>/bin
folder. For example, node http-server which serves on localhost:8080
.
Navigate the web browser to http://localhost:8080/tests.html
, which runs the unit tests automatically. Command example:
Alternatively tests can run with GoogleChrome/puppeteer which is a version of Google Chrome that runs in the terminal (useful for Continuous integration like travis CI, etc)
node run_puppeteer --help
for more options to debug and reporting.npm install
only needs to be executed once, since installs the tools dependencies; after that they are ready to use.PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=1 npm install --no-save puppeteer
to skip automatic downloading of Chromium. You may specify own Chromium/Chrome binary through PUPPETEER_EXECUTABLE_PATH=$(which google-chrome)
environment variable. BEWARE: Puppeteer is only guaranteed to work with the bundled Chromium, use at your own risk.For example:
lts/carbon
from nvm
).[optional] To build opencv.js
with threads optimization, append --threads
option.
For example:
The default threads number is the logic core number of your device. You can use cv.parallel_pthreads_set_threads_num(number)
to set threads number by yourself and use cv.parallel_pthreads_get_threads_num()
to get the current threads number.
opencv.js
if you want to enable this optimization. And the threads optimization only works in browser, not in node.js. You need to enable the WebAssembly threads support
feature first with your browser. For example, if you use Chrome, please enable this flag in chrome://flags.[optional] To build opencv.js
with wasm simd optimization, append --simd
option.
For example:
The simd optimization is experimental as wasm simd is still in development.
opencv.js
if you want to enable this optimization. For browser, you need to enable the WebAssembly SIMD support
feature first. For example, if you use Chrome, please enable this flag in chrome://flags. For Node.js, you need to run script with flag --experimental-wasm-simd
.opencv.js
built by latest LLVM upstream may not work with the stable browser or old version of Node.js. Please use the latest version of unstable browser or Node.js to get new features, like Chrome Dev
.[optional] To build wasm intrinsics tests, append --build_wasm_intrin_test
option.
For example:
For wasm intrinsics tests, you can use the following function to test all the cases:
And the failed cases will be logged in the JavaScript debug console.
If you only want to test single data type of wasm intrinsics, you can use the following functions:
[optional] To build performance tests, append --build_perf
option.
For example:
To run performance tests, launch a local web server in <build_dir>/bin folder. For example, node http-server which serves on localhost:8080
.
There are some kernels now in the performance test like cvtColor
, resize
and threshold
. For example, if you want to test threshold
, please navigate the web browser to http://localhost:8080/perf/perf_imgproc/perf_threshold.html
. You need to input the test parameter like (1920x1080, CV_8UC1, THRESH_BINARY)
, and then click the Run
button to run the case. And if you don't input the parameter, it will run all the cases of this kernel.
You can also run tests using Node.js.
For example, run threshold
with parameter (1920x1080, CV_8UC1, THRESH_BINARY)
:
Alternatively, the same build can be can be accomplished using docker containers which is often easier and more reliable, particularly in non linux systems. You only need to install docker on your system and use a popular container that provides a clean well tested environment for emscripten builds like this, that already has latest versions of all the necessary tools installed.
So, make sure docker is installed in your system and running. The following shell script should work in Linux and MacOS:
In Windows use the following PowerShell command:
2.0.10
using the following command:In Windows use the following PowerShell command:
To build the documentation doxygen
needs to be installed. Create a file named Dockerfile
with the following content:
Then we build the docker image and name it opencv-js-doc
with the following command (that needs to be run only once):
Now run the build command again, this time using the new image and passing --build_doc
: