Vyntek 机器视觉设计概述
www 工作副本 · M1+M2+M3+M4（Arden · 2026-10-21 Asia/Shanghai）
双轨：本页已迁入 Vyntekwww；mvdocs.treeden.app 仍在线作权威对照，直至 Vernon 下线。已迁 toolflow、host-integration、imaging/memory/session、M4、M5 显示。完整 test-contracts 与 M6 场景/验证仍外链 mvdocs。示例入口见 examples。
实现边界：公开头为嵌套子树 + CM1 便利伞头。采集 / 会话 / 显示对拍 tipe46c042（见 design-map）。多数 NON-STABLE ABI / STUB——有声明 ≠ 验收完成。
对照：迁移盘点 · 规格对照 · API 摘录 · 预览 http://127.0.0.1:8792
⚠ 编排产品模型：Tool / ToolFlow（请先读）
编排核心以 toolflow.md 为准（对照站 mvdocs 仍在线）。
- 工具叫 Tool；容器叫 ToolFlow（工具流）。不要用 ToolBlock / 工具块作类型名。
- 心智上借用 Tool /（原 CogToolBlock）容器思路；除该心智模型外，整体设计与 VisionPro 完全不一样（架构、服务边界、实现、持久化、与 UI 关系等均为自研重建，不以复刻为设计目标，不承诺任何兼容）。
- 基建为 UI 无关的 C++ 底层服务；上层：C# 封装做显示/编辑、其它 UI 接入、以及 纯编排运行（无 UI）。
- 不接入现有 MPF_ToolBlock。原「DAG 图像流转」专题已废止并移除独立文件，勿再当历史权威或编排对照阅读；编排只读 toolflow.md。
成像与显示专题（图像模型、内存、显示等）仍有效，作为 Tool / ToolFlow 所消费的像素与显示基建。
本目录是 Vyntek 多格式机器视觉设计系统的方案入口。契约正文仍是目标设计权威；公开头已在本仓落地（见 cpp-headers），核心语义已实现（编排 Run/Link/Validate、.avtf Load/Save、采集停流与归还泵、成像句柄与内存协调），但真实算法仍 stub、且不可当作已验收能力。显示规格见本站 image-display；可选宿主对照见 控件总览。接口声明省略方法体和内部构造，不能作为当前库 API 直接使用。
语言 / 示例定调：编排与成像核心示例为 C++（命名空间 vyntek::toolflow / vyntek::imaging，示意非已发布 ABI）；ImageDisplay 为 C# 封装（UI/显示层；勿把显示示例写成 C++ UI）。细则与篱笆约定见 examples.md（T12）。头文件与打包库名（T14：libvyntek_toolflow / libvyntek_imaging，MVP 无稳定 ABI）见 cpp-headers.md；R5 伪树见 sketch/README.md（示意实现对照，不可编译）；托管绑定细则见 csharp-binding.md（T11）；宿主同核与示意 C 导出见 host-integration.md（R7，编排波未迁）。开放风险只登记见 validation-and-roadmap.md（T15）；R8 术语终检与角色路径见 glossary.md / 下文「角色化 ~10 分钟路径」。
本轮建立专题边界、导航与完善顺序，不修改源码、项目依赖、Gallery 或当前控件文档。已确认契约、待细化机制和实现证据分别记录，不能把文档完成当作功能完成。
专题索引
| 专题 | 负责的问题 | 不负责的问题 |
|---|---|---|
| Tool / ToolFlow（编排专题） | C++ Tool / ToolFlow / 终端 / 顺序 Run；多 UI 与 headless；持久化复用；§3.4 句柄交接对照；§7.6 Tool 作者契约与 fake 替身 | 不接入 MPF；除心智外与 VP 完全不同，不做兼容/复刻 |
| C++ 头文件与模块边界 | 公开 include 树、vyntek::toolflow / vyntek::imaging、TypeDesc、公开头 vs detail/、与 ImageDisplay（仅 C#）分界；MVP 绑定 PInvoke；T14 库名 libvyntek_toolflow / libvyntek_imaging（无稳定 ABI） | 不替代 toolflow 执行语义正文；不写第二套 Imaging；不写完整 CMake |
| C# 适配 / 绑定 | MVP PInvoke；opaque handle + Release/Dispose；ImageDisplay 经绑定消费句柄 | C++/CLI 非默认；不写第二套执行/成像；不写 C++ UI |
| 宿主集成契约 | R7：headless / C# 显示宿主同核；示意 vyntek_toolflow_* / vyntek_imaging_* 导出；停止矩阵宿主侧分派；PInvoke 边界 | 不改 v1.9 语义/码表；无稳定 ABI；无 CMake；不写 C++ UI / 编辑 UI / IPC |
| 图像模型与格式 | 图像信息、格式接口、版本、工厂和类型化临时图像（C++ 示意） | 队列调度与 UI 生命周期 |
| 内存与访问生命周期 | 存储、引用、读写协调、初始化、pin 和真实归还；可勾选 TC-MEM-* / S12（Arden · R11） | ToolFlow 编排与相机业务调度 |
| 工具输出与动态调试 | 最近输出、集合事件（空快照/Unavailable/Evicted）、动态连接、历史、订阅及查看者寿命；观察不驱动 Run；可勾选 TC-OUT-* / S10（Arden · R9） | 改写业务输出或替队列释放 |
| 相机采集与缓冲回收 | SDK 持帧/复制、入口接管、归还泵及预览解耦；可勾选 TC-ACQ-* / S11（Arden · R10） | 供应商未提供的地址稳定保证 |
| 会话停止与故障 | 排空/中止、实际工作结束、外部保留及 SDK 关闭；可勾选 TC-SESS-* / S11（Arden · R10；薄摘 TC-SESS） | 强制回收仍被访问的地址 |
| ImageDisplay 集成 | 四格式显示、稳定快照、取样、回执和显示副本（C# 封装；像素来自 C++ 句柄）；可勾选 TC-DISP-* / S13（Arden · R12） | 相机启停、可靠录制和逐帧背压；勿写 C++ UI（≠ T15 R10） |
| 使用示例 | 编排/成像核心（C++）；ImageDisplay（C#）；语言分工见文首 T12 | 重复声明完整公共接口；勿改显示示例为 C++ UI |
| 示例场景规划 | 成体系场景目录（S01–S08；R6 S09a–d；Arden · R9 S10 输出观察；Arden · R10 S11 采集/会话；Arden · R11 S12 存储/pin；Arden · R12 S13 显示集成）+ 代表性骨架；主路径与 §10.1 / Diagnostic / fake / TC-OUT-* / TC-ACQ-* / TC-SESS-* / TC-MEM-* / TC-DISP-* 对照 | 不替代 examples 契约片段；不写第二执行引擎或 C++ UI |
| 测试契约表 | R4 MVP 可勾选契约：前置·动作·期望 code/状态·章节；§10.1 / H1–H10 / Diagnostic / S01–S13（含 R6；Arden · R9–R12）；Arden · R13 与 toolflow §10.1 T13 索引对齐 | 不写覆盖率 KPI；不替代 toolflow 语义正文；不混 MPF/DAG |
| 伪仓库树（sketch） | R5 最小可看见树：公开头路径 + fake_acq / Load .avtf / headless 碎片；与 cpp-headers 对齐 | 不可编译；无稳定 ABI；不写 CMake；非验收正文（对照 test-contracts / examples-scenarios） |
| 性能与诊断 | 热路径、预算、计数、持有时长和测量口径 | 未经实测的帧率或零分配承诺 |
| 术语终检表 | R8：Tool / ToolFlow / ToolId / TypeDesc / DiagnosticCode / .avtf / PixelImageHandle / Access·ReadOnly / Adopt·Release / 同核；Arden R4–R13 vs T15 风险 R1–R10 撞号（含 Arden · R9 ≠ 编辑 UI；Arden · R10 ≠ C++ UI·已关闭；Arden · R11/R12/R13 ≠ 任何 T15 同号——T15 无 R11/R12/R13；Arden · R12 显示仅 C# ≠ T15 R10）；禁混词 | 不改语义/码表；不另立执行模型 |
| 验证与完善路线 | 当前差异、开放细节、依赖顺序、退出条件、验收矩阵；T15 开放风险登记；Arden · R13 本批横切收束（文档侧 B–F 已收口，除阶段 A） | 把未完成事项写成既有能力；不把登记项当本轮交付 |
先阅读 Tool / ToolFlow（若关心编排）以及图像模型和内存生命周期；再按角色进入采集或显示。调试与会话清理同时核对，不作为实现末尾才补的功能。编排专题只认 ToolFlow；原 DAG 专题已废止并移除文件，勿再当权威。
角色化 ~10 分钟路径（R8）
按角色选一条短路径即可；细节仍以各专文为准。术语终检见 glossary.md。
| 角色 | ~10 分钟读序 | 立刻点到 |
|---|---|---|
| 编排作者 | toolflow.md §2–§4 → §3.4 句柄交接 → §7.6 作者/fake → test-contracts.md 对应 TC-* → 场景 S08 / S09 | Tool / ToolFlow / TypeDesc / DiagnosticCode / .avtf；勿 ToolBlock/DAG |
| Headless 宿主 | host-integration.md §1–§2 → toolflow §7.2 / §7.4.3 停止矩阵 → S07 headless 段 → sketch headless_main → TC-RUN-04 / TC-SER-01 | 同核；示意 vyntek_toolflow_*（非稳定 ABI）；无 UI |
| C# 显示宿主 | host-integration §1 / §3–§4 → csharp-binding.md → image-display（仅 C#）→ S07 / S13 显示段 → sketch ImageDisplayHost → TC-CTL-05 / TC-DISP-*（Arden · R12） | PInvoke；Adopt·Release / Dispose；UI 只消费投影；观察不驱动 Run；显示契约仅 C#（≠ T15 R10） |
| 成像消费者 | image-model.md + memory-management.md → toolflow §3.4 H1–H10 → S05 / S12 → TC-MEM 摘录（§10 · Arden · R11；全文 test-contracts 仍 mvdocs） → cpp-headers.md imaging 头 | PixelImageHandle；Access·ReadOnly；权威在 C++ vyntek::imaging（禁止「仅依赖 .NET」） |
四条路径共用：overview 专题索引 · glossary.md · toolflow v1.9 · validation-and-roadmap.md（T15 风险与 Arden 撞号）。
系统依赖方向
flowchart LR
Camera[相机适配] --> Imaging["C++ vyntek::imaging 像素/句柄权威"]
Flow[Tool / ToolFlow 编排核心] --> Imaging
Inspect[输出存储与调试] --> Imaging
Display[ImageDisplay C#] --> Imaging
Decoder[编码图像解码适配] --> Imaging
Decoder --> Loading[现有 ImageLoading 服务]箭头表示代码依赖。像素/句柄基建权威在 C++ vyntek::imaging；不引用 Avalonia、Skia、相机 SDK 或任一流程引擎。.NET/C# 仅为绑定/显示投影（含 ImageDisplay），不是第二套 Imaging 核心，也不存在「Imaging 仅依赖 .NET」的表述。像素与显示契约见成像专题；编排与执行见 Tool / ToolFlow；头文件见 cpp-headers.md。
定位：图像基建、工具流与显示消费者
本方案的主体是可供相机、算法、工具流、存储与显示共同使用的多格式图像基建。图像信息、存储寿命、内容稳定性和临时读写权限分别建模，ImageDisplay 是其中一个只读消费者。图像基建必须可在没有 Avalonia、Skia、窗口或 UI dispatcher 的进程中使用。
基础不变量：每份资源有明确所有者；工具流内交给下游的图像句柄保持内容稳定（只读语义，见成像/内存专题，不称 DAG 边）；共享读取允许并行，工具只对自有未发布输出独占写入；每次队列接受、拒绝、丢弃、取消和停止都有释放责任；SDK 只在实际使用结束后归还。锁保护字节访问，所有权协议保护流程语义，二者不能互相代替。
Tool / ToolFlow见 toolflow.md：工具流（或组）内自上而下顺序 Run + 终端链接；心智借用 Tool /（原 CogToolBlock）容器思路，除该心智外与 VisionPro 完全不同，由自研 C++ 核心承载。图像句柄的格式与寿命仍遵循成像/内存专题。工具不得通过别名或 native 指针绕过成像包的访问契约；变换创建新输出或显式复制后再作为稳定结果交给下游。
ImageDisplay 的职责是显示当前静态图像。文件、内存像素和算法输出均为一次独立的图像内容；所谓图像流显示，是宿主持续提交新的静态图像来更新当前显示。
控件不建立连续帧会话，不检查采集帧号递增，不保证每次提交都实际绘制，也不通过等待绘制来控制生产速度。采集调度、处理顺序、可靠录制、预览节流和选择哪张图像提交由宿主负责。
图像业务编号和采集时间均为可选元数据。相同编号、较小编号、较早时间、历史图像或同一图像的再次提交都合法。控件按请求的先后更新期望内容，不以元数据大小决定新旧。
本提案统一规划 Gray8、RGB24、BGR24 与 Depth16 的图像接口、显示、取样和内存寿命，保留托管/native 内存导入、共享读取、独占写入、ROI、负步长、SDK 归还和按需保存显示副本。四种格式均属于目标显示能力，分阶段实施时单独报告进度。GPU-only、动态 map/unmap、跨进程图像和设备 fence 不在本轮接口中。
存储、图像与显示更新
| 概念 | 责任与寿命 |
|---|---|
| ImageBuffer | 底层分配的身份、可访问容量、保留成本、访问协调和最终归还 |
| ImagePixelReader / ImagePixelWriter | 有效期内的读权限或整份分配的独占写权限 |
| ImageBufferPin | native 算法使用稳定地址期间独立保留资源与访问权 |
| ImageInfo | 宽高、像素排列、格式和可选业务信息，不拥有像素 |
PixelImageHandle / 格式特化句柄（C++ vyntek::imaging） | 权威图像数据项；可写 handle 保留存储，稳定只读 handle 还保留内容稳定性 |
IPixelImage / IPixelImage<TPixel>（C# 绑定投影） | 对上述 C++ 句柄的托管投影；非第二套语义；仅绑定/显示层使用 |
ReadOnlyView / WritableView（C++）；绑定层可有同名投影 | 工具自行取得的临时访问视图，将图像信息、像素类型和访问权限绑定在一起 |
| DisplaySnapshot（内部） | 某次取得的稳定内容，持有原图读取或完整私有副本，供 UI/准备/渲染安全共享 |
| ImageDisplayUpdate | 一次设置当前图像的结果与输入释放确认，不持有算法的像素资源引用 |
图像模型、工厂与内存访问的权威在 C++ vyntek::imaging（公开头 <vyntek/imaging/...>），见 cpp-headers.md 与 image-model / memory 专题。.NET/C# 仅为绑定/显示投影（如可选包 Vyntek.Imaging 将句柄投影为 IPixelImage 等）；禁止把 Imaging 写成「仅依赖 .NET」或第二套像素真相。相机、算法、无 UI 工具流和显示共同消费同一 C++ 句柄模型。当前只修改设计稿，不创建工程。显示快照、更新、绘制通知与渲染策略属于现有 ImageDisplay（C# 封装）/控件集成层；相机 SDK 适配器属于宿主或对应集成包。MVP 托管绑定 = PInvoke（C++/CLI 非默认）；细则见 csharp-binding.md。
图像数据项、临时访问和显示更新是不同对象。同一个有效句柄（C++ PixelImageHandle，或经绑定投影的 IPixelImage）可以供多个控件或算法使用，各参与者自行申请访问；每次显示请求有独立回执。没有单查看器来源会话，也不再要求图像包装为专用显示来源。
| 层 / 命名空间 | 拟议类型 |
|---|---|
C++ 核心 vyntek::imaging（公开头 <vyntek/imaging/...>） | ImageBuffer、reader/writer/pin、ImageContentVersion、PixelFormat、ImageInfo、句柄与格式特化、PixelImage 工厂、临时视图、Rgb24/Bgr24 |
C++ 核心 vyntek::toolflow（公开头 <vyntek/toolflow/...>） | Tool、ToolFlow、Terminal、Link、RunSession、Registry、.avtf 序列化 |
| 绑定投影 Vyntek.Imaging（.NET，可选；PInvoke，见 csharp-binding.md） | 对 C++ 句柄的托管投影（IPixelImage 等）；opaque handle + Dispose；非 Imaging 权威、非第二套语义 |
| C# 封装 MachineVision.Controls | ImageDisplay 的设置/查询、ImageDisplayUpdate、保留策略、DepthDisplayOptions、取样与绘制通知 |
ImageBuffer、图像实现、reader、writer 与 pin 由工厂或资源方法创建。ImageInfo 是调用方直接创建的信息对象：信息集中在一个类里，打开读取或写入只负责控制访问期限。
依赖方向为相机/编排核心/显示 → C++ vyntek::imaging 句柄（及 Tool / ToolFlow C++ 核心 vyntek::toolflow），不能反向引用 UI。新的编排引擎即 Tool / ToolFlow（见 toolflow.md）；头文件边界见 cpp-headers.md。成像核心不依赖 Avalonia、.NET 或某一 UI 框架。托管投影中的 IPixelImage 不继承 Avalonia 的 IImage 或项目现有 ImageSource；文件来源类型只在解码适配层使用。现有 Shared 的 ImageLoading 可继续作控件侧解码，但不能成为 C++ 成像核心的必需依赖。
契约的维护位置
类型与字段以图像模型为准；状态与访问原子性以内存文档为准；Tool / ToolFlow 编排以 toolflow.md 为准（句柄交接可测对照见该文 §3.4；作者/注册/fake 见 §7.6）；成像句柄寿命以内存文档为准；最近结果与订阅以输出观察文档为准。显示映射不能改写基础图像语义，编排核心也不能把已发布给下游的图像句柄当作可写优化例外。
跨专题变更先更新负责该契约的正文，再同步调用者和示例。概述维护公共原则、边界与导航，不复制完整 API；专题回链本概述，旧单篇文件只保留入口链接。
逐步完善的顺序
- 基础契约收敛：锁定格式、只读发布、引用和临时访问，完成 API 最小编译验证。
- 内存机制闭环：验证初始化、失败写入、权限/取消竞争、native pin 与真实归还；可勾选见 Arden · R11（TC-MEM-* / S12）。
- Tool / ToolFlow MVP 闭环：落实 Tool/ToolFlow/Terminal/顺序 Run/链接校验、
.avtf读写与 headless runner；退出条件见 toolflow.md §10.1（可勾选单测/headless）；公开头与模块边界见 cpp-headers.md；成像句柄交接与 image-model.md/memory-management.md 对齐（权威均在 C++；对照表见 toolflow §3.4）；Tool 作者最小契约与 fake 替身见 §7.6。脚本、产线 IO、编辑 UI 不阻塞本步。 - 持续采集与会话闭环：验证 SDK 导入/复制、归还调度、满载、停流和断线；可勾选见 Arden · R10（TC-ACQ-* / TC-SESS-* / S11）。
- 动态调试闭环：最近集合事件（T10：
EmptySnapshot/Unavailable/Evicted）、订阅一致性和外部保留成本；观察永不驱动 Run；可勾选见 Arden · R9（TC-OUT-* / S10）。 - 多格式显示与系统验证：接入四格式渲染与原始取样，完成负载、故障和 AOT 验收；文档侧可勾选见 Arden · R12（TC-DISP-* / S13；仅 C#；≠ T15 R10）。
- 本批横切收束（Arden · R13）：toolflow §10.1 T13 阶段索引对齐 OUT/ACQ/SESS/MEM/DISP + S10–S13；validation / glossary / sketch 薄回链；文档侧阶段 B–F（及编排契约索引）已收口，除阶段 A 模型契约；实现证据另册。不自动开下一批；T15 无 R13。
当前全部处于设计阶段，不仅按文档完成度推进。详细开放项与退出条件见验证与完善路线。
文档状态：设计草案（2026-10-21，Asia/Shanghai）。编排权威 toolflow v1.9；Imaging 权威 C++ vyntek::imaging；ImageDisplay 仅 C#；场景见 examples-scenarios.md（含 R6 S09；Arden · R9 S10；Arden · R10 S11；Arden · R11 S12；Arden · R12 S13）；R4 契约表见 test-contracts.md；R5 伪树见 sketch/README.md；R7 宿主集成见 host-integration.md；R8 导读/术语终检见本文角色路径 + glossary.md；Arden · R13 本批横切收束（文档侧 B–F 已收口，除阶段 A；T15 无 R13）。