From ed6cd4ecbfdc93006c0222ebe6eb8bac25adc174 Mon Sep 17 00:00:00 2001 From: TuxMonkey <8196772+tuxmonkey@user.noreply.gitee.com> Date: Tue, 28 Jul 2026 15:10:47 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20add=20complete=20step-by-step=20walkthr?= =?UTF-8?q?ough=20section=20(clone=E2=86=92build=E2=86=92run=20all=208=20e?= =?UTF-8?q?xperiments)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 347 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 347 insertions(+) diff --git a/README.md b/README.md index 1cf87b3..13a2a63 100644 --- a/README.md +++ b/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