# vision

**Repository Path**: feng_yezi/vision

## Basic Information

- **Project Name**: vision
- **Description**: 2d视觉
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-15
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# vision

可嵌入的二维视觉流程库。宿主传入图像，流程通过独立 DLL 节点处理，最终返回带固定类型字段的 JSON。

## 第一版

- 计算接口：IVision；无窗口内核：createCore；嵌入编辑器：createVision 返回 IVisionGui。
- 数据：IData、IImage、IPose2D、IAffine2D、IJsonData；下游可绑定任意上游输出。
- 视图：I2DView；ROI：IRoi（矩形、圆形、圆环、多边形）。矩形、圆形和圆环支持拖拽手柄缩放。
- 四个标准 DLL：2D预处理（一个工具，内部 7 种处理步骤）、圆形查找、2D定位补正、数据导出。
- 独立插件模板：plugin_template，仅依赖安装后的 Vision::sdk。
- 流程保存恢复、运行取消、类型/环校验；窗口不覆盖宿主 QSS。
- OpenCV 4.12.0 已通过现有 vcpkg 安装，算法只使用 core/imgproc。

当前找圆使用真实图像边缘、有效掩膜过滤和轮廓最小二乘拟合，不是霍夫圆查找。官方定位补正采用 ROI 模板匹配，保存参考图并直接输出平移补正矩阵；暂不包含复杂检测、机台控制或三维处理。[ROI 定位跟随](docs/ROI定位跟随.md)由框架统一管理：仅选择矩阵来源，不需要下游示教；框架支持平移与旋转。编辑器采用紧凑流程列表和手动输入来源选择，不是可自由拖线的节点画布。

## 打开试用

本机源码工程 Release 界面：
C:/item/libs/out/build/vision/release/run/vision_example.exe

打开根目录 CMake 工程后，默认构建 vision_example 和 vision_contract_test。Visual Studio 重新配置后，在启动目标中选择 vision_example.exe；测试目标不是示例界面。构建自动部署 Qt 平台插件和运行 DLL，直接运行不需要指定 Qt 插件路径。

1. 点击“示例图像”或“图像导入”。
2. 在配置列表下方的仓库选择“图像处理”页签，将“2D预处理”拖到上方列表指定位置。
3. 双击设置算法参数和手动输入来源；窗口底部“单步调试”提交当前参数并执行到本节点，关闭窗口也会保存并执行，没有取消按钮。预处理内部添加、排序和设置步骤，数据导出内部配置字段映射。框架管理名称、输入来源和 ROI；拖动外层列表仅调整顺序，不接线。显示编号按插件类型分别累计，例如“2D预处理1、圆形查找1”，删除不回收，数据连接的内部 ID 始终全局唯一。
4. 右键节点“单步调试”会重跑其依赖并执行到该节点；选中节点时，列表顶部标准结果面板显示状态、耗时与 JSON 属性树。最右侧“运行”执行完整流程，最终信封通过底部 logger 打印一行，不弹出结果窗口。
5. 最右侧“保存工程/打开工程”保存、恢复流程配置；执行输入图像不自动写入工程。

选中流程实例后，在视图工具栏选择插件声明的 ROI 槽位和允许的形状，点击“绘制/重画”。不能自由增加槽位；重画替换当前槽位，切换实例只编辑该实例的范围。多边形双击结束，已有范围可移动或双击编辑。必填槽位未设置时可以保存草稿，但不能运行。预处理声明可选的“预处理范围”，未设置表示整图。

工具箱 extractRoi 返回裁剪图、0/255 有效掩膜及原图偏移；圆形的无效四角不作为黑色有效数据参与计算。见 [ROI 槽位与图像工具](docs/ROI槽位与图像工具.md)。

找圆试用：在最右侧点击“示例图像”，添加“圆形查找”，在设置中手动选择原图输入，并将数据导出输入绑定到找圆实例的 result。选中找圆实例并绘制范围，再点击右侧“运行”。可自行加入 2D预处理并手动配置输入来源。双击找圆实例设置半径和阈值。结果包含 found、原图 center 和 radius；详见 [圆形查找插件](docs/圆形查找插件.md)。

## SDK 使用

```cmake
find_package(Vision CONFIG REQUIRED COMPONENTS gui)
target_link_libraries(App PRIVATE Vision::gui)
```

```cpp
auto module = vision::createVision();
layout->addWidget(module->getWidget());
module->setInputImage(image); // GUI 线程，宿主负责采集或解码图像。
// 从工作线程调用，图像由宿主提供：
QJsonObject result = module->execute(image);
// 完成后回到 GUI 线程：
module->refreshVisualization();
```

纯算法宿主请求 core；独立插件请求 sdk。宿主安装时由 Config 自动部署所选组件运行时和所需标准插件。

## 文档

- [插件开发入门](docs/插件开发入门.md)：第一次编写独立 DLL 从这里开始。
- [框架现状与后续计划](docs/框架现状与后续计划.md)：已实现和建议后续补充的能力。
- [节点结果与标准窗口](docs/节点结果与标准窗口.md)：JSON 报告、内嵌面板和单步调试。

- [架构设计](docs/架构设计.md)
- [公共接口与数据协议](docs/公共接口与数据协议.md)
- [插件开发契约](docs/插件开发契约.md)
- [工程保存与恢复](docs/工程保存与恢复.md)
- [CMake 与安装约定](docs/CMake与安装约定.md)
- [第一阶段与验收标准](docs/第一阶段与验收标准.md)

代码版本 0.1.0，插件接口 ABI 7（旧 DLL 和宿主必须用当前 SDK 重编）。包与目录不带版本后缀。不提供旧工程或旧插件的兼容层。

插件可以返回标准结果图层，显示圆、十字、轮廓和文本，不操作视图、不污染业务 JSON。参见 [结果图层与插件绘图](docs/结果图层与插件绘图.md)。