Conoscope 图像、采集与分析
Conoscope 是 VAM/锥镜图像观察、关注点采样、色域/对比度计算与导出插件。本主题是其单一正文;源码旁 README 保留包入口和必要风险,Docs/ARCHITECTURE.md 只指向这里。
入口与运行依赖
宿主 Tool 菜单的 VAM 进入 ConoscopeWindow。文件打开、ImageEditor 右键和采集结果入口统一通过 ConoscopeDocument.CanOpenFile 检查:支持 32 位浮点 XYZ CVCIE,以及带有可重放 XYZ 校正参数的三通道 CVRAW。入口依据文件的测量能力,不受编辑器当前显示 RGB 或单通道 Y 的影响;不允许把未校正 RAW 的 RGB 当作 XYZ。模块入口负责寻找/打开窗口,单文档 View 不靠静态 Window 单例刷新业务状态。
身份和最低宿主要求读取 manifest.json,发布版本以 Conoscope.csproj 生成的 DLL FileVersion 为准。当前工程为 Windows/x64、net10.0-windows WPF,引用 Engine、ImageEditor 和 Solution;完整运行还依赖匹配的 ColorVision/cvColorVision 库、OpenCV 及所用功能的供应商运行库,不能只交付一个插件 DLL。CVCommCore.* / MQTTMessageLib.* 当前类型来源与旧独立程序集的兼容要求见 cvColorVision 命名空间与程序集,不把历史 DLL 名称当作本项目固定输出。
未打开文档时,主页显示紧凑的打开、型号和观察相机操作,工作区显示“打开数据文件”和“前往采集”入口,空文档标签栏不占位;采集、处理、分析和系统页仍可访问。打开文档后恢复主页的视图与导出分组,关闭最后一个文档后返回开始页。空工作区按整个停靠布局(包括浮动文档)判断,不以当前活动图像是否就绪判断,避免加载和切换时误回开始页。采集期间开始页入口暂时禁用并显示进度;切换工作区状态不改变用户手动折叠 Ribbon 的选择。
这里有四种不同来源:
| 来源 | 责任与前提 |
|---|---|
| 已有 CVCIE | 从本地文件读取内嵌通道;不要求相机硬件。文件格式、通道读取及版本限制见 FileIO |
| 已校正 CVRAW | 从原始像素及尾部保存的色度校正快照还原 XYZ;缓存命中时使用独立 RAW 副本,尚未落盘或仅缓存也可打开;不要求另存 CVCIE 或连接相机。只有匹配像素布局且 CanReplay=true 的三通道校正可用于完整分析 |
| Ribbon 测量采集 | ConoscopeCaptureWorkflow 调用 Engine Flow 或服务列表中的 DeviceCamera,需要对应模板/设备服务与结果记录 |
| MVS 观察相机 | MVSViewManager、MvsCaptureSession 和观察窗口管理预览/光栅;另需海康驱动及 MvCameraControl.dll,不是 Engine 测量相机的替代实现 |
打开本地文件不授权触发设备;Flow、相机采集、数据库保存和导出分别需要相应权限及现场授权。菜单出现、驱动存在或观察画面正常不证明 Engine 测量链可用。
打开 MVS 观察相机时,插件关闭各可用触发选择器的触发并读回确认连续采集,无法确认时关闭设备并显示错误。预览按实际收到的像素格式显示,设置的格式被相机拒绝时仍可使用相机当前格式。状态栏帧率来自相机的 ResultingFrameRate,图像数在实时预览接受帧后更新。空画面可用反馈日志中的触发设置、首帧、收帧错误及像素转换错误定位。
采集完成、文件发现与打开不是一个信号
ConoscopeWindow 的按钮通过 ConoscopeCaptureWorkflow 执行业务,再尝试打开结果。进度按钮的默认预期时间为 20000ms,是显示估计,不是执行超时。
| 阶段 | 当前判据 | 不代表什么 |
|---|---|---|
| Flow 返回 | ConoscopeFlowCaptureResult.Started 仅检查返回对象非空,Completed 检查 FlowStatus.Completed | 不代表已经找到测量文件,也不是原生设备安全确认 |
| 相机回包 | 等待 MsgRecordState.Success / Fail / Timeout,只有 Success 继续找文件 | 不代表文件已经落地或本地可读 |
| 找到文件 | HasFile 表示得到非空路径;查找器接受通过头部/校正能力检查的 CVCIE 或校正 CVRAW | 不证明三个通道已完整加载或最终渲染成功 |
| 窗口操作成功 | 业务成功且有文件时调用 OpenConoscope,然后将按钮操作标为成功 | 不等待文档首屏或完整 XYZ 加载 |
| 文档/显示 | 由下节事件、数据状态和 View 渲染另行完成 | 与 Flow/消息状态、按钮计时结果不同 |
Flow 路径用返回结果的 SerialNumber 查询本次批次,找不到时不使用其它批次的结果。有效批次下最多查询结果10轮,每次未找到后等待300ms;只在本批次成功的图像记录中按 Id 倒序查找第一个可用测量文件。“光谱参考校正”在 CVRAW 矩阵写回成功后追加图像记录,因此放在流程末端时会优先打开修正后的 RAW,不再选到较早的相机结果。相机路径最多查询8轮,每次未找到后等待300ms:从当前 MsgReturn.Data.MasterId 查结果,整数读取失败返回0;两条链都按 FileUrl、RawFile 顺序查找;CVRAW 先检查进程内文件缓存,命中即可使用,未命中才检查磁盘,不负责下载远端 URL。
CaptureCameraAsync 按相机配置选择单曝光或 R/G/B 三曝光,传入选中的标定参数,以及 ID 为 -1 的自动曝光/JSON 模板参数。它复用的是 Engine 相机契约,Flow 执行另见 FlowExecutionSession。
WaitForMsgRecordAsync 订阅状态事件后再次检查状态以缩小漏接终态的窗口,完成后退订;本层没有独立超时或取消参数,等待仍依赖上游进入三种终态。文件查询轮数也不包含之前的 Flow/消息等待时间。窗口关闭后的 disposed 检查可阻止继续打开结果,但不是对在途 Flow/相机请求的取消或设备停止确认。
文档加载、Y-first 例外与 Mat 所有权
ConoscopeView.OpenConoscope 清理当前显示和关注点后,以 fire-and-forget 方式调用 ConoscopeDocument.OpenAsync。Document 新请求会取消旧请求并先释放原文档数据;失败不会自动恢复上一张图。
| OpenAsync 路径 | 提交与事件 |
|---|---|
| 无需联合预处理 | 读取或从 RAW 还原 Y,完成适用的单通道处理后提交 Y,发布 InitialDisplayReady;随后顺序加载 X、Z并补齐,发布 DeferredChannelsReady |
applyPreprocess && DustRemovalEnabled | 先读 Y 但不发布首屏;读取 X/Z并联合预处理后一次提交 XYZ,只发布 InitialDisplayReady |
| 首屏前失败 | 通过 LoadFailed(exception, initialDisplayCompleted: false) 报告,View 显示打开错误 |
| Y 首屏已提交、后续 X/Z失败 | 保留已提交 Y,状态栏显示“仅 Y 可用”及重新加载入口,悬停可看错误原因;完整 XYZ 能力仍未就绪 |
InitialDisplayReady 表示对应数据已提交,不证明 WPF 渲染成功。View 收到该事件才调用 RefreshDisplayedImage;渲染异常另记录日志并提示。Document 对 Changed / LoadFailed / LoadStateChanged 逐订阅者隔离异常。状态栏跟随活动文档显示加载过程及失败状态。RetryLoadAsync 仅在失败且无在途加载时生效,保留打开时的处理参数并重读全部通道,避免将旧 Y 与磁盘上已修复或替换文件的新 X/Z 混合。重试会重置当前预览和关注点;已捕获曲线快照保留,成功后清除错误状态。加载内部捕获取消和一般异常,因此等待 OpenAsync Task 正常返回也不证明成功;调用方应结合事件及 HasDisplayData / HasXyzData,不能等待一个所有路径都会发出的 DeferredChannelsReady。
资源约束属于 Document,而不是窗口状态:
- 每个 Document 通过加载信号量串行处理请求;提交同时校验取消源身份、加载版本和取消状态,过期请求不能接管当前 Mat。它不是跨标签页的全局加载锁。
- X/Y/Z 的替换与释放由 Document 负责;View 借用引用,不另存一套生命周期。未成功提交的候选由创建路径释放。
- 联合预处理的后台委托接管 Y 后,不把令牌传给
Task.Run的调度参数,保证即使调度前取消也进入委托的清理路径;工作内部仍检查取消。 ApplyPreprocess通过ref更新 Mat,并在finally保留已替换通道;中途异常不等于整个处理已回滚。Reload是同步重读 XYZ并按配置执行非正值 clamp,不是OpenAsync的分阶段过程。DataVersion随数据变化递增;ImageCenter 色差参考随数据版本失效,避免曲线/导出逐点重复扫描同一参考 ROI。
CVCIE 仍调用 CVFileUtil.ReadCIEFileChannel 读取指定内嵌通道,不改走会跟随关联源文件的通用打开流程。CVRAW 通过 Engine 的 CalibratedRawFileReader 读取原始像素,以文件尾部 colorvision.calibration.color 快照调用原生校正逐通道还原 32 位浮点 XYZ;不依赖当前模板,不从预览 RGB 反算,不改写或另存源文件。一次加载共用同一像素和校正快照,完成或取消后释放,防止 Y 与 X/Z 来自不同版本。原生单通道计算前后检查取消;进行中的一次原生调用结束后才能响应取消。曝光信息来自校正快照。缺失、损坏、布局不匹配、不可重放或仅单通道亮度的校正拒绝用于 Conoscope;预处理和非正值 clamp 仍由 Document 按配置执行。底层格式与读取限制归 FileIO,此处不另维护二进制协议。
支持轻量检查的宿主先验证 CVRAW 文件头、校正快照和像素长度,正式加载时才映射文件或复制缓存像素。旧宿主继续使用原有的打开检查。
视图状态、通道能力与轻量 Host
每个 View 的普通语义值集中在 ConoscopeViewState:通道、伪彩、预处理、色差/对比度选择、坐标轴与可用能力。活动标签页的 Ribbon 跟随该对象;需要校验或触发渲染的操作由 View 方法完成。没有活动 View 时保留快捷区布局并禁用操作,不用控件当前值反向充当第二份业务状态。
文档停靠由 Presentation/Docking/ConoscopeDocumentLayout 处理:从完整布局树查找文档,包括分栏与浮动窗口;激活和新文档插入使用实际所属面板,重复打开按同一文档标识定位。移位和取消关闭不释放文档,只有 Closed 才释放对应 View,主窗口退出仍释放所有打开的 View。停靠外观复用共享 AvalonDock 主题资源,旧宿主缺少共享资源时回退到兼容主题,不复制维护一套共享停靠模板。
图像坐标选择、关注点工具和色阶保持悬浮在图像上的布局,避免固定工具栏压缩有效图像区。左上角只显示坐标选择框,名称由工具提示与辅助功能提供;它切换已渲染图像的坐标投影,不能复用主程序图像窗口的通道切换状态。Ribbon 按任务页组织功能组,主要操作使用图标和文字,次级操作紧凑排列;图标集中在 Presentation/ConoscopeIcons.xaml。高度随内容布局,横向滚动仅在实际超宽时出现;右上角可收起命令区,点击任务页签重新展开。直角与极坐标参考图统一从 ConoscopePlotTheme 获取背景、文字、网格和通道颜色;主题切换仅刷新参考图显示,保留当前直角图缩放范围,不重新加载图像或改动文档数值。主题事件由订阅时的发布者实例退订。
坐标网格默认使用半透明浅灰细线、12 DIP 白色描边标注和珊瑚色参考线,标注随缩放保持屏幕字号,并约束在图像边界内。已有型号保存的字号、线宽与显示开关继续生效;默认外观调整不覆盖用户配置。
通道能力由同一套检查用于显示、参考曲线及导出:Y只要求 Y;Contrast 要求 Y与同尺寸的对应参考 Y;X/Z/CIE和色差要求完整 XYZ,色差的自定义/参考图模式还需各自有效参考。衍生 Mat 生成失败不能用 Y冒充目标通道。方位、极角导出沿用当前显示通道;高级导出也须通过对应通道检查。
ConoscopeImageHost 不创建完整 ImageView,但仍拥有 DrawEditorContext、选择 visual、Zoombox 和 DrawCanvas。内部 FocusCircleEditor 管理圆形 visual、选择/绘制/擦除、菜单、边界和延迟刷新;FocusCircleInteractionMode 表达互斥交互状态。悬浮工具首个选择箭头开关控制关注点编辑:开启时按 Ctrl 拖动平移,关闭时直接拖动平移;工具提示和辅助功能名称明确该语义。
- 新文档使用
ResetDocument,清除旧关注点和编辑状态。 - 同文档换通道或伪彩使用
ReplaceDisplayedImage,在清理画布时保留关注点与交互模式。 - Host 的
Dispose幂等,退订内部事件并释放绘制/鼠标资源;Window 退订配置、参考、服务和主题事件,并释放其打开的 View。 - 鼠标捕获、缩放和绘图仍是 WPF 组合点职责;不为缩短文件而重新拆成共享状态的机械 partial,也不引入 Window/View 两份状态快照。
测量与分析使用 Document 当前 XYZ 数值,不从伪彩/缩放后的屏幕像素反算;若已经预处理,这些数值也已处理,不能把“数值计算”误写成总是原文件未处理数据。
Polar 与三种 H/V 图像坐标
图像区左上角的坐标 ComboBox 提供 Polar、H/V、North Polar 与 East Polar;这是单 View 的显示状态,不写回型号配置。后三项都是 Horizontal-Vertical 角度坐标,不是把图像像素简单改名为平面 x/y。H/V 对应 EZCom 手册所称 Azimuthal,另外两项采用不同的顺序旋转定义。
极坐标图启用「显示文字」时,从圆心 0° 沿右侧半径标到型号最大极角。VA60 默认每 10° 标到 60°,空间不足时省略部分中间标签。极坐标网格默认使用黄色描线和深色轮廓。伪彩色条叠在图像视口右下方,给右侧 0° 方位标记留出空间。左图右键「截屏」可将当前视口保存为 PNG,包含可见的坐标刻度、参考线、关注点和伪彩色条。
ConoscopeHorizontalVerticalProjection 先把源极坐标写成方向分量 x = sin(theta) cos(phi)、y = sin(theta) sin(phi)、z = cos(theta),再按目标系统计算 H/V;反算通过方向分量和 atan2 保留完整象限:
H/V (Azimuthal): H = atan2(x, z), V = atan2(y, z)
North Polar: H = atan2(x, z), V = asin(y)
East Polar: H = asin(x), V = atan2(y, z)
North inverse: x = cos(V) sin(H), y = sin(V), z = cos(V) cos(H)
East inverse: x = sin(H), y = cos(H) sin(V), z = cos(H) cos(V)
theta = atan2(sqrt(x^2 + y^2), z), phi = atan2(y, x)只有 theta <= MaxAngle 的目标像素有效,所以三种 H/V 的四角都显示为黑色;Azimuthal 与 North/East 的有效域和内部形变并不相同,North 与 East 互为不同旋转顺序而不是图片整体旋转。当前显示路径先按原始全分辨率通道确定伪彩范围,再以双线性插值生成最长边不超过 2049px 的方形预览;缓存的是当前坐标系统约 2049² 的反向映射,不复制或替换 Document 持有的全分辨率 XYZ。切换通道、伪彩和参考线复用该映射;切换坐标系统、换文件、改变 FOV/计算直径/手动系数或释放 View 时销毁并按需重建映射。
三种投影网格的横轴均为 H、纵轴均为 V。鼠标悬停先按当前系统从 H/V 位置反算源图坐标,再读取 Document 当前 XYZ,并同时显示系统名、H/V 与极角/方位角;右侧方位直径和极角圆周参考曲线仍在源 Polar 数据上采样,叠加到图上的参考线按当前系统的角度关系弯曲。
在任一 H/V 投影中,主页参考模式还提供 H、V:固定 H 是竖线,沿 V 采样;固定 V 是横线,沿 H 采样。可输入固定角度,或启用参考交互后在图像有效域内点击、拖动。切回 Polar 时恢复方位线,保留分别记录的方位角、极角及 H/V 值,不把固定角度偷换为另一种坐标。固定角输入限制在 [-MaxAngle, MaxAngle],非有限输入不改变当前值。固定 H/V 曲线用直角坐标绘制,极坐标曲线显示按钮禁用。
ConoscopeHorizontalVerticalCrossSection 以当前投影公式将每个 H/V 采样点反算至全分辨率 Polar 源图,双线性读取 XYZ,再计算所选通道。色差参考图与对比度参考图在相同源坐标双线性读取;并不先对预览伪彩图或低分辨率结果采样。实时步长为 0.1°,变化角从 -MaxAngle 到 +MaxAngle,最后一个端点始终包含;当步长不能整除范围时,最后一段较短。极角超出型号有效域、映射越出源图或所需源数值非有限时保留 NaN 断口,不夹取边缘或补零。有效性依赖型号的中心与像素/度系数,插值不是额外的镜头标定。
固定 H/V 的“导出当前”沿用步长、小数位与元数据选项,独立输出 H (degrees),V (degrees),Value,Valid,SourceX,SourceY;Valid 同时要求几何有效及通道结果有限。元数据包含源文件名、型号、投影、固定坐标、通道、单位、步长、插值方式、源几何、数据版本、实际加载/预处理参数及参考来源。它与历史方位/极角导出为不同契约。
参考曲线右上角的保留按钮冻结当时的横轴位置和通道数值;快照列表按钮打开命名、显示勾选、比较、删除与 CSV 导出窗口。ConoscopeCurveSnapshot 复制数组,只持有数值与元信息,不持有 Mat 或回调;拖动、换通道、重新预处理不改写旧快照。比较以选中快照为基准,只叠加变化角度含义(H/V 包含投影定义)与单位兼容的曲线,并提示不兼容数量。方位直径与圆周快照仍标识源 Polar 横轴,不因图像投影改变而冒充 H/V。快照 CSV 用 R 精度输出捕获的数值,不重新采样;当前截线 CSV 按所选步长重新采样并采用所选小数位。
快照由 ConoscopeWindow 的工作区持有,全部文档共享同一个列表;主页“曲线快照”入口在关闭全部图像后仍可使用。关闭快照窗口仅隐藏,关闭源文档也保留曲线及来源信息;退出工作区时,未保存修改会提示保存、放弃或取消。源文件完整路径区分同名文件,路径只是来源元信息,恢复时不读取它,也不会随源文件更新重算快照。
打开 CVCIE 或校正 CVRAW 后,选择“分析 → 亮度角分布”,在参数窗口选择物理量和可选填充区域,再点“生成对比曲线”。每次打开参数窗口默认亮度、镜像关闭;取消不提交任何设置或曲线,也不更改全局配置。默认向上述工作区追加 φ=0°、45°、90°、135° 四条方位直径截线及 360° 方位平均,选中平均曲线。分析始终读取提交参数时已加载的源 Y 缓冲(包含当时已应用的预处理),不依赖当前显示通道或预览投影;源中心、像素/度系数和型号视场随请求冻结。后台仅保留源 Y 的 OpenCV 头引用,不克隆整幅图;切换、重新处理或关闭源文档不改变已发起的分析。分析期间再次点击入口可取消,取消不追加部分结果。此入口要求半视场在 (0°, 90°];采样采用双线性插值,径向步长 0.1°,包括 0° 和精确视场端点。历史参考曲线和方位/极角导出的最近像素规则保持原样,所以新截线与旧导出之间不保证逐点相等。
360° 方位平均对每个非零半径按 1° 方位步长取 360 个样本,中心仅取一次;它不是四条截线的平均,也不是光通量积分。任一采样位置(开启镜像后使用对应参考位置)超出源图或插值邻域缺测,该半径保留 NaN,禁止边缘复制或只对剩余方位取平均。平均曲线在正负入射角上对称展示,这种显示不等于镜像填充。曲线元信息记录分析版本、源几何、采样规则、曝光与加载/预处理参数;同一请求内全部曲线共享捕获时间及来源路径。
“估算发光强度(cd)”使用 Iv = Lv × A × cosθ,假设平面发光区域内亮度近似均匀;θ 为源 Polar 入射角,使用当前 Y 亮度而非显示通道。支持圆形发光区域直径(mm,A = π × (d/2000)² m²)或直接面积(mm²,乘 10⁻⁶ 转 m²)。尺寸必须有限、正数且换算面积不溢出/下溢;这里的尺寸是实际有效发光区域,不是角度图中的亮斑尺寸,也不是仪器响应校正系数。90° 端点投影因子明确为 0,缺测仍为 NaN。固定面积缩放只改变绝对强度,在峰值归一化后抵消;cos 因子改变曲线形状和 FWHM。强度快照以 Iv / cd 标识,与 Y / cd/m² 快照分开比较。
“启用遮挡区域镜像填充”支持上→下、下→上、左→右、右→左;箭头起点为参考侧,终点为替换侧。在源亮度缩略预览的目标侧拖动框选,或输入 θx/θy 矩形范围(源 Polar 平面中向右/向上为正,单位度);默认整个目标半区,矩形须位于该半区并与圆形视场相交。橙色标记将替换的范围,蓝色虚线标记镜像参考范围;预览始终保留未填充源亮度。分析只对目标矩形与圆形视场内的射线反射采样坐标,不替换对称轴,不串联填充结果,不凭低亮度自动判断遮挡。参考位置无效则保持缺测,不回退到被遮挡值。填充基于对称假设,属于估算;开启时同时追加所选物理量的五条未填充曲线和五条镜像估算曲线,先填充采样再换算强度并计算平均,默认选中镜像平均曲线。所有派生计算不写源 Mat、源文件或原有测量;关闭选项保持默认数值采样契约。快照名称、说明、CSV 和版本 1 会话保留物理量、发光尺寸、公式、填充方向与角度范围;元信息还记录有效镜像/参考缺测射线样本数(平均曲线计完整方位采样,正负显示不重复计数)。
亮度入射角曲线(Y、cd/m²,方位直径或固定 H/V)和估算发光强度曲线(Iv、cd)显示峰值角与半高全宽 FWHM;圆周、色度和对比度曲线不计算此指标。峰值取最高有限正采样值,同高时先取最接近 0° 者,再取较小角度;不扣除基线,向两侧找包围该峰的最近 50% 交点并线性插值。选中曲线的分析参数与有效半高交点在图上方说明,交点在图中标记;缺测截断交点搜索,缺少任一交点时显示不可用及原因,多半高区域提示仅代表所选主瓣。勾选“按各曲线峰值归一化(仅显示)”可比较各自除以正峰值后的形状,没有有效正峰值的曲线跳过并提示;各快照、CSV 数值及会话文件不变,归一化开关不写入会话。
“保存会话”写入版本 1 的 .conocurves JSON 文件,保留名称、来源、捕获 UTC 时间、投影与横轴语义、通道、单位、处理元信息、完整精度位置/数值、勾选、颜色与当前选择。非有限数值以 JSON null 保存为断口,恢复为 NaN。“导入会话”先验证整份文件,再追加到当前列表,不覆盖现有曲线;重启后可从主页手动导入,不自动加载上次会话。文件上限 128 MiB、每个会话合计最多 2,000,000 个采样值,避免无界反序列化;未知版本、缺失关键字段和不等长数组会拒绝导入。保存使用同目录临时文件,成功后才替换目标。
Manual EZCom Software 第 109/111 页按线条横竖命名 Marker,第 110/112 页按固定角度命名截线;第 52 页描述跟踪,第 122–123 页明确是 VT 比较。通用命名快照是本产品的扩展,不应把这些手册章节解读成完整的通用快照生命周期定义。
边界如下:
- 三种 H/V 模式均不转换圆形关注点。存在关注点时拒绝切换,进入任一投影模式后关注点工具栏禁用;返回 Polar 后恢复。
- 现有方位、极角和高级导出仍是源 Polar 数据语义;固定 H/V 仅提供当前一条截线导出,没有 H/V 全栅格导出。
- 3D 视图仍使用源通道与 Polar 圆形掩膜,不把 H/V 预览当测量数据输入。
ConoscopeView.CreateExportContext 使用源 XYZ 的 sourceImageCenter / sourcePixelsPerDegree,不使用 H/V 预览的中心与比例。圆截面、直径截面及矩阵导出因此保持源 Polar 采样位置,不随显示投影改变。固定逗号分隔的 CSV 对角度行列头、通道值及数值元信息统一使用 InvariantCulture,不随 Windows 小数分隔符改变列结构;既有字段名、顺序和精度设置保留。
方位/极角矩阵导出逐行取样并直接写 CSV,仅保存两个角度轴和文件缓冲。采样位置由角度累加及端点容差生成,按行列顺序读取最近像素,并使用配置的数值精度写出。矩阵及当前截线导出的最小采样步长统一为 0.1°,默认仍为 1°;旧配置中的更小步长读取时提升到 0.1°,其他配置与旧字段保留,非有限步长回退到默认值。直接调用导出服务时拒绝小于 0.1° 的步长。VA60 方位/径向均为 0.1° 时为 2,161,800 个采样值。快照 CSV 保留捕获位置,不重采样。高级导出允许仅选截面,并按当前视场和所选步长显示采样值数量与估计文件大小;文件大小随数值位数变化,不是磁盘空间保证。
简单矩阵导出及高级导出的全部文件在后台串行执行;1.5 秒内完成时不显示进度窗,超过该时间才显示当前文件和采样进度并支持取消。成功自动关闭进度窗;失败仍明确显示,取消的批次保留已完成文件数量供查看。取消与失败保留已完成文件,当前文件用同目录临时文件写入,结束前不替换已有目标。原有截线导出同样使用原子写入。ConoscopeExportProgressWindow 持有导出数据直到后台任务结束,强制关闭拥有者时也先取消任务;ConoscopeExportSource 在 UI 线程保留当前原始 XYZ 和参考图的 OpenCV 引用计数头,并固定型号、几何、参考模式与参考数值。后台回调不读取 View/Config,不克隆完整 XYZ。此方式依赖已发布通道只读:预处理和参考更新必须生成新 Mat 后替换,不能原地改写被导出持有的缓冲区。
使用两个实际源文档捕获兼容曲线,关闭源文档后保存会话,再重建窗口导入并核对名称、勾选和比较结果。使用受控样本测量最小步长全量导出和多通道批次的磁盘耗时,并检查取消时既有目标文件是否保留。
- 几何精度仍受当前型号的中心、
MaxAngle与线性像素/度系数约束;CVCIE 文件本身没有在此层提供独立镜头畸变标定时,H/V 变换不能替代现场标定。
在实际样本中检查 H 竖线、V 横线、曲线跟踪、三投影切换、Polar 回退及快照窗口关闭重开。
亮度角分布验收需使用已确认型号和校正条件的样本,核对现场标定、遮挡区域、几何参数和真机采集。现场样本和验收输出留在独立目录。
配置 working copy、参考与持久化
ConoscopeConfig 持有全局默认值和型号配置;单 View 的 State 是当前文档状态。ConoscopeConfigWindow 复制可编辑设置为 working copy,预处理控件直接绑定该副本,恢复默认也只先修改副本。取消或未应用即关闭不会主动提交这些编辑。
“应用并保存”先更新绑定源并检查输入验证错误,再备份活配置、把副本复制到活配置、调用 ConfigService.Instance.Save<ConoscopeConfig>(),正常返回后设置 DialogResult = true。catch 中只在实际抛出异常时复制备份回活对象。当前 ConfigHandler.Save<T>() 丢弃 TrySave 的失败结果,因此窗口返回成功不证明落盘成功,内存通知也可能已经发出;不能宣称此窗口具有“文件与全部消费者一起回滚”的事务。完整保存机制见配置持久化。
Window 将预处理/显示属性变更合并到待执行的 Dispatcher 刷新中,再更新打开的 View;这不是同步完成所有渲染的承诺,也不表示所有 View 始终与全局默认值相同。
ConoscopeGlobalReferenceStore 独占全局色差 U/V及黑/白参考 Y Mat,保存参考文件、维护配置路径,并用 Changed 通知窗口。参考矩阵、配置文件和事件不是一笔原子事务:例如色差参考顺序写 U/V,再替换内存和保存配置;加载/删除参考文件失败有记录日志后继续的路径。不得以文件存在或通知发出单独证明全部参考已持久化、恢复或删除。
关注点模板与分析快照
关注点 ROI 计算属于插件本地 FocusPointMeasurementService,不等同于 Engine 的滤除计算;但关注点模板持久化仍复用 Engine POI 模型与 MySQL。FocusPoiTemplateRepository 承担读取/创建/保存,View 负责显示结果和错误,不自己创建数据库连接。保存先调用主表 DAO,再用独立事务删除并重插明细;明细失败回滚不包含之前的主表保存,不能宣称整份模板创建/保存原子完成。
记录 R/G/B或白/黑时,View 一次遍历当前全部关注点,从当前 XYZ求 ROI均值,构造 MeasurementCapture 并写入该窗口的 ConoscopeAnalysisSession 槽位;任一点失败不会提交这次完整槽位。它是当时的采样快照,不会随之后换图、移动圆或预处理自动重新采样。FocusPointPolarEditModel 作为编辑草稿,提交才写回圆;修改位置后若要比较同一物理区域,应重新记录相关槽位。
CanComputeGamut 只检查 R/G/B槽位和标准非空;CanComputeContrast 只检查白/黑槽位非空。实际计算的点位对应由 MeasurementCaptureAlignment.Align 决定:
- 多点快照优先取
Key交集;当前 View 用关注点名称同时生成Key和Name,不比较实际坐标。 - 单点参考可广播到多个点;全部都是单点时直接形成一组。
- 多点快照没有共同 Key但数量相同时按列表顺序对齐;否则报不匹配。存在部分共同 Key时,只计算交集,不保证输出全部已记录点。
因此槽位完整或按钮可点,不证明位置一致或所有点都被计算。色域值为样本 RGB色度三角形面积除以标准面积再乘100,不是两个色域交集面积;对比度为白场亮度除以黑场亮度,黑场必须大于0。Session 把计算异常转成结果为空和错误文本,由窗口提示;成功结果进入独立的色域/对比度结果窗口。
结果窗口可查看汇总和单关注点。当前视图的方位/极角/高级导出与分析结果 CSV由各自导出入口负责;它们不是自动附属于采集成功的副作用。变更分析字段时需同时核对结果模型、结果窗口与 CSV,不在 README再复制一份流程。
本地构建、宿主复制与发布
普通构建写本地产物。从仓库根目录使用 PowerShell。
dotnet build .\Plugins\Conoscope\Conoscope.csproj -c Release -p:Platform=x64上述项目直接构建在未提供有效 SolutionDir 时通常只保留项目输出;一旦该属性有效,两个独立 target 会写宿主:
| target | 当前副作用 |
|---|---|
导入的 PluginProject.HostCopy.targets / PostBuild | 把本次主 DLL及存在的 manifest、README、CHANGELOG同步复制到宿主 Debug和Release的 Plugins/Conoscope/,不是只写当前配置 |
Conoscope.csproj / CopyHostProjectReferences | 从 ReferenceCopyLocalPaths 筛选顶层 ProjectReference DLL(排除资源程序集),将其及存在的 PDB复制到两套宿主根目录,SkipUnchangedFiles=true |
目录根为 ColorVision/bin/x64/Debug/net10.0-windows/ 与 ColorVision/bin/x64/Release/net10.0-windows/。这会更新宿主依赖,不是完全隔离的插件构建;复制文件存在也不是完整运行依赖或交付已经验证。通用插件产物、manifest和安装边界见插件产物与交付。
只有用户明确要求发布 Conoscope 时才执行:
.\Scripts\package_plugin.bat Conoscopewrapper 会构建、校验、上传并清理本地 .cvxp;不把它当本地验证命令,不使用 --no-upload。构建成功不代表发布成功;退出结果、远端版本与可下载包属于另一层交付证据。包内 README保留平台/依赖和风险,完整正文需要匹配版本的源码仓库。
测试范围与验证缺口
在实际 CVCIE 和 CVRAW 大图上分别核对分阶段显示、XYZ 和导出,记录通道、耗时及峰值工作集。现场还需验证镜头标定、WPF 交互、Flow 批次回退、相机消息与文件时序、联合灰尘预处理失败、设置保存失败和驱动释放。真实样本只读使用。
