现在位置: 首页 / 系统运维 / 正文

小白也能看懂！OpenCV 从零开始安装配置全教程（包含Windows / Ubuntu / 树莓派）系统详细操作配置教程

小白也能看懂！OpenCV 从零开始安装配置全教程（包含Windows / Ubuntu / 树莓派）系统详细操作配置教程

摘要

本教程是面向“小白也能懂”的OpenCV安装与配置全攻略，涵盖Windows、Ubuntu和树莓派三大平台，真正实现“从零开始”快速上手。文章详细讲解了OpenCV下载安装教程、OpenCV安装、Ubuntu安装OpenCV、树莓派安装OpenCV等步骤，手把手指导小白用户进行环境准备、依赖库安装、解压与环境变量配置、CMake编译、源码编译与apt-get安装等操作。通过本教程，小白也能一步步完成OpenCV安装配置，为后续图像处理与计算机视觉项目开发打下坚实基础。

 

前言

本教程专为从未接触过图像处理、编译配置的小白用户打造。我们将带你“从零开始”，逐步完成在不同系统（Windows、Ubuntu、树莓派）上安装和配置 OpenCV（Open Source Computer Vision Library）的全过程。只要你跟着步骤走，即使对命令行、编译环境、依赖库一无所知，也能轻松完成安装。

  • 目标读者：零基础学习者、对图像处理感兴趣的同学、想动手搭建计算机视觉开发环境的初学者。
  • 教程亮点：
    1. 详细步骤图文结合（文字详尽说明）。
    2. 包含常见报错及解决方案。
    3. Windows、Ubuntu、树莓派三大平台全覆盖。
    4. 关键词标注，让你快速检索 “opencv下载安装教程”、“opencv安装”、“ubuntu安装opencv”、“树莓派安装opencv” 等内容。

准备工作与基础知识

什么是 OpenCV？

OpenCV（Open Source Computer Vision Library）是一个开源的、跨平台的计算机视觉与机器学习软件库。它提供了上千个算法和函数，涵盖以下主要方向：

  • 图像处理：图像读取、显示、保存、滤波、几何变换、阈值分割、形态学操作等。
  • 特征检测与描述：如边缘检测（Canny）、角点检测（Harris、Shi-Tomasi）、ORB、SIFT、SURF 等。
  • 目标识别与跟踪：人脸检测与识别（Haar 特征、DNN）、物体跟踪（KCF、MOSSE、CSRT 等）。
  • 机器学习：支持 SVM、决策树、随机森林、神经网络等常见模型。
  • 深度学习支持：可加载预训练的 Caffe、TensorFlow、Torch、Darknet 等模型进行推理。
  • 三维重建与增强现实：立体匹配、相机标定等模块支持三维重建和 AR 应用。

OpenCV 社区非常活跃，文档齐全、示例丰富。对于计算机视觉入门和项目开发都是非常理想的选择。

为什么要学习 OpenCV？

  1. 功能强大且免费开源：几乎涵盖所有常见图像处理与计算机视觉需求。
  2. 跨平台支持：Windows、Linux（Ubuntu）、macOS、Android、iOS、树莓派 等。
  3. 语言接口多样：C++（官方核心实现）、Python、Java、MATLAB 等接口，初学者可先用 Python 体验。
  4. 社区活跃，资料丰富：Stack Overflow、GitHub Issue、各种技术博客、官方文档、书籍等一应俱全。
  5. 工业与学术通用：无论是学术论文验证，还是工业项目快速落地，OpenCV 都是首选。

运行环境与系统要求

由于本教程覆盖 Windows、Ubuntu、树莓派 3 个系统，下面分别说明各自的最小要求，供小白用户简单确认。

平台 最低要求（推荐）
Windows Windows 10（64 位），4 GB 内存以上，至少 10 GB 硬盘空间
Ubuntu Ubuntu 18.04/20.04/22.04（64 位），4 GB 内存以上，至少 10 GB 硬盘
树莓派 Raspberry Pi 4（推荐 4GB or 8GB 内存），运行 Raspberry Pi OS（64 位），SD 卡 16GB 以上
  • 网络连接：下载源码或依赖时需要联网，建议有稳定的网络。
  • 开发环境：
    • Windows：建议安装 Visual Studio Community（2019/2022）或配置 MinGW。
    • Ubuntu：需要安装 gcc/g++、make、CMake 等常见开发工具。
    • 树莓派：建议使用自带的终端环境，可直接 sudo apt-get 安装依赖。

后续部分会详细说明各自的前置准备和依赖安装。

Windows 下安装 OpenCV

在 Windows 系统上安装 OpenCV 最简单的方式就是下载官方提供的预编译安装包，然后配置系统环境变量和开发工具链（Visual Studio / MinGW）。本节将以 Visual Studio 2022 为例，手把手教你完成整个过程。

一、环境准备

  1. 操作系统：Windows 10 或更高，64 位（Win7/8 也可，但推荐 Win10 以上）。
  2. Visual Studio Community 2022（免费版即可）
    • 网站下载地址（仅供参考，具体版本以微软官网最新版本为准）：

      https://visualstudio.microsoft.com/zh-hans/vs/community/

    • 在安装时，勾选“使用 C++ 的桌面开发”工作负载，确保安装：
      • MSVC v143 - VS 2022 C++ x64/x86 build tools
      • CMake 工具
      • Windows 10 SDK
  3. Python（可选，若想用 Python 接口）
    • Python 3.7 及以上版本均可，推荐 3.8/3.9。
    • Windows 上安装时，必须勾选“Add Python to PATH”。
  4. 管理员权限：建议使用管理员身份运行安装程序与配置命令行，否则容易出现权限不足的问题。

二、下载 OpenCV 安装包

  1. 打开 OpenCV 官方 GitHub Release 页面：

    https://github.com/opencv/opencv/releases

  2. 找到最新的稳定版本（如 4.8.0、4.7.0 等），对应 Windows 的预编译文件一般为 opencv-{version}-vc{msvc_version}.zip 或者 opencv-{version}-vc{msvc_version}-opencv_contrib.zip。
    • 推荐下载：opencv-{version}-vc{msvc_version}.zip（此包已包含主模块，且自带 VS 预编译二进制）。
    • 如果需要 contrib 模块（额外的算子、samples 等），可以下载 opencv_contrib 版本，但体积更大。
  3. 将下载好的压缩包放到一个容易找到的位置（如 D:\ 或 C:\Users\你的用户名\Downloads\）。

三、解压与配置环境变量

  1. 解压目录
    • 右键点击下载的 opencv-*.zip，选择 “解压到 opencv-xxx\” （推荐路径：C:\opencv\）。
    • 解压后，你会看到： 
      C:\opencv\
  ├── build\
  │    ├── x64\
  │    │    ├── vc15\
  │    │    │    ├── bin\
  │    │    │    ├── lib\
  │    │    │    └── etc...
  │    └── ...
  ├── samples\
  ├── sources\
  └── ...
  2. 配置系统环境变量
    • 右键 “此电脑” → “属性” → “高级系统设置” → “环境变量”。
    • 在 “系统变量” 区域，找到 Path，选择后点击 “编辑”。
    • 点击 “新建”，添加下面两项（根据你的解压路径修改）： 
      C:\opencv\build\x64\vc15\bin
C:\opencv\build\bin\Release

      说明：

      • vc15 表示 MSVC 15/.NET 2017 或更高版本，如果你的版本不一样，按实际目录填写。
      • 添加后，打开新的命令行（CMD / PowerShell），输入 opencv_version 无报错即生效。

四、配置 Visual Studio 编译环境

以下操作将演示如何在 Visual Studio 2022 中创建一个简单的 C++ 项目，并链接 OpenCV 库。

  1. 启动 Visual Studio 2022
    • 点击 “创建新项目” → 选择 “空项目（Empty Project）” → 点击 “下一步”。
    • 项目名称取为 HelloOpenCV，选择合适路径，如 D:\Projects\HelloOpenCV → 点击 “创建”。
  2. 配置附加包含目录
    • 右击解决方案资源管理器中的项目 → “属性” → 左侧选择 “配置属性”→“C/C++”→“常规”→“附加包含目录”。
    • 点击右侧的 “编辑”，添加： 
      C:\opencv\build\include

      说明：这样编译器才能找到 OpenCV 的头文件（.hpp、.h 等）。

  3. 配置附加库目录
    • 同样在项目属性中，选择 “配置属性”→“链接器”→“常规”→“附加库目录”，添加： 
      C:\opencv\build\x64\vc15\lib

      该目录下包含 opencv_world480.lib（或 opencv_world470.lib，视版本而定）等库文件。

  4. 添加依赖库
    • 项目属性 → “配置属性” → “链接器” → “输入” → “附加依赖项”，点击 “编辑”，将需要的 .lib 文件添加进去，例如： 
      opencv_world480.lib

      如果你下载的是 contrib 版本，可能需要添加其它模块的 lib，但 opencv_worldxxx.lib 已经包含所有模块，最简单。

  5. 设置运行时 DLL
    • 由于编译时会链接动态库（.dll），运行 exe 前需要确保 C:\opencv\build\x64\vc15\bin 已加入系统 PATH（已在上一步完成）。
    • 若未配置环境变量，可将 *.dll 文件复制到可执行文件所在目录。

五、验证安装（Hello OpenCV）

  1. 添加源文件
    • 在项目中右键 “源文件” → “添加” → “新建项” → 选择 “C++ 文件”，命名为 main.cpp。
  2. 输入示例代码 
    #include <opencv2/opencv.hpp>
#include <iostream>

int main() {
    // 创建一张 300x300 的黑色图像
    cv::Mat image = cv::Mat::zeros(300, 300, CV_8UC3);

    // 在图像中心画一个蓝色圆圈（BGR ）
    cv::circle(image, cv::Point(150, 150), 100, cv::Scalar(255, 0, 0), -1);

    // 显示窗口
    cv::imshow("Hello OpenCV", image);

    // 等待按键
    cv::waitKey(0);
    return 0;
}
  3. 编译与运行
    • 按下 F5 或点击 “本地 Windows 调试器” 运行项目。
    • 如果一切正常，将弹出一个名为 “Hello OpenCV” 的窗口，显示一个蓝色填充圆圈。
    • 若窗口正常出现且无报错，则 Windows 平台上的 OpenCV 安装配置成功。

Ubuntu 下安装 OpenCV

在 Ubuntu 下安装 OpenCV 常见两种方式：通过 apt-get 直接安装（快速）、或者从源码编译安装（自由配置、性能更优）。本节将分别介绍二者，并为初学者标注重点。

一、环境准备

  1. 操作系统：Ubuntu 18.04/20.04/22.04 LTS（64 位）。
  2. 用户权限：需要能运行 sudo 命令。
  3. 网络环境：建议使用国内源（如阿里云、清华源）以加快下载速度。
    • 修改 /etc/apt/sources.list，将官方源替换为国内镜像。（若不熟悉，可跳过，后续命令会慢一些）。
  4. 基本开发工具：在终端中执行： 
    sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y build-essential cmake git pkg-config
    • build-essential：包含 gcc/g++、make 等常见工具。
    • cmake：构建工具，用于从源码编译。
    • git：克隆源码。
    • pkg-config：管理安装库时查找包信息。

温馨提示：若已安装最新版 Ubuntu，build-essential、cmake 等工具一般自带，只需更新即可。

二、从 apt-get 安装（推荐快速入门）

  1. 安装 OpenCV 库及 Python 绑定 
    sudo apt-get install -y libopencv-dev python3-opencv
    • libopencv-dev：OpenCV C++ 开发包，包含头文件和库。
    • python3-opencv：Python3 接口，安装后可以直接在 Python 中 import cv2。
  2. 验证 C++ 接口
    1. 创建一个测试目录，例如 ~/opencv_test： 
      mkdir ~/opencv_test && cd ~/opencv_test
    2. 编写 main.cpp： 
      #include <opencv2/opencv.hpp>
#include <iostream>

int main() {
    cv::Mat img = cv::Mat::zeros(200, 400, CV_8UC3);
    cv::putText(img, "Ubuntu OpenCV", cv::Point(50, 100),
                cv::FONT_HERSHEY_SIMPLEX, 1.0, cv::Scalar(0, 255, 0), 2);
    cv::imshow("Test", img);
    cv::waitKey(0);
    return 0;
}
    3. 使用 pkg-config 编译： 
      g++ main.cpp -o test `pkg-config --cflags --libs opencv4`
      • 注意：Ubuntu 20.04 及以后的版本，OpenCV4 对应的 pkg-config 名称为 opencv4，若低版本，可能是 opencv。
    4. 运行： 
      ./test
      • 如果弹出标题为 “Test” 的窗口，且显示绿色文字 “Ubuntu OpenCV”，则说明安装成功。
  3. 验证 Python 接口
    1. 打开终端，输入 python3 进入交互式 Python： 
      python3
>>> import cv2
>>> print(cv2.__version__)
4.x.x
>>> img = cv2.imread("test.jpg")  # 若当前目录有图片文件
>>> cv2.imshow("img", img)
>>> cv2.waitKey(0)
>>> cv2.destroyAllWindows()
    2. 若能成功 import cv2，且能调用函数，就说明 Python 接口正常工作。

Tips：使用 sudo apt-get install libopencv-dev python3-opencv 安装的版本一般不是最新，若想体验最新版本或编译选项，请参阅下一节源码编译安装。

三、从源码编译安装（适合高级定制）

如果你想要：

  • OpenCV 最新稳定版/alpha 版；
  • 自定义编译选项（是否启用 CUDA、是否启用 contrib 模块）；
  • 优化性能（选择 TBB、OpenMP、多线程；或者使用 NEON、V4L2）。

就需要自行从源码编译。以下步骤示例基于 Ubuntu 20.04，OpenCV 4.8.0 为例。

1. 安装额外依赖

先安装编译 OpenCV 常用依赖库和拓展功能库，包括图像编解码、GUI 支持、视频 I/O、数学优化等：

sudo apt-get update
sudo apt-get install -y build-essential cmake git pkg-config \
    libjpeg-dev libpng-dev libtiff-dev libopenexr-dev libwebp-dev \
    libavcodec-dev libavformat-dev libswscale-dev libv4l-dev \
    libxvidcore-dev libx264-dev libgtk-3-dev libatlas-base-dev gfortran \
    python3-dev python3-numpy

说明关键依赖：

  • libjpeg-dev, libpng-dev, libtiff-dev 等：支持常见图像格式。
  • libavcodec-dev, libavformat-dev, libswscale-dev：FFmpeg 相关，用于视频读写。
  • libv4l-dev：Linux 视频采集接口，用于摄像头。
  • libgtk-3-dev：GUI 窗口显示支持。
  • libatlas-base-dev 或 libopenblas-dev：线性代数加速。
  • python3-dev, python3-numpy：Python 接口依赖。
2. 下载 OpenCV 与 OpenCV Contrib 源码
cd ~
git clone https://github.com/opencv/opencv.git
git clone https://github.com/opencv/opencv_contrib.git
  • opencv/：主库源码。
  • opencv_contrib/：官方扩展模块（如 xfeatures2d、aruco、text 等）。

如果网络较慢，可考虑使用国内镜像，如 Gitee，或者先下载压缩包再解压。

3. 创建构建目录并使用 CMake 配置
cd ~/opencv
mkdir build && cd build

使用 cmake 命令生成 Makefile 或 Ninja 配置。以下示例配置较常用选项，适合大多数入门需求：

cmake -D CMAKE_BUILD_TYPE=Release \
      -D CMAKE_INSTALL_PREFIX=/usr/local \
      -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \
      -D BUILD_EXAMPLES=ON \
      -D BUILD_TESTS=OFF \
      -D BUILD_DOCS=OFF \
      -D BUILD_PERF_TESTS=OFF \
      -D BUILD_opencv_python3=ON \
      -D ENABLE_NEON=ON \
      -D WITH_TBB=ON \
      -D WITH_V4L=ON \
      -D WITH_QT=OFF \
      -D WITH_OPENGL=ON \
      -D BUILD_opencv_ts=OFF \
      -D OPENCV_ENABLE_NONFREE=ON \
      ..

参数详解：

  • CMAKE_BUILD_TYPE=Release：发布版本，开启编译优化，速度更快。
  • CMAKE_INSTALL_PREFIX=/usr/local：安装到 /usr/local，供全局使用。
  • OPENCV_EXTRA_MODULES_PATH：指向 opencv_contrib/modules，启用扩展模块。
  • BUILD_EXAMPLES：编译官方示例，帮助学习。
  • BUILD_opencv_python3=ON：生成 Python3 接口。
  • ENABLE_NEON=ON：启用 ARM NEON 优化（在 Raspberry Pi 上有用）。
  • WITH_TBB=ON：启用 Intel TBB 多线程加速。
  • WITH_V4L=ON：启用视频采集。
  • OPENCV_ENABLE_NONFREE=ON：启用 SIFT/SURF 等非自由算法（仅在需要时开启）。

如出现依赖缺失，会提示缺少的 dev 库名称，按提示用 sudo apt-get install <缺少的库> 即可。

4. 编译与安装
  1. 并行编译（4 核 CPU 为例，可根据实际修改 -j4）： 
    make -j4
    • 编译时间：根据机器性能，一般在 10~30 分钟之间。
    • 如果编译过程中报错，查看报错信息，根据提示安装缺失依赖再运行 make。
  2. 安装 
    sudo make install
sudo ldconfig
    • make install 会将编译好的库、头文件、Python 模块等安装到 /usr/local/。
    • ldconfig 更新系统库缓存，确保新库可被链接。
5. 验证安装
  1. C++ 测试
    • 参考上文 Ubuntu apt-get 验证方法，使用 pkg-config： 
      pkg-config --modversion opencv4

      若返回 4.8.0（或你编译时的版本号），说明正确识别。

    • 编写同样的 main.cpp，然后： 
      g++ main.cpp -o test `pkg-config --cflags --libs opencv4`
./test
  2. Python 测试
    • 打开 Python3 交互式，执行： 
      python3
>>> import cv2
>>> cv2.__version__
'4.8.0'
>>> img = cv2.imread("test.jpg")
>>> cv2.imshow("img", img)
>>> cv2.waitKey(0)
>>> cv2.destroyAllWindows()
    • 若能正常 import cv2，版本号正确，且能够调用 GUI 函数，则编译安装成功。

注意：若 Python import 失败，可能是在多个 Python 环境中出现混淆，可使用 python3 -m pip install numpy 或者检查 cv2.so 是否在 /usr/local/lib/python3.x/dist-packages/ 下。

树莓派（Raspberry Pi）下安装 OpenCV

树莓派（Raspberry Pi）是一款非常适合学习计算机视觉和物联网项目的廉价嵌入式开发板。虽然性能有限，但借助 OpenCV 和 Raspberry Pi 相机模组（或 USB 摄像头），也能完成大量有趣的项目。本节重点介绍如何在树莓派上安装 OpenCV。

一、准备树莓派硬件与系统

  1. 硬件准备
    • Raspberry Pi 4（推荐 4GB/8GB 内存版，树莓派 3 也可，但编译时间更长）。
    • microSD 卡：容量 ≥16GB，建议使用 UHS-I 高速卡。
    • 电源适配器：5V/3A（树莓派 4 推荐）。
    • 外部显示器、键盘、鼠标：用于初次系统配置。
    • USB 摄像头 或 Raspberry Pi Camera Module V2（可选，用于测试摄像头功能）。
  2. 系统安装
    • 下载 Raspberry Pi OS（64 位推荐）镜像：

      https://www.raspberrypi.com/software/operating-systems/

    • 使用 Raspberry Pi Imager 将镜像写入 microSD 卡。
    • 将 SD 卡插入树莓派，接好显示器、键盘、鼠标、电源线，启动后完成系统首次配置（连接 Wi-Fi、更新系统）。
    • 系统更新： 
      sudo apt-get update
sudo apt-get upgrade -y
    • 打开摄像头接口（若使用 Pi Camera）： 
      sudo raspi-config
# 选择 Interface Options → Camera → Enable
# 然后重启
sudo reboot

提示：初次使用终端不熟悉的同学，可以先学习一些 Linux 基础命令，如 ls, cd, cp, mv, rm, sudo 等。

二、使用 apt-get 直接安装

Raspberry Pi OS 自带的源中，有配套 OpenCV 的二进制包，安装方法与 Ubuntu 类似：

sudo apt-get install -y libopencv-dev python3-opencv
  1. 安装 C++ 接口与 Python 接口
    • libopencv-dev：C++ 开发包
    • python3-opencv：Python3 接口
  2. 验证 C++ 接口
    1. 新建测试目录： 
      mkdir ~/opencv_pi_test && cd ~/opencv_pi_test
    2. 编写 main.cpp： 
      #include <opencv2/opencv.hpp>
#include <iostream>

int main() {
    cv::Mat img = cv::Mat::zeros(200, 400, CV_8UC3);
    cv::putText(img, "Rpi OpenCV", cv::Point(50, 100),
                cv::FONT_HERSHEY_SIMPLEX, 1.0, cv::Scalar(255, 0, 0), 2);
    cv::imshow("PiTest", img);
    cv::waitKey(0);
    return 0;
}
    3. 编译并运行： 
      g++ main.cpp -o test `pkg-config --cflags --libs opencv4`
./test
      • 若能正常打开窗口并显示文字，说明 C++ 部分正常。
  3. 验证 Python 接口 
    python3
>>> import cv2
>>> print(cv2.__version__)
4.x.x
>>> img = cv2.imread("test.jpg")
>>> cv2.imshow("img", img)
>>> cv2.waitKey(0)
>>> cv2.destroyAllWindows()
    • 如果无法弹出窗口，请检查是否在 SSH 终端中运行。需要在本地桌面环境运行，或使用 cv2.imwrite("out.jpg", img) 保存后查看。

缺点：apt-get 安装的版本多数较旧，可能缺少新版模块和性能优化项。如果需要更高性能、更灵活功能，建议从源码编译。

三、从源码编译安装（性能优化）

树莓派性能有限，源码编译时间较长（一次完整编译可能需要 2–4 小时）。但能开启 NEON、V4L、TBB、GTK 等模块，对树莓派摄像头优化显著。以下以 OpenCV 4.8.0 编译为例：

1. 安装依赖
sudo apt-get update
sudo apt-get install -y build-essential cmake git pkg-config \
    libjpeg-dev libpng-dev libtiff-dev libavcodec-dev libavformat-dev \
    libswscale-dev libv4l-dev libxvidcore-dev libx264-dev libgtk-3-dev \
    libatlas-base-dev libhdf5-dev libprotobuf-dev protobuf-compiler \
    libgoogle-glog-dev libgflags-dev python3-dev python3-numpy

特别注意：

  • libatlas-base-dev：线性代数加速。
  • libv4l-dev：视频捕获接口（Pi Camera 也需此支持）。
  • libgtk-3-dev：GUI 窗口。若仅做无窗口脚本可忽略。
2. 获取源码
cd ~
git clone https://github.com/opencv/opencv.git
git clone https://github.com/opencv/opencv_contrib.git

也可切到指定版本分支或 tag，例如：

cd ~/opencv
git checkout 4.8.0
cd ../opencv_contrib
git checkout 4.8.0
3. 配置编译
cd ~/opencv
mkdir build && cd build

cmake -D CMAKE_BUILD_TYPE=Release \
      -D CMAKE_INSTALL_PREFIX=/usr/local \
      -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \
      -D BUILD_EXAMPLES=ON \
      -D WITH_TBB=OFF \               # 树莓派通常不开启 TBB，加快编译
      -D WITH_V4L=ON \
      -D WITH_QT=OFF \
      -D WITH_OPENGL=ON \
      -D ENABLE_NEON=ON \
      -D BUILD_opencv_python3=ON \
      -D OPENCV_ENABLE_NONFREE=ON \
      -D BUILD_DOCS=OFF \
      -D BUILD_TESTS=OFF \
      -D BUILD_PERF_TESTS=OFF \
      ..
  • ENABLE_NEON=ON：启用 ARM NEON 优化。
  • WITH_TBB=OFF：关闭 TBB，以免编译失败。
  • WITH_OPENGL=ON：若用 OpenGL 渲染。
  • 其他同 Ubuntu 源码配置。
4. 编译与安装
make -j4  # 如果是树莓派 4，默认 4 核并行
sudo make install
sudo ldconfig
  • 编译时间：2–4 小时不等。耐心等待。
  • 若过程中报错，可根据缺少的依赖名称安装补充。
5. 验证安装与摄像头测试
  1. C++ 测试
    • 同 Ubuntu 步骤，用 pkg-config 验证版本： 
      pkg-config --modversion opencv4

      若返回 4.8.0 或对应版本号，即可进行示例编译。

  2. Python 测试 
    python3
>>> import cv2
>>> print(cv2.__version__)
'4.8.0'
>>> cap = cv2.VideoCapture(0)
>>> ret, frame = cap.read()
>>> cv2.imshow("Cam", frame)
>>> cv2.waitKey(0)
>>> cap.release()
>>> cv2.destroyAllWindows()
    • 若使用 Pi Camera，需要先安装 python3-picamera 并配置 opencv 支持。
  3. 摄像头测试（USB 摄像头或 Pi Camera）
    • USB 摄像头：只要 VideoCapture(0) 即可访问。
    • Pi Camera：
      1. 安装 picamera 支持： 
        sudo apt-get install -y python3-picamera
      2. 测试代码（Python）： 
        import cv2
from picamera.array import PiRGBArray
from picamera import PiCamera
import time

camera = PiCamera()
camera.resolution = (640, 480)
rawCapture = PiRGBArray(camera, size=(640, 480))
time.sleep(0.1)

for frame in camera.capture_continuous(rawCapture, format="bgr", use_video_port=True):
    image = frame.array
    cv2.imshow("PiCam", image)
    rawCapture.truncate(0)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

camera.close()
cv2.destroyAllWindows()
      3. 运行： 
        python3 pi_camera_test.py
        • 画面出现后，按 q 键退出。

至此，树莓派平台上的 OpenCV 安装与测试完成！

常见问题及故障排查

本节汇总一些各平台常见的安装错误与解决方案，帮小白迅速定位问题。

1. 环境变量不生效

  • 现象：Windows 上在 CMD 中输入 opencv_version 提示命令未找到；运行 exe 报错找不到 *.dll。
  • 检查：
    1. 确认是否在 “系统变量” 而非 “用户变量” 中添加 PATH。
    2. 重新打开一个新的 CMD/PowerShell 窗口，环境变量变更才会生效。
    3. PATH 中的路径是否拼写正确，没有多余空格或反斜杠。
  • 解决方案：
    • 重新编辑环境变量，复制粘贴完整路径后确定。
    • 在命令行输入 echo %PATH% 或 echo $Env:Path（PowerShell）检查是否包含 C:\opencv\build\x64\vc15\bin。

2. CMake 找不到依赖

  • 现象：在 Ubuntu/树莓派源码编译时，运行 cmake 报类似 “Could NOT find GTK3 (missing: GTK3_X11_INCLUDE_DIR)” 或 “Could NOT find libjpeg” 等错误。
  • 检查与解决：
    1. 从提示信息中提取关键缺失库名称，例如 GTK3_X11_INCLUDE_DIR，使用 sudo apt-get install libgtk-3-dev。
    2. 若缺少图像编解码支持，安装对应 dev 包： 
      sudo apt-get install -y libjpeg-dev libpng-dev libtiff-dev
    3. 安装视频 I/O 相关依赖： 
      sudo apt-get install -y libavcodec-dev libavformat-dev libswscale-dev libv4l-dev
    4. 重新运行 cmake，直到没有依赖缺失的警告。

3. Python 导入失败

  • 现象：import cv2 报 ModuleNotFoundError: No module named 'cv2'。
  • 原因：可能同时有多个 Python 版本，cv2 安装到了其它环境；或者源码编译时 Python 环境不一致。
  • 解决：
    1. 确保使用的是系统默认 Python3，输入 which python3 查看路径。
    2. 再次安装 numpy： 
      python3 -m pip install --user numpy
    3. 确认 cv2 模块文件是否在 Python site-packages 中： 
      python3 -c "import sys; print([p for p in sys.path if 'site-packages' in p])"
ls /usr/local/lib/python3.*/dist-packages | grep cv2
    4. 若编译后没有生成 cv2.so，可尝试重新编译并确认 BUILD_opencv_python3=ON。

4. 编译报错“缺少 xxx 库”

  • 现象：在 Windows/Ubuntu/树莓派上从源码编译时，make 过程中提示 “undefined reference to <某个函数>”、“找不到 <某个库>” 等。
  • 可能原因 & 解决思路：
    1. Windows：
      • 检查 Visual Studio 扩展是否完整安装，确保 C++ 桌面开发工作负载已勾选。
      • 检查 CMake 文件中指定的 OPENCV_EXTRA_MODULES_PATH 是否正确。
      • 确认是否遗漏 dll/lib 目录或连接错误。
    2. Ubuntu/树莓派：
      • 查找提示的缺少库名称和对应的 dev 包，例如如果报缺少 protobuf，则： 
        sudo apt-get install -y libprotobuf-dev protobuf-compiler
      • 若提示缺少 Python 头文件，确保已安装 python3-dev。
      • 有时需要先卸载系统自带 OpenCV： 
        sudo apt-get purge libopencv*
sudo apt-get autoremove

        然后再编译安装。

总之，遇到编译错误时，仔细阅读报错信息中的关键词（库名、函数名），在网上搜索对应的缺失包名，然后执行 apt-get 安装即可。对新手来说，依赖安装是最常见的环节，多试几次就熟悉了。

总结与扩展阅读

至此，你已经掌握了在 Windows/Ubuntu/树莓派 上 “从零开始” 安装与配置 OpenCV 的全过程。无论是直接使用预编译包，还是从源码编译定制，都涉及到了如下关键步骤：

  1. 环境准备：编译工具、依赖库、Python 环境。
  2. 获取 OpenCV：选择预编译版本或克隆源码。
  3. 配置 & 编译：CMake 参数设置、make 并行编译、安装与 ldconfig。
  4. 环境变量 & 依赖管理：确保系统能找到 DLL/SO 库、Python 能找到 cv2 模块。
  5. 验证安装：用最简单的 “Hello OpenCV” 代码测试窗口显示与图像处理功能。
  6. 常见问题排查：环境变量、CMake 缺失依赖、Python 路径混淆、编译报错缺少库等。

持续学习与扩展

  • 官方文档：
  • 经典书籍：
    • 《Learning OpenCV 4 Computer Vision with Python 3》
    • 《OpenCV 4 with C++ Blueprints》
  • 示例项目：
    • GitHub 上搜索 “awesome-opencv” 了解各类示例与实践项目。
    • 在树莓派上尝试人脸识别、物体跟踪、机器学习模型的推理等。
  • 社区资源：
    • Stack Overflow（中英双语），随时搜索具体问题的解决方案。
    • CSDN、博客园等国内技术博客，大量教程与心得。

请将本教程保存至你常用的笔记工具，转发给同学或网友，让更多 “零基础的小白” 能够快速开启计算机视觉之旅。如果在安装过程中遇到任何问题，欢迎留言交流，我们一起排查解决！

祝你学习顺利，早日完成第一个 OpenCV 项目！ 用心阅读、动手实践，你一定能从“小白”变成“小高手”！