Metadata-Version: 2.4
Name: snowycv
Version: 1.1.3
Summary: My own computer vision library
Home-page: https://github.com/SnowyMCP/SnowyCV
Author: snowy
Author-email: mucp6270@163.com
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: opencv-python
Requires-Dist: numpy
Requires-Dist: onnxruntime
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ❄️ SnowyCV 计算机视觉可视化工具箱
**Version: 1.0 | 基于 Python + OpenCV + Open3D + Tkinter**

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

---

## 目录
1. [项目简介](#1-项目简介)
2. [环境依赖与安装](#2-环境依赖与安装)
3. [项目文件结构](#3-项目文件结构)
4. [整体运行方式](#4-整体运行方式)
5. [九大功能模块详细使用说明](#5-九大功能模块详细使用说明)
6. [通用功能说明](#6-通用功能说明)
7. [常见问题 & 故障排查](#7-常见问题--故障排查)
8. [功能拓展建议](#8-功能拓展建议)
9. [开源声明](#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 命令：
```bash
# 国内镜像（推荐，加速下载）
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，执行命令：
   ```bash
   import snowycv
   snowycv.run()
   ```
   或者
3. 安装完，直接输入就能打开软件：
 ```bash
   snowycv
   
   ```
c
3. 程序启动后会显示**主菜单界面**，点击对应按钮即可跳转至各个功能子页面。

### 4.2 单独运行子模块
如需单独调试某一个功能，可直接运行对应页面文件：
```bash
# 示例：单独运行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 一键安装命令](#22-一键安装命令)，补全所有依赖。

### 问题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. 完成测试后点击「重置所有参数」。
