# OpenCV Python Tutorial Notes

**Repository Path**: liufumore/open-cv-python-tutorial-notes

## Basic Information

- **Project Name**: OpenCV Python Tutorial Notes
- **Description**: opencv python 讲义教程，是2025-opencv的续作
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 2026-OpenCV-python

OpenCV-Python 中文学习讲义工程：18 个章节循序渐进，从图像基础操作到视频处理、人脸检测与图像拼接，配套 70+ 可直接运行的示例脚本、图文讲义与素材。

## 目录

- [项目简介](#项目简介)
- [技术栈](#技术栈)
- [章节总览](#章节总览)
- [快速开始](#快速开始)
- [目录结构](#目录结构)
- [代码约定](#代码约定)
- [注意事项](#注意事项)
- [许可证](#许可证)

## 项目简介

本项目是一套面向初学者的 OpenCV-Python 中文教程，按 18 个编号目录（`01-opencv` ~ `18-opencv`）组织。每个章节包含：

- **Markdown 讲义**（`.md`）：原理讲解、函数原型、完整代码与运行效果截图
- **示例脚本**（`.py` / `.ipynb`）：每个知识点一个脚本，可直接运行
- **素材文件**：测试图片（`cat.jpg`、`dog.jpg` 等）、测试视频（`*.mp4`）
- **效果截图**（`img/` 目录）

内容编排呈明显递进关系：**基础操作 → 图像处理 → 特征分析 → 视频应用 → 综合实战**。

## 技术栈

| 组件 | 版本 |
|---|---|
| Python | 3.11（`.venv` 虚拟环境） |
| opencv-python | 5.0.0.93 |
| opencv-contrib-python | 5.0.0.93 |
| numpy | 2.4.6 |
| matplotlib | 3.11.1 |
| pillow | 12.3.0 |

> **注意**：本项目基于 **OpenCV 5.0**，该版本已移除传统的 Haar 级联人脸检测 API（`cv2.CascadeClassifier`、`detectMultiScale` 及 haarcascade XML 数据）。12 章视频人脸检测改用官方推荐的深度学习检测器 **YuNet**（模型文件 `face_detection_yunet_2023mar.onnx` 已随仓库提供），讲义中保留了 OpenCV 4.x 旧写法注释供参考。

## 章节总览

| 章节 | 主题 | 内容要点 | 脚本数 |
|---|---|---|---|
| 01 | OpenCV 入门 | 历史发展、环境、读取/显示/保存图像 | 1 |
| 02 | OpenCV 基础模块 | Core / Imgproc / HighGUI 三大模块、绘图、交互式标注程序（鼠标 + 滑动条） | 2 |
| 03 | 图像处理基础 | 像素访问、ROI、通道分离合并、缩放 | 1 |
| 04 | 图像基本操作 | 综合案例：像素 / ROI / 通道 / 几何变换四合一演示 | 1 |
| 05 | 图像算术运算 | 加减乘除、位运算（与/或/非/异或）、图像混合 | 9 |
| 06 | 图像阈值处理 | 简单阈值、自适应阈值、Otsu 二值化 | 3 |
| 07 | 图像平滑处理 | 均值 / 高斯 / 中值 / 双边滤波 | 4 |
| 08 | 图像形态学操作 | 腐蚀、膨胀、开/闭运算、形态学梯度 | 5 |
| 09 | 图像边缘检测 | Canny、Sobel、Laplacian | 3 |
| 10 | 图像轮廓检测 | findContours、drawContours、面积/周长/外接矩形/多边形逼近、完整实例 | 9 |
| 11 | 图像直方图 | calcHist、直方图均衡化、颜色直方图、compareHist | 6 |
| 12 | 视频处理 | 读取视频/摄像头、帧操作、VideoCapture/Writer、视频人脸检测与运动检测 | 14 |
| 13 | 视频目标跟踪 | MeanShift、CamShift 算法 | 2 |
| 14 | 视频背景减除 | MOG、MOG2 算法 | 3 |
| 15 | 人脸检测 | Haar 级联分类器检测静态图像人脸 | 1 |
| 16 | 物体识别 | 模板匹配 `cv2.matchTemplate()` 完整案例 | 3 |
| 17 | 图像拼接 | SIFT 特征检测 + BFMatcher/KNN 匹配 + 单应变换拼接 | 1 |
| 18 | 简单滤镜效果 | 灰度 / 怀旧 / 浮雕 / 模糊 / 锐化 / 边缘检测 6 种滤镜 | 6 |

## 快速开始

### 1. 创建虚拟环境并安装依赖

```bash
# 方式一：直接使用仓库自带的虚拟环境
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # Linux / macOS

# 方式二：自行创建
python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -r requirements.txt
```

### 2. 运行示例

```bash
# 运行任意章节脚本（以 05 章图像加法为例）
python "05-opencv\opencv-05-图像相加-01.py"
```

脚本通过 `cv2.imshow` 弹出窗口显示结果，按任意键（或 Esc）关闭窗口；部分视频处理脚本按 `q` 退出。

> 所有脚本均以自身所在目录为基准拼接素材路径（`os.path.dirname(__file__)`），**无需切换工作目录**即可运行。

### 3. 查看讲义

各章 Markdown 讲义（如 `05-opencv\OpenCV图像算术运算.md`）包含原理讲解、函数原型与运行效果截图，建议配合示例脚本对照学习。

## 目录结构

```
2026-OpenCV-python/
├── 01-opencv/          # 第 1 章：入门（ipynb + 讲义）
├── 02-opencv/          # 第 2 章：基础模块（含 HighGUI 交互演示）
├── 03-opencv/          # 第 3 章：图像处理基础
├── 04-opencv/          # 第 4 章：图像基本操作（综合案例）
├── 05-opencv/          # 第 5 章：图像算术运算
├── 06-opencv/          # 第 6 章：图像阈值处理
├── 07-opencv/          # 第 7 章：图像平滑处理
├── 08-opencv/          # 第 8 章：图像形态学操作
├── 09-opencv/          # 第 9 章：图像边缘检测
├── 10-opencv/          # 第 10 章：图像轮廓检测
├── 11-opencv/          # 第 11 章：图像直方图
├── 12-opencv/          # 第 12 章：视频处理（含 YuNet 人脸检测模型）
├── 13-opencv/          # 第 13 章：视频目标跟踪
├── 14-opencv/          # 第 14 章：视频背景减除
├── 15-opencv/          # 第 15 章：人脸检测
├── 16-opencv/          # 第 16 章：物体识别（模板匹配）
├── 17-opencv/          # 第 17 章：图像拼接
├── 18-opencv/          # 第 18 章：简单滤镜效果
├── .venv/              # Python 虚拟环境（已配置依赖）
├── requirements.txt    # 依赖清单
├── output.avi          # 示例脚本输出产物（已提交，见注意事项）
├── output.mp4          # 示例脚本输出产物（已提交，见注意事项）
└── LICENSE             # 许可证
```

每个章节目录内部结构示例：

```
05-opencv/
├── OpenCV图像算术运算.md      # 讲义
├── cat.jpg / dog.jpg         # 素材
├── opencv-05-图像相加-01.py   # 示例脚本
├── opencv-05-图像相减-02.py
└── img/                      # 运行效果截图
```

## 代码约定

- **路径可移植**：统一使用 `os.path.dirname(__file__)` 定位素材，任意工作目录下运行均能找到图片。
- **中文注释**：每个知识点/步骤均有中文说明，适合边读边学。
- **两种代码形态**：
  - 早期章节（01~03）为 Jupyter Notebook（`.ipynb`）
  - 04 章起为独立 `.py` 脚本，命名规范统一：`opencv-<章节>-<知识点>-<序号>.py`
- **综合案例**：04、10、16、17 章为函数化组织的高质量综合演示（docstring、多图对比排版），其余章节为单知识点简短演示。
- **交互示例**：02 章 `highgui_demo.py` 演示鼠标点击标注 + RGB 滑动条调色 + 键盘保存/清除的完整 HighGUI 交互。

## 注意事项

1. **OpenCV 5.0 适配**：15 章静态人脸检测仍使用 Haar 方案（讲义内容），12 章视频人脸检测已适配 YuNet 深度学习方案，两章存在新旧 API 并存，学习时注意区分。
2. **输出产物**：根目录 `output.avi` / `output.mp4` 为运行 12 章脚本产生的输出文件，`.gitignore` 已忽略 `*.avi` / `*.mp4`，但这两个文件已被提交进版本库。
3. **编码问题**：`.gitignore` 文件存在 GBK/UTF-8 编码不一致导致的乱码（不影响使用）；若在 Windows 控制台运行脚本出现中文乱码，可参考 18 章脚本中的 `sys.stdout.reconfigure(encoding='utf-8')` 处理。
4. **调试遗留**：`16-opencv/test.py` 为调试遗留文件，与讲义脚本不同源。

## 许可证

本项目使用 [LICENSE](LICENSE) 文件中的开源许可证。