# 统一工作区、共享蒙版和现有跟踪链路审计 2026-11-05,Asia/Shanghai。审计基线 `b33b963`;以下源码观察来自本产品,不是 Color Finale 运行证据。本文件记录本次负责的 `DYToolState.h/.mm`、`DYMaskPanel.inc.h` 和 `DYSharedMaskDiagnostics.inc.h`,正式构建与宿主结果由主交付记录另行补齐。 ## 已有链路与复用接口 - 原始固定工具身份为 `base:`,独立层是 UUID;`DYInsertTool(document,type,afterID)` 使用 `after` 稳定锚点,不能以列表序号寻址。`DYToolManager` 代理独立 UUID 参数,不支持把 `base:type` 伪造成 UUID。固定工具需直接使用 root host manager。 - `DYToolDisplayOrder` 是界面目录与锚点树顺序。旧基础渲染的实际执行顺序保留在 `DYToolRender.inc.h` 的 `anchors`:一级、三原色、曲线、色阶、平衡、HSL、颜色分级、基础、黑白、LUT、肤色,随后蜘蛛盘和尾部工具。目录顺序与旧基础运算顺序不同;本次界面调整不能默默改写旧颜色链。 - `DYModelChanged` 通知对象是 root host。原主检查器主动调用 `synchronizeTools` 刷新子检查器。工作区直接嵌入的 `DYInspector` 必须由工作区监听 root host 再主动 `refresh`,因为原 embedded 检查器自身监听的是其 `DYToolManager`。 - `DYToolCanvasSelection`:对象 root host;userInfo `node`、`mask`、可选 `document`、`draw`、`hidden`。用于选择蒙版、切换钢笔绘制与隐藏轮廓。 - `DYToolCanvasCommand`:对象 root host;`node`、`mask`、`command=finish/cancel` 与精确 `timeValue/timeScale/timeEpoch`。 - `DYToolTrack`:对象 root host;`node`、`mask`、`direction=-2/-1/0/1/2/9`,分别反向单帧、反向、双向、正向、正向单帧、取消。 - 基线 `DYToolTrackingStatus` 回传 `node/message`,共享库应同时带mask以免两个共享对象切换后旧状态覆盖新项;面板已兼容按可选mask过滤。`DYToolCanvasState` 回传 `node/mask/drawing`。选择身份、开合和排版属于显示状态,不应额外写一次调色撤销。 ## 当前跟踪实现的真实范围 `DYToolHostMethods.inc.h` 的 `toolTrackRequested:` 在主队列宿主 action 冻结当前 UUID、完整蒙版、参考 CMTime 和方向;通过 `FxAnalysisAPI` 启动 GPU 分析。`desiredAnalysisTimeRange:` 和 `setupAnalysisForTimeRange:` 使用宿主精确帧长;`analyzeFrame:` 对连续时间逐帧复核,不以移动播放头或 320×180 LUT 预览代替实际源帧。 `toolGrayFrame:error:` 要求完整宿主 image bounds,支持源图原点、像素长宽比,限制显示比例分析图到 1280×720,不放大小图。`dyToolCapture` 在降采样前对源覆盖范围低通;颜色输入解除预乘,经显示编码形成 luma。这是分析图,调色输出保持原分辨率。 算法源码为本产品 `MaskCore/DYTracker.hpp` 与 `DYTracking.metal`:最多 300 个 Shi–Tomasi 类角点,最小间隔 10px、相对阈值 3%、亚像素细化;最多 4 层金字塔,21×21 patch,每层最多 30 次 LK 类迭代;正反光流误差 ≤1.1px;确定性 400 次三点仿射 RANSAC,3px 细化容差,至少 8 内点、52% 一致性,拒绝近线状分布。置信度综合保留比例与中值残差,低于0.3停止;另检查单步缩放、旋转、累计尺度和中心是否出画。 输出是中心、旋转、独立 X/Y 缩放;内部累计仿射包含更多自由度,但最终蒙版参数不保存完整剪切/透视,也不是非刚性逐钢笔节点描边。不能把这一实现称为 Color Finale 算法完全等价,需由独立逆向证据和对照实验另行证明。 收尾通过 `_trackingFinishing.exchange(true)` 与 generation 防重入;双向共用同一参考起点,最终只提交一次。`DYMergeTracking` 保留手工键和范围外旧轨迹。写回时检查当前完整蒙版等于冻结蒙版,避免覆盖外部编辑;正常取消、丢失与单帧结束使用 SDK `kFxError_UserCancelled` 明确结束宿主任务。单帧后先把源时间转换成时间线时间,再请求播放头移动。上述旧问题的修复不应被新 UI 绕开。 ## 本次共享对象模型 作者文档继续兼容 schema1/2;schema3 增加 `sharedMasks`,最多64个唯一蒙版对象。原 `baseMasks[type]`、`node.masks` 可混合旧完整蒙版与单字段引用 `{sharedID: UUID}`,维持组合顺序。同一共享对象可以被多个模块引用,单模块禁止重复引用;悬空引用、引用夹带字段、重复真实 UUID 均拒绝。每模块16项、单蒙版16384键、全作者65536键与24MiB上限保留;全作者键数对共享对象只计一次。 `DYMasksForTool(document,nodeID)` 返回解引用对象本身。可变文档中,两个模块返回的是同一个可变共享字典;画布草稿提交、数字编辑、跟踪写回修改这一个对象,因此所有关联模块同步。特殊 `nodeID=@"shared"` 直接选择共享库,支持先画蒙版再指定模块。 新增函数: | 接口 | 行为 | | --- | --- | | `DYSharedMasks` / `DYSharedMaskWithID` | 读取全局库及唯一对象 | | `DYAddSharedMask` | 新建未关联共享对象,返回实际库中字典 | | `DYSetSharedMaskAssigned` | 给 `base:type` 或 UUID 增删引用,解除单层不删除对象 | | `DYToolIDsForSharedMask` | 列出所有关联工具身份 | | `DYRemoveSharedMask` | 删除对象及所有引用,保留工具层 | | `DYShareToolMask` | 将旧独立蒙版提升成唯一共享对象,保留原UUID与全部数据 | | `DYResolvedToolDocument` | 一次性展开为临时schema2渲染文档,单引用确定性UUID;不供编辑 | | `DYToolRenderSnapshot` | 先展开、再按指定CMTime求值;所有渲染副本删除轨迹作者键 | 渲染副本的 `sourceSharedID` 保留源身份。确定性临时UUID由共享ID与工具ID派生,以满足旧schema2全局UUID唯一校验,并使快照及缓存稳定;它不是另一个作者蒙版。没有时间参数的 `DYResolvedToolDocument` 清空展开共享副本的keys,与既有直接渲染读取基础参数的行为一致;有时间的宿主渲染必须经过 `DYToolRenderSnapshot`。 ## 外部必须适配的位置 以下为基线文件/方法位置,后续行号随编辑变化;检索键可用 `rg 'baseMasks|\[@"masks"\]' '大鱼调色/Plugin'`: | 文件与基线行 | 原读取 | 必要适配 | | --- | --- | --- | | `DYToolHostMethods.inc.h:11` `adoptToolCanvasDocument:` | 直接遍历baseMasks/node.masks寻找启用对象 | 使用 `DYMasksForTool`,并包括全局共享库;已有所选共享节点应保持 | | 同文件`:24` `toolMask:node:document:` | 已使用DYMasksForTool | 无需改为复制对象;此处必须返回可变文档真实对象 | | 同文件`:28` `toolCanvasSelection:` | 所选node改变即取消并丢弃跟踪 | 从关联层切到shared库是相同蒙版但node变化;可保守取消,若要求跨入口不中断,比较唯一共享ID而非仅node | | `DYToolCanvasEditing.inc.h` 画布添加种类 | 直接DYNewMask并加入层列表 | 新全局入口用DYAddSharedMask;可选模块用DYSetSharedMaskAssigned关联 | | `DYInspector.mm:858` `refresh` | 直接baseMasks数量判断可见 | 引用数组本身仍有数量,但详情/显示蒙版名称必须解引用 | | `DYToolRender.inc.h:44` `renderToolsSource:...` | baseMasks及node.masks传Metal | 先验证作者文档,再DYResolvedToolDocument;正常pluginState已为展开快照 | | 同文件`:101` `exportLUT:...tools:` | 引用数组count用于拒绝空间导出 | 只拒绝实际关联蒙版;未分配的全局库不影响画面、不必阻止Cube | | `DYPrimaryRender.inc.h`、`DYManagedRender.inc.h` 主render方法 | 固定一级/film及附加层直接取masks | 入门先验证作者,再展开引用;不要把refs传给maskBuffer读取parameters | | `DYPlugIn.mm:33` `pluginState` | DYToolRenderSnapshot | 已由本次共享模型统一解决,无需另外复制作者对象 | ## 紧凑蒙版编辑器 `DYToolMaskPanel` 实现 `DYWorkspaceMaskEditing`,公开 `workspaceMode`、`contentHeight`、`selectedMaskID`、`refreshWithDocument:time:`、`addMenu:` 和 `selectMaskID:`。workspaceMode在≥560pt宽时把参数网格与跟踪操作分为两列,860pt以上单行头部;600–1200pt宽适应,低高度交由外层滚动容器。窄检查器保留原有竖排尺寸;小于560pt时contentHeight也返回完整竖排高度,实际377pt编辑列不会因误用多列高度截掉跟踪区域。`contentHeight` 按当前宽度动态返回,外层应先设宽、再读取高度、再设置文档视图高度。 选中同一个、已经活跃的蒙版不会重发canvas选择,不会在每次刷新时取消钢笔草稿;首次选中默认首项仍激活画布。空库清空旧maskID,避免保留已删除对象。shared模式的删除提示包含全部关联,操作仍走既有单次Undo宿主写入。此面板不单独复制跟踪算法或作者状态。 ## 验证范围 新增 `DYSharedMaskDiagnostics.inc.h`:先画后关联、两模块同一对象、编辑与轨迹同步、安全归档、确定性独立渲染绑定、悬空/重复/伪复制拒绝、单层解除和全局删除、旧蒙版提升、64库/16引用独立上限、共享键预算只计一次,以及六种蒙版在377/600/860/1200pt布局内的可见控件边界与交叠。`DYToolState.mm`、包含新面板的 `DYInspector.mm`、包含新诊断的 `DYDiagnostics.mm` 已通过本机clang语法检查,只有既存弃用和动态probe警告。运行结果待主交付的正式安装自检记录;本文件不预写运行“通过”。