构建 OpenCV.js

注意

如果您只需开始使用，则不必构建自己的副本。参考 Opencv.js 使用教程，了解如何从我们的版本或在线文档中获取预构建副本。

安装 Emscripten

Emscripten 是 LLVM 到 JavaScript 编译器。我们将使用 Emscripten 构建 OpenCV.js。

注意

虽然此处说明如何从头开始安装所需工具，但下面还有一个章节描述了一种备选程序，使用 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}'

2.0.10 版本的 Emscripten 已验证用于最新的 WebAssembly。请检查 Emscripten 版本以使用 WebAssembly 的最新功能。

例如

./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>。

   例如，要构建在 build_js 目录中

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

   注意

   这需要在开发环境中安装 python 和 cmake。

2. 构建脚本默认构建 asm.js 版本。如要构建 WebAssembly 版本，添加 --build_wasm 开关。默认情况下，WebAssembly 代码将全部绑定到一个 JavaScript 文件，方法是使用 base64 对其进行编码。对于生产构建，你可以添加 disable_single_file，它会通过将 WebAssembly 代码写入专用 .wasm 文件（由生成 JavaScript 文件自动加载）来减小总大小。

   例如，在 build_wasm 目录中构建 wasm 版本

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

3. [可选] 如要构建 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。

   示例代码

   // 设置路径配置
   let pathsConfig = {
   wasm: "../../build_wasm/opencv.js",
   threads: "../../build_mt/opencv.js",
   simd: "../../build_simd/opencv.js",
   threadsSimd: "../../build_mtSIMD/opencv.js",
   }
    
   // 加载 OpenCV.js，并使用 pathsConfiguration 和 main 函数作为参数。
   loadOpenCV(pathsConfig, main);

4. [可选] 如要构建文档，添加 --build_doc 选项。

   例如

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

   注意

   它需要在你的开发环境中安装 doxygen。

5. [可选] 如要构建测试，添加 --build_test 选项。

   例如

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

6. [可选] 如要启用 OpenCV 贡献模块，添加 --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"

7. [可选] 如要启用 WebNN 后端，添加 --webnn 选项。

   例如

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

运行 OpenCV.js 测试

记得启动构建命令，并像前文提到的那样传递 --build_test。这会生成可以与 opencv.js 文件一起在 build_js/bin 中运行的测试源代码

在浏览器手动

如要运行测试，请在 <build_dir>/bin 文件夹中启动一个本地 Web 服务器。例如，在 localhost:8080 上运行的 node http-server。

在网页浏览器中导航到 http://localhost:8080/tests.html，自动运行单元测试。命令示例

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

注意

此代码段和以下内容需要安装 Node.js。

使用 Puppeteer 无头

或者，测试可以通过 GoogleChrome/puppeteer 运行，GoogleChrome/puppeteer 是在终端中运行的 Google Chrome 版本（对 travis CI 这样的持续集成很有用，等等）

cd build_js/bin
npm install
npm install --no-save puppeteer # 自动下载 Chromium 包
node run_puppeteer.js

注意

结帐 node run_puppeteer --help 了解有关调试和报告的更多选项。

命令 npm install 仅需执行一次，因为它安装了工具依赖项；之后即可准备就绪使用。

使用 PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=1 npm install --no-save puppeteer 跳过自动下载 Chromium。您可以通过 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 线程支持 功能。例如，如果您使用 Chrome，请在 chrome://flags 中启用此标志。

2. [可选] 要使用 wasm simd 优化构建 opencv.js，请附加 --simd 选项。

   例如

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

   simd 优化是实验性的，因为 wasm simd 仍处于开发阶段。

   注意

   现在，只有 emscripten LLVM 上游后端支持 wasm simd，请参考 https://emscripten.org/docs/porting/simd.html。因此，您需要先使用以下命令设置上游后端环境

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

   如果您希望启用此优化，则应构建 opencv.js 的 wasm 版本。对于浏览器，您首先需要启用 WebAssembly SIMD 支持 功能。例如，如果您使用 Chrome，请在 chrome://flags 中启用此标志。对于 Node.js，您需要使用标志 --experimental-wasm-simd 运行脚本。

   由最新 LLVM 上游构建的 opencv.js 的 simd 版本可能无法与稳定浏览器或旧版本的 Node.js 配合使用。请使用最新版本的非稳定浏览器或 Node.js 来获取新功能，例如 Chrome Dev。

3. [可选] 要构建 wasm 内在函数测试，请附加 --build_wasm_intrin_test 选项。

   例如

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

   对于 wasm 函数测试，可以使用以下函数测试所有案例

   cv.test_hal_intrin_all()

   失败的案例将记录在 JavaScript 调试控制台中。

   如果只想测试单个数据类型的 wasm 函数，可以使用以下函数

   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 服务器。例如，node http-server 在 localhost:8080 上提供服务。

   现在性能测试中有一些内核，例如 cvtColor、resize 和 threshold。例如，如果您想测试 threshold，请将 Web 浏览器导航到 http://localhost:8080/perf/perf_imgproc/perf_threshold.html。您需要输入诸如 (1920x1080, CV_8UC1, THRESH_BINARY) 的测试参数，然后点击 运行 按钮来运行案例。如果您不输入参数，它将运行此内核的所有案例。

   您还可以使用 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。以下 shell 脚本应适用于 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