4. XG-X项目文件与配方数据结构
在XG-X控制器上做换型调试，最容易踩的坑不是“参数改错了”，而是“改在了错误的层级”。同一个曝光时间，可能存在于相机单元里，也可能被某个场景覆盖，还可能被配方文件整体替换。如果不先弄清项目文件与配方的层级结构，换型时就会出现“明明改了参数，切换后却没生效”或“切回旧配方，部分参数没恢复”的问题。本节把XG-X的项目文件组织方式和配方文件的可切换参数范围讲清楚，为后续的配方创建、切换与校验打基础。
一、项目文件是“容器”，配方是“可替换的参数快照”
XG-X的项目文件（Project）是保存整套视觉系统配置的顶层容器，它包含硬件连接关系、相机与光源设置、场景与单元的逻辑结构、检测参数、通信与I/O映射等。项目文件本身是“当前正在运行的那一套配置”。而配方（Recipe）并不是一个独立的项目，它是从项目中抽取出来的、可被整体替换的参数集合。可以这样理解：项目是“舞台和剧本结构”，配方是“某一款产品的台词本”。换型时切换配方，相当于换台词本，但舞台结构（相机、光源、通信）通常保持不变。
因此，配方文件里保存的是“随产品变化而需要切换的参数”，而不是整个项目。哪些参数进配方、哪些留在项目里，是换型调试中必须提前规划的核心问题。
二、项目、场景、单元、参数组的四层结构
XG-X内部采用“项目 → 场景 → 单元 → 参数组”的层级组织方式。理解这四层，才能判断一个参数到底属于哪一层、切换配方时会不会被覆盖。
- 项目（Project）：最顶层，对应一台XG-X控制器上的完整配置。一个项目可以包含多个场景，项目级参数包括通信设置、I/O分配、全局触发方式、系统校准数据等。这些通常不随产品换型而改变。
- 场景（Scene）：项目下的逻辑分支，通常对应一种检测任务或一个工位。例如“外观检测场景”“尺寸测量场景”。场景可以独立启用或切换，场景级参数包括该场景使用的相机、触发条件、检测流程顺序等。
- 单元（Unit）：场景内的功能模块，是实际执行检测、测量、判断的最小逻辑单元。例如“边缘检测单元”“斑点计数单元”“OCR单元”。单元级参数包括ROI区域、阈值、算法类型、判定上下限等，这些是换型时最常调整的部分。
- 参数组（Parameter Group）：单元内部按功能归类的参数集合。例如一个边缘检测单元下可分为“采集参数组”（曝光、增益）、“处理参数组”（滤波、边缘阈值）、“判定参数组”（宽度上下限）。参数组是配方文件实际读写的最小组织单位。
这四层是“包含”关系：项目包含场景，场景包含单元，单元包含参数组。配方文件在保存时，会按照这个层级路径记录每个可切换参数的位置，例如“场景1 / 单元2 / 处理参数组 / 边缘阈值”。切换配方时，系统按路径逐项替换，路径不匹配的参数不会被覆盖。
三、配方文件里到底保存哪些可切换参数
配方文件保存的是“与产品型号强相关、换型时必须整体替换”的参数。根据XG-X的实际使用习惯，可切换参数大致分为以下几类：
| 参数类别 | 典型参数 | 所在层级 | 是否进配方 |
|---|---|---|---|
| 采集参数 | 曝光时间、增益、光源亮度、光源通道 | 单元 → 采集参数组 | 是 |
| 处理参数 | 滤波类型、边缘阈值、二值化阈值、形态学次数 | 单元 → 处理参数组 | 是 |
| 判定参数 | 尺寸上下限、面积上下限、计数阈值、判定条件 | 单元 → 判定参数组 | 是 |
| 坐标参数 | ROI位置、ROI尺寸、搜索范围、偏移量 | 单元 → 坐标参数组 | 是 |
| 场景状态 | 场景启用/禁用、场景执行顺序 | 场景 | 是 |
| 通信与I/O | PLC地址映射、触发信号分配、输出点定义 | 项目 | 否 |
| 系统校准 | 相机标定数据、镜头畸变校正、坐标变换矩阵 | 项目 | 否 |
需要特别注意的是，通信与I/O、系统校准这类参数通常不进入配方。原因是它们与硬件接线和安装状态绑定，换产品时硬件不变，这些参数也不应改变。如果误把I/O映射放进配方，切换配方后可能导致触发信号错乱，这是换型调试中需要避免的。
四、换型时参数如何被替换：一个具体示例
假设当前项目中有“场景1：外观检测”，其下有一个“边缘检测单元”，该单元包含采集、处理、判定三个参数组。现在要从产品A换型到产品B，操作过程如下：
- 在XG-X的配方管理界面中，选择已保存的“产品B配方”。
- 系统按配方文件中记录的路径，逐项查找对应参数。例如路径“场景1 / 边缘检测单元 / 采集参数组 / 曝光时间”，将当前值从产品A的800μs替换为产品B的1200μs。
- 路径“场景1 / 边缘检测单元 / 判定参数组 / 宽度上限”，从产品A的10.5mm替换为产品B的12.0mm。
- 路径“场景1 / 边缘检测单元 / 坐标参数组 / ROI位置”，从产品A的(320,240)替换为产品B的(350,260)。
- 项目层的通信设置、I/O分配、系统校准保持不变，不参与替换。
替换完成后，建议逐项核对关键参数是否已更新。可以在XG-X的参数列表中查看当前值，并与配方文件中的记录值对比。如果发现某个参数没有变化，首先检查该参数是否被正确包含在配方文件中，其次检查路径是否匹配——例如单元名称被修改过，路径就会失效。