docs: add complete step-by-step walkthrough section (clone→build→run all 8 experiments)
This commit is contained in:
TuxMonkey
347
README.md
347
README.md
@@ -9,6 +9,7 @@
|
||||
|
||||
## 📖 目录
|
||||
|
||||
0. [完整实操演练：从下载到运行（跟随操作）](#0-完整实操演练从下载到运行跟随操作)
|
||||
1. [课前准备：你的第一个任务](#1-课前准备你的第一个任务)
|
||||
2. [什么是 OpenCV？为什么要学它？](#2-什么是-opencv为什么要学它)
|
||||
3. [环境准备：在你的电脑上安装 OpenCV](#3-环境准备在你的电脑上安装-opencv)
|
||||
@@ -27,6 +28,352 @@
|
||||
|
||||
---
|
||||
|
||||
## 0. 完整实操演练：从下载到运行（跟随操作）
|
||||
|
||||
> 如果你是第一次接触这个项目，请**一步一步跟随本节的命令操作**。你会看到完整的终端输出，帮助确认每一步是否正确。
|
||||
> 建议打开一个 WSL 终端窗口，**看到一条命令就敲一条**，不要一次性全部粘贴。
|
||||
|
||||
---
|
||||
|
||||
### Step 0：打开 WSL 并克隆仓库
|
||||
|
||||
首先按 `Win + R`，输入 `wsl`，回车，打开 WSL 终端。
|
||||
|
||||
```bash
|
||||
# 进入你的 WSL 家目录
|
||||
cd ~
|
||||
|
||||
# 克隆仓库
|
||||
git clone https://code.tuxmonkey.cn/TuxMonkey/vision-training-2026-opencvcpp.git
|
||||
|
||||
# 进入仓库
|
||||
cd vision-training-2026-opencvcpp
|
||||
|
||||
# 看看里面有什么
|
||||
ls
|
||||
```
|
||||
|
||||
**你应该看到的输出：**
|
||||
|
||||
```
|
||||
exp1_read_write/ exp2_color_space/ exp3_gaussian_blur/ exp4_canny/
|
||||
exp5_threshold/ exp6_morphology/ exp7_inrange/ exp8_pipeline/
|
||||
images/ README.md
|
||||
```
|
||||
|
||||
> **如果提示 `git: command not found`**，先运行 `sudo apt install -y git`，再重新 clone。
|
||||
|
||||
---
|
||||
|
||||
### Step 1：编译运行 exp1（图像读取与保存）
|
||||
|
||||
```bash
|
||||
cd ~/vision-training-2026-opencvcpp/exp1_read_write
|
||||
mkdir build && cd build
|
||||
cmake ..
|
||||
make -j4
|
||||
./exp1
|
||||
```
|
||||
|
||||
**你应该看到的关键输出：**
|
||||
|
||||
```
|
||||
[步骤 1] 正在生成一张 640x480 的彩色测试图片...
|
||||
-> 测试图片已保存为 test_image.jpg
|
||||
[步骤 2] 正在读取 test_image.jpg...
|
||||
-> 读取成功！图像信息：
|
||||
宽度 (cols): 640 像素
|
||||
高度 (rows): 480 像素
|
||||
通道数: 3 (3=彩色, 1=灰度)
|
||||
[步骤 3] 正在保存为 output.jpg...
|
||||
-> 图片已成功保存为 output.jpg
|
||||
-> 请在 Windows 资源管理器中打开该文件查看结果！
|
||||
|
||||
===== 实验 1 完成 =====
|
||||
你学会了：
|
||||
1. cv::Mat 是 OpenCV 存储图像的数据类型
|
||||
2. cv::imread() 从文件读取图像
|
||||
3. cv::imwrite() 将图像写入文件
|
||||
4. 读取后一定要检查 empty()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 2：编译运行 exp2（颜色空间转换）
|
||||
|
||||
```bash
|
||||
cd ~/vision-training-2026-opencvcpp/exp2_color_space
|
||||
mkdir build && cd build
|
||||
cmake ..
|
||||
make -j4
|
||||
./exp2
|
||||
```
|
||||
|
||||
**关键输出：**
|
||||
|
||||
```
|
||||
[步骤 1] 正在生成彩色测试图片...
|
||||
-> 原始彩色图已保存为 original.jpg
|
||||
[步骤 2] BGR -> Gray（灰度）...
|
||||
-> 已保存为 gray.jpg（单通道灰度图）
|
||||
[步骤 3] BGR -> HSV...
|
||||
-> 已保存为 hsv.jpg（注意：HSV 图片直接查看颜色会怪怪的...）
|
||||
[步骤 4] BGR -> Lab...
|
||||
-> 已保存为 lab.jpg
|
||||
[步骤 5] BGR -> YCrCb...
|
||||
-> 已保存为 ycrcb.jpg
|
||||
[步骤 6] 分离 HSV 各通道...
|
||||
-> 已保存 hsv_channel_H.jpg / S.jpg / V.jpg
|
||||
|
||||
===== 实验 2 完成 =====
|
||||
你学会了：
|
||||
1. cv::cvtColor() 可以在不同颜色空间之间转换
|
||||
2. BGR → Gray：加权平均得到亮度
|
||||
3. BGR → HSV：分开颜色和亮度，对光照变化更鲁棒
|
||||
4. cv::split() 把多通道图像拆成单通道
|
||||
5. RoboMaster 中 HSV 是核心！后面实验 7 会用到
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 3：编译运行 exp3（高斯模糊）
|
||||
|
||||
```bash
|
||||
cd ~/vision-training-2026-opencvcpp/exp3_gaussian_blur
|
||||
mkdir build && cd build
|
||||
cmake ..
|
||||
make -j4
|
||||
./exp3
|
||||
```
|
||||
|
||||
**关键输出：**
|
||||
|
||||
```
|
||||
[步骤 1] 正在生成测试图片（含清晰边缘和纹理）...
|
||||
-> 原始图片已保存为 original.jpg（注意看上面的散点噪声）
|
||||
[步骤 2] 应用轻微高斯模糊 (ksize = 3x3)...
|
||||
-> 已保存为 blur_3x3.jpg（轻微模糊，细节基本保留）
|
||||
[步骤 3] 应用中度高斯模糊 (ksize = 9x9)...
|
||||
-> 已保存为 blur_9x9.jpg（中度模糊，噪声消失，边缘变软）
|
||||
[步骤 4] 应用重度高斯模糊 (ksize = 21x21)...
|
||||
-> 已保存为 blur_21x21.jpg（重度模糊，近乎一片朦胧）
|
||||
[步骤 5] 应用各向异性模糊 (sigmaX=15, sigmaY=3)...
|
||||
-> 已保存为 blur_anisotropic.jpg（水平方向很糊，垂直方向较清晰）
|
||||
|
||||
===== 实验 3 完成 =====
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 4：编译运行 exp4（Canny 边缘检测）
|
||||
|
||||
```bash
|
||||
cd ~/vision-training-2026-opencvcpp/exp4_canny
|
||||
mkdir build && cd build
|
||||
cmake ..
|
||||
make -j4
|
||||
./exp4
|
||||
```
|
||||
|
||||
**关键输出：**
|
||||
|
||||
```
|
||||
[步骤 1] 正在生成测试图片（包含各种边缘结构）...
|
||||
-> 原始图片已保存为 original.jpg
|
||||
[步骤 2] 转换为灰度图...
|
||||
-> 灰度图已保存为 gray.jpg
|
||||
[步骤 3] Canny 边缘检测 (阈值 50 / 150)...
|
||||
-> 已保存为 edges_low.jpg（低阈值，细节丰富）
|
||||
[步骤 4] Canny 边缘检测 (阈值 100 / 200)...
|
||||
-> 已保存为 edges_mid.jpg（中等阈值，适中结果）
|
||||
[步骤 5] Canny 边缘检测 (阈值 200 / 400)...
|
||||
-> 已保存为 edges_high.jpg（高阈值，只保留强边缘）
|
||||
[步骤 6] 先高斯模糊，再 Canny 边缘检测...
|
||||
-> 已保存为 blurred.jpg（高斯模糊后）
|
||||
-> 已保存为 edges_after_blur.jpg（模糊后再做 Canny，边缘更干净）
|
||||
|
||||
===== 实验 4 完成 =====
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 5：编译运行 exp5（图像阈值化）
|
||||
|
||||
```bash
|
||||
cd ~/vision-training-2026-opencvcpp/exp5_threshold
|
||||
mkdir build && cd build
|
||||
cmake ..
|
||||
make -j4
|
||||
./exp5
|
||||
```
|
||||
|
||||
**关键输出：**
|
||||
|
||||
```
|
||||
[步骤 1] 正在生成灰度渐变测试图...
|
||||
-> 原始渐变图已保存为 gradient.jpg
|
||||
[步骤 2] THRESH_BINARY（标准二值化）...
|
||||
[步骤 3] THRESH_BINARY_INV（反二值化）...
|
||||
[步骤 4] THRESH_TRUNC（截断）...
|
||||
[步骤 5] THRESH_TOZERO（置零）...
|
||||
[步骤 6] THRESH_TOZERO_INV（反置零）...
|
||||
|
||||
===== 实验 5 完成 =====
|
||||
你学会了：
|
||||
1. 阈值化就是把灰度图按某个界限分成两部分
|
||||
2. 有 5 种阈值类型，最常用的是 THRESH_BINARY
|
||||
3. 阈值化是图像分割的基础操作
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 6：编译运行 exp6（形态学操作）
|
||||
|
||||
```bash
|
||||
cd ~/vision-training-2026-opencvcpp/exp6_morphology
|
||||
mkdir build && cd build
|
||||
cmake ..
|
||||
make -j4
|
||||
./exp6
|
||||
```
|
||||
|
||||
**关键输出：**
|
||||
|
||||
```
|
||||
[步骤 1] 正在生成二值测试图片...
|
||||
-> 原始二值图已保存为 binary.jpg
|
||||
[步骤 2] 执行腐蚀操作 (Erosion)...
|
||||
[步骤 3] 执行膨胀操作 (Dilation)...
|
||||
[步骤 4] 执行开运算 (Opening = 腐蚀 + 膨胀)...
|
||||
[步骤 5] 执行闭运算 (Closing = 膨胀 + 腐蚀)...
|
||||
[步骤 6] 执行多次腐蚀 (iterations=3)...
|
||||
|
||||
===== 实验 6 完成 =====
|
||||
你学会了：
|
||||
1. 腐蚀：白色区域缩小，可以去噪点
|
||||
2. 膨胀：白色区域扩大，可以填黑洞
|
||||
3. 开运算：去噪点但大体保持目标大小
|
||||
4. 闭运算：填空洞但大体保持目标大小
|
||||
5. 结构元素决定了操作的形状和范围
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 7：编译运行 exp7（颜色提取——核心！）
|
||||
|
||||
```bash
|
||||
cd ~/vision-training-2026-opencvcpp/exp7_inrange
|
||||
mkdir build && cd build
|
||||
cmake ..
|
||||
make -j4
|
||||
./exp7
|
||||
```
|
||||
|
||||
**关键输出：**
|
||||
|
||||
```
|
||||
[步骤 1] 正在生成彩色测试图片...
|
||||
-> 原始彩色图片已保存为 original.jpg
|
||||
[步骤 2] 将 BGR 图片转换为 HSV...
|
||||
[步骤 3] 使用 inRange 提取红色区域...
|
||||
[步骤 4] 用 mask 提取原图中的红色部分...
|
||||
[步骤 5] 额外实验：提取蓝色区域...
|
||||
|
||||
===== 实验 7 完成 =====
|
||||
你学会了：
|
||||
1. inRange 按颜色范围提取目标区域
|
||||
2. 为什么要用 HSV：分离颜色和亮度
|
||||
3. 红色需要两个 H 范围（因为色相是环状）
|
||||
4. bitwise_or 合并 mask，bitwise_and 提取原图
|
||||
5. 这是 RoboMaster 视觉灯条检测的基础！
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 8：编译运行 exp8（综合流水线——串联一切！）
|
||||
|
||||
```bash
|
||||
cd ~/vision-training-2026-opencvcpp/exp8_pipeline
|
||||
mkdir build && cd build
|
||||
cmake ..
|
||||
make -j4
|
||||
./exp8
|
||||
```
|
||||
|
||||
**这是最重要的一个实验！你应该看到如下输出：**
|
||||
|
||||
```
|
||||
===== 实验 8：综合流水线 开始 =====
|
||||
|
||||
[阶段 1/6] 生成模拟 RoboMaster 场景的测试图片...
|
||||
-> 已保存 01_original_scene.jpg（原始场景图）
|
||||
[阶段 2/6] BGR → HSV 颜色空间转换...
|
||||
-> 已保存 02_hsv.jpg
|
||||
[阶段 3/6] 高斯模糊（减少噪点对后续处理的影响）...
|
||||
-> 已保存 03_hsv_blurred.jpg（模糊后的 HSV 图）
|
||||
[阶段 4/6] inRange 提取红色区域...
|
||||
-> 已保存 04_red_mask_raw.jpg（原始红色 mask）
|
||||
[阶段 5/6] 形态学操作清理 mask...
|
||||
-> 已保存 05a_mask_opened.jpg（开运算：去除噪点）
|
||||
-> 已保存 05b_mask_cleaned.jpg（闭运算：填充内部空洞）
|
||||
[阶段 6/6] 在原图上标记检测结果...
|
||||
-> 已保存 06a_red_extracted.jpg（仅保留红色区域）
|
||||
-> 已保存 06b_mask_edges.jpg（mask 的边缘检测结果）
|
||||
-> 共找到 5 个轮廓
|
||||
-> 已保存 06c_result.jpg（最终结果：绿灯条框标记 = 检测到的灯条）
|
||||
-> 共检测到 2 个有效灯条
|
||||
|
||||
===== 实验 8 完成 =====
|
||||
流水线回顾（你完整的加工步骤）：
|
||||
1. 读取 / 生成图像
|
||||
2. BGR → HSV 颜色空间转换
|
||||
3. 高斯模糊（去噪）
|
||||
4. inRange 提取目标颜色
|
||||
5. 形态学操作（清理 mask）
|
||||
6. 轮廓检测 + 画框（定位目标）
|
||||
|
||||
恭喜你！这已经是一个简化的 RoboMaster 灯条检测流程了！
|
||||
```
|
||||
|
||||
> **重点看这一行**：`-> 共检测到 2 个有效灯条`
|
||||
> 这说明程序成功从图中找出了两个红色灯条！如果看到的是其他数字，说明筛选参数需要微调（参见讲义第 13 节）。
|
||||
|
||||
---
|
||||
|
||||
### 如何查看输出的图片
|
||||
|
||||
每个实验运行后，输出图片都保存在各自的 `build/` 文件夹中。有两种方式查看：
|
||||
|
||||
**方式一（推荐）：用 Windows 资源管理器打开**
|
||||
|
||||
在 WSL 终端的 build 目录下运行：
|
||||
|
||||
```bash
|
||||
explorer.exe .
|
||||
```
|
||||
|
||||
会在 Windows 资源管理器中打开当前目录，你可以直接双击 `.jpg` 文件查看图片。
|
||||
|
||||
**方式二：在 WSL 中确认文件存在**
|
||||
|
||||
```bash
|
||||
ls *.jpg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 重要提醒
|
||||
|
||||
1. **每个实验完全独立**——只需要进入对应的 exp 文件夹，`mkdir build && cd build && cmake .. && make -j4 && ./expX` 即可运行。不需要按顺序执行。
|
||||
2. **`mkdir build && cd build && cmake .. && make -j4` 是重复出现的"标准四步"**，每个实验都一样，请记住这套编译流程。
|
||||
3. **生成的图片请仔细对比**——讲义中每个实验末尾都有"运行结果预览"表格，列出了 `asset/` 文件夹中的参考图片。把你自己生成的图片和参考图片做对比，确保效果一致。
|
||||
4. **如果编译报错**：
|
||||
- 最常见的错误是 OpenCV 没装好，运行 `pkg-config --modversion opencv4` 确认版本号能正确输出。
|
||||
- 其次是在错误的目录运行了 cmake，请确保你**在 `build/` 目录内**运行 `cmake ..`（注意是两个点 `..`，表示上一级目录）。
|
||||
5. **所有实验的运行结果图片都可在 `asset/` 文件夹找到参考版本**，如果你不确定自己的输出是否正确，可以对比参考图。
|
||||
|
||||
---
|
||||
|
||||
## 1. 课前准备：你的第一个任务
|
||||
|
||||
### 1.1 确认你的电脑上已经有 WSL Ubuntu
|
||||
|
||||
Reference in New Issue
Block a user