文件
dayu-color/research/MaskTrackingAndToolStack.md
T

11 KiB

续作方案:工具实例、蒙版与跟踪

2026-11-01。这是下一阶段方案,尚未实现。 用户明确要增加蒙版、跟踪和可添加工具,并举例“一层 HSL 不够,再加一个 HSL”。本文的具体类型、按钮和实施顺序为建议,不把参考库现有全部功能自动扩为新产品的承诺。

一、先解决多个 HSL 的身份和执行问题

当前固定 HSL 在 DYModel.mm 注册,使用 DYUniforms 的一组 hsl* 字段,DYColorTables.mm 构造一份 24 参数 HSL 查表。DYGrade.metal 调用融合的 dy_grade,蜘蛛盘随后执行。CST 位于原有显示域调色链之前。

推荐为可添加工具建立统一实例模型;先开放 HSL,一旦成立再扩展支持的类型。一个实例至少保存稳定 UUID、工具类型及版本、名称、启用状态、混合强度、独立参数和其蒙版引用;作者文档保存有序实例列表。显示名称和列表位置都不能代替身份。

界面最小闭环:添加工具 → HSL → 出现第二张独立 HSL 卡片 → 调整各自参数 → 单独启停/折叠 → 保存重开仍互不覆盖。复制、删除、重命名、排序是适合此模型的后续操作建议;若本阶段提供,均须使用同一作者状态和单次宿主撤销。

折叠只写 folds[nodeID] 一类界面状态,眼睛写实例启用;不能共用现有 folds["hsl"]。所有控件回调、异步加载、选中目标和 Undo 都绑定 nodeID + 参数键,不能绑定可能因插入/删除变化的数组下标。

渲染与旧参数的适配

先写清工具顺序和每个阶段的颜色域。保持 CST 输入/一级/输出的现有全局前段;新增 HSL 不应再执行一次 CST 或其它全局调整。当前固定链有融合内核,不能为每个工具直接重复调用整个 renderSource,否则会重复曝光、LUT、统计或空间处理。

原固定 HSL 可用稳定的兼容实例映射到原参数 ID,以保留旧工程和已有宿主动画;新增 HSL 必须有自己的参数存储与缓存。若需要将原链拆成可重排阶段,先做旧路径与拆分路径数值回归,再让新文档使用新计划。若先采用附加工具段,也必须在界面和文档明确其实际执行位置,不能让 UI 顺序与渲染顺序不同。

无新增状态的旧工程必须沿用原路径;显式迁移后记录格式版本,避免同一 HSL 同时从旧融合链和新实例链执行两次。旧参数 ID、枚举值、944 字节 ABI 前缀不能重排。新工具使用中性参数时应直通;关闭工具、混合为零或空新增列表应恢复原结果。

每个实例的查表/中间纹理缓存至少按 device、类型、完整有效参数和相关域信息隔离。第一层调值不能污染第二层。建立完整帧/分块、半透明、负值/HDR、重排以及连续多实例的检查,不把“面板能多开”当成多工具渲染已完成。

二、作者状态、动画和预设先定合同

本项目现有 DYAssetState 在参数 9001,标志含 NOT_ANIMATABLE。可以保留它存 LUT/蜘蛛盘资源;若新增工具参数需要宿主关键帧,须另行选择可动画的参数方案或明确时间化作者状态,不能直接塞入 9001 后默认为支持关键帧。

需区分:宿主可动画参数、工具/蒙版作者数据、逐帧求值后的不可变渲染计划,以及可丢弃缓存。轨迹作者数据随工程保存,运行计划按给定 CMTime 求值,不能由 UI 当前播放头或可变全局选择决定渲染。

所有新增类型应覆盖 NSSecureCoding 白名单、copy、isEqual、hash、验证、资源路径、预设、宿主归档和渲染状态。当前 InspectorToken schema 2、预设 JSON v3、临时 render-state schema 1 分属不同格式。不要用一次任意“schema++”代替各格式的明确迁移。

对新数据设置数量/大小/嵌套上限,验证有限数值、合法工具类型、UUID 唯一和引用完整性。失败加载保持旧作者文档;不加载任意类。必要时为当前插件增加明确文档格式,而不是依赖不可版本化的 UI 对象。

三、把蒙版绑定到工具实例

建议先移植矩形、椭圆和闭合钢笔;羽化、反转、强度和组合规则应有明确数学定义。其它 HSL/亮度键、人物或外部蒙版只作为父库的后续候选,未获本轮逐项指定。

每个工具保存自己的蒙版列表和当前蒙版 ID。首阶段优先正常混合:output = mix(toolInput, toolResult, clamp(maskCoverage * toolOpacity, 0, 1))。多蒙版的加/减/交集顺序、无蒙版的覆盖语义、空路径和禁用蒙版的含义须先确定并测试。不要用一个全局蒙版同时影响所有 HSL。

CPU、Metal、预览和 OSC 共用坐标合同:源图/目的图范围、宿主 tile bounds、top/bottom origin、非方形像素、缩放/旋转及视图变换都要处理。计算蒙版不能依赖检查器或浏览器尺寸。保留 alpha,明确直通 RGB 与预乘 RGB 的转换和混合边界。

画面控件通过宿主的 OSC 机制绘制,使用当前效果实例和稳定工具/蒙版 ID 隔离。点击效果标题、开关显示控件、关闭工具窗口后是否保留轮廓等行为在正式 FCP 中验证。不要自建一张静帧预览来冒充宿主当前画面的编辑和跟踪。

四、跟踪移植的范围与易错点

父库正式68采用 Metal 图像金字塔/正反光流与确定性 RANSAC,输出位置、旋转和独立横纵缩放。其输出合同不包括透视/剪切。建议复用前向、后向、同参考帧双向和前后单帧;连续范围、单帧参考区间、取消行为均按精确帧长定义,不猜帧率。

从宿主分析接口取得实际源帧。当前 lookLUTPreview 只是 320×180 预览,不足以替代最终跟踪输入;也不能靠拖动播放头或缓存最后一帧伪造完整分析。需要检查、实现并验证 FxAnalyzer / FxAnalysisAPI 生命周期和真实帧调度。

分析开始时冻结效果实例、文档/工具/蒙版 ID、形状 revision、参考 CMTime、范围和帧长。每次结果发布验证目标仍匹配;切片段、切实例、删除工具、编辑蒙版或新一轮分析后,过时回调不得写回当前文档。

将手工键和自动轨迹分开保存;手工修正优先,合并只替换指定区间的可替换自动结果,保留区间外轨迹、羽化和强度动画。取消保留可信段;空结果不制造作者编辑。低置信度/丢失要有明确提示,不能静默填成功或持续外推。

先读父库 research/tracking-host-lifecycle.md。 它记录过提前返回后不收尾、跨 action 分组无效、预览刷新吃掉 Undo/Redo、旧实例在切片段后持续刷新等实际问题。当前可复用方案在准备好结果后,单个有效 action 内完成命名 Undo 起止和完整作者状态写入,然后 endAction;分析收尾保证一次,迟到/重复收尾不再编辑。别恢复早期58–67的已知问题流程。

五、参考库导航(只读)

本次核对:/Volumes/备份/大鱼调色/大鱼调色盘,HEAD f8950384e514685c8809fe8e8ee2dd5f16ad0bd7;正式68源码 d05994d5f4547687511bef524efe8c881e8a5c9c。接手时先检查差异,若参考更新则固定并记录新节点。

参考入口 复用方向
HANDOFF.md、verification/release-2.0.0-build68.json 正式68的真实完成范围与宿主证据
Sources/DYSettings.h/.mm 作者文档、图层、每层蒙版与归档
Sources/DYPanelLayers.inc 图层/工具列表操作与编辑目标
Sources/DYMaskState.h/.mm 精确 CMTime、手动/自动键、形状与变换求值
Core/DYMask.h、DYMaskOperator.h、DYLayerPlan.h 蒙版数学、组合/源阶段、渲染计划
Sources/DYPanelMasks.inc、DYInspectorMaskControls.inc 蒙版编辑器、宿主检查器入口
Core/DYTracker.hpp、Sources/DYMetalTracker.h/.mm 光流后端、RANSAC、结果/区间合并
Sources/DYPlugin.mm FxAnalyzer、目标冻结、取消/收尾、预览归属、Undo 提交
Sources/DYRenderer.mm、Shaders/DYColor.metal 计划执行、纹理与蒙版合成,需适配本项目
research/tracking-host-lifecycle.md 宿主生命周期、单 action 撤销和旧实例刷新防护
Tools/test_tracking.py、Tools/test_mask_refinement.py 参考测试和合成运动素材思路,不能替代本产品验收

父库有独立 Bundle ID、参数表、1032 字节 DYGrade、作者格式和更大的产品范围。本项目为 1104 字节 DYUniforms。按功能适配源码,保留本产品颜色链和品牌/安装身份;不整仓覆盖、不盲抄 PID/结构体,不把父库已验收数量记成本项目通过。移入源码时记录来源节点、文件摘要与必要资源,构建不得依赖兄弟 APP 或另一目录运行时存在。

六、建议里程碑与验收

阶段 可交付行为 最低验收重点
A:两个 HSL 独立添加、调值、眼睛和折叠;实例保存 不共用参数/缓存;旧工程画面不变;删除/插入不串目标;单次 Undo/Redo;重开与预设
B:每实例蒙版 两个 HSL 分别影响不同区域 蒙版/羽化/反转/透明度 CPU–GPU 对照;原点、tile、4K与非方形画面;关闭精确旁路
C:宿主控件 在 FCP 检视器画与改蒙版 当前实例隔离、真实拖动/绘制、工具窗口关闭后的行为、一次手势一次撤销
D:跟踪 实际运动帧驱动对应蒙版 前后/双向/单帧;取消可信段;低置信度;手工键优先;精确 CMTime;切片段/旧回调隔离
E:正式回归 保存、导出、性能与发行 冷重开轨迹完整一致;一次 Undo/Redo 的作者文档核对;旧预设/工程、CST/蜘蛛盘/LUT 回归;正式交付

用本产品独立合成源验证平移、旋转、独立轴缩放、边界/透明、局部遮挡或目标离画;量化中心和尺寸误差,并区分算法样本与实机结果。对任意遮挡不能作无证据保证。导出后检查完整运动序列,不能只看静态首帧轮廓。

新增无蒙版、无逐帧依赖的逐像素 HSL 可表达为 LUT;空间蒙版和跟踪不能完整写入普通 3D Cube。到实现时应明确选择阻止完整导出、或让用户明确导出全局部分,并在 UI 说明;不得静默丢掉局部调色后仍称完整一致。

七、工作与交付边界

本轮只交接,不实现这些功能、不改变正式 1.3.1(19)。下一轮遵循 /Users/mac/.codex/AGENTS.md:先保护当前工作,保存并推送阶段检查点;构建/CLI 测试在固定缓存,用户可见测试走已签名公证的唯一正式安装。新增功能后递增版本/构建号,刷新模型模板,完整签名、公证、安装、FCP 验收、清理、PKG、Release 完整下载与远端恢复。

用户正在使用浏览器时,不为额外测试重启或复位其工程。优先用新合成测试库,完整保留其 LUT、预设、最近使用和现有轨迹。此任务不需要 NAS 后端部署,不新增生产服务。