📚 课程目录第4章 MERLIC项目工程化组织

4. MERLIC项目工程化组织

当MERLIC项目从单机验证走向量产部署，工程化组织的质量直接决定维护成本。一个典型的MERLIC项目包含VisionApp、图像源配置、工具参数、标定数据、通信接口配置以及配方（Recipe）文件。如果这些内容散落在不同目录、命名随意、版本混乱，那么每次换型、每次产线复制都会变成一次高风险的手工操作。本节从目录结构、命名规范、版本管理、多产品共线配方管理四个维度，给出可直接落地的组织方法。

一、可复用的项目目录结构

MERLIC本身以项目文件（.mvtc）为核心，但工程化项目不应只依赖单个项目文件。推荐将项目根目录划分为配置层、资源层、输出层和文档层，使VisionApp、标定、通信、配方各自独立又可追溯。以下是一个可直接复用的目录骨架示例：

Line3_MERLIC_Project/
├─ 00_Project/
│   ├─ Line3_Main.mvtc          # 主VisionApp项目文件
│   └─ Line3_Main.mvtc.bak      # 版本备份
├─ 01_Calibration/
│   ├─ cam01_intrinsic.cal
│   ├─ cam01_handeye.cal
│   └─ calib_report_20240612.md
├─ 02_Recipes/
│   ├─ ProductA/
│   │   ├─ recipe_A_v1.0.rcp
│   │   └─ roi_A.json
│   ├─ ProductB/
│   │   ├─ recipe_B_v1.0.rcp
│   │   └─ roi_B.json
│   └─ recipe_index.csv
├─ 03_Communication/
│   ├─ plc_siemens_s7.cfg
│   └─ tcp_ip_config.json
├─ 04_Images/
│   ├─ golden_samples/
│   └─ test_batch_202406/
├─ 05_Export/
│   ├─ runtime_package/
│   └─ deploy_checklist.md
└─ 06_Docs/
    ├─ change_log.md
    └─ line3_layout.pdf

这种分层的关键在于：标定数据与项目文件分离，因为标定结果通常由现场相机和机械手决定，换线时可能复用；配方独立于主项目，使多产品共线时只需切换配方而非重建VisionApp；通信配置单独存放，便于不同PLC品牌或协议版本的管理。实际部署时，MERLIC Runtime只加载主项目与当前激活配方，其余目录作为工程资产保留在版本库中。

二、命名规范：让文件名自解释

命名规范的目标是让任何工程师在不打开文件的情况下判断其用途、版本和归属。建议采用“对象_功能_版本_日期”的四段式命名，各段用下划线连接，避免空格和中文。例如：

相机标定文件：cam01_handeye_v2.1_20240612.cal
产品配方：recipe_ProductA_v1.3_20240610.rcp
PLC通信配置：plc_s7_1200_v1.0.cfg
黄金样本图：golden_ProductA_cam01_20240610_001.png

对于VisionApp内部的工具和ROI命名，同样需要规范。MERLIC的工具树中，建议按“工位_功能_序号”命名，例如ST01_Blob_01、ST01_Calib_Check。ROI名称应与配方中的产品特征对应，如ROI_ProductA_LeadFrame。这样在切换配方时，可以通过配方文件中的ROI映射表快速定位需要调整的区域，而不是逐个工具手动修改。

三、版本管理策略

MERLIC项目文件是二进制格式，直接放入Git等文本版本控制系统效果有限。推荐采用“项目文件+导出配置+变更日志”的组合策略：每次修改后，将MERLIC项目导出为可读的配置描述（如工具参数列表、ROI坐标、通信地址表），与.mvtc文件一同提交。变更日志中记录修改人、修改内容、影响范围、验证结果。对于关键版本，使用Line3_Main_v1.2_20240612.mvtc这样的带版本号副本，并在change_log.md中登记。

建议在MERLIC项目内使用“注释”功能标记关键工具的作用和修改日期，这样即使项目文件被单独复制，也能保留部分上下文信息。

四、多产品共线时的配方与参数管理

多产品共线的核心矛盾是：同一套VisionApp需要适应不同产品的ROI位置、阈值、模板和判定标准。MERLIC的配方机制允许将工具参数保存为独立配方文件，切换时批量加载。工程化做法是建立“配方索引表”，明确每个产品对应哪些配方文件、哪些参数需要随产品变化、哪些参数保持全局固定。

以下是一个配方索引表的示例结构，用于管理三条产品线的共线生产：

产品型号	配方文件	ROI偏移量(mm)	Blob阈值	模板匹配分数	适用工位
ProductA	recipe_A_v1.3.rcp	X:0, Y:0	128	0.85	ST01, ST02
ProductB	recipe_B_v1.0.rcp	X:12.5, Y:-3.0	145	0.80	ST01, ST02
ProductC	recipe_C_v2.1.rcp	X:-8.0, Y:5.5	110	0.90	ST01, ST03

配方切换的触发方式通常有两种：一是通过PLC信号触发MERLIC的配方切换接口，二是由操作员在HMI上选择产品型号后，由上位机调用MERLIC的远程控制命令加载对应配方。无论哪种方式，切换后必须执行一次“配方验证”：用该产品的黄金样本图运行一次完整检测，确认所有工具的输出在预期范围内。验证结果应记录到生产日志中，作为换型确认的依据。

配方管理还需要注意参数的作用域划分。建议将参数分为三类：全局参数（如相机曝光、通信超时，所有产品共用）、产品参数（如ROI坐标、模板图像、阈值，随配方切换）、工位参数（如特定工位的触发延时，与产品无关但与工位绑定）。在MERLIC中，全局参数放在主VisionApp中，产品参数放入配方文件，工位参数通过工位配置文件管理。这样当新增产品时，只需创建新的配方文件并更新索引表，无需改动主项目结构。

配方切换后如果未执行黄金样本验证，可能因ROI偏移或阈值不匹配导致漏检。建议将“切换后验证”写入换型SOP，并在MERLIC的远程控制接口中增加验证结果回传信号，由PLC判断是否允许放行。

最后，多产品共线时建议保留一份“配方变更记录表”，记录每次配方修改的产品、修改参数、修改前后的值、修改原因和验证结果。这份记录与版本管理中的change_log.md互为补充：前者面向生产换型，后者面向工程版本。两者结合，才能让MERLIC项目在量产环境中既灵活又可控。