OpenCV GitHub 入门指南 – wiki基地

作者： /

OpenCV GitHub 入门指南：从源代码构建与探索

OpenCV（Open Source Computer Vision Library）是计算机视觉领域最常用、功能最强大的开源库之一。无论是图像处理、目标检测、视频分析，还是机器学习，OpenCV 都提供了丰富的函数和工具。对于大多数用户而言，通过包管理器（如 pip, apt, brew）或下载官方预编译版本即可开始使用。然而，直接从 OpenCV 的 GitHub 仓库获取源代码并进行构建，提供了更深入的了解、更灵活的配置以及访问最新功能或贡献代码的机会。

本指南将带你详细了解如何从 OpenCV 的 GitHub 仓库入手，包括获取代码、理解仓库结构、进行源代码构建、配置和使用，以及如何参与社区。这不仅是获取最新版 OpenCV 的一种方式，更是深入学习其内部工作原理、进行高级定制和问题排查的基础。

1. 为什么选择从 GitHub 获取 OpenCV 源代码？

虽然预编译版本方便快捷，但从 GitHub 获取源代码有其独特的优势：

  • 获取最新功能与修复： GitHub 仓库包含了 OpenCV 最活跃的开发分支（通常是 master 或 main），你可以第一时间体验到最新的算法、性能优化和 bug 修复，这对于追求前沿技术的开发者尤为重要。
  • 灵活的构建配置： 源代码构建允许你根据自己的需求定制 OpenCV 的功能。例如，你可以选择是否包含特定模块（如 contrib 模块中的额外算法）、启用或禁用硬件加速（如 CUDA, OpenCL）、集成特定的第三方库，或生成 Debug 版本用于调试。
  • 深入学习与调试： 直接访问源代码使你能够查看函数的实现细节、理解算法流程。当遇到问题时，你可以轻松地在 IDE 中设置断点，单步调试 OpenCV 的内部代码，这对于定位复杂问题非常有帮助。
  • 参与社区贡献： 如果你希望为 OpenCV 贡献代码、修复 Bug 或添加新功能，从 GitHub Fork 仓库是第一步。
  • 支持特定平台或编译器： 对于一些非主流的操作系统、硬件平台或编译器版本，可能没有官方提供的预编译版本，此时从源代码构建是唯一的选择。

简而言之，从 GitHub 入手 OpenCV 源代码，赋予了你更大的控制权和更广阔的视野。

2. 入门前的准备工作

在开始之前，你需要准备好一些基础工具和环境：

  • Git： 一个分布式版本控制系统，用于从 GitHub 克隆（Clone）仓库、管理代码版本。
  • CMake： 一个跨平台的开源构建系统生成工具。OpenCV 使用 CMake 来管理其复杂的构建过程，它可以根据你的系统和配置生成针对特定构建工具（如 Makefile, Visual Studio 项目文件, Ninja）的工程文件。
  • C++ 编译器和构建工具： OpenCV 主要由 C++ 编写，你需要一个 C++ 编译器以及配套的构建工具来编译代码。
    • Windows: Visual Studio (社区版免费)，安装时请确保勾选“使用 C++ 的桌面开发”工作负载。
    • Linux: G++ 或 Clang，以及 Make 或 Ninja。通常安装 build-essential 包可以满足大部分需求。
    • macOS: Xcode Command Line Tools (包含了 Clang 和 Make) 或通过 Homebrew 安装 GCC/Clang 和 Ninja。
  • （可选）Python 及 NumPy： 如果你需要编译和使用 OpenCV 的 Python 接口（cv2 模块），你需要安装 Python 和 NumPy。
  • （可选）其他依赖库的开发文件： OpenCV 依赖许多第三方库来实现图像/视频编解码、GUI、优化等功能。例如 libjpeg, libpng, libtiff, FFmpeg, GStreamer, GTK+, Qt 等。在 Linux/macOS 上，你需要安装这些库的开发包（通常以 -dev 或 -devel 结尾）。CMake 会自动检查这些依赖，并提示哪些是缺失的。

请确保以上工具已正确安装并配置到系统环境变量中，以便在命令行中直接调用。

3. 获取 OpenCV 源代码

OpenCV 的核心仓库位于：https://github.com/opencv/opencv

另外，OpenCV 还有一个重要的附加模块仓库，包含了一些非核心或仍在实验阶段的功能，如 Contrib 模块：https://github.com/opencv/opencv_contrib

通常情况下，如果你想使用 OpenCV 的全部功能，你需要同时克隆这两个仓库。

使用 Git 克隆仓库到本地：

  1. 打开终端或命令提示符。
  2. 选择一个合适的目录用于存放源代码。

  3. 执行克隆命令：

    “`bash

    克隆 OpenCV 主仓库

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

    进入主仓库目录

    cd opencv

    克隆 OpenCV Contrib 仓库（通常与主仓库放在同一父目录下，或者根据你的需要指定位置）

    建议将 contrib 仓库克隆到与 opencv 仓库同级的目录中，方便后续 CMake 配置

    cd .. # 返回上一级目录，与 opencv 仓库同级
    git clone https://github.com/opencv/opencv_contrib.git
    “`

现在，你已经在本地拥有了 OpenCV 及其 contrib 模块的源代码。你可以使用 git status 查看当前分支状态，使用 git log 查看提交历史，或者使用 git checkout <tag_name> 切换到特定的版本标签（例如 4.5.5, 4.6.0 等）来获取稳定版本的代码。建议初学者先尝试构建最新的 master 分支，或者一个最新的稳定标签。

4. 理解 OpenCV 仓库结构

在开始构建之前，快速浏览一下 opencv 和 opencv_contrib 仓库的目录结构非常有益：

opencv 仓库主要目录：

  • 3rdparty/: 包含 OpenCV 依赖的一些第三方库的源代码，如果系统没有安装这些库，CMake 会选择编译这里的版本。
  • apps/: 包含一些简单的示例应用程序，如 OpenCV 官方文档生成工具等。
  • cmake/: 包含 CMake 构建系统所需的脚本和配置文件。
  • data/: 包含一些数据文件，比如用于人脸检测的 Haar 和 LBP 分类器 XML 文件。
  • doc/: 文档相关的源文件。
  • include/: OpenCV 的 C++ 头文件目录。构建完成后，这些文件会被安装到系统的指定位置。
  • modules/: 这是 OpenCV 核心模块的目录。每个子目录（如 core, imgproc, highgui, videoio, objdetect 等）代表一个功能模块，包含了该模块的源代码、头文件和 CMake 配置。
  • platforms/: 包含针对不同平台（如 iOS, Android）的构建脚本和配置。
  • samples/: 非常重要的目录！ 包含了大量使用 OpenCV 各个功能的示例代码（C++, Python 等），是学习如何使用 OpenCV 的绝佳资源。
  • src/: 包含一些公共的源文件。
  • tests/: 包含 OpenCV 各个模块的单元测试和性能测试代码。
  • CMakeLists.txt: 仓库根目录下的主要 CMake 脚本，定义了整个项目的构建规则。
  • README.md: 项目说明文件，通常包含构建、安装和使用简介。
  • LICENSE: 许可文件。
  • CONTRIBUTING.md: 贡献指南，说明如何为项目做贡献。

opencv_contrib 仓库主要目录：

  • modules/: 包含 Contrib 模块的源代码。结构与主仓库的 modules/ 类似，每个子目录（如 xfeatures2d, tracking, face, text 等）是一个独立的模块。
  • cmake/: Contrib 模块所需的 CMake 脚本。
  • README.md: Contrib 仓库说明。

了解这些目录结构，有助于你在构建过程中查找文件、理解错误信息，以及在学习时找到示例代码。

5. 源代码构建过程详解

源代码构建是整个过程的核心，也是对初学者来说可能最具挑战性的部分。我们将详细介绍使用 CMake 构建 OpenCV 的通用步骤，并提供在不同操作系统上的具体指导。

构建的基本流程：

  1. 创建构建目录： 强烈建议进行“out-of-source”构建，即在源代码目录 之外 创建一个独立的目录用于存放构建生成的文件（包括编译产生的中间文件、可执行文件、库文件等）。这样做可以保持源代码目录的整洁，方便清理构建结果，并且允许多个不同的构建配置（例如 Debug 和 Release）共存。
  2. 运行 CMake 配置： 在构建目录中运行 CMake，指向源代码目录，并指定构建选项（如是否包含 contrib 模块、是否启用 CUDA 等）和生成器（Generator，指定使用哪种构建工具）。CMake 会检查系统环境、依赖库，并生成构建工具所需的工程文件。
  3. 运行构建工具进行编译： 使用 CMake 生成的工程文件，调用相应的构建工具（如 make, msbuild, ninja）开始编译源代码。这是一个耗时较长的过程。
  4. 运行安装目标： 编译成功后，运行安装目标（通常是 install）将编译好的库文件、头文件、可执行文件等复制到指定的安装目录。

现在，我们来看具体操作：

首先，进入你克隆的 opencv 仓库的父目录。例如，如果你的 opencv 和 opencv_contrib 仓库都在 /home/user/dev/opencv_sources/ 目录下：

bash
cd /home/user/dev/opencv_sources/opencv

接下来，在 opencv 目录 内部 或 外部 创建一个构建目录。通常选择在内部创建，例如 build 目录：

bash
mkdir build
cd build

现在，你已经在 opencv/build 目录中。接下来的 CMake 配置和构建步骤都在这个目录中进行。

5.1. 运行 CMake 配置

在构建目录中，运行 cmake 命令。基本的格式是：

bash
cmake [选项] <OpenCV 源代码目录路径>

因为你已经在 opencv/build 目录中，源代码目录是它的上一级目录，所以可以使用 .. 表示。

基本配置命令（不带 contrib）：

bash
cmake ..

这将使用默认选项配置构建，并尝试找到系统已安装的依赖库。CMake 会输出大量信息，显示检测到的系统信息、启用的模块、找到的依赖库等。仔细阅读这些输出，特别是红色或橙色的警告信息，它们通常指示了缺少依赖或潜在问题。

启用 Contrib 模块的配置命令：

这是常见的需求。你需要通过 OPENCV_EXTRA_MODULES_PATH 选项告诉 CMake Contrib 模块的位置。假设你的 opencv_contrib 仓库和 opencv 仓库在同一父目录下，那么 opencv_contrib 仓库的 modules 目录路径通常是 ../../opencv_contrib/modules (相对于 opencv/build 目录)。

bash
cmake -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules ..

请根据你实际存放 opencv_contrib 仓库的位置调整 ../../opencv_contrib/modules 的路径。

常用 CMake 选项：

CMake 提供了大量的选项来定制构建过程。你可以使用 -D <OptionName>=<Value> 的形式来设置选项。一些常用选项包括：

  • -D CMAKE_BUILD_TYPE=Release：指定构建类型。Release 版本会启用优化，生成的文件更小，运行速度更快，但难以调试。Debug 版本包含调试信息，不进行优化，文件较大，运行较慢，但便于调试。默认通常是 Debug 或 None。生产环境建议使用 Release。
  • -D CMAKE_INSTALL_PREFIX=/path/to/install：指定 OpenCV 编译后安装的目录。如果不指定，默认安装到系统标准位置（如 /usr/local 或 C:/Program Files 下）。
  • -D BUILD_EXAMPLES=ON：构建示例代码（默认是 OFF）。强烈建议开启，示例是学习的最佳起点。
  • -D BUILD_TESTS=ON：构建测试代码（默认是 OFF）。用于验证构建是否成功以及OpenCV功能是否正常。
  • -D WITH_CUDA=ON：启用 CUDA 加速（需要系统安装有支持的 NVIDIA 显卡、CUDA Toolkit 和 cuDNN）。这是一个复杂的选项，可能需要额外的配置。
  • -D WITH_FFMPEG=ON：启用 FFmpeg 支持，用于处理各种视频格式。
  • -D WITH_GSTREAMER=ON：启用 GStreamer 支持（主要在 Linux 上），也用于视频处理。
  • -D WITH_QT=ON：启用 Qt 支持，可以提供更丰富的 GUI 功能（如 imshow 显示窗口，需要安装 Qt 开发包）。
  • -D BUILD_opencv_python3=ON：构建 Python 3 的接口（默认可能是 ON，取决于系统环境）。需要系统安装有 Python 3 和 NumPy。
  • -D PYTHON3_EXECUTABLE=/path/to/python3：指定用于构建 Python 3 接口的 Python 解释器路径。
  • -D OPENCV_ENABLE_NONFREE=ON：启用 Contrib 模块中的一些受专利限制的非免费算法（如 SIFT, SURF）。如果你需要这些功能，必须开启此选项。

你可以在运行 cmake 命令时组合使用这些选项，例如：

“`bash

在 Linux/macOS 上构建 Release 版本，启用 Contrib，安装到指定目录，并构建示例和测试

cmake -D CMAKE_BUILD_TYPE=Release \
-D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules \
-D CMAKE_INSTALL_PREFIX=/opt/opencv-4.x \
-D BUILD_EXAMPLES=ON \
-D BUILD_TESTS=ON \
..
“`

“`powershell

在 Windows 上使用 Visual Studio 2019 (16) 64位构建，启用 Contrib

cmake -G “Visual Studio 16 2019” -A x64 ^
-D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules ^
-D BUILD_EXAMPLES=ON ^
-D BUILD_TESTS=ON ^
..
``
（注意 Windows 命令提示符使用^` 进行换行）

CMake Generator (生成器)：

-G 选项用于指定生成器，告诉 CMake 你希望使用哪种构建工具。
* Windows: 常用 "Visual Studio <version>"，例如 "Visual Studio 16 2019"。使用 -A 选项指定平台，如 -A x64 (64位) 或 -A Win32 (32位)。
* Linux/macOS: 默认通常是 Unix Makefiles (即使用 make)。也可以安装 Ninja 并使用 -G Ninja，Ninja 通常编译速度更快。

运行完 cmake 命令后，仔细检查输出信息，确保你需要的模块和第三方库都被成功检测并启用。如果缺少依赖，CMake 会提示，你需要安装相应的开发包然后再次运行 cmake ..。

5.2. 运行构建工具进行编译

CMake 配置成功后，会在构建目录中生成相应的工程文件（Makefile, .sln 文件等）。现在可以使用构建工具进行实际的编译。

  • Linux/macOS (使用 Make)：

    “`bash
    make -j$(nproc) # Linux
    make -j$(sysctl -n hw.ncpu) # macOS

    或者手动指定并行编译的线程数，例如使用8个线程：

    make -j8
    ``-j选项指定并行编译的线程数，这可以显著加快编译速度。$(nproc)或$(sysctl -n hw.ncpu)` 可以获取CPU核心数。

  • Linux/macOS (使用 Ninja)：

    “`bash
    ninja -j$(nproc) # Linux
    ninja -j$(sysctl -n hw.ncpu) # macOS

    或者手动指定线程数：

    ninja -j8
    ``
    Ninja 默认就会尝试使用所有核心进行并行编译，所以通常只需要运行    ninja`。

  • Windows (使用 Visual Studio)：

    1. 打开构建目录（例如 opencv/build）。
    2. 找到生成的 .sln 文件（例如 OpenCV.sln），双击用 Visual Studio 打开。
    3. 在 Visual Studio 的“解决方案资源管理器”中，右键点击“ALL_BUILD”项目（通常位于 CMakeTargets 文件夹下）。
    4. 选择“生成”（Build）。
      或者在开发者命令提示符中运行：
      “`powershell
      msbuild ALL_BUILD.vcxproj /p:Configuration=Release /m # 编译 Release 版本

    或者

    msbuild ALL_BUILD.vcxproj /p:Configuration=Debug /m # 编译 Debug 版本
    ``/m` 选项启用并行编译。

编译过程会持续一段时间，取决于你的系统性能和编译选项（CUDA 会使编译时间显著增加）。耐心等待，直到编译完成，没有致命错误。

5.3. 运行安装目标

编译成功后，最后一步是将编译好的库、头文件等安装到指定的安装目录 (CMAKE_INSTALL_PREFIX 指定的目录)。

  • Linux/macOS (使用 Make/Ninja)：

    “`bash
    sudo make install # 使用 Make

    或者

    sudo ninja install # 使用 Ninja
    ``
    通常需要    sudo权限才能写入到/usr/local或其他系统目录。如果你指定了用户目录作为安装路径，可能不需要sudo`。

  • Windows (使用 Visual Studio)：

    1. 在 Visual Studio 的“解决方案资源管理器”中，右键点击“INSTALL”项目。
    2. 选择“生成”（Build）。

运行安装目标后，OpenCV 的库文件、头文件、CMake 配置文件、示例可执行文件等将被复制到你指定的安装目录。

6. 配置和使用构建好的 OpenCV

安装完成后，如何在你的项目中使用这个自定义构建的 OpenCV 版本呢？这主要取决于你使用的开发语言和构建系统。

6.1. C++ 项目 (使用 CMake)

使用 CMake 构建 C++ 项目时，OpenCV 官方提供了非常方便的 find_package 机制。在你安装 OpenCV 的目录中，CMake 会生成 OpenCVConfig.cmake 或 opencv-bindings.cmake 文件，包含了查找 OpenCV 所需的信息。

在你的 C++ 项目的 CMakeLists.txt 中：

  1. 告诉 CMake 去哪里找 OpenCV： 如果 OpenCV 没有安装在系统标准路径，你需要设置 CMAKE_PREFIX_PATH 环境变量或 CMake 变量，指向你安装 OpenCV 的目录。

    • 通过环境变量（推荐在终端中设置，或添加到你的 ~/.bashrc/.zshrc）：
      bash
      export CMAKE_PREFIX_PATH=/path/to/your/opencv/install:$CMAKE_PREFIX_PATH
    • 在你的项目 CMakeLists.txt 的顶部（在 find_package 调用之前）：
      cmake
      set(CMAKE_PREFIX_PATH "/path/to/your/opencv/install" ${CMAKE_PREFIX_PATH})
      替换 /path/to/your/opencv/install 为你在 CMAKE_INSTALL_PREFIX 中指定的安装路径。

  2. 查找 OpenCV 包：
    cmake
    find_package(OpenCV REQUIRED)
    如果找到 OpenCV，CMake 会自动设置 OpenCV_FOUND 变量，并导入一些有用的变量，如 OpenCV_INCLUDE_DIRS (头文件路径) 和 OpenCV_LIBS (库文件列表)。

  3. 链接到你的目标： 在你的可执行文件或库的目标中，链接到 OpenCV 库。
    cmake
    add_executable(my_app main.cpp)
    target_link_libraries(my_app PRIVATE ${OpenCV_LIBS})
    # 或者更现代的方式
    target_link_libraries(my_app PRIVATE OpenCV::opencv)

一个简单的 CMakeLists.txt 示例：

“`cmake
cmake_minimum_required(VERSION 3.10)
project(MyOpenCVApp)

如果OpenCV不在标准路径，设置查找路径

set(CMAKE_PREFIX_PATH “/path/to/your/opencv/install” ${CMAKE_PREFIX_PATH})

find_package(OpenCV REQUIRED)

if(OpenCV_FOUND)
message(STATUS “Found OpenCV version ${OpenCV_VERSION}”)
include_directories(${OpenCV_INCLUDE_DIRS}) # 或者使用 target_include_directories

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE ${OpenCV_LIBS})
# 或者
# target_link_libraries(my_app PRIVATE OpenCV::opencv)

else()
message(FATAL_ERROR “OpenCV not found.”)
endif()
“`

这样，CMake 就会自动处理头文件路径和库文件链接的问题。

6.2. Python 项目

如果你构建了 Python 接口 (BUILD_opencv_python3=ON)，会在安装目录中找到 cv2.<platform-specific>.so (Linux/macOS) 或 cv2.pyd (Windows) 文件。

要让 Python 解释器找到这个模块，你有几种方法：

  1. 复制或链接： 将生成的 cv2.* 文件复制或链接到你的 Python 环境的 site-packages 目录中。

  2. 修改 sys.path： 在你的 Python 脚本的开头，将 OpenCV cv2 模块所在的目录添加到 sys.path 中。
    “`python
    import sys
    # 将 ‘/path/to/your/opencv/install/lib/python3.x/site-packages’ 替换为你实际的安装路径
    sys.path.insert(0, ‘/path/to/your/opencv/install/lib/python3.x/site-packages’)

    import cv2
    print(cv2.version)
    “`
    请根据你的安装路径和 Python 版本调整路径。

  3. 设置 PYTHONPATH 环境变量： 将 cv2 模块所在的目录添加到 PYTHONPATH 环境变量中。
    bash
    export PYTHONPATH=/path/to/your/opencv/install/lib/python3.x/site-packages:$PYTHONPATH
    或者在 Windows 命令提示符中：
    powershell
    set PYTHONPATH=/path/to/your/opencv/install/lib/python3.x/site-packages;%PYTHONPATH%

选择一种你觉得最方便的方式即可。现在你可以在 Python 中 import cv2 并使用你刚刚构建的 OpenCV 版本了。

7. 探索示例代码 (Samples)

正如前面提到的，samples 目录是学习 OpenCV 功能的宝库。如果你在构建时启用了 BUILD_EXAMPLES=ON，编译好的示例程序会安装到你的安装目录下的 samples 或 bin 目录中。

花时间浏览 samples 目录下的 C++ 和 Python 示例代码。它们涵盖了 OpenCV 的各种核心功能，通常代码量不大，且有清晰的注释。通过阅读、运行和修改这些示例，你可以快速掌握 OpenCV 的基本用法和特定模块的功能。

8. 保持更新

如果你希望使用 OpenCV 的最新开发进展，你需要定期更新你本地的代码并重新构建。

  1. 进入 opencv 和 opencv_contrib 仓库目录。
  2. 使用 Git 命令拉取最新代码：
    bash
    cd /path/to/your/opencv/opencv
    git pull
    cd /path/to/your/opencv/opencv_contrib
    git pull
  3. 进入你的构建目录。
  4. 重新运行 CMake 配置（如果新版本添加了新的选项或依赖，或者你想更改配置）。通常只需要 cmake ..，CMake 会记住之前的选项，但最好检查一下输出。
  5. 重新运行构建命令（make -jX, ninja -jX, 或 Visual Studio 中的 ALL_BUILD）。构建工具只会重新编译修改过的文件，所以通常比首次构建快得多。
  6. 重新运行安装目标（make install, ninja install, 或 Visual Studio 中的 INSTALL）。

9. 参与社区与获取帮助

  • GitHub Issues： 如果你在使用最新代码时发现 Bug，或者有功能建议，可以在 OpenCV GitHub 仓库的 Issues 页面提交。提交 Bug 报告时，请尽量提供详细信息，包括你的操作系统、编译器版本、CMake 命令、完整的错误输出以及能够重现问题的最小代码示例。
  • Pull Requests： 如果你修复了 Bug 或实现了新功能，可以通过 Fork 仓库、创建分支、提交代码并提交 Pull Request 的方式向 OpenCV 贡献代码。请务必遵循项目的贡献指南 (CONTRIBUTING.md)。
  • OpenCV 官方文档： 始终是获取详细函数说明和教程的最佳来源。
  • OpenCV 论坛和 Stack Overflow： 遇到问题时，可以到官方论坛或 Stack Overflow 搜索现有解答或提问。

10. 总结

从 OpenCV 的 GitHub 仓库获取源代码并进行构建，是深入了解和高级使用 OpenCV 的重要一步。尽管过程比安装预编译版本复杂，需要掌握 Git、CMake 和编译工具的基础知识，但它带来的灵活性、对最新功能的访问能力以及深入调试的可能性是无可替代的。

本指南详细介绍了从获取代码、理解仓库结构、跨平台构建过程到配置使用的方法。希望它能帮助你顺利迈出从 OpenCV 用户到“源代码玩家”的第一步。勇敢地尝试吧！通过实践，你将逐渐熟悉这个过程，并能更自如地驾驭这个强大的计算机视觉库。祝你在 OpenCV 的探索之路上取得丰硕的成果！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部