cvColorVision
Engine/cvColorVision/ 是原生能力绑定层,通过 DllImport 暴露 cvCamera.dll 等底层接口给 C#。它不是纯托管视觉算法库,也不负责 WPF 界面、模板或工作流编排。
本地相机取图由 CM_GetFrame 提供 RAW,校正由 LocalFrameCalibrationService 调用本地 opencv_helper.dll;POI 的 XYZ、xy/uv、CCT 和主波长测量由 PoiMeasurementService 通过 OpenCVCalibration.M_CalculatePoiBatchV2 或 RAW 测量入口计算,缓冲寿命由当前帧或 PoiMeasurementBuffer 管理。旧插件若引用早期 cvColorVision.dll 的句柄式 XYZ 采样 API,需要迁移到本地测量接口并重新编译;当前托管程序集不保证这些旧 API 的二进制兼容。
FOV、SFR、畸变、鬼影与清晰度测量使用本地算法。依赖 FovImgCentre/FovImgCentreEX、SFRCalculation、GhostGlareDectect 或 cvCalArticulation 的旧调用方须迁移后重编译,并核对 DLL 版本和导出序号。Simple 源码用于同步上游,不参与 DLL 构建。
绑定与交付前提
当前工程目标是 net10.0-windows7.0。cvColorVision.csproj 从 DLL/scgd_internal_dll/ 复制和打包供应商 DLL,不在本工程编译这些 native 实现。全部 21 个 DLL 的工程链接、构建/发布输出和 NuGet 包路径统一为 runtimes/win-x64/native/,包含 cvCamera.dll、CommLibrary、OpenCV 及相机和光谱仪 SDK 的间接依赖。供应商原始输入继续保存在 DLL/scgd_internal_dll/。主程序与 PluginKit 的共享文件清单使用相同相对路径,安装工程也须从该目录取文件并安装到对应目录。具体功能还受设备驱动与部署配置约束。校正文件创建由主程序执行,本地校正统一使用 opencv_helper.dll;cvCamera.dll 继续负责相机等设备接口。
CameraNativeLibrary 依次查找托管程序集和宿主旁的 runtimes/win-x64/native/,兼容 RID 发布时的平铺输出。SetDllDirectoryW 将实际目录设为进程 DLL 搜索目录,供 SCGDCamLayer 等 SDK 后续按名称加载依赖。宿主在设备运行时须保留该搜索目录,系统和用户 PATH 独立。
传感器使用 Engine 的 LocalSensorSession(TCP/串口)或 MQTT 服务模式。引用旧 cvColorVision.SensorComm、传感器/TCP 服务导出或 CalGamut、GetMAKETYPE、XYZ2xyuv、CheckLedJudge 的外部插件须迁移并重编译。PG 通过 Communicate_Type 保持枚举及类型兼容,相机继电器的串口函数仅供原生内部调用。
电机控制器 FOCUS_COMMUN 与原生及已有配置的数值保持一致:VID_SERIAL=0、CANON_SERIAL=1、NED_SERIAL=2、LONGFOOT_SERIAL=3、TSM_SERIAL=4、SV6100=5。InitCom / CM_InitComEx 的首参对应原生 HANDLE&,C# 必须传 ref IntPtr 接收独立电机句柄,不能传相机管理器句柄,也不能把整数状态码当句柄。旧调用方需要按此签名重新编译;新增类型需要配套 DLL,选择项存在不证明串口通信已验收。本地相机会话通过 CM_InitComEx 创建电机、下发配置,通过 CM_ShutDown 释放;托管适配器串行进入原生电机注册表,避免不同相机对未加锁的原生句柄表并发访问。
CM_EvaluateFocus(HANDLE, EvaFunc, double&) 是本地对焦使用的同步单帧评价入口,成功为 1,失败保留采集错误码或返回对应的平台错误;失败不写输出。它只采集 RAW 并调用既有原生清晰度算法,不移动电机、不创建异步线程或保存图像。已通过现有 CM_AutoFocusCallBackEx 注册过程预览时,评价成功后同步借出同一 RAW 帧,回调返回后原生帧即释放,不额外取图;失败不发预览。Engine 在回调期间复制为独立显示快照,并在每次评价结束的 finally 中注销回调,委托保活至注销完成;显示错误不跨越原生边界,也不改变有效的清晰度结果。回调为 int32/StdCall,像素指针仅在调用期间有效。Live 模式、未打开的相机和未知评价类型会失败。移动、搜索范围、超时和句柄生命周期由 Engine 的本地相机会话管理,不通过遗留 CM_CalcAutoFocus / CM_GetAutoFocus 启动后台搜索;服务模式仍保留既有异步入口。
当前内部版不包含本地 OLED/CUDA 链路:cvCamera.dll 不再导入 cvOled.dll,默认交付不含 cvoled.dll、cudart64_12.dll,C# 的 CvOledDLL 及其专用枚举也不再提供。原生导出 CM_LedCalInit、CM_LedCalFind、CM_LedCalComBine、CM_LedCalFindHighDensity、CM_FindHighIndensityLed 已删除;需要这些入口的旧插件不能直接使用此版本,按序号导入的外部二进制也需要重新核对。本地普通 LED 检测、远端 CVOLED 服务消息和流程节点不属于这条 DLL 依赖链。
旧 OLED/CUDA 部署的匹配 DLL、源码和恢复说明位于 docs/_history/native-dependencies/oled-cuda/README.txt 所在目录。恢复需要同步核对原生链接、托管声明和打包清单。
Release 构建的 ValidateGaolitongNativeDependencies 会在 Build 前检查 glaDevSys64.dll、xGUSB64.dll、xGCOM64.dll、xserial64.dll 和 FTD2XX.dll 是否存在;缺少其中任一文件就报错。这只是输入存在性门禁,不校验 DLL 能否加载、导出是否匹配或真实设备能否打开。README 也作为 NuGet 包说明打包,但其仓库相对链接不保证包内含有对应知识文件。
cvCamera.dll 的 log4z 日志在 InitResource 启动前读取进程环境变量 COLORVISION_NATIVE_LOG_DIRECTORY。C# 的 cvCameraCSLib.InitResource 在未显式设置该变量时,取当前 log4net 文件输出的实际目录,因此原生日志与主程序日志位于同一目录(安装版通常为 %APPDATA%\ColorVision\Log);原生日志仍保留独立的 .log 文件、文件名和级别。外部程序可在首次初始化前设置该变量,例如 C# 调用 Environment.SetEnvironmentVariable(cvCameraCSLib.NativeLogDirectoryEnvironmentVariable, @"D:\ColorVisionLogs"),或 C++ 调用 SetEnvironmentVariableW(L"COLORVISION_NATIVE_LOG_DIRECTORY", L"D:\\ColorVisionLogs")。支持中文目录;路径按进程设置,不按相机句柄设置。直接调用 native 且未设置变量的程序保留原来的当前工作目录 ./log/ 默认值。日志目录在初始化时读取,运行中的日志配置更改不会自动同步;不要为切换日志目录额外调用设备资源初始化或释放。原生导出名称、序号及 InitResource 参数保持兼容。
默认交付不含 cfg/sys.cfg。配套内部版 cvCamera.dll 的相机创建接口在配置路径为 null 或空字符串时初始化内置曝光、相机、XYZ 通道和空校准列表;显式文件路径仍保留兼容支持。WPF 的本地相机和视频会话使用空路径创建,物理相机及校准参数继续通过既有 JSON 接口注入。不能混用尚未支持空路径初始化的旧 DLL;仅删除配置文件不能替代 native 更新。
配套内部版 cvCamera.dll 不再使用 CameraAttribute.db 或旧 cvTableList 数据表实现,也不再导入 sqlite3.dll。相机读出模式保留 SDK 默认值;制冷能力通过 SDK 查询,温控开关和目标温度使用现有相机配置,停止温控不再依赖属性库。默认交付不含 cvTableList.dll / sqlite3.dll,托管 SQLite 的 SQLitePCLRaw 与 e_sqlite3.dll 依赖继续保留。旧 DataTable / SQLiteBaseControl 的 C++ 导出已移除,依赖这些导出或导出序号的外部程序需重新核对。
默认交付也不捆绑 cfg_files 中的 IKap 510.vlcf 和 MIL 的位深映射/DCF 采集配置。HK 的 MVS、GenTL、MVFG 驱动分支不使用这组默认配置;相机驱动仍须按实际设备安装。IKap/MIL 设备需要另行提供与设备匹配的采集配置,这不代表移除了这些相机 SDK 或改变了相机类型枚举。
内部版 cvCamera.dll 对 HK_USB 和 HK_CARD 的 BV/LV/LVTOBV 普通测量及视频采集默认直接调用已安装的 MVS x64 SDK;WPF 继续使用原有 CM_* 接口,不另设 HK 会话或兼容分支。旧后端预览的回调注销同时停止该回调启动的采集,重复注销及随后关闭不重复停止;重新注册先清理旧预览,再注册并启动。CM_SetCallBack/CM_SetCallBackEx 启动失败返回 CV_ERR_CAM_BEGIN_LIVE,注销时停止失败返回 CV_ERR_CAM_STOP_LIVE,回调设置失败返回 CV_ERR_CAM_SET_PARAM,原生 SDK 返回值和具体步骤写入 CameraPreview 日志;MVS 错误保留原始错误码。打开前通过 CM_UpdateCfgJson(Cfg_Camera) 顶层布尔字段 useHikMvs 选择后端:true 使用 MVS,false 使用旧 SCGDCamLayer。同一 JSON 的顶层整数 hikBayerQuality 可选 0 快速、1 均衡、2 最优、3 最优+,仅用于 MVS 彩色拍照;视频固定使用 2(最优)。顶层布尔字段 hikOutputBgr 选择彩色输出顺序:true 输出 BGR,与旧后端及现有校正契约一致;false 保留 RGB,仅供对照。新管理器默认后端 true、质量 3、BGR 输出 true;后续配置缺少字段时保留已设置值。只传后端、质量或通道顺序字段不重置物理相机参数;非布尔后端/通道顺序、非整数或超出 0–3 的质量、已打开时改变任一偏好均失败,已有连接及输出设置保持不变。WPF 的本机偏好允许随时编辑,仅下次实际打开时下发。彩色 MVS 拍照默认使用 Bayer 插值质量 3(最优+),视频固定使用 2(最优);打开及切换模式时调用 SDK 设置对应质量,切回拍照恢复本次连接保存的拍照质量,失败回滚同时恢复原模式的质量,先转换为 RGB24/RGB48,再按 hikOutputBgr 原地交换红蓝通道,默认交付 BGR24/BGR48;旧 SCGDCamLayer 的 HK 16 位转换也包含这一步,不能从 RGB16 中间格式推断最终输出顺序。LV 为 Mono8/Mono16,忽略通道顺序偏好。平均取图与自动曝光仍使用原生相机层的既有逻辑,本地校正、翻转、缓存和保存仍由现有上层链路处理。CV 滤轮模式、其它采集卡型号及其它相机继续走原接口;MVS 后端不支持 HK 的 QHY 专用 Fast/FastEx 模式。
MVS 开始采集前自动配置触发参数,无需用户先在海康客户端设置:保留设备当前支持的 FrameStart 或 FrameBurstStart 选择,当前选择不适用时优先选择支持的 FrameStart,否则选择 FrameBurstStart;先关闭所有触发选择器,设置 AcquisitionMode=Continuous、TriggerSource=Software;设备提供 AcquisitionBurstFrameCount 时设为 1,使用 FrameBurstStart 时该节点必须可用。测量启用所选触发器,每次清理旧帧后发送一次软件触发;视频保持 TriggerMode=Off,由相机连续曝光,不逐帧清缓存或触发,允许采集与转换重叠。参数在打开及模式切换时读回确认,不增加每帧设参。关闭或打开中途失败时,停止采集后按相反顺序恢复原参数,不调用 UserSetSave。参数设置或读回失败仍明确报错,原生日志记录参数名与 SDK 错误码;不能把通用 -10009 打开失败一概认定为相机离线。调用 MV_CC_OpenDevice 打开设备,GigE 使用独占权限,CameraLink 按 SDK 规则使用控制权限;SDK 不支持所选质量、像素格式或必要接口时明确失败,不静默降低质量或切回旧采集。HikMvsSDK、HikMvsOpen、HikMvsCapture 原生日志记录 SDK 版本、相机序列号、像素格式、质量、曝光/增益、帧号、连续/软件触发模式及等待/转换耗时。模拟接口验证覆盖缓冲释放和关闭重开,不代表实机验收;质量 3 与质量 2 的像素结果可能不同,启用前须对现场亮度、色度、均匀性和 MTF 等业务指标及连续采集耗时做对照。
原始配置在仓库 docs/_history/device-configs/ikap-mil/ 归档,不参与运行输出和默认安装包。该目录的 manifest.json 记录原始路径、字节数和 SHA-256,README.txt 说明按设备恢复工程复制项、安装器和共享清单的方法。恢复前应核对设备型号与位深,并在真实采集卡上验收,不能直接将历史配置当作所有 IKap/MIL 设备的通用默认值。
命名空间与程序集
CVCommCore/ 和 MQTTMessageLib/ 是本项目中的 C# 源码目录,保留 CVCommCore.*、MQTTMessageLib.* 命名空间,随默认 Compile 项编入 cvColorVision.dll。当前 cvColorVision.csproj 不生成两个同名独立程序集,也没有从仓库根 DLL/ 引用 CVCommCore.dll / MQTTMessageLib.dll;不能把 using 的命名空间直接当成缺失 DLL 的清单。
当前 Engine 通过项目引用消费 cvColorVision,依赖该 Engine 的插件沿实际程序集引用和复制规则取得所需库。部署故障应同时核对插件的依赖清单、实际 DLL 版本以及 native 输入;托管类型来源和供应商 DLL 是两种依赖。
这些共享类型也参与本地计算:CVCommCore 的结果编号、点形状和布点参数用于 Flow 与历史结果;MQTTMessageLib 的 POI 数值模型同时用于本地测量写入和结果读取。注册、心跳、服务状态、传感器命令和校正消息仍服务于现有设备链路。算法手动面板与这些数据契约分别维护,移除面板不应改变消息字段、结果编号、CSV 列或模板内容。
旧版或外部插件仍可能引用独立的 CVCommCore / MQTTMessageLib 程序集身份。此时保留并交付其要求的匹配 DLL,不能仅因当前源码编译通过就删除它们,也不能把 cvColorVision.dll 改名来充当旧程序集。应以该插件的实际引用为依据决定兼容部署或重建;同名类型不证明二进制兼容。
签名与返回值不能统一推断
当前相机绑定使用 CM_Open(IntPtr)、CM_SetExpTime(IntPtr, float)、CM_GetFrame(...) 等声明。签名和使用方式见 Camera/cvCameraCSLib.*.cs 及实际设备调用方。
cvCameraCSLib 的原生操作返回值统一保留 int,包括曝光/增益、配置更新、回调、取源图、滤轮、自动对焦、图像处理及校正操作;原先只有 0/1 的操作也预留整数错误码,不再按非零 bool 判断成功。当前这些操作成功值为 CV_ERR_SUCCESS=1,失败保留原始 0、平台错误码或 SDK 错误码。CM_GetErrorMessage 和 GetAllCameraIDV1 的字符串便捷入口同样返回原始整数结果;取源图便捷入口先检查尺寸查询的失败码,失败时不分配图像缓冲。由旧 bool 或 void 声明编译的调用方需要重新编译,原生导出名称与 32 位返回 ABI 保持不变。
当前相机托管层已清理无调用且交付 DLL 不提供的 38 个旧导入及其便捷包装,并移除未使用的 AoiParam.cs、C_AoiParam、PartiCle 和旧角点/布点类型;这不改变服务端 AOI 流程。保留的 CM_Reset 必须传入原生的 delayTimeMs,LedCheckYaQi 返回 int。C++ bool 参数显式使用一字节封送,Windows BOOL 状态返回仍使用四字节封送。
跨 DLL 的 CVImage(对应原生 HImage)、CRECT/IRECT、AutoFocusCfg、ChromaInfo 使用按声明顺序的字段及 Pack=8;Release/x64 大小分别为 24、16、48、44 字节,对焦配置最后一个 double 位于偏移 40。修改字段类型、顺序或对齐时须同步原生定义。连续帧和对焦回调的返回值为 32 位 int,调用约定为 StdCall。配置、SN 和设备模式字符串便捷入口检查原生返回码后才返回字符串;原生文本复制在容量不足时返回平台错误,避免 CRT 的无效参数处理及错误成功。
纯状态查询 CM_IsOpen、CM_GetDeviceOnline、CM_IsFeatureAvailable、CM_IsBurstmodeAvailable 仍返回 bool;无效句柄返回 false,不能被负数平台错误码误判为可用。CM_GetSrcFrameInfo 成功返回 1,尺寸、位深和通道数经引用参数输出;CM_GetFrameMemLength 则返回缓冲字节数,调用方应按各入口的真实语义检查结果。
本地取图、自动曝光和独立相机测试在设置曝光/增益失败时立即通过 CM_GetErrorMessage 构造错误,不继续采集;本地视频初始化检查采集模式、位深、曝光、增益和回调,界面手动设置和滑块调整失败也记录同一错误说明。
CM_SwitchCaptureMode(handle, mode, bpp) 为本地 MVS 的普通拍照/视频切换入口,成功返回 1。模式或位深改变时停止取流,按需调整原生像素格式,将视频切为连续采集、拍照切为单帧软件触发,读回确认后恢复取流并清理旧帧;相同模式及位深不重启取流。首次打开及切换共用位深初始化:LV 单色优先使用已列出或正在使用的原生 Mono8/Mono16;请求 16 位输出但没有原生 Mono16 时,保留当前 Mono10/12/14 或 Mono10/12_Packed 源格式,或从 8 位预览切回枚举支持的高位深单色格式。按真实源格式解包并将有效位左对齐为 16 位单通道输出,例如 12 位左移 4 位,保留全部有效位,不把 8 位源扩成 16 位测量。Mono10/12_Packed 使用旧 GigE 分组打包规则,要求偶数行宽,按打包后的源字节数验证完整性,不能按 16 位字节直接复制;截断帧在写输出前失败,SDK 帧在所有路径归还。LV 的 Bayer 原始平面与 BV 彩色分支保留同相位的 8/16 位格式切换规则,含 Packed 源相位;SDK 必须实际切换并读回验证,未知彩色相位要求唯一的已列出候选。HikMvsPixelFormat 记录当前格式、请求位深、目标格式及枚举是否包含它;独立 MVS 诊断工具仍要求原生 Mono16/Bayer16,用于该路径的对照,不覆盖 LV 高位深源格式的解包链路。均保留相机连接、ROI、曝光、增益及转换偏好;重复切换不追加原参数恢复记录。入口先停止并等待预览回调退出,再取得帧锁,避免回调与切换互相等待。旧后端返回 CV_ERR_CAM_TYPE_NOT=-10030,Engine 才使用原有关闭/重开方案;SDK 错误直接返回,不以重连掩盖失败。失败恢复先前格式及触发模式,无法恢复时关闭连接。原有仅关闭时可设置的 CM_SetTakeImageMode / CM_SetImageBpp 契约不变;MVS 的 Fast/FastEx 模式仍不支持。离线格式与缓冲测试不能代替同一实机的新旧后端测量对照。
CM_GetAutoExpFrame 为测量模式下的独立自动曝光返回达标帧,参数包含调用方持有的图像指针及 uint64_t 字节容量、图像尺寸/位深/通道数,以及各有三个 float 的曝光(ms)和饱和度数组。它保留既有曝光搜索算法;成功为 1,按既有目标饱和度及偏差检查最终图像,未达标返回 CV_ERR_CAM_AUTO_EXP_NOT_CONVERGED=-10075,SDK 失败保留原始整数码。Live 模式拒绝此帧返回入口,避免把改变曝光前排队的回调图像作为最终帧;视频窗口继续使用既有自动曝光及实时显示。曝光与图像来自同一次最终采集;MVS 曝光采用设置时的 SDK 读回值,旧 burst 取图保留该合成帧的有效曝光。单次彩色/灰度采集将曝光和饱和度复制到三个槽位;CV 三通道的数组按 X/Y/Z(R/G/B)排列,图像保持现有 BGR 布局。容量不足或失败时不修改调用方图像及结果输出。Engine 在持有帧期间复制独立预览,随后释放帧;独立自动曝光不写 CVRAW、缓存文件或数据库记录。既有 CM_GetAutoExpTime 和正常测量保存链保持原语义。
直接 MVS 后端的 SDK 调用失败保留 SDK 原始 32 位错误码,通过 int 返回,例如 MV_E_NETER=0x80000206 的有符号值为 -2147483130;MVS 的成功值 0 在相机公共入口仍转换为平台成功值 1。参数校验、输出校验和非 MVS 后端保留原有平台错误码。CM_GetErrorMessage 识别 MVS 错误范围,按构建时从 SDK MvErrorDefine.h 自动生成的名称/英文说明返回解释;未知码仍输出原始十六进制值,不手工维护第二套数值定义。同线程立即查询时还可附带 SDK 操作名和相机 SN,按线程隔离且每次 MVS 操作重新清理上下文;跨线程查询仍能解释返回码本身,不承诺取到原调用的操作上下文。原生与托管日志仍沿用现有机制。
HK_USB 和 HK_CARD 搜索使用直接 MVS 枚举,不受搜索入口占位 CV_MODE 影响。HK_USB 枚举 GigE/USB;HK_CARD 包含多种海康采集卡,不能统一当作 CameraLink。逐一查找已安装的 MvFGProducerCML.cti、MvFGProducerCXP.cti、MvFGProducerGEV.cti 和 MvFGProducerXoF.cti,每类优先使用实际加载 SDK 的目录,再查已安装 MVS x64 runtime;分别调用 MV_CC_EnumInterfacesByGenTL 和 MV_CC_EnumDevicesByGenTL,从 MV_GENTL_DEV_INFO 复制序列号、型号及 CTI 索引,跨传输类型匹配配置的序列号,再调用 MV_CC_CreateHandleByGenTL 创建对应句柄。未安装的 CTI 或接口为空不终止其它类型搜索;单类枚举 SDK 错误写入日志并继续搜索其它类型,最终无设备且存在 SDK 错误时返回首个原始错误。两类枚举共用进程锁,复制 SDK 所有的接口及设备信息后再离开锁;CTI 保持加载,避免影响其它句柄使用的索引。GenTL 接口仅为 HK_CARD 必需,不影响 USB/GigE 的运行依赖。HikMvsGenTL 日志记录各 CTI 路径、接口数、各接口设备数与设备身份及 CTI 索引。创建句柄后,打开、普通测量、视频及模式切换共用 HikMvsCamera。现场需要已安装与采集卡匹配的 MVS/GenTL 驱动;新后端失败时保留 SDK 错误,不自动切回旧后端;CV 滤轮的实际采集后端保持原规则。CM_GetCameraID / CM_GetCameraIDV1 仅将 1 视为成功,SDK 负数错误原样返回;无设备返回 CV_ERR_CAM_SCAN=-10005,不再将失败包装为空列表成功。
HikMvsSDK 同时记录实际加载的 SDK 文件路径与宿主程序路径;默认 DLL 搜索失败后,依次尝试 CommonProgramFiles(x86) 和 CommonProgramFiles 下的 MVS x64 runtime。GetImageBuffer 超时保留 MV_E_NODATA 和操作名;HikMvsTimeout 记录触发参数读回,GigE 另记录本次取流的累计接收字节/帧数、丢帧、重发统计及流目标地址/端口节点。诊断接口或节点不可用时记录各自返回码,不覆盖原始采集错误。独立取图测试运行于 ColorVision.Engine.exe,主程序运行于 ColorVision.exe;测试成功只证明该次测试链路有效,不能据此认定主程序加载的 SDK、会话或程序防火墙规则一致。
MVS 视频回调丢弃坏帧、归还 SDK 缓冲并继续取帧,超时仍无有效帧才退出。HikMvsPreview 记录被丢弃的帧号和丢包数。维护版源码中的同步取帧在直接 GigE 报告 nLostPacket > 0 时可探测包大小,见 HikMvsCamera::Impl::RecoverPacketSize。探测与回滚仅作用于当前相机会话,视频回调沿用现有包大小。原生离线测试覆盖坏帧后取到好帧、缓冲归还、持续坏帧超时及同步取帧恢复,现场丢包表现仍需实机验收。
平台错误 CV_ERR_CAM_ID_MATCH=-10007 明确表示 ID 与枚举设备不匹配;CV_ERR_CAM_OPEN=-10009 仅表示设备打开失败。旧 SCGDCamLayer 普通打开日志记录请求 ID、枚举 ID、型号、模式和失败步骤,其指针接口未提供底层 SDK 错误码时明确标记不可用,不推断为 ID 错误。MVS 打开日志记录序列号、传输类型、失败操作及 SDK 错误。
交付时应核对 DLL 实际导出与结构布局,并在真实 MVS 环境验收采集。
接口混用 int、bool、void,成功值由具体入口决定。例如 Spectrometer.GetErrorMessage 把 1 作为成功而返回空字符串,不能套用“所有 native 调用返回 0 才成功”。绑定存在、构建成功或取得返回值,都不能单独证明采集、校准或输出已安全完成;验证设备动作仍需明确授权和真实状态证据。
先查什么
| 现象 | 第一检查点 |
|---|---|
DllNotFoundException | native DLL 是否在 x64 输出目录,依赖 DLL 是否也在 |
EntryPointNotFoundException | EntryPoint 名称、DLL 版本、供应商导出符号 |
BadImageFormatException | x86/x64 位数混用、AnyCPU 配置 |
AccessViolationException | DllImport 参数、数组长度、指针生命周期、释放顺序 |
| XYZ/CCT/xy/uv 数值异常 | PoiMeasurementService 的平面 CIE 布局、RAW 校正快照与采样区域 |
| PG/源表无响应 | 连接方式、端口/IP、Start/Stop 顺序、原生返回码日志 |
当前能力
| 能力 | 当前入口 | 说明 |
|---|---|---|
| 相机/通用视觉 | Camera/cvCameraCSLib.*.cs | 相机打开关闭、预览、取帧、配置 JSON、自动曝光、ROI、采样、TIFF、对焦和多类检测函数 |
| 光谱仪 | Devices/Spectrometer/ | 光谱设备绑定 |
| 图卡 | Devices/PatternGenerator/PG.cs | PG 初始化、TCP/串口连接、Start/Stop/Reset、帧切换 |
| 源表/电源 | Devices/PassSx/PassSx.cs | 打开关闭、源模式、2/4 线、前后端口、电压电流、步进/扫描 |
| 极薄入口 | Algorithms.cs 等 | 直接暴露少量底层函数 |
| MQTT/设备 DTO | MQTTMessageLib/、CVCommCore/ | 原生/设备链路相关消息和数据结构 |
检查
| 验收项 | 通过标准 |
|---|---|
| native DLL 就位 | cvCamera.dll 及其实际依赖能在 Release/x64 输出目录加载;隔离加载不需要 OLED/CUDA,实际导出覆盖当前 C# 声明 |
| 位数一致 | 主程序、插件、native DLL 都是 x64 |
| 相机链路 | 初始化、枚举/打开、取帧、关闭和释放能按真实设备流程跑通 |
| PG 链路 | 初始化、连接、Start/Stop/Reset、上下切换或指定帧切换可被设备服务调用 |
| 源表链路 | 打开、设置源模式、读电压电流、步进/扫描、关闭有明确调用顺序 |
| 错误码 | 原生返回码能进入日志或上层异常,不被吞掉 |
cvCamera.dll 许可证构建约定
以下是外部源码仓库的交付约定,不是本仓库可单独证明的运行状态;未提供该外部源码与真实设备测试时,不应断言当前 DLL 的许可证分支已完成验证。
本仓库 DLL/scgd_internal_dll/cvCamera.dll 默认保存公司内部使用版本:相机和光谱仪打开链路均不执行许可证验证。外部 scgd_internal_dll 源码仓库仅用于本地修改和构建,不在本仓库的交付流程中提交;确认产物后,只把 DLL 复制到本仓库并在这里提交。
生成内部版本时,检查以下开关:
| 设备链路 | 源码位置 | 内部版本 | 需要许可证的交付版本 |
|---|---|---|---|
| 相机 | cvCameraItem/cvCameraItem/cvCamera.cpp 中的 CM_ValiLic | 许可证分支使用 if (false) | 使用 if (true) |
| vLight 光谱仪 | cvCamera/cvCamera/SpectroHelper.cpp 中的 _ACTIVE_LICENSE_ | 定义为 0 | 定义为 1 |
| 高立通光谱仪 | cvCamera/cvCamera/SpectroGaolitong.cpp 中的许可证分支 | 使用 if (false) | 使用 if (true) |
pCamMan->SetDeviceMode(mode) 保存的是许可证中的 device_mode,供 CM_GetDeviceMode 返回,不是设置相机硬件工作模式。内部版本不执行许可证分支时不要单独补调用;此时设备模式保持为空,上层应继续使用配置的相机型号作为回退。
按 Release|x64 构建后,确认相机、vLight 光谱仪和高立通光谱仪的打开路径没有活动的 LicenseValidate 调用,再把产物复制到 DLL/scgd_internal_dll/cvCamera.dll。静态许可证/HASP 代码或导出仍可能保留在 DLL 中;内部版本的验收标准是上述运行路径不触发许可证验证。
验证入口与缺口
验证缺口:未登记能替代真实供应商 DLL 与硬件的完整自动化测试;外部源码和许可证构建说明不能由本仓库静态检查直接证明,交付需核对产物和设备路径。
