| OpenCV 3.4.8 Open Source Computer Vision

Build OpenCV.js

## Installing Emscripten

Emscripten is an LLVM-to-JavaScript compiler. We will use Emscripten to build OpenCV.js.

Note
  While this describes installation of required tools from scratch, there's a section below also describing an alternative procedure to perform the same build using docker containers which is often easier.

To Install Emscripten, follow instructions of Emscripten SDK.

For example:

./emsdk update
./emsdk install latest
./emsdk activate latest

Note
  To compile to WebAssembly, you need to install and activate Binaryen with the `emsdk` command. Please refer to Developer's Guide for more details.

After install, ensure the `EMSCRIPTEN` environment is setup correctly.

For example:

source ./emsdk_env.sh
echo ${EMSCRIPTEN}

## Obtaining OpenCV Source Code

You can use the latest stable OpenCV version or you can grab the latest snapshot from our Git repository.

### Obtaining the Latest Stable OpenCV Version

- Go to our releases page.
- Download the source archive and unpack it.

### Obtaining the Cutting-edge OpenCV from the Git Repository

Launch Git client and clone OpenCV repository.

For example:

git clone https://github.com/opencv/opencv.git

Note
  It requires `git` installed in your development environment.

## Building OpenCV.js from Source

1. 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:

   cd opencv
   python ./platforms/js/build_js.py build_js
   Note
     It requires `python` and `cmake` installed in your development environment.

2. The build script builds asm.js version by default. To build WebAssembly version, append `--build_wasm` switch.

   For example, to build wasm version in `build_wasm` directory:

   python ./platforms/js/build_js.py build_wasm --build_wasm

3. [optional] To build documents, append `--build_doc` option.

   For example:

   python ./platforms/js/build_js.py build_js --build_doc
   Note
     It requires `doxygen` installed in your development environment.

4. [optional] To build tests, append `--build_test` option.

   For example:

   python ./platforms/js/build_js.py build_js --build_test

   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.

   You can also run tests using Node.js.

   For example:

   cd bin
   npm install
   node tests.js
   Note
     It requires `node` installed in your development environment.

5. [optional] To build `opencv.js` with threads optimization, append `--threads` option.

   For example:

   python ./platforms/js/build_js.py build_js --build_wasm --threads

   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.

   Note
     You should build wasm version of `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.

6. [optional] To build `opencv.js` with wasm simd optimization, append `--simd` option.

   For example:

   python ./platforms/js/build_js.py build_js --build_wasm --simd

   The simd optimization is experimental as wasm simd is still in development.

   Note
     Now only emscripten LLVM upstream backend supports wasm simd, refering to https://emscripten.org/docs/porting/simd.html. So you need to setup upstream backend environment with the following command first:
     ./emsdk update
     ./emsdk install latest-upstream
     ./emsdk activate latest-upstream
     source ./emsdk_env.sh
     You should build wasm version of `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`.
     The simd version of `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`.

7. [optional] To build wasm intrinsics tests, append `--build_wasm_intrin_test` option.

   For example:

   python ./platforms/js/build_js.py build_js --build_wasm --simd --build_wasm_intrin_test

   For wasm intrinsics tests, you can use the following function to test all the cases:

   cv.test_hal_intrin_all()

   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:

   cv.test_hal_intrin_uint8()
   cv.test_hal_intrin_int8()
   cv.test_hal_intrin_uint16()
   cv.test_hal_intrin_int16()
   cv.test_hal_intrin_uint32()
   cv.test_hal_intrin_int32()
   cv.test_hal_intrin_uint64()
   cv.test_hal_intrin_int64()
   cv.test_hal_intrin_float32()
   cv.test_hal_intrin_float64()

8. [optional] To build performance tests, append `--build_perf` option.

   For example:

   python ./platforms/js/build_js.py build_js --build_perf

   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)`:

   cd bin/perf
   npm install
   node perf_threshold.js --test_param_filter="(1920x1080, CV_8UC1, THRESH_BINARY)"

## Building OpenCV.js with Docker

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:

git clone https://github.com/opencv/opencv.git
cd opencv
docker run --rm --workdir /code -v "$PWD":/code "trzeci/emscripten:latest" python ./platforms/js/build_js.py build

In Windows use the following PowerShell command:

docker run --rm --workdir /code -v "$(get-location):/code" "trzeci/emscripten:latest" python ./platforms/js/build_js.py build

Warning
  The example uses latest version of emscripten. If the build fails you should try a version that is known to work fine which is `1.38.32` using the following command:

docker run --rm --workdir /code -v "$PWD":/code "trzeci/emscripten:sdk-tag-1.38.32-64bit" python ./platforms/js/build_js.py build

### Building the documentation with Docker

To build the documentation `doxygen` needs to be installed. Create a file named `Dockerfile` with the following content:

FROM trzeci/emscripten:sdk-tag-1.38.32-64bit
RUN apt-get update -y
RUN apt-get install -y doxygen

Then we build the docker image and name it `opencv-js-doc` with the following command (that needs to be run only once):

docker build . -t opencv-js-doc

Now run the build command again, this time using the new image and passing `--build_doc`:

docker run --rm --workdir /code -v "$PWD":/code "opencv-js-doc" python ./platforms/js/build_js.py build --build_doc