VisionFlow 说明

VisionFlow 是一个用于编辑视觉流程的独立流程编辑器项目。它负责提供视觉工具编排、参数配置、流程校验、流程运行调试、变量与日志查看，以及视觉流程文件的加载和保存。

本项目不负责完整设备软件或产线业务闭环。视觉配方管理、产品型号管理、相机采集、外部触发、PLC 通信、结果上报、MES/上位机交互、生产节拍控制等功能，应由上层调用程序负责。VisionFlow 只作为视觉流程编辑与执行组件，被上层项目集成或调用。

项目定位

VisionFlow 当前定位为：

• 编辑视觉流程：通过工具箱拖拽或双击添加工具节点，组成顺序、分支、循环等流程结构。
• 配置工具参数：支持引用上游工具输出作为下游输入，并提供部分工具的专用配置页面。
• 校验流程引用：运行前检查必填输入、引用路径、变量类型、分支输出、流程输出等是否合理。
• 调试运行流程：可加载图像后运行流程，查看变量、日志、结果轮廓和节点执行状态。
• 保存和加载流程：将流程结构、节点参数、工具类型和可序列化参数保存为 JSON 文件。

VisionFlow 当前不定位为：

• 视觉配方管理系统。
• 生产运行主程序。
• 相机采集服务。
• PLC/运动控制/IO 通信程序。
• 结果上报或数据追溯系统。
• 完整的产线 HMI。

当前项目结构

项目	说明
VisionFlow.Base	流程核心、节点、运行上下文、变量、校验、序列化、运行时接口
VisionFlow.EditorCore	与 UI 无关的流程编辑模型、工具箱注册表、插件加载
VisionFlow.Tools	内置 HALCON 视觉工具
VisionFlow.Controls	图像显示、ROI 绘制和基础视觉控件（WinForms 控件，经 WindowsFormsHost 嵌入 WPF）
VisionFlow.WpfApp	WPF 流程编辑器应用，复用现有流程核心、工具和专用工具编辑窗体
VisionFlow.WpfToolEditors	WPF 专用工具编辑页面

已提供的流程能力

VisionFlow 支持以下流程节点：

• 顺序流程：按节点顺序依次执行。
• 工具节点：调用具体视觉工具，读取输入变量并写入输出变量。
• IfElse 分支：根据条件执行 If 或 Else 分支，并可配置公共输出（在“编辑公共输出”窗口中设置名称、类型和各分支的取值）。条件可以是单条比较（含包含、开头是、结尾是、有效、无效等比较符）、按“全部满足 / 任一满足”组合并可嵌套的条件组，或布尔表达式；运行日志逐项记录条件的实际值与结果。
• For 循环：
  • 按次数循环。
  • 按集合循环，可遍历上游数组输出。
• While 循环：条件成立时重复执行（条件写法同 IfElse），可选先执行一次再判断（条件可引用循环体输出，适合“重试直到找到”）；最多执行次数防止死循环；循环体内可用 Loop.Index。
• 跳出循环 / 跳过本次：放在循环体内（可放在 IfElse 分支中），作用于最内层的 For 或 While 循环。
• Switch 多分支：按选择值执行第一个匹配的分支（每个分支可写多个匹配值），都不匹配时执行默认分支；可配置公共输出，各分支分别给出取值。
• 子流程：调用另一个 .vflow.json 文件（相对路径相对于当前流程文件），子流程沿用当前流程的 Input.* 输入并可追加映射，顶层“流程输出”的结果以子流程节点名回到当前流程；子流程变量互不污染，检测循环引用。双击子流程节点打开编辑窗口，可编辑输入映射、校验并试运行。
• 流程输出：将最终结果统一输出为 Ok、Code、Message、坐标、测量值等上层需要读取的变量。

已提供的工具

内置工具

分类	工具
图像采集	图像加载
图像处理	图像滤波（原“均值滤波”，工具 ID 不变：均值 / 高斯 / 中值 / 平滑（deriche1、deriche2、shen、gauss）/ 双边 / 锐化 / Sobel 梯度幅值 / 灰度腐蚀、膨胀、开、闭，按方式显示参数，彩色图逐通道处理）、灰度增强（线性变换、自动拉伸、按百分比拉伸（只统计图像定义域，配合 ReduceDomain 可按 ROI 拉伸）、直方图均衡、反相、伽马、光照校正、彩色转灰度、像素类型转换）、图像仿射变换、图像几何变换（缩放（按系数 / 按目标尺寸）、旋转、镜像（row / column / diagonal）、矩形裁剪、按区域裁剪；输出新图与 HomMat / InverseHomMat，新图上的检测结果可经“图像坐标转世界坐标”等映射回原图）、极坐标展开（圆环展开成矩形，圆心可固定、引用圆形测量结果或按定位矩阵跟随，展开尺寸可自动计算，编辑窗口在原图上拖动圆心与内外半径并实时预览；输出展开图与记录实际参数的 PolarParams）/ 极坐标逆变换（按 PolarParams 把展开图上的区域、XLD 映射回原图）、区域转图像（二值掩膜图：前景 / 背景灰度，尺寸取参考图像或 Width / Height；绘制到图像：在参考图上填充或画区域边缘，生成结果图）、ReduceDomain 限定图像域、图像运算（原“图像加减”，工具 ID 不变：加 / 减 / 乘 / 除 / 差的绝对值 / 取大 / 取小，两图宽高与通道数须一致，byte 结果超出 0 ~ 255 时截断）、通道分解、三通道合成、RGB 色彩空间转换（hsv / hls / yuv / yiq / i1i2i3 / argyb / ciexyz / ihs / hsi / cielab / cieluv / cielchab / cielchuv / lms）
定位匹配	模板匹配、灰度匹配、缩放形状匹配、局部变形匹配、通用形状匹配（HALCON 22.11 通用形状模型：旋转、等比 / 行列不同比例缩放、多模板同时匹配、杂乱判定、越界匹配、最大变形量、超时）、描述子匹配（纹理特征点，抗透视）、区域定位；匹配类工具支持搜索区域（限定模型参考点）和结果排序（得分、行、列、先行后列、先列后行），最佳结果始终取最高分；模板匹配、缩放形状匹配与通用形状匹配可从上游 XLD 轮廓或 DXF 文件建模（DXF 只在示教时读取），模板匹配、灰度匹配、缩放形状匹配与通用形状匹配可设置模型原点（匹配输出即原点位置）
区域处理	阈值分割（手动/自动/二值/快速/字符/局部/动态/HSV 颜色/RGB 颜色，工具内选择；颜色方式用于 byte 三通道彩色图，HSV 色相下限大于上限表示跨 0，编辑窗口可在图像上点击取色并按容差自动填入范围）、区域处理（连通/填充/合并/骨架/圆形与矩形形态学/按形状填充/边界/按宽高切分/动态切分/取反，工具内选择）、手动 Region（含阵列生成）、Region 相减 / 合并 / 交集 / 形状转换、Region 特征值、区域灰度统计（最小/最大/范围/均值/标准差）、区域筛选（形状或灰度、单条件或多条件、按序号取件）、区域排序（行列编号）、分区检测、XLD 转 Region
XLD 轮廓	边缘提取（彩色边缘 / 灰度边缘 / 亚像素阈值 / 线条提取）、边缘选择（形状特征或轮廓特征，按长度或序号取件）、边缘合并、XLD 分割（直线 / 圆弧 / 椭圆弧）、XLD 特征值（含圆度、凸性、最小外接矩形、椭圆轴、是否闭合等形状特征）、XLD 处理（平滑 / 闭合 / 裁剪 / 形状转换 / 排序 / 连接相邻、共线、共圆轮廓 / 仿射跟随）、Region 转 XLD
几何测量	椭圆测量、直线测量、一维卡尺测量、一维圆弧卡尺测量（一维卡尺/圆弧卡尺支持边缘对宽度测量：输出宽度、间距、中心点，显示轮廓带尺寸线；边缘对模式下 Rows / Columns 等边缘输出依次为每对的两条边缘，长度为边缘对数的 2 倍）、矩形测量、圆形测量（直线/矩形/圆形/椭圆测量可设卡尺数、卡尺间距、最低得分、实例数、距离阈值、插值方式，输出得分、边缘点和多实例结果）、找角（一个模型测两条边，输出交点、夹角（弧度与度）和两条边端点，两边平行按未找到处理）、灰度投影（测量矩形长轴方向的灰度曲线与一阶导数，输出最小/最大/平均灰度及位置，编辑窗口显示曲线）、拟合直线、拟合圆、拟合椭圆/矩形、交点计算（直线与直线、直线与轮廓、轮廓与轮廓）、区域距离（点到区域、区域到区域，逐一配对或一对多）、轮廓距离（点到轮廓、轮廓到轮廓，输出最近点对）、几何关系测量（点到直线距离与垂足、两直线夹角、线段与线段 / 直线距离）、单位换算（原“角度换算”：弧度/角度互转，折算到 -90°90°、0°180° 等范围；支持像素长度/面积换算（mm 或 um），当量可固定填写，也可来自标定：引用“图像坐标转世界坐标”或“畸变校正”输出的 Matrix，或读取 .vfcal.json / 旧版矩阵标定文件，按矩阵行、列方向缩放的平均值并依标定单位折算为 mm/像素，两方向相差超过 1% 时日志警告）
识别工具	读码（一维码/二维码，支持高级模型参数与多图训练）、字符识别（传统文本模型 / Deep OCR，支持 ROI、定位矩阵跟随、字符集过滤、期望格式正则校验）、颜色识别（逐区域求色彩空间均值后与参考色比对，支持 RGB / HSV / CIELAB，超允许距离判“未知”）、颜色分割（MLP / GMM 逐像素分类，每类框选样本训练、结果序列化保存，输出各类区域与拒识区域）、深度学习推理（.hdl 模型加载、设备选择、预热、模型元数据输出；句柄缓存可选 Instance / 流程内 / 项目级共享）、深度学习检测（目标框 / 类别 / 分数 / 轮廓，支持 ROI 与 TopN 过滤）、深度学习分类（TopK / 期望类别比对）、深度学习分割（逐类区域 / 掩膜 / 面积，像素置信过滤）
数据与判定	数值区间分类（按“标签=下限~上限”规则把数值映射为文字标签，支持弧度/角度归一）、变量计算（每行一条“结果名|类型|表达式”，引用写在花括号内，如 {测量1.Row} - {测量2.Row}；支持算术、比较、逻辑、条件运算和数学、字符串、数组函数，后面的计算可引用前面的结果）、数组处理（统计、取值、排序、筛选、变换、拼接、逐元素运算、去重，筛选和变换用 {Item} / {ItemIndex} 表达式，结果同时给出合计、平均、最大最小等统计）、综合判定（每行一项“名称|取值|下限|上限|NG代码|NG信息”，汇总为 Ok / Code / Message 和不合格原因，可直接接流程输出）
缺陷检测	差分检测（用良品图训练“标准图 + 允许偏差图”，检出超出偏差的区域：standard / robust 多张样本或 direct 单张良品图建模，亮暗阈值可分开设置，修改阈值不需要重新训练；可接定位矩阵对齐、限定检测区域，输出缺陷区域、个数、面积和是否有缺陷，无缺陷是正常结果；模型可内嵌或改用外部模型文件 ModelFile）
标定	图像坐标转世界坐标（原在“几何测量”，工具 ID 不变：Row / Column 支持单值或数组，可选角度输入换算为物理角度；标定来自引用的矩阵、标定文件（.vfcal.json，旧版 write_tuple 矩阵文件按内容自动识别）或内嵌在工具中的标定数据，二者互斥；支持仿射矩阵与相机标定结果（image_points_to_world_plane）两种方式；输出物理坐标数组、角度（弧度与度）、数量和所用矩阵）。编辑窗口内含 N 点标定助手：图像坐标可从上次运行变量取值、在图像上点击或手动输入，物理坐标手动输入或 CSV 导入，按 affine / similarity / rigid 求解并显示残差，超阈点标红可删除重算，结果保存为标定文件或内嵌到工具；同一窗口的旋转中心页由同一特征点多次旋转后的位置求旋转中心（带角度时按角度求解，否则圆拟合），与 N 点标定合并保存；相机标定页用 HALCON 标定板（如 calplate_80mm.cpd）的多张图像标定相机内参与测量平面位姿（area_scan_division / polynomial，逐张显示识别结果与反投影误差，未找到的可移除重算，选一张参考图像并填写标定板厚度确定测量平面），结果与已有标定合并保存；主窗口工具栏“标定助手”也可单独打开）、纠偏计算（由当前位姿与示教基准位姿计算平台补偿量 DeltaX / DeltaY / DeltaAngle：先绕旋转中心转回角度差、再平移，或只补偿平移；相机固定与相机随轴两种安装的符号相反，相机随轴暂只支持只补偿平移；角度差在物理坐标系中计算，镜像标定也正确；当前位姿为 NaN 时输出 NaN、Valid = false 而不中断流程；编辑窗口可“用当前结果设为基准”）、畸变校正（按相机标定把图像校正为测量平面上比例均匀的图像：像素当量可指定或按原图中心自动计算，输出区域可指定或自动覆盖整个视野，双线性 / 最近邻插值；校正映射缓存并参与预热；输出校正图、实际像素当量 ActualPixelSize 和“校正图像素 → 测量平面坐标”的矩阵，可直接接图像坐标转世界坐标）
逻辑控制	IfElse 分支、Switch 多分支、For 循环（次数/集合）、While 循环（条件）、跳出循环、跳过本次、子流程、流程输出

原独立的“形态学”“Region Union1”已并入“区域处理”，历史流程文件中的这两类节点仍可正常加载运行。阈值分割、区域处理、区域筛选、区域距离以及边缘提取、边缘选择、交点计算、XLD 处理、拟合椭圆/矩形、轮廓距离、几何关系测量的编辑界面只显示当前方式用到的参数。“线线交点”已更名为“交点计算”，工具 ID 不变，历史流程可正常加载。

匹配、区域运算与筛选、XLD、拟合、交点计算、跟随测量、一维码等工具提供 FailWhenNotFound 参数（默认开启）：开启时“未找到”（匹配 0 个、结果为空、未找到边缘等）会让节点失败并中断流程；关闭后工具照常输出 Found=false、数量为 0，流程继续，可由下游 IfElse 按 Found 或数量判定 NG。匹配与测量输出的轮廓（Contours、ResultContour）为 XLD 类型，可直接接入拟合直线、拟合圆、交点计算等 XLD 工具。

迁移说明（2026-10-08）：两处既有行为已修正，请检查依赖旧行为的流程。

• 区域工具的空结果不再“通过”：阈值分割、区域处理、Region 相减 / 合并 / 交集 / 形状转换 / Union1、形态学、区域筛选、XLD 转 Region（以及极坐标逆变换）在没有任何有效像素时，此前会输出一个面积 0 的空区域并报 Count = 1、Found = true（FailWhenNotFound 不生效）；现在按“未找到”处理，输出 Count = 0、Found = false，FailWhenNotFound 开启（默认）时节点失败并中断流程、关闭时输出 Found=false 并继续。原先“区域为空也当作找到 1 个”继续运行的流程需改为关闭 FailWhenNotFound 并用下游 Found / 数量判定。
• ReduceDomain 限定图像域改为并集：区域输入含多个对象时，此前 HALCON 只取第一个对象、其余被静默忽略；现在先合并（union1）再限定，定义域为全部区域的并集。单个区域对象（含关闭 Connection 的阈值结果）不受影响。原先把多对象区域直接接给本工具并依赖“只取第一个”的流程需先自行取件（如接区域筛选）。

识别到区域后需要精确的亚像素坐标时，有两种做法：

• 区域形状直接测量：矩形测量、圆形测量的“初始区域”输入选择上游区域（如 区域筛选1.Region）。工具对其中每个对象取最小外接矩形或最小外接圆作为初始几何，做亚像素测量，不需要示教。结果序号对应区域对象序号；单个对象测量失败会计入 FailedCount，不影响其他对象。数组输出 Rows / Columns / Phis（圆形为 Radii）与初始区域对象逐一对齐，失败项为 NaN。
• 阵列目标的行列编号（如晶圆上的 chip、料盘穴位）：灰度分割得到各目标区域后，接“区域排序(行列编号)”，再把它输出的 Region 作为矩形测量的初始区域。
  • 排序工具给每个区域分配全局行号、列号（RowIndices / ColumnIndices），并按行优先或列优先输出。晶圆边缘缺料或中间漏检不会让后面的编号前移；同一行列位置出现两个区域时计入 DuplicateCount。
  • 网格有旋转时把“角度方式”设为 Auto（取各区域方向角的中位数，适用于旋转小于 45° 的矩形目标）或 Fixed。行、列容差为 0 时自动取目标高度、宽度中位数的一半。
  • 测量数组与行列号数组下标一一对应，可直接作为流程输出交给上位机。
  • 测量角度为弧度；接“单位换算”（角度模式，原名“角度换算”）可转为度，并折算到指定范围。
    • 范围按周期折算，区间宽度即周期。例如 -90°~90° 会把 100° 折算为 -80°。
    • 不分正反方向的矩形选 -90°90°；需要区分正反时选 -180°180° 或 0°360°；近似正方形的 chip 选 -45°45°。
    • 输入可以是单值或数组，测量失败项（NaN）原样输出。
  • 不直接用 HALCON sort_region：它只按单一坐标排序，同一行内的行坐标抖动会打乱列顺序，也不给出行列号。
• 区域定位后跟随测量：工件形状固定、只有位姿变化时，使用“区域定位”输出的 Matrix 作为测量工具的变换矩阵，测量框按示教基准跟随。

完整性检查（如泡罩缺粒/错粒，对应 HALCON 示例 check_blister）的推荐做法：

1. “区域定位”求当前位姿。
2. “手动 Region”用阵列生成画出检测格。输出模式选 PerShape，格子顺序即序号；“运行跟随矩阵”选 区域定位1.BaseToCurrentMatrix，检测格随工件位姿变换，不必对整图做仿射变换，结果也直接是原图坐标。
3. 分割出目标后交给“分区检测”。它逐格按面积、灰度判定 OK / 错误 / 缺失，输出每格结果、各状态数量、AllOk，以及错误格和缺失格的区域。

也可以用“图像仿射变换”按 CurrentToBaseMatrix 把整张图对齐到示教位姿后再检测。

手动 Region 编辑器的“当前图像”示教模式会按当前姿态显示 ROI，确定时用逆矩阵换算回示教基准保存，所以可以在任意一张生产图上调整检测格。

纹理丰富、存在透视变形的目标（如包装盒的印刷面，对应 HALCON 示例 locate_cookie_box_multiple_models）使用“描述子匹配”：

• 示教：在参考图上框选矩形模板，点击“创建模型”。
• 输出：
  • 与其他匹配工具相同的结果，其中 HomMat 为参考图到当前图的仿射近似，可直接供测量和手动 Region 跟随。
  • 投影四边形轮廓。
  • 平面内转角 Angle（可接“数值区间分类”判断正放、侧放、倒放）。
  • Items[i].ProjectiveHomMat：完整的投影矩阵。
• 模型保存：描述子模型可达数十 MB，流程中只保存模板裁剪图与训练参数。模型在预热或首次运行时训练（数秒到数十秒），并缓存到本机 %LocalAppData%\VisionFlow\DescriptorModelCache，缓存键为模板像素、参数与 HALCON 版本的哈希，之后加载只需几十到两百毫秒。
• 投产前请调用 FlowResources.Prepare 预热；该缓存目录可随时清空。
• 当前使用非标定描述子，不需要相机标定，也不输出三维位姿。

插件工具

第三方插件工具通过 [ToolboxTool] 特性注册到工具箱，由 WPF 宿主扫描输出目录下的 plugins 文件夹加载。与内置工具同名的插件工具会按工具箱显示名去重，避免重复显示。专用编辑器应匹配宿主 UI 技术；没有可用专用页面时使用通用编辑器。

标准示例流程

项目提供 examples 目录作为核心能力回归和使用参考：

文件	说明
examples\threshold-region.vflow.json	二值化、形态学、区域筛选、区域特征和流程输出示例
examples\xld-line.vflow.json	边缘提取、边缘筛选、拟合直线和流程输出示例
examples\region-measure.vflow.json	二值化、区域筛选后按区域形状做亚像素矩形测量（无需示教），并演示部分失败计数
examples\blister-check.vflow.json	复现 HALCON 示例 check_blister：区域定位、检测格跟随位姿（阵列 + PerShape）、药片分割、分区检测缺粒/错粒；需使用 HALCON 安装附带的 blister 示例图像
examples\pizza-salami.vflow.json	复现 HALCON 示例 color_segmentation_pizza：RGB → CIELab，在 b 通道分割披萨与意式香肠；需使用 HALCON 安装附带的 color\pizza_* 示例图像
examples\cookie-box.vflow.json	复现 HALCON 示例 locate_cookie_box_multiple_models：4 个面的描述子匹配 + 数值区间分类判断正放/侧放/倒放；模板 ROI 已预填，需先用 HALCON 附带的 packaging\cookie_box_reference_01~04 在编辑器中创建模型
examples\wafer-chips.vflow.json	晶圆约 500 颗 chip 的行列定位：灰度分割 → 区域筛选 → 区域排序（行列编号，自动网格角度）→ 按区域形状做亚像素矩形测量 → 角度换算（度，-90°~90°），输出行号、列号、中心与角度数组；配套合成图像 examples\images\wafer-chips.png
examples\datacode-default-settings.vflow.json	复现 HALCON 2d_data_codes_default_settings：读码工具以三档识别强度解码 %HALCONIMAGES%\datacode\qrcode\qr_workpiece_01.png 并输出质量评分
examples\ocr-expiration-date.vflow.json	复现 HALCON find_text_expiration_date：字符识别（TextModel）读取 %HALCONIMAGES%\ocr\medication_package_02_right.png 有效期，正则校验 PatternOk
examples\color-fuses-classify.vflow.json	复现 HALCON color_fuses：颜色识别对 %HALCONIMAGES%\color\color_fuses_00.png 的 5 个保险丝按 HSV 参考色分类
examples\color-pieces-mlp.vflow.json	复现 HALCON color_pieces：颜色分割（内嵌预训练 MLP）逐像素分类 %HALCONIMAGES%\color\color_pieces_01.png
examples\dl-detect-pills.vflow.json	复现 HALCON detect_pills：深度学习检测 %HALCONIMAGES%\pill_bag\pill_bag_001.png（官方模型 detect_pills.hdl，典型 Count=12、BestScore≈1.0）；示例设 FailWhenNotFound=false
examples\dl-classify-pill-defects.vflow.json	复现 HALCON classify_pill_defects：深度学习分类 %HALCONIMAGES%\pill\ginseng\contamination\pill_ginseng_contamination_001.png（典型 Top1=good 0.606、Top3=[good,crack,contamination]）
examples\dl-segment-pill-defects.vflow.json	复现 HALCON segment_pill_defects：深度学习分割同一药片图（典型 Count=2、Areas=[189507,93,0]）

示例流程默认读取运行时输入 Input.Image。在编辑器中可先打开 src\Image\razors1.png，再加载示例流程运行。

如何编辑视觉流程

1. 启动 VisionFlow.WpfApp。
2. 从左侧工具箱中双击或拖拽工具到流程树。
3. 在流程树中调整节点顺序，或将节点放入 IfElse 分支、For 循环体中。
4. 选中节点后，在参数面板中配置输入引用。
5. 双击工具节点，打开对应工具的专用配置页面，设置工具参数。
6. 使用“校验”检查流程引用和输出配置。
7. 可打开一张图像后点击“运行”，查看变量、日志和图像叠加结果。

如何保存视觉流程

在编辑器工具栏点击“保存流程”，选择保存路径即可。

流程默认保存为 JSON 文件，推荐扩展名为：

*.vflow.json

保存内容包括：

• 流程节点结构。
• 节点 ID 和名称。
• 工具类型。
• 工具模块名。
• 工具可序列化参数。
• IfElse 条件和公共输出。
• For 循环配置。
• 流程输出配置。

保存内容不包括：

• 运行时变量值。
• 当前运行日志。
• 上层配方信息。
• 相机、PLC、触发、结果上报等外部设备配置。

如何加载视觉流程

在编辑器工具栏点击“加载流程”，选择 .vflow.json 或 .json 文件即可。

加载后 VisionFlow 会重新构建流程树，并执行一次流程校验。如果发现引用缺失、类型不匹配、输出配置错误等问题，会弹出校验结果。

需要注意：

• 流程中使用的工具类型必须在当前程序或插件目录中可用。
• 插件工具对应的 DLL 需要放在 VisionFlow.WpfApp 输出目录的 plugins 子目录下。
• 如果流程引用了外部文件路径，例如图像、模型、标定文件，上层项目需要保证这些文件路径有效，或在集成时重新配置。
• 标定文件 .vfcal.json（JSON，可读可比对）记录标定类型（Affine2D / RotationCenter / Camera）、单位、点对与误差，由 N 点标定助手、旋转中心助手与相机标定助手生成（三者可合并写在同一文件中，旋转中心供纠偏计算使用，相机标定供坐标转换的相机方式与畸变校正使用），上层项目也可直接调用 VisionFlow.Tools.Calibration.CalibrationService（SolveAffine / SolveRotationCenter / MergeRotationCenter / MergeCamera / Save / Load）与 CameraCalibrator（BuildStartParameters / Calibrate）自动生成；同一工位的多个流程可共用一个标定文件。坐标转换、纠偏计算与畸变校正也可把标定内容内嵌在工具里（流程文件中按既有序列化行为写成 \uXXXX 转义），文件与内嵌二者互斥，同时存在时流程校验报错。
• 差分检测的模型较大（standard / robust 约 12 字节 / 像素，640×480 约 3.5 MB），超过 10 MB 时编辑窗口与运行日志会建议改用外部模型文件：在编辑窗口“导出为外部文件”后流程只保存 ModelFile 路径（.vfvm），运行时从该文件加载，文件同样由上层项目部署。外部文件与内嵌数据互斥，两者同时存在时流程校验报错；重新训练会清空 ModelFile，改用内嵌的新模型。

流程文件和单节点数据均携带 FormatVersion，按流程实际用到的功能写最低所需版本：未使用条件组、表达式条件、新增比较符、While 循环、跳出 / 跳过本次、Switch 或子流程的流程仍为版本 1，旧版编辑器照常可读；用到这些功能时为版本 2，旧版编辑器会明确提示版本过高而不是静默出错。内置工具使用与 CLR 类名无关的固定 ToolId。工具重命名或程序集迁移时，可通过 FlowSerializer.RegisterToolType(type, stableId, aliases) 显式登记历史身份，重复身份会报错而非覆盖。旧版仅带 TypeName 的文件仍可读取。

工具资源的预热与释放

流程文件只保存可序列化参数，例如模板以字节数据保存。加载流程时不会创建 HALCON 模型句柄等运行期资源，所以没有安装 HALCON 的机器也能打开和校验流程。这些资源默认在工具首次运行时按需加载，并缓存在工具实例里，之后的运行直接复用。实现了 IToolResourceLifecycle 的工具（目前是各匹配工具（含通用形状匹配）、差分检测和坐标转换）支持显式预热和释放，由 FlowResources 对整棵流程树统一调用：

时机	调用	说明
加载流程或切换配方后、投入生产前	FlowResources.Prepare(root)	提前加载资源，消除首拍延迟；检查 FlowPrepareResult.Issues，有失败就不投产
切换配方	先 Prepare(新流程)，替换成功后再 Release(旧流程)	旧流程必须已经停止运行
删除节点、工具配置被整体替换、关闭流程、程序退出	FlowResources.Release(root 或 tool)	确定性释放；释放后再次运行会按需重新加载

两个方法都可以重复调用，并且与工具运行线程安全。编辑器已在以下位置接入：

• 打开流程后在后台预热；新建或打开流程时释放旧流程。
• 删除节点时释放被删除的子树。
• 工具编辑确认后，释放被替换的旧工具，并预热新配置；编辑窗口关闭时，释放编辑副本。
• 主窗口关闭时释放全部资源。

与上层项目的职责边界

VisionFlow 输出的是视觉流程能力，上层项目负责设备与业务闭环。

功能	负责方
视觉流程编辑	VisionFlow
视觉工具编排	VisionFlow
流程保存/加载	VisionFlow
流程校验和调试运行	VisionFlow
视觉配方管理	上层项目
产品型号/工位管理	上层项目
相机采集	上层项目
外部触发	上层项目
PLC/IO/运动控制通信	上层项目
结果上报	上层项目
MES/数据库/文件追溯	上层项目
生产运行界面	上层项目

上层项目可以加载 VisionFlow 保存的流程文件，并在自己的采集、触发和通信逻辑中调用流程运行接口，将图像或输入变量传入流程，再读取流程输出结果。流程中含子流程时，请用 FlowSerializer.LoadFile(path) 加载流程文件（而不是读入文本后调用 Load），子流程的相对路径才能按流程文件所在目录解析；并随主流程一起部署子流程文件。

运行资源与预览约定

• 每次生产运行推荐使用独立的 FlowContext；执行成功与产品判定合格是不同概念，合格状态应读取流程业务输出。
• 调用方图像通过默认借用包装（如 new HalconImage(image)）注入，仍由调用方释放。工具新输出归运行上下文所有。
• 结果仍在显示或被下游使用时，不得释放上下文。消费结束后调用 FlowContext.Dispose()，统一回收该次运行的自有资源，包括被同名变量覆盖的旧输出。
• 预览通过 CreatePreviewContext() 派生，集合数据独立，源 HALCON 资源保持借用；源上下文必须晚于预览释放。自定义引用类型结果应保持只读或实现 ICloneable。
• 已配置定位矩阵但引用无效时，正式运行明确失败，不退回固定位置。仅显式创建的降级预览 CreatePreviewContext(allowMatrixFallback: true) 可以使用固定位置，权限不会写入流程文件。

项目不提供撤销/重做；参数取消、未保存修改提示和保存失败保护属于文档安全功能，不受此范围约束影响。

回归入口

VisionFlow.Tests 使用 xUnit，覆盖引用、流程文件、输入契约、编辑状态与 HALCON 资源等行为：

dotnet test .\VisionFlow.Tests\VisionFlow.Tests.csproj --configuration Debug --no-restore

HALCON 资源与示例图像用例需要本机原生运行库和授权；每个相关用例独立检查环境，缺失时明确失败，不会早退后被计为通过。 HALCON 最低版本为 22.11（通用形状匹配使用 22.11 的 *_generic_shape_model 算子）：编译引用 lib\halcon\halcondotnet.dll（不入库）须取自 HALCON-22.11-Steady\bin\dotnet35\halcondotnet.dll，20.11 的库文件缺少这些方法，无法编译。 示例基线用于回归，不代表现场精度、节拍或工况覆盖已经达标。

默认回归包含两个样例各 100 次的持续运行冒烟，CSV 保存到 TestResults\soak。 用 --filter "Category=Soak" 可单独运行；次数、采样间隔和资源/耗时阈值可通过环境变量配置。 未配置阈值时只报告功能回归，不宣称性能验收。命令、指标口径和现场/UI 记录模板见 docs\VF11-ACCEPTANCE.md。

暂不包含的内容

以下内容等 VisionFlow 项目更完善、工具更丰富后再开发：

• 大规模工具回归测试。
• 完整用户手册。
• 更完整的生产运行界面。
• 更系统的部署和发布包。

当前阶段优先保证流程编辑器、工具编排、流程保存加载和核心工具体系稳定。