机器视觉系统基建设计概述
⚠ 编排产品模型：Tool / ToolFlow（请先读）
编排核心以
toolflow.md为准。
- 工具叫 Tool；容器叫 ToolFlow（工具流）。不要用 ToolBlock / 工具块作类型名。
- 心智上借用 Tool /（原 CogToolBlock）容器思路；除该心智模型外，整体设计与 VisionPro 完全不一样（架构、服务边界、实现、持久化、与 UI 关系等均为自研重建，不以复刻为设计目标，不承诺任何兼容）。
- 基建为 UI 无关的 C++ 底层服务；上层：C# 封装做显示/编辑、其它 UI 接入、以及 纯编排运行（无 UI）。
- 不接入现有 MPF_ToolBlock。原「DAG 图像流转」专题已废止（
dag-dataflow.md仅为防 404 的废止短文），勿再当历史权威或编排对照阅读。成像与显示专题（图像模型、内存、显示等）仍有效，作为 Tool / ToolFlow 所消费的像素与显示基建。
本目录是多格式机器视觉系统基建的方案入口。所有新接口、基础包和工具流契约均为目标设计/API 草案，尚未实施；现有实现仍见 ImageDisplay 总览与实现与生命周期。接口声明省略方法体和内部构造，不能作为当前库 API 直接使用。
本轮建立专题边界、导航与完善顺序，不修改源码、项目依赖、Gallery 或当前控件文档。已确认契约、待细化机制和实现证据分别记录，不能把文档完成当作功能完成。
专题索引
| 专题 | 负责的问题 | 不负责的问题 |
|---|---|---|
| Tool / ToolFlow（编排专题） | C++ Tool / ToolFlow / 终端 / 顺序 Run；多 UI 与 headless；持久化复用 | 不接入 MPF；除心智外与 VP 完全不同，不做兼容/复刻 |
| 图像模型与格式 | 图像信息、格式接口、版本、工厂和类型化临时图像 | 队列调度与 UI 生命周期 |
| 内存与访问生命周期 | 存储、引用、读写协调、初始化、pin 和真实归还 | 节点拓扑与相机业务调度 |
| （已废止）原 DAG 图像流转 | — | 已废止，见 toolflow.md；文件仅防旧书签 404 |
| 节点输出与动态调试 | 最近输出、动态连接、历史、订阅及查看者寿命 | 改写业务输出或替队列释放 |
| 相机采集与缓冲回收 | SDK 持帧/复制、入口接管、归还泵及预览解耦 | 供应商未提供的地址稳定保证 |
| 会话停止与故障 | 排空/中止、实际工作结束、外部保留及 SDK 关闭 | 强制回收仍被访问的地址 |
| ImageDisplay 集成 | 四格式显示、稳定快照、取样、回执和显示副本 | 相机启停、可靠录制和逐帧背压 |
| 使用示例 | 节点构建输出、文件/SDK、显示和深度取样 | 重复声明完整公共接口 |
| 性能与诊断 | 热路径、预算、计数、持有时长和测量口径 | 未经实测的帧率或零分配承诺 |
| 验证与完善路线 | 当前差异、开放细节、依赖顺序、退出条件和验收矩阵 | 把未完成事项写成既有能力 |
先阅读 Tool / ToolFlow（若关心编排）以及图像模型和内存生命周期；再按角色进入采集或显示。调试与会话清理同时核对，不作为实现末尾才补的功能。编排专题只认 ToolFlow；原 DAG 文已废止，勿再当权威。
系统依赖方向
flowchart LR
Camera[相机适配] --> Imaging[机器视觉 Imaging 基础包]
Flow[Tool / ToolFlow 编排核心] --> Imaging
Inspect[输出存储与调试] --> Imaging
Display[ImageDisplay] --> Imaging
Decoder[编码图像解码适配] --> Imaging
Decoder --> Loading[现有 ImageLoading 服务]
箭头表示代码依赖。Imaging 仅依赖 .NET，不引用 Avalonia、Skia、相机 SDK 或任一流程引擎。像素与显示契约见成像专题；编排与执行见 Tool / ToolFlow。
定位：图像基建、工具流与显示消费者
本方案的主体是可供相机、算法、工具流、存储与显示共同使用的多格式图像基建。图像信息、存储寿命、内容稳定性和临时读写权限分别建模，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 | 宽高、像素排列、格式和可选业务信息，不拥有像素 |
IPixelImage / IPixelImage<TPixel> / 格式接口 |
单个图像数据项；可写 handle 保留存储，稳定只读 handle 还保留相应的内容稳定性 |
ReadOnlyImage<TPixel> / WritableImage<TPixel> |
节点自行取得的具体临时图像实例，将图像信息、像素类型和访问权限绑定在一起 |
| DisplaySnapshot（内部） | 某次取得的稳定内容，持有原图读取或完整私有副本，供 UI/准备/渲染安全共享 |
| ImageDisplayUpdate | 一次设置当前图像的结果与输入释放确认，不持有算法的像素资源引用 |
图像模型、工厂与内存访问规划在 Avanti.Toolkit.MachineVision.Imaging 工程及同名命名空间，仅依赖 .NET 内存与并发能力。相机、算法、无 UI 工具流和显示已有实际复用需求，因此该包承载实际图像实现，不是空基础工程。当前只修改设计稿，不创建该工程。显示快照、更新、绘制通知、编码来源适配与渲染策略属于现有 ImageDisplay/控件集成层，相机 SDK 适配器属于宿主或对应集成包。
图像数据项、临时访问和显示更新是不同对象。同一个有效 IPixelImage 可以供多个控件或算法使用，各参与者自行申请访问；每次显示请求有独立回执。没有单查看器来源会话，也不再要求图像包装为专用显示来源。
| 包与命名空间 | 拟议类型 |
|---|---|
| 目标 Imaging 工程，Avanti.Toolkit.MachineVision.Imaging | ImageBuffer、底层 reader/writer/pin、ImageContentVersion、ImagePixelFormat、ImageInfo、IPixelImage 及泛型/格式接口、PixelImage 工厂、临时图像、Rgb24/Bgr24 |
| MachineVision，Avanti.Toolkit.MachineVision.Controls | ImageDisplay 的设置/查询成员、ImageDisplayUpdate、安装结果、输入保留策略、DepthDisplayOptions、多格式取样与绘制通知 |
ImageBuffer、图像实现、reader、writer 与 pin 由工厂或资源方法创建。ImageInfo 是调用方直接创建的信息对象：信息集中在一个类里，打开读取或写入只负责控制访问期限。
依赖方向为相机/编排核心/显示 → Imaging（及 Tool / ToolFlow C++ 核心），不能反向引用 UI。新的编排引擎即 Tool / ToolFlow（见 toolflow.md）；本概述中的成像提案仍规定像素交接边界。Imaging 不依赖 Avalonia 或某一 UI 框架。IPixelImage 不继承 Avalonia 的 IImage 或项目现有 ImageSource；文件来源类型只在解码适配层使用。现有 Shared 的 ImageLoading 服务可以继续复用，但不能成为 Imaging 的必需依赖。
契约的维护位置
类型与字段以图像模型为准；状态与访问原子性以内存文档为准；Tool / ToolFlow 编排以 toolflow.md 为准；成像句柄寿命以内存文档为准；最近结果与订阅以输出观察文档为准。显示映射不能改写基础图像语义，编排核心也不能把已发布给下游的图像句柄当作可写优化例外。
跨专题变更先更新负责该契约的正文，再同步调用者和示例。概述维护公共原则、边界与导航，不复制完整 API；专题回链本概述，旧单篇文件只保留入口链接。
逐步完善的顺序
- 基础契约收敛：锁定格式、只读发布、引用和临时访问，完成 API 最小编译验证。
- 内存机制闭环：验证初始化、失败写入、权限/取消竞争、native pin 与真实归还。
- Tool / ToolFlow MVP 闭环：落实 Tool/ToolFlow/Terminal/顺序 Run/链接校验与 headless runner（见 toolflow.md）；成像句柄交接与 image-model.md/memory-management.md 对齐。
- 持续采集与会话闭环：验证 SDK 导入/复制、归还调度、满载、停流和断线。
- 动态调试闭环：完善最近集合、空/不可用通知、订阅一致性和外部保留成本。
- 多格式显示与系统验证：接入四格式渲染与原始取样，完成负载、故障和 AOT 验收。
当前全部处于设计阶段，不仅按文档完成度推进。详细开放项与退出条件见验证与完善路线。