OpenCV.jsのビルド

覚え書き

単に使い始めたいだけであれば、自分でコピーをビルドする必要はない。プリビルド済みのコピーをリリースまたはオンラインドキュメントから入手する手順については、Using Opencv.js チュートリアルを参照すること。

Emscripten のインストール

Emscripten は LLVM から JavaScript へのコンパイラである。OpenCV.js をビルドするために Emscripten を使用する。

覚え書き

ここでは必要なツールを最初からインストールする方法を説明するが、後述のセクションでは、同じビルドを docker コンテナを使って実行する代替手順についても説明しており、そちらのほうが多くの場合容易である。

Emscripten をインストールするには、Emscripten SDK の手順に従うこと。

例:

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

インストール後、EMSDK 環境が正しくセットアップされていることを確認する。

例:

source ./emsdk_env.sh
echo ${EMSDK}

最近のバージョンの Emscripten では、emcmake / emmake ランチャーを使用する必要がある。

emcmake sh -c 'echo ${EMSCRIPTEN}'

最新の WebAssembly については emscripten のバージョン 2.0.10 で検証済みである。WebAssembly の最新機能を使用するには Emscripten のバージョンを確認すること。

例:

./emsdk update
./emsdk install 2.0.10
./emsdk activate 2.0.10

OpenCV ソースコードの入手

最新の安定版 OpenCV を使用するか、Git リポジトリ から最新のスナップショットを取得できる。

最新の安定版 OpenCV の入手

• リリースページに移動する。
• ソースアーカイブをダウンロードして展開する。

Git リポジトリからの最新版 OpenCV の入手

Git クライアントを起動し、OpenCV リポジトリをクローンする。

例:

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

覚え書き

これには開発環境に git がインストールされている必要がある。

ソースからの OpenCV.js のビルド

1. opencv.js をビルドするには、python スクリプト <opencv_src_dir>/platforms/js/build_js.py <build_dir> を実行する。このビルドスクリプトはデフォルトで WebAssembly 版をビルドする（--build_wasm スイッチは後方互換性のために残されている）。デフォルトでは、WebAssembly コードを base64 エンコードして1つの JavaScript ファイルにすべてまとめる。本番ビルドでは --disable_single_file を追加でき、これにより WebAssembly コードを専用の .wasm ファイルに書き出し（生成された JavaScript ファイルが自動的に読み込む）、全体のサイズを削減できる。

   例えば、build_js ディレクトリにビルドするには次のようにする。

   emcmake python ./opencv/platforms/js/build_js.py build_js

   覚え書き

   • これには開発環境に python と cmake がインストールされている必要がある。
   • Emscripten 4.0.20 以降でビルドするには、–cmake_option="-DCMAKE_CXX_STANDARD=17" を追加する。Embind は Emscripten 4.0.20 以降では C++17 以降を必要とする。

     emcmake python ./opencv/platforms/js/build_js.py build_js --cmake_option="-DCMAKE_CXX_STANDARD=17"

2. [省略可能] OpenCV.js ローダーをビルドするには、--build_loader を追加する。

   例:

   emcmake python ./opencv/platforms/js/build_js.py build_js --build_loader

   覚え書き

   ローダーは <opencv_js_dir>/bin/loader.js のパスにある js ファイルとして実装されている。ローダーは WebAssembly Feature Detection を利用してブラウザの機能を検出し、対応する OpenCV.js を自動的に読み込む。これを使用するには、WebAssembly Feature Detection の UMD 版を使用し、Web アプリケーションに loader.js を導入する必要がある。

   コード例:

   // Set paths configuration
   let pathsConfig = {
       wasm: "../../build_wasm/opencv.js",
       threads: "../../build_mt/opencv.js",
       simd: "../../build_simd/opencv.js",
       threadsSimd: "../../build_mtSIMD/opencv.js",
   }
    
   // Load OpenCV.js and use the pathsConfiguration and main function as the params.
   loadOpenCV(pathsConfig, main);

3. [省略可能] ドキュメントをビルドするには、--build_doc オプションを追加する。

   例:

   emcmake python ./opencv/platforms/js/build_js.py build_js --build_doc

   覚え書き

   これには開発環境に doxygen がインストールされている必要がある。

4. [省略可能] テストをビルドするには、--build_test オプションを追加する。

   例:

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

5. [省略可能] OpenCV contrib モジュールを有効にするには --cmake_option="-DOPENCV_EXTRA_MODULES_PATH=/path/to/opencv_contrib/modules/" を追加する。

   例:

   emcmake python ./platforms/js/build_js.py build_js --cmake_option="-DOPENCV_EXTRA_MODULES_PATH=opencv_contrib/modules"

6. [省略可能] WebNN バックエンドを有効にするには、--webnn オプションを追加する。

   例:

   emcmake python ./opencv/platforms/js/build_js.py build_js --webnn

OpenCV.js テストの実行

前述のとおり、ビルドコマンドの起動時に --build_test を渡すことを忘れないこと。これにより、build_js/bin 内の opencv.js ファイルと一緒に実行できるテストのソースコードが生成される。

ブラウザで手動実行

テストを実行するには、\<build_dir\>/bin フォルダでローカル Web サーバを起動する。例えば、localhost:8080 で配信する node http-server などである。

Web ブラウザで http://localhost:8080/tests.html にアクセスすると、ユニットテストが自動的に実行される。コマンド例:

npx http-server build_js/bin
firefox http://localhost:8080/tests.html

覚え書き

このスニペットおよび以降のものでは Node.js がインストールされている必要がある。

Puppeteerによるヘッドレス実行

あるいは、テストは GoogleChrome/puppeteer を使って実行することもできる。これはターミナル上で動作するGoogle Chromeの一種である（travis CIなどの継続的インテグレーションで便利）

cd build_js/bin
npm install
npm install --no-save puppeteer    # automatically downloads Chromium package
node run_puppeteer.js

覚え書き

デバッグやレポート出力のためのその他のオプションについては node run_puppeteer --help を確認すること。

npm install コマンドはツールの依存関係をインストールするため、一度だけ実行すればよい。その後はすぐに使用できる。

Chromiumの自動ダウンロードをスキップするには PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=1 npm install --no-save puppeteer を使用する。環境変数 PUPPETEER_EXECUTABLE_PATH=$(which google-chrome) を通じて独自のChromium/Chromeバイナリを指定することもできる。注意: Puppeteerは同梱のChromiumでのみ動作が保証されている。それ以外の使用は自己責任で行うこと。

Node.jsの利用

例:

cd build_js/bin
npm install
node tests.js

覚え書き

すべてのテストが失敗する場合は、8.x系のNode.js（nvm の lts/carbon）の使用を検討すること。

1. [省略可能] opencv.js をスレッド最適化付きでビルドするには、--threads オプションを付加する。

   例:

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

   デフォルトのスレッド数は、使用しているデバイスの論理コア数である。cv.parallel_pthreads_set_threads_num(number) を使って自分でスレッド数を設定したり、cv.parallel_pthreads_get_threads_num() を使って現在のスレッド数を取得したりできる。

   覚え書き

   この最適化を有効にしたい場合は、opencv.js のwasm版をビルドする必要がある。また、スレッド最適化はブラウザでのみ動作し、node.jsでは動作しない。まずブラウザで WebAssembly threads support 機能を有効にする必要がある。例えばChromeを使用している場合は、chrome://flags でこのフラグを有効にすること。

2. [省略可能] opencv.js をwasm simd最適化付きでビルドするには、--simd オプションを付加する。

   例:

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

   wasm simdはまだ開発中であるため、simd最適化は実験的なものである。

   覚え書き

   現時点ではemscripten LLVM upstreamバックエンドのみがwasm simdをサポートしている。https://emscripten.org/docs/porting/simd.html を参照のこと。そのため、まず以下のコマンドでupstreamバックエンド環境をセットアップする必要がある:

   ./emsdk update
   ./emsdk install latest-upstream
   ./emsdk activate latest-upstream
   source ./emsdk_env.sh

   この最適化を有効にしたい場合は、opencv.js のwasm版をビルドする必要がある。ブラウザの場合は、まず WebAssembly SIMD support 機能を有効にする必要がある。例えばChromeを使用している場合は、chrome://flags でこのフラグを有効にすること。Node.jsの場合は、--experimental-wasm-simd フラグを付けてスクリプトを実行する必要がある。

   最新のLLVM upstreamでビルドされた opencv.js のsimd版は、安定版ブラウザや古いバージョンのNode.jsでは動作しない場合がある。Chrome Dev のような最新の不安定版ブラウザまたはNode.jsを使用して、新機能を利用すること。

3. [省略可能] wasm intrinsicsテストをビルドするには、--build_wasm_intrin_test オプションを付加する。

   例:

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

   wasm intrinsicsテストでは、以下の関数を使ってすべてのケースをテストできる:

   cv.test_hal_intrin_all()

   失敗したケースはJavaScriptのデバッグコンソールに記録される。

   wasm intrinsicsの単一データ型のみをテストしたい場合は、以下の関数を使用できる:

   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()

4. [省略可能] パフォーマンステストをビルドするには、--build_perf オプションを付加する。

   例:

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

   パフォーマンステストを実行するには、<build_dir>/bin フォルダでローカルWebサーバを起動する。例えば、localhost:8080 で配信するnode http-serverなど。

   パフォーマンステストには現在 cvtColor、resize、threshold といったカーネルがある。例えば threshold をテストしたい場合は、Webブラウザで http://localhost:8080/perf/perf_imgproc/perf_threshold.html にアクセスする。(1920x1080, CV_8UC1, THRESH_BINARY) のようなテストパラメータを入力し、Run ボタンをクリックしてケースを実行する。パラメータを入力しない場合は、このカーネルのすべてのケースが実行される。

   Node.jsを使ってテストを実行することもできる。

   例えば、パラメータ (1920x1080, CV_8UC1, THRESH_BINARY) で threshold を実行する:

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

Dockerを使ったOpenCV.jsのビルド

あるいは、同じビルドを docker コンテナを使って行うこともできる。これは特に非Linuxシステムにおいて、しばしばより簡単で信頼性が高い。システムに docker をインストールし、emscriptenビルド向けにクリーンで十分にテストされた環境を提供する一般的なコンテナを使用するだけでよい。このようなコンテナには、必要なツールの最新版がすべてインストールされている。

したがって、システムに docker がインストールされ、実行されていることを確認すること。以下のシェルスクリプトはLinuxとMacOSで動作するはずである:

git clone https://github.com/opencv/opencv.git
cd opencv
docker run --rm -v $(pwd):/src -u $(id -u):$(id -g) emscripten/emsdk emcmake python3 ./platforms/js/build_js.py build_js

Windowsでは以下のPowerShellコマンドを使用する:

docker run --rm --workdir /src -v "$(get-location):/src" "emscripten/emsdk" emcmake python3 ./platforms/js/build_js.py build_js

警告

この例ではemscriptenの最新版を使用している。ビルドが失敗する場合は、正常に動作することがわかっているバージョン 2.0.10 を以下のコマンドで試すとよい:

docker run --rm -v $(pwd):/src -u $(id -u):$(id -g) emscripten/emsdk:2.0.10 emcmake python3 ./platforms/js/build_js.py build_js

Windowsでは以下のPowerShellコマンドを使用する:

docker run --rm --workdir /src -v "$(get-location):/src" "emscripten/emsdk:2.0.10" emcmake python3 ./platforms/js/build_js.py build_js

Dockerを使ったドキュメントのビルド

ドキュメントをビルドするには doxygen がインストールされている必要がある。以下の内容で Dockerfile という名前のファイルを作成する:

FROM emscripten/emsdk:2.0.10
 
RUN apt-get update \
  && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends doxygen \
  && rm -rf /var/lib/apt/lists/*

次に、以下のコマンドでdockerイメージをビルドし、opencv-js-doc という名前を付ける（このコマンドは一度だけ実行すればよい）:

docker build . -t opencv-js-doc

次に、今度は新しいイメージを使い --build_doc を渡して、もう一度ビルドコマンドを実行する:

docker run --rm -v $(pwd):/src -u $(id -u):$(id -g) "opencv-js-doc" emcmake python3 ./platforms/js/build_js.py build_js --build_doc