OpenCV 4.11.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>。

    例如，要在build_js目录中构建

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

  2. 构建脚本默认情况下构建 asm.js 版本。要构建 WebAssembly 版本，请添加--build_wasm开关。默认情况下，所有内容都通过base64编码 WebAssembly 代码打包到一个 JavaScript 文件中。对于生产版本，您可以添加--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 功能检测来检测浏览器的功能并自动加载相应的 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 和主函数作为参数。
    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 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"

  7. [可选] 要启用 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://127.0.0.1:8080/tests.html，这将自动运行单元测试。命令示例

npx http-server build_js/bin
firefox https://127.0.0.1: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 的自动下载。您可以通过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

    由于 wasm simd 仍在开发中，因此 simd 优化是实验性的。

    注意
    目前只有 emscripten LLVM 上游后端支持 wasm simd，请参考https://emscripten.webassembly.net.cn/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 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://127.0.0.1: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
2025年1月8日星期三16:06:35 为 OpenCV 生成，由 doxygen 1.12.0 提供