snowycv 1.1.3

My own computer vision library

❄️ SnowyCV 计算机视觉可视化工具箱

Version: 1.0 | 基于 Python + OpenCV + Open3D + Tkinter

一站式零代码视觉工具，集成图像预处理、分割、特征匹配、2D测量、双目3D重建全链路功能，支持实时预览 + 自动生成可运行Python代码，兼顾教学学习、课程设计、算法快速验证与简易工程调试。

---

目录

1. 项目简介
2. 环境依赖与安装
3. 项目文件结构
4. 整体运行方式
5. 九大功能模块详细使用说明
6. 通用功能说明
7. 常见问题 & 故障排查
8. 功能拓展建议
9. 开源声明

---

1. 项目简介

1.1 项目概述

SnowyCV 是一套纯 Python 开发的图形化计算机视觉工具箱，依托 OpenCV 实现主流图像处理算法、Open3D 实现 3D 点云可视化，Tkinter 搭建统一交互界面。 全程无需手动编写代码，通过按钮、滑块、单选框、鼠标交互完成所有操作，参数调节实时生效，同时自动生成对应算法代码，方便学习、复用与二次开发。

1.2 适用场景

• 📚 高校课程：数字图像处理、机器视觉、OpenCV 课程实验、课程设计、毕业设计
• 🧪 算法验证：快速调试图像处理参数、对比不同算法效果
• 👨‍💻 入门学习：OpenCV 零基础入门，直观理解算法原理
• 🏭 简易工程：工业图像2D测量、双目视觉配准、点云预览等轻量化需求

1.3 核心优势

• ✅ 统一UI风格：所有功能模块布局、交互逻辑一致，上手零成本
• ✅ 实时预览：参数拖动、功能切换即时展示处理效果
• ✅ 代码自动生成：每一步操作生成标准 Python+OpenCV 代码，可直接复制运行
• ✅ 2D+3D 全覆盖：从基础图像处理到双目深度、3D点云一站式完成
• ✅ 轻量化：纯Python实现，部署简单，跨Windows/Linux平台

---

2. 环境依赖与安装

2.1 依赖库列表

本项目依赖以下第三方库，请提前安装：

库名称	作用
opencv-python	核心图像处理、算法实现
opencv-contrib-python	扩展算法（SIFT/SURF/AKAZE等特征算子）
numpy	矩阵运算、数值计算
pillow	图像格式转换、Tkinter图像渲染
open3d	3D点云加载、可视化

2.2 一键安装命令

打开命令提示符(CMD) / 终端，执行以下 pip 命令：

# 国内镜像（推荐，加速下载）
pip install opencv-python opencv-contrib-python numpy pillow open3d -i https://pypi.tuna.tsinghua.edu.cn/simple

注意事项：

1. 建议使用 Python 3.8 ~ 3.11 版本，高版本Python可能存在Open3D兼容性问题；
2. 若已安装旧版本 OpenCV，建议先卸载再重装：pip uninstall opencv-python opencv-contrib-python；
3. Linux 系统若提示权限不足，在命令后加 --user。

---

3. 项目文件结构

将所有代码文件放在同一个文件夹下，完整目录如下：

SnowyCV/
├── main.py                # 【主程序入口】全局菜单，一键切换所有功能模块
├── page1_preprocess.py    # 模块1：图像预处理（滤波、二值化、形态学）
├── page2_shape_analysis.py# 模块2：轮廓检测、边缘检测、形态分析
├── page3_advanced_segment.py # 模块3：分水岭/区域生长/模板匹配
├── page4_feature_matcher.py  # 模块4：双图特征点匹配（ORB/SIFT/FAST等）
├── page5_restore_color.py    # 模块5：图像复原、去模糊、HSV色彩提取
├── page6_2d_measure.py       # 模块6：2D交互式测量（长度/角度/直径/面积）
├── page7_geometry.py         # 模块7：几何变换（旋转、仿射、透视、裁剪）
├── page8_3d_vision.py        # 模块8：3D双目视觉、视差/深度/点云、手眼标定
└── README.md                 # 项目使用文档（本文档）

---

4. 整体运行方式

4.1 启动主程序

1. 进入项目根目录 SnowyCV；
2. 打开终端/CMD，执行命令：

   import snowycv
   snowycv.run()
   

   或者
3. 安装完，直接输入就能打开软件：

  snowycv
  

c 3. 程序启动后会显示主菜单界面，点击对应按钮即可跳转至各个功能子页面。

4.2 单独运行子模块

如需单独调试某一个功能，可直接运行对应页面文件：

# 示例：单独运行3D视觉模块
python page8_3d_vision.py

4.3 基础界面通用规则

所有子模块界面遵循统一布局：

1. 左侧：原始图像预览区 + 加载图片按钮；
2. 中间：功能选择、参数调节面板（支持滚动）；
3. 右侧：处理结果预览区 + 结果导出按钮；
4. 底部：自动生成代码展示区、全局重置、代码导出按钮；
5. 鼠标滚轮：参数面板/全局界面支持滚轮上下滚动。

---

5. 九大功能模块详细使用说明

模块1：图像预处理（page1_preprocess.py）

功能定位：图像基础降噪、二值化、形态学操作，是所有视觉任务的前置步骤。

支持功能

• 滤波：高斯模糊、中值滤波、双边滤波；
• 二值化：全局二值化、自适应二值化、Otsu自动阈值；
• 形态学操作：腐蚀、膨胀、开运算、闭运算、梯度运算；
• 基础转换：灰度化、色彩空间转换。

使用步骤

1. 点击「加载图片」选择本地图像；
2. 在参数面板选择处理算法，拖动滑块调节参数；
3. 右侧实时查看处理效果；
4. 底部代码区自动生成对应代码，可导出 .py 文件；
5. 点击「重置所有参数」恢复默认配置。

---

模块2：轮廓检测与形态分析（page2_shape_analysis.py）

功能定位：边缘提取、轮廓检测、目标形态特征计算。

支持功能

• 边缘检测：Sobel、Laplacian、Canny 主流算子；
• 轮廓操作：轮廓绘制、外接矩形、最小旋转矩形、凸包、多边形拟合；
• 特征计算：轮廓面积、周长、圆形度。

使用步骤

1. 加载原图，选择边缘检测算法并调节阈值；
2. 切换轮廓绘制模式，自定义线条颜色、粗细；
3. 查看轮廓形态与特征数据；
4. 导出标注图像与算法代码。

---

模块3：高级图像分割（page3_advanced_segment.py）

功能定位：复杂目标分割，解决目标粘连、目标定位场景。

三大核心功能

1. 分水岭分割
   • 适用：粘连物体分割；
   • 参数：形态学核大小、距离变换阈值系数；
   • 使用：勾选「启用分水岭分割」，拖动参数实时优化分割效果。
2. 区域生长
   • 适用：同色块区域填充分割；
   • 参数：种子点坐标、灰度阈值、4/8邻域切换；
   • 使用：手动设置种子点 (X/Y)，调整灰度相似度阈值。
3. 模板匹配
   • 适用：在大图中查找指定模板目标；
   • 支持4种匹配算法，加载模板图后点击「执行匹配」，自动框选匹配区域。

---

模块4：双图特征点匹配（page4_feature_matcher.py）

功能定位：图像配准、拼接、目标检索，主流特征算子一站式测试。

支持算法

ORB、SIFT、SURF、AKAZE、BRISK、FAST 六大经典特征检测算法。

核心功能

• 匹配策略：KNN匹配（推荐）、交叉匹配；
• 辅助配置：KNN阈值、保留匹配点数量、匹配线条颜色/粗细；
• 场景快捷选型：内置「图像拼接、双目配准、高精度检测、实时运行」等场景预设；
• 数据输出：实时显示匹配度、匹配点数量、特征平均距离。

使用步骤

1. 分别加载「图像1」和「图像2」；
2. 选择特征算法与匹配策略，可直接选择场景预设；
3. 点击「执行匹配」，右侧展示匹配连线效果图；
4. 底部自动生成特征匹配完整代码。

提示：SIFT/SURF 为专利算法，需确保 opencv-contrib-python 正常安装。

---

模块5：图像复原 & 色彩提取（page5_restore_color.py）

功能定位：老旧图像修复、逆光图像优化、指定颜色筛选。

功能分类

1. 图像复原增强
   • 维纳滤波：去除运动模糊；
   • 逆光修复：基于LAB空间亮度均衡，优化过暗/过亮区域；
   • 双边滤波：去除划痕、细小噪点（保留边缘）；
   • 简易超分辨率：图像放大优化。
2. 色彩处理
   • 色彩空间转换：RGB → HSV / HSI；
   • 白平衡、色差校正（亮度/对比度调节）；
3. HSV颜色筛选
   • 一键提取：红色、绿色、蓝色（内置经典HSV阈值）；
   • 手动调节 H/S/V 上下限，自定义颜色筛选范围。

---

模块6：2D交互式测量工具（page6_2d_measure.py）

功能定位：基于鼠标交互的像素级2D测量，工业视觉尺寸检测轻量化方案。

测量模式（5种）

长度测量、角度测量、圆孔直径、两点间距、多边形面积。

交互规则

• 鼠标左键：在图像上打点（测量关键点）；
• 鼠标左键拖拽：拖动已选点位，实时修正测量结果；
• 鼠标右键：一键清空所有测量点；

使用步骤

1. 加载待测图像；
2. 在控制面板选择对应测量模式；
3. 根据模式打点：
   • 长度/间距：打2个点；
   • 角度：打3个点（角顶点放中间）；
   • 圆孔直径/面积：打≥3个点；
4. 界面实时显示测量像素值；
5. 支持导出标注效果图和 TXT测量数据文件。

---

模块7：几何变换（page7_geometry.py）

功能定位：图像空间变换、视角校正。

支持功能

• 基础变换：缩放、旋转、平移、水平/垂直镜像、裁剪；
• 高级变换：仿射变换、透视变换（四点标定校正倾斜图像）；

使用说明

• 旋转：设置旋转角度、旋转中心；
• 透视变换：手动选取4个角点，自动校正透视畸变（文档扫描、倾斜照片常用）。

---

模块8：3D视觉工具箱（page8_3d_vision.py）

功能定位：双目视觉全流程：双目图 → 视差图 → 深度图 → 3D点云，附带手眼标定助手。

依赖：必须安装 open3d 库。

核心流程（按顺序执行）

1. 加载左图 / 加载右图：选择双目相机拍摄的左右对齐图像；
2. 计算视差图：基于StereoBM算法生成视差热力图；
3. 重建深度图：根据相机焦距、基线距离，由视差换算出深度信息；
4. 生成3D点云：结合左图色彩与深度数据，生成彩色三维点云；
5. 显示点云：调用Open3D窗口可视化点云，支持鼠标旋转、缩放、平移视角；
6. 手眼标定助手：弹窗提示手眼标定（眼在手上/眼固定）功能说明，可在此基础上二次开发标定算法。

全局操作

• 「清空」：重置所有图像、视差、深度、点云数据。

---

6. 通用功能说明

6.1 图片导出

所有带「导出结果」按钮的模块：

1. 处理完图像后，点击按钮；
2. 选择保存路径、文件名、格式（PNG/JPG）；
3. 确认后完成图片导出。

6.2 代码导出

1. 底部代码区域会实时同步当前操作的完整Python代码；
2. 点击「导出Python代码」，选择路径保存为 .py 文件，可直接用Python运行。

6.3 全局重置

「重置所有参数」按钮作用：

• 清空已加载图像、处理结果；
• 所有滑块、单选框、勾选框恢复为默认参数；
• 清空代码区、测量数据、日志信息。

6.4 滚动界面操作

参数面板、主界面均支持：

• 鼠标滚轮：上下滚动；
• 兼容Linux/Mac 触摸板、鼠标上下键。

---

7. 常见问题 & 故障排查

问题1：运行代码提示 ModuleNotFoundError

• 原因：对应依赖库未安装；
• 解决：重新执行 2.2 一键安装命令，补全所有依赖。

问题2：SIFT/SURF 算法无法使用、报错

• 原因：缺少 opencv-contrib-python 扩展库；
• 解决：安装扩展库 pip install opencv-contrib-python。

问题3：3D点云无法显示，提示 No module named open3d

• 解决：单独安装Open3D：pip install open3d；
• 兼容问题：Python 3.12+ 对Open3D支持较差，建议降级至 Python3.9/3.10。

问题4：图像加载后预览区域空白

• 原因1：图片路径包含中文、特殊字符、空格； 解决：将图片移动到纯英文路径下（如 D:/img/test.jpg）。
• 原因2：图片格式不支持； 支持格式：jpg / jpeg / png / bmp / tif，不支持webp、heic等格式。

问题5：2D测量打点位置和实际像素偏差大

• 原因：预览图做了缩放适配；
• 说明：程序内部已做坐标换算，测量结果为原始图像真实像素，不影响精度。

问题6：程序闪退、卡顿

• 解决1：使用尺寸较小的测试图片（建议分辨率 < 2000*2000）；
• 解决2：关闭其他占用内存的软件，重启程序。

---

8. 功能拓展建议

基于现有框架，可自主拓展以下功能：

1. 算法拓展：新增深度学习分割（YOLO、U-Net）、更多特征匹配算法；
2. 标定功能：完善手眼标定、相机内参标定、棋盘格角点检测；
3. 单位换算：2D测量增加物理单位(mm/cm)，结合标定板实现像素-实际尺寸转换；
4. 批量处理：增加文件夹批量图像处理、批量导出功能；
5. 点云拓展：点云滤波、点云裁剪、点云配准、点云网格重建。

---

9. 开源声明

1. 本项目基于 MIT 开源协议，免费用于学习、教学、个人项目；
2. 禁止直接二次打包为商业软件售卖；
3. 引用本项目代码/功能时，请保留项目出处说明；
4. 项目基于 OpenCV、Open3D 开源库开发，遵循对应开源协议。

---

补充：快速上手流程（新手极简版）

1. 安装依赖库 → 运行 main.py 打开主菜单；
2. 选择功能模块 → 加载本地测试图片；
3. 选择算法 + 调节参数 → 查看实时效果；
4. 按需导出图片 / 导出代码；
5. 完成测试后点击「重置所有参数」。