CVRAW / CVCIE 图像导出
原生导出将 CVRAW 原图、可重放校正参数生成的 XYZ,或旧服务 CVCIE 的选定通道写为普通图像,由 CVRawFileExporter、ExportCVCIE 和 VExportCIE 实现。它与 Copilot 批量图像工具使用不同的输出路径;批量工具的一源一图和同名编号规则不能套用到这里。专有文件解码与关联源图的读取边界见 FileIO。
使用导出窗口
在解决方案中选中存在的 .cvraw 或 .cvcie 文件,使用右键“导出”;已打开的 CV 图像也提供“导出”入口,CVRAW 命中进程内缓存即可导出,异步尚未落盘和仅缓存模式不要求源磁盘文件存在。缓存淘汰后的读取按普通缺失文件处理。窗口用于处理单个文件:
- 核对源文件、尺寸、位深与通道数。
- CVCIE 可选择 Y;三通道文件另可选择 X、Z,关联原图可读取时才显示“原图”。带有效且
CanReplay=true校正参数的 CVRAW 同样提供 CIE 通道选择,原图来自自身;单通道亮度校正只有 Y。无可重放参数的 CVRAW 只导出原图。 - 设置名称、输出目录和格式。CVRAW 原图提供 TIFF、PNG、JPEG,CVCIE 窗口提供 TIFF。选择测量通道时须使用 TIFF,若选择 PNG 或 JPEG,可取消测量通道后重试,仅导出原图。TIFF 可选 LZW 或 ZIP,PNG 使用自动压缩,JPEG 使用质量 100。
- 点击导出。工作在后台执行,期间表单和按钮禁用;成功提示后关闭窗口,异常提示后保留窗口。进度条不表示通道完成比例。
名称默认取源文件主干,可在窗口中修改。目录可新建,最近导出位置通过 recent-image-export-locations.json 保存。单个输出先在同目录编码临时文件,像素和参数写入成功后才替换目标;编码或元数据写入失败保留已有目标。没有同名覆盖确认或整组回滚;需要保留已有文件时选择新的空目录。
TIFF 中的 ColorVision 参数
TIFF 输出在标准 ImageDescription(Tag 270)中保存 ColorVision.CVImage/2 JSON;PNG 使用标准 tEXt,关键字为 ColorVision。两种容器使用相同语义,保留源类型、实际导出的 Src / X / Y / Z 通道、输入及关联文件名、CV 文件版本、行列数、位深、源通道数、NDPort、增益和曝光。存在实际执行的色度校正快照时,保存其完整参数,矩阵已包含曝光、增益等归一化因素,重放时不重复施加。文件名只保存末级名称,不写本机完整路径。CVCIE 的 Src 图使用关联原图自己的文件头参数,X/Y/Z 使用 CVCIE 参数。校正 CVRAW 的 X/Y/Z 逐通道生成 32 位浮点 TIFF,保留负值,不做显示归一化;不生成中间 CVCIE,也不改写源图。
每次原生导出从同一个已打开的源快照读取文件头、像素、校正参数和采集记录。同一次导出的多张图沿用这份记录,即使编码期间源文件更新。CVCIE 的关联原图有独立快照。可选参数尾块损坏时,仍可导出有效的原图像素。
pixelRole 区分校正输入、已计算测量通道和显示图,pixelSha256 绑定逐行紧密样本(统一 RGB 顺序、不含行填充),另校验尺寸、布局和通道身份。哈希只需行缓冲,计算成本随像素数线性增长。相同尺寸和位深不赋予重放资格。再次打开时,ImageEditor 独立解码像素和参数;可选 Engine 提供者在正式发布前验证绑定,满足条件的校正输入提供按需 XYZ/POI,已计算浮点 Y 直接测量,不再乘矩阵。X/Z 单平面只保留通道记录,不能当作完整 XYZ 或亮度测量。无需原 CVRAW 或原模板。
解析成功的参数在统一信息页以只读记录展示。兼容旧 ColorVision.CVImage/1;未知版本、坏参数、绑定不匹配或缺少 Engine 时仍可打开基础像素,但不启用测量。普通第三方图片保持原行为。PNG/TIFF 的文件身份不变为 CVCIE。图像编辑撤销测量资格并保留参数记录;RGB/XYZ 显示切换保留能力。重新打开的有效图片可以从当前内容快照导出测量原图。本地拍照在采集记录的 acquisition.opticalCenter 中保存当时有效的物理相机光心 X/Y(未翻转图像坐标);该记录与后续相机配置修改无关,旧图像缺失此项时不补写。原生导出同时带出已有的相机采集记录、光心及校正来源摘要,PNG/TIFF 再打开后在只读图像信息中显示光心;没有光心不影响像素和色度测量。通用 Save、截图和叠图输出只携带显示用途的采集/相机/校正摘要,不继承矩阵或重放绑定;通用批量处理输出不继承有效校正参数,JPEG 不携带可重放参数。
命令行导出
使用已安装、具备对应 Engine/FileIO 与 原生图像运行依赖的 ColorVision。命令会启动应用的初始化链并写输出文件,不是纯读取或独立解码器;-q 也不保证启动过程的所有错误都无弹窗。
以下是从 PowerShell 调用单个文件的参数形状。替换实际路径后才执行;自动化包装器还需设置进程超时并收集实际输出证据。
$colorVisionExe = 'C:\Program Files\ColorVision Inc\ColorVision\ColorVision.exe'
& $colorVisionExe -e 'C:\Images\sample.cvraw' -o 'C:\Exports\sample-run' -q -t tif -mx 5| 参数 | 含义与默认值 |
|---|---|
-e / --export | 一个现存 .cvraw 或 .cvcie 文件;不是目录或通配符批量入口 |
-o / --output | 输出目录,按需创建;未提供时使用源文件目录 |
-q / --quiet | 直接执行导出并退出;未提供时打开导出窗口 |
-t / --type | 精确小写 tif、png、jpg;输出后缀分别为 .tiff、.png、.jpg;省略或其它值回退 TIFF |
-mx / --mx | 当前编码器的压缩/质量值,见下表;非整数值不覆盖默认设置 |
| 编码器 | -mx 行为 |
|---|---|
| TIFF | 默认 5(LZW),8 为 ZIP;0 映射回 5,其它整数传给编码器,CLI 不限于窗口的两项 |
| PNG | 默认自动;显式值限制在 0–9。需要自动时省略参数:解析器不会把以 - 开头的下一个参数当作数值,因此不要依赖 -mx -1 |
| JPEG | 默认 100,显式值限制在 0–100 |
格式值与 Copilot 工具的 tiff / jpeg 枚举不同,-t jpeg 回退 TIFF。CVCIE 和可重放校正的 CVRAW 默认选择测量通道,静默导出使用 -t tif。传入 -t png 或 -t jpg 时,程序在写图前报告失败。普通 CVRAW 仅导出原图时支持 JPEG,输出为 8 位。
通道与输出名称
CLI 不提供自定义名称或通道选择参数。默认名称为源文件主干,默认导出原图;CVCIE 和带可重放校正参数的 CVRAW 另默认选中可用的 X、Y、Z。一次只导出一张图时直接使用 Name;一次导出多张图时,输出器将 Name 与下列通道后缀组合,再追加格式后缀。名称中即使包含点,也会保留 _Src、_X、_Y、_Z,不会让多个通道落到同一路径。
| 源内容 | 文件名示例,默认名称为 sample |
|---|---|
| CVRAW 原图 | sample.tiff |
| 三通道校正 CVRAW 原图和 XYZ | sample_Src.tiff、sample_X.tiff、sample_Y.tiff、sample_Z.tiff |
| CVCIE 三通道 | sample_X.tiff、sample_Y.tiff、sample_Z.tiff |
| CVCIE 只导出一个通道或只导出关联原图 | sample.tiff |
| CVCIE 多图并包含关联原图 | 原图另写 sample_Src.tiff |
CVCIE 导出从同一文件句柄读取选定的内嵌通道,并在多通道导出时复用一个平面缓冲。关联原图不存在或不能读取时可跳过原图,继续导出可用内嵌通道;只有一个输出成功也可能满足内部“至少导出一个图像”的条件。需要完整 X/Y/Z 或原图集合时,应逐项确认。多通道处理中发生异常不会撤销已经写出的文件,同名文件也可能已经被覆盖。
自动化的完成判据与排障
真正到达 CVRAW/CVCIE 静默分支后,SaveToTif 正常返回 0 对应进程退出码 0,捕获导出异常返回 -1 对应退出码 1。但源文件不存在、导出器分派失败或初始化异常可以先返回到 App.Application_Startup 的错误路径;该路径显示错误对话框后仍调用 Environment.Exit(0)。这是当前退出码契约的缺口。
因此,包装器应枚举明确的输入范围,默认顺序处理,每个源文件、每次运行使用独立空输出目录,并同时记录退出码、超时、非空输出与请求所需通道。-t tif 应检查 .tiff。超时、非零退出码、无输出或缺少请求通道均记为失败;保留已生成文件用于诊断,不把部分结果算作全部成功。若调用多个进程,应分别隔离输出,避免同名源文件或通道相互覆盖。
| 现象 | 检查位置 |
|---|---|
| 返回 0,没有输出或停在弹窗 | 源文件是否存在、导出器是否加载、是否真正进入静默分支;查看应用日志,不能只依赖 stdout/stderr |
| 请求 PNG/JPEG 却生成 TIFF | 检查 -t 的精确值与大小写;交互窗口的 CVCIE 格式范围另有限制 |
| 少了原图或 XYZ 通道 | 检查真实通道数、关联源图、选择项和同名覆盖;一张输出不证明整组完成 |
只找到 .tif 搜索结果为空 | 原生 TIFF 输出扩展名是 .tiff |
| 失败后目录仍有文件 | 按实际输出判断部分完成,当前路径没有原子整组提交或自动回滚 |
源码与验证
FileProcessorCVRaw.cs 负责 CLI 参数和静默退出;VExportCIE 负责名称、通道、编码与路径;ExportCVCIE.xaml.cs 负责窗口状态和提示;FileProcessorFactory.TryExportFile 与 App.Application_Startup 决定分派和上层失败语义。随包的 colorvision-batch-image-conversion 技能保留脚本执行所需的最小参数与失败规则,不能只依赖未随包交付的仓库文档。
交付验收按实际进程核对退出码、启动弹窗、超时和整组输出。只读核对无需启动导出、覆盖文件或读取现场样本。
