OpenCV 4.12.0
开源计算机视觉
加载中...
搜索中...
无匹配项
构建 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}'

Emscripten 的 2.0.10 版本已经过最新 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>。构建脚本默认构建 WebAssembly 版本（保留 --build_wasm 开关是为了向后兼容）。默认情况下，所有内容都通过 base64 编码 WebAssembly 代码捆绑到一个 JavaScript 文件中。对于生产构建，您可以添加 --disable_single_file，这将通过将 WebAssembly 代码写入专用的 .wasm 文件来减少总大小，生成的 JavaScript 文件将自动加载该文件。

    例如，要在 build_js 目录中构建

    emcmake python ./opencv/platforms/js/build_js.py build_js
    注意
    这需要在您的开发环境中安装 python 和 cmake。

  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 功能检测来检测浏览器的功能并自动加载相应的 OpenCV.js。要使用它，您需要使用 WebAssembly 功能检测的 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);

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

将 Web 浏览器导航到 https://:8080/tests.html，它会自动运行单元测试。命令示例

npx http-server build_js/bin
firefox https://:8080/tests.html
注意
此代码段和以下代码段需要安装 Node.js。

使用 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。您可以指定自己的 Chromium/Chrome 二进制文件，通过 PUPPETEER_EXECUTABLE_PATH=$(which google-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() 获取当前线程数。

    注意
    如果您想启用此优化，您应该构建 wasm 版本的 opencv.js。线程优化仅在浏览器中有效，在 node.js 中无效。您需要先使用您的浏览器启用 WebAssembly threads support 功能。例如，如果您使用 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.cn/docs/porting/simd.html。因此，您需要首先使用以下命令设置上游后端环境
    ./emsdk update
    ./emsdk install latest-upstream
    ./emsdk activate latest-upstream
    source ./emsdk_env.sh
    如果您想启用此优化，您应该构建 wasm 版本的 opencv.js。对于浏览器，您需要先启用 WebAssembly SIMD support 功能。例如，如果您使用 Chrome，请在 chrome://flags 中启用此标志。对于 Node.js，您需要使用标志 --experimental-wasm-simd 运行脚本。
    由最新的 LLVM 上游构建的 opencv.js 的 simd 版本可能无法与稳定的浏览器或旧版本的 Node.js 一起使用。请使用最新版本的不稳定浏览器或 Node.js 来获取新功能，例如 Chrome Dev。

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

    性能测试中现在有一些内核，如 cvtColor、resize 和 threshold。例如，如果您想测试 threshold，请将 Web 浏览器导航到 https://: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。以下 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
由 doxygen 1.12.0 于 2025 年 7 月 3 日星期四 12:14:36 为 OpenCV 生成