文件
dayu-color/research/WorkspaceTrackingAudit-20261105.md
T

9.5 KiB
原始文件 Blame 文件历史

统一工作区、共享蒙版和现有跟踪链路审计

2026-11-05,Asia/Shanghai。审计基线 b33b963;以下源码观察来自本产品,不是 Color Finale 运行证据。本文件记录本次负责的 DYToolState.h/.mm、DYMaskPanel.inc.h 和 DYSharedMaskDiagnostics.inc.h,正式构建与宿主结果由主交付记录另行补齐。

已有链路与复用接口

  • 原始固定工具身份为 base:<type>,独立层是 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警告。运行结果待主交付的正式安装自检记录;本文件不预写运行“通过”。