主程序光谱仪搜索与配置
本页适用于 ColorVision 设备树中光谱仪的属性页和许可证管理窗口。独立光谱仪软件的连接、测量与标定见 Spectrum 插件。
主程序光谱卡片与 ViewSpectrum 结果详情的登记、首次显示和首结果入口见设备详情视图按需初始化。
结果列表展示序号、测量时间、积分时间和光谱测量指标。标准亮度和光通量 CSV 保留 Lot 的 BatchID 与 380–780 nm 固定列,在实测波长范围内按起点和间隔对齐光谱。没有实测样本的列留空,不插值。
结果视图右下角设置打开 ViewSpectrumConfig。View → 显示光谱彩色填充 控制相对和绝对光谱的单曲线填充。关闭 View → 显示显色指数 可在结果表隐藏 Ra、R1~R15 和显色性状态,开启后恢复原逐列设置。两项设置即时生效并保存,分析与导出仍提供显色结果。
在光谱仪的 修改配置 → 设备与连接 设置 启用本地光谱仪,右键设备卡片选择 本地光谱仪 打开本地窗口,属性中的 本地光谱仪管理 也保留入口。新配置及缺少 UseLocalSpectrum 字段的旧配置优先本地,已保存的选择继续生效。下次打开时按偏好选用 SDK 或服务,已经打开的连接继续由原后端管理,关闭后才切换。服务打开后心跳断线不代表释放硬件,需要确认服务连接已关闭后再打开本地。窗口和流程共用设备会话及 Spectrum 插件的驱动占用保护,原生释放失败时不允许再创建连接。
本地窗口支持连接、断开、单次/连续采集、停止、手动校零、自适应校零初始化、重置校零、自动积分、校正组和结果导出。关闭窗口保留连接;设备卡片和本地窗口的停止按钮仅在连续采集中显示,断开命令仍可请求停止当前单次或连续采集。自动曝光通过 CM_Emission_GetAutoTimeCancelable 在各次 SDK 调用之间检查停止请求,停止后不继续校零或开始正式采集;窗口和流程共用该取消通道。设备占用保留到原生工作真正结束后释放,停止完成前不接受新的连接或测量。正在执行的单次厂商 SDK 采样需要先返回,当前接口不能强制中断该采样;已完成的正式采集继续保存和展示。物理 SN、连接类型、串口和许可证沿用现有配置,连接后核对实际 SN,拒绝误连其它设备。已导入的许可证写入应用 license 目录供 SDK 验证;已有 LIC 文件继续供 SDK 使用,客户端到期判断使用配置库中的许可证记录。相对校正文件路径以应用目录解析,采集前验证波长/幅度文件,修改校正组在下次采集生效,不重启服务。修改连接类型、SN 或串口后需要关闭重开。
自动曝光保留正常信号的比例搜索及暗场采用配置上限的规则,曝光下限为 1 微秒,最多采样 64 次;重复曝光、持续饱和至下限或达到采样次数上限时返回不收敛错误,提示检查光路、亮度或 ND,并允许调整后重试。取消返回 -13026,不收敛返回 -13027,无效参数或采样数据返回 -13028。起始时间与最大积分时间必须有效,最大积分时间还需满足原生整数微秒范围。搜索失败或停止不会覆盖本次积分参数,也不继续后续采集;暗场采用较长上限时,正式采集本身仍可能等待较长时间。
CMvSpectra 的原生 SDK 调用在 cvCamera.dll 内串行执行,并保护调用线程内的访问异常和 C++ 异常。捕获后停用当前进程内的 SpectraArsenal SDK,清理包装句柄时不再调用该 SDK,也不卸载故障 SDK;搜索和连接返回 -13025,提示重启程序后再连接。普通 SDK 失败仍按原返回码处理,不触发停用。日志记录故障函数、异常码及地址。此边界不覆盖 SDK 后台线程崩溃、栈溢出、fail-fast 或已经造成的内存破坏,不能替代真实设备验收和崩溃转储分析。
本地设备卡片的“打开”、本地管理窗口和流程自动连接共用同一到期检查:原生连接成功并核对 SN 后,读取该 SN 的 lic_type=1 许可证记录,只比较 ExpiryDate 与当前本机时间,不解码载荷或增加签名校验。到期时间缺失或不晚于当前时间时,通过当前入口提示许可证问题,并关闭、释放本次连接及驱动占用;原生连接先失败时保留原生错误。选项中的“实验功能”(ExperimentalFeaturesConfig.IsEnabled)默认关闭,开启时跳过这项应用侧缺失/到期检查及该检查所需的许可记录查询;关闭后恢复上述规则。SDK 的许可证文件准备、有效 SN、连接与签名规则保持原有行为,实验开关不保证原生 SDK 可以在无有效许可证时打开设备。复用已打开会话、单次/连续采集和校零不重复检查,关闭后再次打开才重新判断。服务端打开路径保持原有行为。
流程的 本地光谱采集 节点支持设备、积分时间、平均次数、自动积分、使用 ND、校零和自动连接;属性中的本地管理窗口可试采集,再通过 应用到节点 回写参数并保存流程。已有 SpectrumNode(GetData / InitDark)与 SpectrumEQENode 在设备选用本地后端时由 LocalSpectrumFlowExecution 接管,使用原节点参数。FWNode 的 光谱仪+ND 类别仍选择光谱仪设备 Code;光谱仪使用本地后端,或绑定的 ND 已启用本地时,由 LocalSpectrumNdFlowExecution 转发切位,不要求改成独立滤色轮类别。连接、定位或采集失败终止本次命令,不回退到 MQTT。仅包含本地节点或可本地转发节点的流程可以由未连接的 MQTT 开始节点手动执行;含其它服务节点时仍要求服务连接。
SpectrumNode 的“输出文件”位于高级属性,默认隐藏;手动开启高级属性后可编辑。默认文件名仍为 SPData.json,已有流程保存的自定义名称继续加载,并按原参数参与执行。
本地采集和手动校零的积分时间须在 0.001 至 2,147,483.5 ms 内,保护原生微秒整数转换。硬件仍可能限制或量化时长。在“编辑重复框…”中可保存逐轮积分时间和平均次数,每轮独立生成请求,自动积分不会修改节点默认值或保存的数组。自动积分开启时禁用逐轮积分时间。启用同步频率时两项逐轮覆盖均禁用,手动校零、自动暗校正和正式采集使用相同的同步计时规则。请求日志保存本轮参数,结果记录实际积分时间和平均次数。重复次数与单轮内部平均次数分别生效。
本地同步频率采集完成后,结果显示实际积分时间,采集输入框保留原设定供下一次采集及“应用到节点”使用。
单次、连续测量和流程执行将光谱、色度与实际积分时间直接交给界面/流程。连续测量逐条保存并追加到主界面和本地窗口,下一次测量不替换上一条;停止期间已经完成的原生采集仍保存和展示。离线结果逐条留在内存,可由本地窗口导出 JSON;在线历史结果写入原 MySQL 光谱结果表,流程遵守 PersistResults。保存成功后列表及导出使用数据库记录 ID;写入失败停止连续测量并报告错误,不继续静默丢弃记录。任何采集结果都不写配置 SQLite。图表按原生返回的波长起点、间隔和有效点数绘制,保留原始结果用于校正与导出。
光谱、显色性数组和 CIE 扩展数据以原始 JSON 文本写入历史表,不再由 ORM 额外序列化字符串。写入数值列前,将光谱指标、EQE 和通量中的 NaN、正负无穷转换为数据库 NULL,不伪造为零;电压、电流和系数转换为单精度后溢出的值也按缺失处理。原始光谱样本及 CIE 扩展 JSON 保留原值,显色性数组包含无效值时沿用缺失处理;此保护不修改本次采集对象或光路配置。读取兼容既有的 JSON 数组/对象及被引号包装的历史字符串,无需批量重写数据。普通查询和高级查询先完成读取、转换,再替换当前列表,查询失败时保留原列表。
本地 EQE 沿用服务的电气输入契约:旧 SpectrumEQENode 默认读取本次流程前面的 SMUResult,其中电压为 V、电流为 mA;开启“自定义电压/流”时以节点填写值覆盖 V/I,保留原有测量关联,且不修改上游测量对象。转交原生 EQE 之前电流只转换一次为 A(例如 25 mA → 0.025 A)。缺少上游且未启用自定义时明确失败,不使用设备界面中的上次值或 PG 九路数据。PG 的 POWER.MEASURE 没有服务默认的多路合成规则,不自动转成 SMUResult。
新“本地光谱采集”节点的“使用上游源表电压/流”默认开启,启用 EQE 后读取本次流程实际执行过的上游 SMU 测量并按相同规则转换;仅存在节点却没有有效测量结果时明确报错,不自动回退到手填值。需要手动输入时关闭该选项,再填写 V/A;输入框只在 EQE 手动输入时显示。旧流程缺少该选项时采用上游默认值,已经明确保存的开启或关闭值继续保留。普通光谱不因此要求 SMU。节点保存值不被上游覆盖,执行日志和结果参数记录实际使用的 V/A 及原始 SMUData(mA)。手动窗口的 V/I 继续为 V/A。历史表 VResult / IResult 按服务约定保存 V/mA,并关联有效的上游 SMU 结果 ID,不把原生返回的 A 直接写入 mA 字段。
本地 EQE 暂不支持同步频率模式。启用 NDConfig.IsNDPort 后,ND 与光谱仪组成同一测量链:绑定已有滤轮时复用其本地会话,不要求再打开“使用本地滤色轮”开关;未绑定设备时使用 ND 配置的串口、波特率,由光谱仪会话持有连接。打开光谱仪时检查 ND 连接和实际孔位。断开时分别释放光谱仪、串口快门和自有 ND 连接,共享滤轮继续可用。任一步失败仍尝试释放其余设备,并报告所有关闭错误。已知服务占用、并发指令、配置变化或定位读回不符均明确失败;服务失联不视为已释放串口。
ND 采集始终读取实际孔位,加载该孔位对应的波长和幅值文件。标定优先按分组的 NDHoleIndex 匹配,再兼容 NDCaliNameGroups 的分组名及孔位名称;旧配置中的幅值文件路径仍可使用。缺少或损坏的标定拒绝测量,不使用其它孔位的文件替代。开启采集参数的 使用 ND 与 自动积分 后,按 NDRate 的倍率顺序联动切孔;倍率列表下标是物理孔位,倍率须非负且不重复。NDMinExpTime、NDMaxExpTime 定义可接受的积分范围,EnableResetND 从最小倍率孔开始。各次自动曝光之间检查停止请求,越界、重复孔位或无法收敛时停止,不继续校零或采集。尝试切孔后遇到停止或采集失败,会在释放 ND 占用前恢复初始孔位和原有暗数据。恢复孔位失败时提示检查光路。成功采集后保留选定的测量孔位。
未启用外部快门时,已配置 ND 的真实暗采集及自适应校零初始化使用 DarkNDPort,结束后恢复操作前读回的测量孔位;失败仍尝试恢复,恢复失败明确提示检查光路。同一滤轮同时被旧快门配置引用时,复用 ND 占用,并兼容快门配置中的校零孔位。未配置 ND 或外部快门时仍要求手动遮光;自适应暗校正需要先完成初始化。设备驱动、实际许可证、校正文件与现场遮光条件仍由真实设备验收确认。
本地外部快门沿用 修改配置 → 快门 的启用开关、串口、波特率、开关指令与等待时间,不依赖光谱 SDK 的快门接口。固定快门控制器要求 DTR 有效才能返回回执,串口创建时默认启用 DTR,RTS 保持关闭,不增加配置项,已有快门配置直接生效。光谱仪连接打开后,设备卡片和本地窗口均可打开、关闭快门;首次操作按需连接串口,采集和流程共用该连接,关闭光谱仪或释放设备时一并释放串口。关闭本地窗口继续保留连接。手动指令、单次/连续采集和流程执行共用操作门禁,采集中拒绝额外开关操作,不转发光谱仪 MQTT 指令。快门连接配置修改后在下次操作时重连。
光闸的遮光/通光方向按设备配置,不能由 Open/Close 名称或 a/b 字母固定推断。 设备卡片和本地窗口按钮只显示 遮光、通光。在 修改配置 → 快门 配置打开指令 OpenCmd 和关闭指令 CloseCmd(默认 a/b),并设置 遮光使用打开指令(本地)(OpenForDark):选中时遮光使用打开指令、通光使用关闭指令,取消时两者互换。旧配置缺少该项时默认选中,保持已发布本地版本的行为。回执按实际发送的字符匹配:a → turn on、b → turn off,交换 a/b 后不会继续等待原字段对应的回执;其它自定义指令沿用打开/关闭的既有回执约定。相反回执及超时仍拒绝操作,不能为消除“不匹配”而关闭校验。手动按钮只切换光路,不采集或校零;串口回执不证明实际光路,仍需现场核对。
服务模式保留 cvwindowsservice 已长期使用的打开通光、关闭遮光约定及已验收的指令配置,OpenForDark 只影响本地后端。设备卡片在服务模式下仍把遮光映射为 ShutterDoClose、通光映射为 ShutterDoOpen;不能把某台本地设备的 a/b 方向套到服务端,也不自动改写服务端配置。
同一 shutter 配置中的“使用滤色轮校零”(ShutterCfg.UseFilterWheel)默认关闭,旧配置继续使用电动 shutter。启用 shutter 并打开此项后,隐藏串口和开关指令,显示独立的滤轮绑定、测量位及校零位;测量位和校零位使用下拉框,按绑定滤轮的孔位名称选择,默认分别显示 Spectrum 和 ND0。切换绑定滤轮时刷新选项,不自动覆盖原孔位;未匹配的孔位暂留空供重新选择。绑定和两个孔位保存在 ShutterCfg 内,孔位仍保存整数索引以兼容已有配置,与 ND 标定分组绑定分别配置。提交拒绝未绑定、负孔位或测量位与校零位相同的配置;运行时还检查绑定设备及唯一孔位映射。
滤色轮方式仅接入本地光谱:复用绑定 DeviceCfwPort 的现有通道,必要时先打开已关闭的滤轮,不另开串口。手动 通光 切到测量位,真实暗采集及自适应校零初始化切到校零位,结束后恢复指定测量位;每次定位都等待设置回执,并读取 Port 确认到位。滤轮始终按测量位/校零位控制,不使用串口 a/b 方向。定位、校零或恢复失败会终止本次测量;校零失败仍尝试恢复测量位。整个采集或校零期间占用该滤轮,拒绝本程序通过同一设备发送的额外手动开关及切位;结束时只释放占用,不关闭共享滤轮,也不按临时校零位切换光谱标定组。其它进程或服务端相机流程直接控制同一硬件不在此门禁内,共用滤轮的相机取图和光谱校零须按顺序执行。服务光谱模式拒绝该选项,保留停止和关闭入口。
本地单次、连续及流程采集开始时保留手动光闸状态,不主动发送开关指令;自动积分使用当前光路,正常测量前点击 通光。不能为了“确保打开”在采集入口补发开关指令,避免覆盖人工选择。自动校零在确定积分时间后按配置遮光、采集暗电流、恢复通光,再采集光谱;默认配置为 a → 采暗数据 → b,反向配置为 b → 采暗数据 → a。手动校零和自适应校零初始化沿用该遮光与恢复顺序;读取已初始化的自适应暗电流表不切换光路。回执兼容分段与大小写,发送前清除旧回执;等待时间不大于零时沿用 1000 ms。收到正确回执后再等待同样时长供机械动作稳定。相反状态、超时或通信异常均停止后续采集;遮光或校零失败后仍尝试恢复通光,恢复失败提示检查光路。
自适应校零初始化的步数、积分间隔和平均次数均至少为 1,起始和末次积分时间均须在原生支持范围内。参数无效时保留已初始化的暗电流表与当前光路。
本地模式的设备卡片和本地窗口提供 重置;设备卡片将按钮放在自适应校零设置按钮之后。重置要求连接已打开且没有正在执行的采集或设备操作,清空当前会话中的暗数据并使自适应校零初始化状态失效。成功后关闭设备界面的自动校零和自适应暗校正,下次手动测量可直接对比清除暗扣除后的结果;重新启用自适应暗校正前必须重新初始化。普通校零每次替换暗数据,不累加;暗数据只保留在当前连接内,关闭光谱仪也会清除。重置不关闭连接、不驱动快门、不删除历史结果或标定文件,也不重算既有结果;流程节点的校零选项仍按节点自身设置执行。SDK 将测量信号减去暗数据后截断负值,因此不充分遮光得到的暗数据可能使后续曲线大面积贴零,不能据此判断物理快门当前是否关闭。
本地采集的平滑算法在 修改配置 → 采集参数 设置:GetDataConfig.SmoothingMethod 默认为 Mean=0(均值滤波),SavitzkyGolay=1 使用优化后的二阶 SG。缺少此字段的旧配置仍为均值,原有 FilterBW 数值原样保留;均值宽度小于等于 2 时沿用 5 点、偶数窗口和零填充保持原样。SG 使用原始采样索引的缓存卷积核,宽度必须为 3~2047 的奇数且不超过实际点数,非法值拒绝采集。它沿用零填充,可能出现负旁瓣和边缘过冲,目前只有合成数据验证。算法选择在每次本地普通、同步频率或 EQE 采集前应用于同一原生句柄,切回均值不会沿用 SG。远程服务不使用此选项。
搜索设备
在光谱仪属性页的 设备与连接 → 搜索光谱仪 查询本机设备。搜索依次遍历 CMvSpectra、LightModule、Gaolitong,不受当前配置选中的连接方式限制。每种方式先查询 USB;配置串口大于 0 时,另对 CMvSpectra 和 LightModule 查询该串口。高利通只能通过 USB 枚举,连接时使用的串口不能传给其枚举接口。
结果按连接方式和端口显示序列号;将对应连接方式和 SN 填入 修改配置。搜索不修改已保存的连接方式、不创建连接句柄、不重启服务。查询在线设备仍可能受供应商驱动或设备占用影响,发现序列号不等于连接成功。
查询在后台依次执行,运行期间禁止从同一入口重复启动。某种驱动异常或原生返回值不为 1 时保留该项错误并继续查询其余方式。原生响应 {"number":1,"ID":["SN"]} 中只读取 ID,数量字段不作为设备序列号;同一结果内过滤空值和重复序列号。
许可证窗口的 获取光谱仪许可 使用同一搜索逻辑,对三种方式查询 USB,不再为读取 SN 打开和关闭设备。联网更新由物理光谱仪管理中的独立按钮执行。
主程序的 许可证管理 同时列出相机和光谱仪许可证,顶部统计正常、30 天内到期、已过期及日期未知的数量。到期判定沿用本地时间戳:到期时间早于当前时间才算过期;缺失日期显示“日期未知”。一键清除过期 显示待删除数量并要求确认,只删除本次确认范围内仍已过期的许可证记录,保留期间续期的记录、日期未知记录、设备配置和导出的 LIC 文件;清除不会重启服务或卸载运行中的许可证。完成后刷新列表并显示实际删除数量,失败保留错误信息。
物理光谱仪管理 可从设备配置窗口顶部、设备属性页的“设备与连接”或光谱仪 SN 属性旁的“编辑”打开。顶部保留“扫描”和“导入”,左侧按 SN / 型号查询;右侧沿用物理相机的型号、SN 与紧凑许可证横条。横条内“更新”导入当前 SN 的本地许可证,下载图标后台联网更新,另提供复制和导出。它不提供相机的配置或备份属性,也不单列批量联网更新或手动登记按钮。
许可证横条下方的“光谱仪工具”额外提供驱动工具、光谱校正和光谱仪日志,原设备页入口继续保留。驱动和日志可在尚未选择 SN 时打开,复用原有工具校验、确认及日志定位逻辑。光谱校正仅匹配已经载入且 Config.SN 与当前物理 SN 一致的设备;只有一个时直接使用,多个时先选择目标,没有匹配设备时禁用并通过工具提示说明绑定要求。执行前重新核对关联,复用该设备原有校正命令、测量门禁及文件应用逻辑,不创建或自动绑定逻辑设备。
清单合并未删除的 ServiceTypes.PhySpectrums = 103 资源、lic_type=1 的既有许可证和逻辑光谱仪配置中的 SN,忽略大小写并去重;读取清单不做数据库迁移。旧许可证即使没有物理资源也继续可见。登记只创建 SN 资源,不生成相机配置、不修改逻辑设备 SN。SN 下拉复用同一清单及卡片样式,关闭管理窗口后刷新,原有 ConfigSpectrum.SN 保存格式及手动输入保持兼容。
扫描默认查询全部驱动的 USB;从设备打开时带入该设备的串口,从设备配置窗口打开时默认串口为 0。发现的 SN 去重后登记到物理光谱仪资源并刷新清单。“本次发现”仅表示此轮查询发现,“未确认在线”不表示离线;某项驱动失败不隐藏其它查询结果,详情区保留逐项错误。扫描不下载许可证、不打开设备连接。
联网更新按当前 SN 调用现有许可证下载接口,检查 HTTP 状态及 JSON / 文本错误,直接读取 ZIP 中唯一匹配的 <SN>.lic,不使用服务端文件名落盘或解压路径。许可证沿用 Base64 JSON 格式,读取型号、客户和到期日期后才保存 lic_type=1 记录;更新保留原许可证 ID 及关联,遇到相同 SN 的其它类型许可证时拒绝覆盖。历史库中同一 SN 有多条光谱仪许可证时,本地导入和联网续期同步更新这些记录的许可内容、型号、客户及到期时间,保留各条记录的 ID、创建时间和设备关联,避免清单与连接读取不同记录而继续使用旧许可。当前格式没有独立 SN 字段,身份匹配依赖 LIC 文件名;这里不代替驱动加载时的签名校验。联网更新静默执行,不显示进度、成功或失败提示,详细错误只写日志;成功后刷新许可证状态,不自动重启服务或使运行中的驱动重新加载许可。
顶部“导入”无需预选设备,支持多个 LIC / ZIP,并按文件名将各个 SN 的许可证加入清单;全部文件内容验证通过后再逐条保存,重复 SN 拒绝导入。横条“更新”只接受当前 SN 对应的 LIC 或 ZIP。本地导入失败在窗口底部显示原因;复制、导出和联网更新不会弹出完成提示。
配置入口
设备卡片将标定分组选择和分组管理按钮放在“打开 / 关闭”同一行的右侧;长分组名可通过下拉选择查看,连接状态和采集参数区域继续按设备状态显示。
连接、单次采集、连续采集启停及手动校零复用按钮进度条提示执行过程,只防止当前按钮重复触发;完成、失败或超时后恢复按钮。打开、关闭及测量执行期间保留原有卡片布局,在连接完成、断开等有效结果后更新可用功能;关闭入口及底层驱动占用保护继续沿用。
服务连续光谱及 EQE 使用回包的 MasterId 显示对应采样并回写积分时间。缺少有效 ID 或记录不存在时保留当前显示。旧版内联光谱结果仍直接从回包读取。
| 分类 | 操作 |
|---|---|
| 设备与连接 | 修改配置、编辑显示配置、物理光谱仪管理、搜索光谱仪、光谱仪驱动工具 |
| 校准与校正 | 标定分组管理、应用当前分组、光谱校正、自适应校零、校零设置、SP100 暗电流设置 |
| 数据与日志 | 光谱仪日志 |
| 服务与维护 | 删除 |
属性页与其他设备共用 GenCommand 自动生成机制,通过 CommandDisplay、Category 和 Description 元数据定义入口,不单独维护光谱仪布局或刷新数字角标。入口复用原有命令及权限检查;删除保留原有确认。分类之间使用细分隔线,紧凑操作项随可用宽度换列,窄窗口可纵向滚动;色彩和交互状态跟随更新窗口的浅色、深色主题。
设备配置窗口顶部的物理光谱仪入口,在当前选中光谱仪设备时带入其 SN 与串口,否则打开全体 SN 清单。
光谱仪驱动工具 打开随主程序交付的 Zadig,仅用于现场手动安装或替换 GCS 光谱仪 USB 驱动。打开前会校验工具文件的 SHA-256 并再次提示设备选择风险;工具缺失或被替换时拒绝运行。进入 Zadig 后依次启用 Options → List All Devices,只选择 GCS Spectrameter,将目标驱动选为 libusb-win32,再点击 Replace Driver。不要选择键盘、鼠标、接收器、摄像头或 USB Hub。该入口不会自动识别、选择或替换驱动,最终设备选择与管理员提权仍由现场人员确认。
修改配置 打开专用 EditSpectrum 窗口。设备与连接页提供 SN、连接方式、自动连接、本地后端和串口参数,采集参数 页提供 光通量模式。本地后端和光通量模式也可在 编辑显示配置 中设置,两处共用本机显示配置。SN 旁的搜索、许可证上传和管理用于辅助配置。校准与校正、快门、ND 滤光轮和文件保存各有独立页面,底部“属性编辑”提供完整服务参数入口。
编辑页搜索复用全连接方式枚举,在后台读取设备,即使项目尚未配置 SN 或许可证清单读取失败,仍可显示本次发现的 SN 及查询来源。下拉选择或手动输入只修改编辑草稿,不自动切换驱动类型、打开连接、登记物理资源或下载许可证。上传先提交 SN 输入,只接受当前 SN 对应的 LIC / ZIP,校验后立即保存许可证并刷新状态;取消参数编辑不会撤销已单独执行的许可证操作。文件选择或导入失败在窗口底部显示原因,日志记录上传开始、保存完成及完整异常,便于区分文件窗口未打开、保存失败与状态刷新失败。
串口连接默认关闭,端口与波特率隐藏,保存和搜索时使用端口 0。开启后选择或输入 COM1~COM256,已有非零 ComPort 配置打开时自动启用串口。端口仍保存为原有数字字符串。点击确定后,设备参数保存到设备资源,本地后端与光通量模式保存在本机显示配置。只改这两个显示选项时,服务配置无需保存或重启。取消会丢弃草稿,服务参数有改动时保存仍会清理 ND 未使用的连接字段。
四色校正的单次采集
本地后端的 GetData 回执直接携带内存结果,单次采集接口使用该结果构建色度/校正数据,不再通过数据库查找 MasterId。以下历史查询行为只适用于服务回执和已存入 MySQL 的结果。
DeviceSpectrum.CaptureColorMeasurementAsync 复用现有 GetData 指令、设备状态检查、动态超时和本次 MasterId 数据库查询,一次返回原始 fPh、fx、fy、相对光谱及 fIp 峰值 AD、积分时间、ND、设备 Code、结果 ID 与时间。它与普通测量、连续测量和光谱校正共用设备测量门禁;忙碌时拒绝并发,不另发第二次采集。该色度接口拒绝光通量 / EQE 结果与非有限的 Y/x/y 或光谱值,有限负数原样保留。波长优先使用结果中的起始波长和正间隔,缺少时按点数回退 380 nm 与 0.1/1 nm。
GetRecentColorMeasurementsAsync 只读查询当前设备最近 100 条非光通量结果的摘要;LoadColorMeasurementAsync 再次按设备 Code、ID 和测量类型读取原始值及完整光谱。两者不触发硬件采集,已有结果和现场采集共用 CreateColorMeasurement 转换,不从已做亮度 / 负值裁剪的显示字符串回读数据。当前提供数据库历史选择,不解析外部 CSV / Excel。
历史结果缺少采集时间时保留未知状态,不以当前时间补齐;窗口要求核对其色块归属。峰值 AD 缺失保持 null;四色校正窗口按 AD / 65535 × 100% 检查 IP 30%~95%,非法 AD 拒绝,缺失或范围异常需复核,详见四色校正采集。
该接口只完成光谱仪的一次采集,不切换 ND、画面或外部机构。四色校正窗口负责将结果绑定到当前 R/G/B/W 样本;现场仍需核对设备连接、当前 ND、被测画面与数据库结果归属。
波长文件和幅值文件是当前标定分组的兼容镜像。属性窗口修改这两个文件时同步更新当前分组;分组窗口保存或应用分组时再把分组文件同步回这两个字段。加载已有配置时以非空的当前文件修复活动分组中的旧路径,避免 Default 分组在后续应用时恢复过期文件。切换分组窗口中的浏览选择不会在保存前改变活动分组。
启动恢复和内部回写当前活动标定分组时,下拉框只更新显示,不发送 ND 指令;延迟到初始化完成后的绑定更新也遵守此规则。
ND 已启用且光谱仪或绑定 ND 使用本地后端时,手动设置、读取和“光谱仪+ND”流程均操作实际 ND;切位前验证目标标定,读回到位后才提交位置、活动分组、波长及幅值文件。缺少绑定设备、标定缺失、定位失败或超时保留原标定并报告原因。读取位置以实际读回值同步对应标定。未启用 ND 时,本地设置、读取明确失败;选择标定分组仍可直接应用文件,不触发机械动作。启动恢复和内部标定回写不会触发切位。连续采集沿用开始时的配置快照,但每次按实际 ND 孔位选择该快照中的标定。
服务后端的分组切换沿用 ND 联动:绑定外部滤光轮时向该服务发送端口指令,否则使用光谱仪自身的 ND 指令。只有设备成功回执后才提交活动分组、文件和显示端口;发送失败、设备失败或超时时恢复原分组和端口。没有关联 ND 的分组仍直接应用。由 ND 位置回写分组属于程序内部应用,受重入保护且不会反向再发 ND 指令;一条用户切换尚未结束时也不会重复启动下一条切换。
独立 ND 滤光轮按设备 Code 将所选位置保存在客户端显示配置中;有效位置因下拉选择或设置、读取成功回执变化时,立即保存显示配置到磁盘,不依赖进程退出时统一保存。位置通过固定下拉列表选择;重新打开软件或刷新孔位映射时按 HoleIndex 恢复,不依赖下拉项的对象实例。设备已打开或连接后首次显示下拉框时均保留记录,不自动读取或移动机构。设置、读取位置成功回执会更新记录,失败或超时不以请求值覆盖记录;多台滤光轮的位置分别保存。记录用于恢复界面选择,不能代替读取真实位置。
验证边界
现场验收应核对 SDK、光谱采集、滤轮及串口动作、窗口恢复、真实 MySQL、许可证入库、驱动加载和设备扫描。
