OpenCV  3.4.8-pre
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

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.

    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