# Image Processing Project Tutorial

**Repository Path**: liufumore/image-processing-project-tutorial

## Basic Information

- **Project Name**: Image Processing Project Tutorial
- **Description**: 《OpenCV & Python 图像处理项目教程（微课版）》（项目编号 65178）配套实战源码仓库。
全库按 9 个项目（章节）组织：200+ 个可直接运行的 Python 脚本、全部示例图片/视频素材、人脸检测/识别预训练模型，以及每个项目的讲义（`项目N.md`）。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-09
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 图像处理项目教程（微课版）· 配套源代码

> 《OpenCV & Python 图像处理项目教程（微课版）》（项目编号 65178）配套实战源码仓库。
> 全库按 **9 个项目（章节）** 组织：**200+ 个可直接运行的 Python 脚本**、全部示例图片/视频素材、
> 人脸检测/识别预训练模型，以及每个项目的讲义（`项目N.md`）。

- 语言/技术栈：**Python 3.11 + OpenCV 4.10（opencv-contrib-python）+ NumPy 1.26**
- 代码风格：每个脚本对应教材一个知识点或任务，文件名 `项目-序号功能.py`，中文注释，单文件即可运行
- 平台：Windows 实测（Linux/macOS 亦兼容；`9-9` dlib 与个别脚本除外，见「注意事项」）

---

## 一、九大项目总览

| 项目 | 主题 | 核心内容 / API | 代表脚本 | 讲义 |
|---|---|---|---|---|
| 1 | 搭建开发环境——图像基础 | 数字图像概念、OpenCV 模块、运行官方示例 | `1samples/python/`（137 个 OpenCV 官方示例）、`1samples/data/` | [项目1.md](1samples/项目1.md) |
| 2 | 图片打码——图像基本操作 | 图像读写、NumPy 数组构造/遍历像素、摄像头与视频读写 | `2-2写入图像.py`、`2-9numpy构造灰度图.py`、`2-7摄像头写入视频.py` | [项目2.md](2图片打码/项目2.md) |
| 3 | 照片美化——图像变换 | 仿射/透视变换，均值/中值/高斯/双边滤波，Sobel/Laplacian，filter2D（锐化/浮雕/运动模糊），腐蚀/膨胀/形态学 | `3-2 仿射变换warpAffine.py`、`3-9双边滤波bilateralFilter.py`、`3-20高级形态变换morphologyEx.py` | [项目3.md](3照片美化/项目3.md) |
| 4 | 简易画图板——GUI | 窗口与 ROI 选择，绘制直线/矩形/圆/椭圆/多边形/文本（含中文），鼠标与键盘事件，Trackbar 调色板，综合实现画图板 | `4-11鼠标画圆.py`、`4-12简单调色板.py`、`4-15任务实现 简易画图板.py`、`应用题-奥运五环.py` | [项目4.md](4简易画图板/项目4.md) |
| 5 | 图像融合——直方图与图像金字塔 | calcHist / np.histogram，直方图均衡化与 CLAHE，直方图相似度比较，高斯/拉普拉斯金字塔，金字塔图像融合 | `5-5CLAHE自适应直方图均衡化.py`、`5-10拉普拉斯金字塔.py`、`图像融合-鼠标.py` | [项目5.md](5直方图和金字塔/项目5.md) |
| 6 | 图像换背景——图像分割 | 全局阈值、OTSU、adaptiveThreshold、inRange 颜色阈值、distanceTransform、分水岭 watershed、前景 mask 提取 | `6-2 OTSU阈值.py`、`6-6watershed分水岭.py`、`应用题6-1七巧板.py`、`视频颜色分割.py` | [项目6.md](6图像换背景/项目6.md) |
| 7 | 物品自动计数——图像轮廓 | findContours / drawContours，凸包，直边界/最小外接矩形，最小外接圆，approxPolyDP，fitEllipse / fitLine，综合实现硬币/豆子自动计数 | `7-1findContours查找轮廓.py`、`7-5boundingRect轮廓的直边界矩形.py`、`7-17任务实现-自动计数.py` | [项目7.md](7物品自动计数/项目7.md) |
| 8 | 全景图片拼接——图像特征点 | Harris / Shi-Tomasi / cornerSubPix 角点，FAST / SIFT / ORB 特征，暴力匹配与 FLANN，findHomography 单应性，Hough 直线/圆，图像拼接与无缝拼接 | `8-4SIFT_create特征点检测.py`、`8-10findHomography对象查找.py`、`8-18任务实现-图像无缝拼接.py` | [项目8.md](8全景图片拼接/项目8.md) |
| 9 | 人脸识别考勤程序——人脸检测与识别 | Haar 级联（人脸/眼睛/笑脸/车牌），DNN 人脸检测（Caffe/TensorFlow 模型），EigenFaces / FisherFaces / LBPH（cv2.face），行人 HOG 检测，dlib 68 特征点，完整考勤系统 | `9-1Haar级联分类器检测人脸.py`、`9.2.3基于LBPH的人脸识别.py`、`项目9-人脸识别考勤.py` | [项目9.md](9人脸识别考勤/项目9.md) |

各项目目录内另含 `pic/`（示例素材）、部分项目的 `faces/`、`facesImg/`、`model/`、`recognizer/`（人脸样本与预训练模型），以及 `_测试结果/`（脚本运行输出留档）。以 `_` 开头的 `.py` 是教材配套的文档校验/截图辅助工具，与知识点无关，可忽略。

## 二、目录结构

```text
.
├── 1samples/                 # 项目1：OpenCV 官方示例（python/ 137 个示例脚本 + data/ 素材）与图像基础讲义
├── 2图片打码/                 # 项目2：图像读写、NumPy 数组、像素操作、视频
├── 3照片美化/                 # 项目3：几何变换、滤波、边缘检测、形态学
├── 4简易画图板/               # 项目4：绘制函数、鼠标/键盘交互、调色板、画图板实战
├── 5直方图和金字塔/            # 项目5：直方图、均衡化、金字塔、图像融合
├── 6图像换背景/               # 项目6：阈值分割、颜色分割、分水岭、前景提取
├── 7物品自动计数/              # 项目7：轮廓查找/绘制/分析、拟合、自动计数实战
├── 8全景图片拼接/              # 项目8：角点与特征检测、匹配、单应性、拼接实战
├── 9人脸识别考勤/              # 项目9：Haar/DNN 人脸检测、三种识别器、考勤系统实战
│   ├── faces/                #   测试照片（真实人脸，注意隐私，见注意事项）
│   ├── facesImg/             #   对齐裁剪后的人脸训练样本
│   ├── model/                #   Haar 级联 XML、Caffe/TensorFlow 人脸检测模型
│   └── recognizer/           #   LBPH 训练结果 trainingData.yml（已随仓库提交）
├── .venv/                    # 【不入库】本地 Python 虚拟环境
├── opencv-4.10.0/  opencv-5.x/ # 【不入库】本地留存的 OpenCV 源码树（供编译/查阅）
├── opencv-4.10.0.zip  opencv-5.x.zip # 【不入库】上述源码的压缩包
├── requirements.txt          # 环境依赖与版本锁定说明（必读）
└── README.md                 # 本文件
```

## 三、环境搭建

> 依赖版本经过 62 个示例实测锁定，请先按本节步骤搭环境，再运行代码。详细说明见 [requirements.txt](requirements.txt) 内注释。

```powershell
# 1) 安装 Python 3.11 后，在项目根目录创建虚拟环境
python -m venv .venv

# 2) 安装依赖（国内可用阿里云镜像加速）
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
```

核心依赖：`opencv-contrib-python==4.10.0.84`（**必须是 contrib 版**，项目 9 的 `cv2.face.*` 识别器只存在于 contrib 包中）、`numpy==1.26.4`、`matplotlib==3.9.2`、`Pillow==10.4.0`。

### 为什么锁定 OpenCV 4.10 + NumPy 1.26，而不用最新版？

教程代码基于 OpenCV 4.x 编写。实测 62 个官方示例：OpenCV 4.10 + NumPy 1.26 可跑 **57** 个，OpenCV 5.0 + NumPy 2.4 仅 **48** 个。不兼容点主要包括：

- OpenCV 5：移除 `logPolar/linearPolar`（改用 `warpPolar`）；BRISK/AKAZE/KAZE 迁入 `cv2.xfeatures2d_*`；`HoughLinesP` 返回维度变化（`8-12HoughLinesP概率霍夫变换.py` 等正文代码报错）。
- NumPy 2.x：删除 `ndarray.ptp()`；单元素数组不再允许 `int()` 转换；`uint8` 越界赋值由静默截断改为抛异常。

## 四、如何运行

脚本内部全部使用 **相对路径**（`pic/`、`faces/`、`model/` 等），因此**必须先切换到对应项目目录再运行**：

```powershell
cd 4简易画图板
..\\.venv\Scripts\python "4-15任务实现 简易画图板.py"
```

- 涉及摄像头的脚本（如 `2-7摄像头写入视频.py`、`9-6任务1-采集人脸图像.py`）需要可用摄像头。
- 弹窗类脚本按 `Esc` 或任意键退出（具体见脚本内注释）。
- 运行输出与截图留档在各项目 `_测试结果/` 目录，可对照查看预期效果。

## 五、仓库中【故意不收录】的大文件

以下文件在本地保留、但不提交 Git（已写入 [.gitignore](.gitignore)），克隆后请按需自备：

| 内容 | 大小 | 原因与获取方式 |
|---|---|---|
| `.venv/` | ~272 MB | 虚拟环境因机器而异，按上文命令重建即可 |
| `opencv-4.10.0/`、`opencv-5.x/` 及两个 `.zip` | ~530 MB | 本地编译参考用的 OpenCV 源码树，非教学代码；到 [opencv/opencv releases](https://github.com/opencv/opencv/releases) 下载 |
| `9人脸识别考勤/model/lbfmodel.yaml` | 54 MB | 历史遗留的 LBPH 导出文件，**代码实际读取的是 `recognizer/trainingData.yml`（1 MB，已入库）**；且超过 Gitee 免费版单文件 50 MB 限制 |
| dlib 与 `shape_predictor_68_face_landmarks.dat`（~99 MB） | — | 仅 `9-9检测人脸的68个特征点.py` 使用；Windows 中文环境需特殊步骤编译 dlib，详见 [requirements.txt](requirements.txt) 注释；模型到 dlib 官网（shape_predictor_68_face_landmarks.dat，KD-files 镜像）下载后放到 `9人脸识别考勤/` |
| `9人脸识别考勤/faces/kaoqin.mp4` | 21.5 MB | `应用题9-1视频人脸检测.py` 使用的课堂演示视频；从教材配套资源获取，或换用任意含人脸的视频并修改脚本路径 |
| `4简易画图板/STSONG.TTF` | 11.2 MB | `4-10绘制中文.py` 所需中文字体（华文宋体），中文 Windows/Office 自带；亦可把脚本里 `fontpath` 改为 `C:/Windows/Fonts/simsun.ttc` 等本机字体 |
| `1samples/data/vtest.avi`、`2图片打码/pic/vtest.avi` | 7.8 MB ×2 | OpenCV 官方示例视频，可从本机 `opencv-4.10.0/samples/data/vtest.avi` 拷贝，或下载 OpenCV 源码包获取 |
| `1samples/python/out.ply` | 9.4 MB | `stereo_match.py` 运行时生成的产物，无需下载，重跑脚本即可再生成 |

## 六、注意事项

1. **隐私提醒**：`9人脸识别考勤/faces/`、`facesImg/` 为教材配套的**真实人脸照片**。本仓库仅作教学演示；请勿将他人照片用于其他用途，如要求下架可提 issue。
2. **SURF 不可用**：`surf特征点检测.py` 等涉及专利算法 SURF，pip 安装的 OpenCV 未编译非自由模块，需源码编译并开启 `OPENCV_ENABLE_NONFREE`（SIFT 在 4.4+ 专利过期后已包含在正常发行版中，可正常使用）。
3. **中文路径**：项目目录为中文名，个别第三方库（如旧版 dlib 的安装过程）在中文路径 + GBK 控制台下会踩坑，参见 requirements.txt 中的补丁方法。
4. **`.vscode/settings.json` 未入库**：其中含本机绝对路径，克隆后可在 VS Code 里重新选择解释器为 `.venv`。

## 七、推送到 GitHub / Gitee（上云指南）

本目录 **已初始化 Git 仓库并完成首次提交**（`master` 分支，约 1000 个文件 ≈ 141 MB，`.git` 约 140 MB；入库最大文件已控制在 5 MB 以内，远离 Gitee 50 MB 限制）。只需两步即可上云：

```powershell
# 0) 仅首次使用 git 时需要（配置提交者身份）
git config --global user.name  "你的名字"
git config --global user.email "you@example.com"

# 1) 在 GitHub 和 Gitee 网页上各新建一个【空的】仓库（不要勾选自动生成 README/.gitignore）

# 2) 绑定两个云端仓库并推送
git remote add origin https://github.com/<你的用户名>/<仓库名>.git
git remote add gitee  https://gitee.com/<你的用户名>/<仓库名>.git
git push -u origin main      # 推 GitHub
git push -u gitee  main      # 推 Gitee
# 以后日常：改完 → git add . ; git commit -m "..." ; git push origin main ; git push gitee main
```

要点与排错：

- **单文件限制**：GitHub 超过 100 MiB 直接拒收（50 MiB 警告）；Gitee 免费版单文件 50 MB。≥5 MB 的大素材已按第五节停止跟踪，当前入库最大文件为人脸检测模型 `caffemodel`（约 5.1 MB），安全线以内。
- **HTTPS 推送慢/超时**：可 `git config http.postBuffer 524288000`，或改用 SSH 远端；国内推 GitHub 建议代理，Gitee 直连即可。
- **认证**：GitHub 已不支持密码，用 Personal Access Token（Settings → Developer settings → Tokens）或 SSH key；Gitee 用密码或 SSH key。
- **如果误把大文件提交进了历史**：`git push` 被拒后不能只删文件再推，需用 `git filter-repo --path <文件> --invert-paths` 重写历史（或干脆删 `.git` 重新 init）。可随时用 `git ls-files | ForEach-Object { (Get-Item $_).Length } | Measure-Object -Maximum` 检查入库文件是否超限。
- **想瘦身**：`1samples/`（约 52 MB，OpenCV 官方示例）如无需上云，可将其加入 `.gitignore` 后 `git rm -r --cached 1samples` 移除，只推项目 2–9。
- 若确有必要提交 >50 MB 的文件，可改用 Git LFS：`git lfs install && git lfs track "*.zip"`，GitHub LFS 免费 1 GB 存储/每月 1 GB 流量，Gitee 需付费资源包。

## 八、许可与免责声明

本仓库附带 **Apache License 2.0**（见 [LICENSE](LICENSE)），适用于本次提交的原创脚本与整理内容；但**教材文字及配套素材**（`pic/`、`faces/`、`facesImg/` 等图片、视频、人脸照片示例）的版权归原作者与出版社所有，仅供学习与教学演示使用，请勿用于商业分发。如需商用或要求下架相关素材，请联系出版社或通过 issue 沟通。