feat: WIP unified workspace shared mask objects and OpenCV tracker core

这个提交包含在:
mac 于 2026-11-05 03:16:17 +08:00 提交
1 父节点 78e53b3889
当前提交 ca352248c1
36 个文件已更改
+5298 -164

没有与搜索条件相匹配的文件

@@ -0,0 +1,65 @@
# Color Finale 工作区与区域跟踪证据(2026-11-05)
## 身份、边界和证据保留
本机 `/Applications/ColorFinale.app` 为2.16.2(625),主插件 `Contents/PlugIns/ColorFinale.pluginkit/Contents/MacOS/ColorFinale` 完整SHA-256为 `49121a6f5487060d322a59e7658166ab772e8a56f7dc1bcfa9d433a89436b30f`。2026-11-05重新核验,原文件只读。Ghidra12.1.4/arm64的分析profile为 `c991deeff48f794414bcbf9d15409d809db80062959eb2c963195db4cd97614a`,复用11月1日snapshot并补充本轮查询。静态调用链是发行产物观察,不是原版运行时逐项验收;用户提供的截图仅支持其中可见结构。
完整证据与反编译中间产物仅存本机 `/Users/mac/Library/Caches/CodexBuilds/ColorResearch/workspace-20261105/`;仓库仅保留事实、接口、实施合同和证据ID,不复制商用二进制、图标、nib或反编译实现。
## 工作区逻辑链
1. 顶栏工具动作 `addLayerWithType:`(`0x1000769cc`,`ev_9e1abf39aeee8571405645352af5b24cc00d4c08a4920a7b638266fee983960b`)创建对应工具节点,统一进入 `insertLayer:`。
2. `insertLayer:`(`0x100076bac`,`ev_7e4a2dd8c5ccc4fe7cfd6a5c7f3589c1f68a2f2f54e6e06ef1a8e750058a018c`)读取第一项选择:无选择则根索引0;普通层则当前索引;组选中则组内0。在一个命名Undo组中插入。
3. 插入block(`0x100076dd4`,`ev_aa0e9a9146fcb8527d086b91a39c51bf8fbe7a5c180686d5bcd2cdda16c69f17`)执行beginUpdates、必要展开组、insertLayer、选择新层、endUpdates、storeAdjustments,再更新右区和键盘焦点。
4. `setActiveViewControllerForLayer:`(`0x100077758`,`ev_a0d38bcebc4979e7a77baa47c173fcaa6aae4640992709a18bbd8ea7db048613`)先检查当前层蒙版是否selected且enabled:满足则切蒙版控制器并updateScene;否则按工具类型切曲线、色轮、HSL、LUT等控制器,再setNode到当前真实对象。
5. `setActiveViewController:`(`0x100077a98`,`ev_eacade9dcaa7e283df2af98aa0dc6ab2ec69cb48b6cad8c6fd84a4d35bc065df`)卸载旧控制器并清空其node,再把新控制器view放入同一viewHost。不是叠加多份浮动参数窗。
6. `storeAdjustments`(`0x1000760f0`,`ev_2a855e029cca778e55e861367fffd6cb9adf4d7e52914841ffc3beb51285fae7`)从layersViewModel.rootNode取得实际文档,经apiManager.performActions提交。检查器、工作区和渲染不应各建一份作者数据。
官方[图层工作区文档](https://docs.colorfinale.com/docs/layers/)同时确认:可调大小浮窗、横排工具、点击新增独立图层、左列选层、右区编辑、图层眼睛和右键菜单、底部强度/混合/蒙版/删除。原版文档所称默认新层在顶部与上面的无选择/当前选择/组内插入分支相容。文档描述不是本机运行验证。
## 蒙版编辑与共享对象
`addLayerMask:`(`0x1000f0c30`,`ev_cada231cd5850104fb9806190f532f919e4d82e2c2026a771d5cdf010b81594a`)对选择层中无蒙版者建立FTFxNodeMask,已有者保留;统一作者更新。`maskSelectionDidChange:`及block(`0x100078480/0x100078514`,`ev_a42abc5cdccfdba24fa750e3b2ceb178d949b89445c985c314cb1e7b382a31e1`、`ev_c4bbaccfaa18337b20e24cf38373237af45fc5817c199f0b6507ff3c9d8f6237`)经宿主action保存并切右区。
`FTMaskDetailViewController::updateControls`(`0x100015a98`,`ev_030904608107bf6f0220345798ac4adfbf2fa726ae0387dfc6ca1851fde04c0f`)按真实蒙版类型选择形状、图像、HSL、人物、FCP子控制器,解绑非当前节点。仅可动画形状展示跟踪区;自动跟踪时关闭冲突属性与关键帧操作。属性编辑包含羽化、强度、位置、缩放、旋转,另有反转与组合模式。
官方[蒙版文档](https://docs.colorfinale.com/docs/masks/masks/)确认在工作区右区替换调色控件,画布叠加小工具栏;面板加号与画布直接绘制为两个入口;同层可有多个形状,支持Add/Subtract/Intersect。官方[跟踪文档](https://docs.colorfinale.com/docs/masks/tracking/)确认前后区域跟踪与关键帧操作;[显示模式](https://docs.colorfinale.com/docs/masks/fourmaskdisplaymode/)描述结果、输入、输入叠蒙版与黑白合成;[形状编组](https://docs.colorfinale.com/docs/masks/grouping-mask-shapes/)描述多选组变换。
本轮用户进一步要求“画布左侧常驻蒙版工具”“先画/先选模块”“同一蒙版关联多个模块并共享形状和轨迹”。这是大鱼的新需求;当前证据不能直接声称Color Finale提供完全相同的跨任意模块共享引用操作。实施合同应是文档scene中唯一maskID对象+模块maskRef,而非复制mask字典;一次修改应影响全部引用,删除某模块仅移除引用,孤立对象清理需保留可独立选择的已画蒙版。形状、轨迹和手工关键帧都属于该共享对象;当前模块选择、右区页签、布局和画布显示属于界面状态。
## 窗口边界
`FTRemoteColorCorrectionWindowController::initWithMinSize:maxSize:containerViewController:`(`0x10010aa0c`,`ev_df055fd889e786ea4e4cdca060207f8ffbe73be5445d5e1f198b9ba6fa9e447e`)建立不透明white约0.122的FxRemoteWindow及contentViewController。`showPanelForPlugin:`(`0x10010af60`,`ev_df9a209ebfdd992dcab10802f1535537ab2992b57ac83a960e49e1977045a6f1`)绑定当前plugin,必要时关闭重开以更新尺寸,否则激活已有窗。`updateWindowSize` block(`0x10010a7b0`,`ev_1afe52ae28a67dc775a4f5f5164aeb351790ae4eded25783b840335240072b44`)读取三档layersPanelSize并设min/max约1/1.25/1.5倍率。
现有证据支持自由调整的独立浮窗。没有证据证明第三方FxPlug可以嵌入FCP检视器内部;“检视器下方窄条、不挡画面”应作为本产品默认摆放/尺寸目标,通过公开FxRemoteWindow API与实际宿主验证实现,不能声称已原生停靠FCP。
## 可复现的开放算法配置
本机原版opencv2.framework Info.plist为4.5.1。该框架只读核对版本,不复制、不链接;大鱼可由官方OpenCV4.5.1源码独立构建。官方tag peeled commit:`1363496c1106606684d40447f5d1149b2c66a9f8`(tag object `3e80752d72a4b78820a732087217668e67701981`)。
核心观察来自 `FTAreaTracker::track:trackerState:`(`0x100035e40`,`ev_dcd7aa770925f63c8c14c968ae6b417fda78685c7be7fa739a78209957d40e2d`),逐帧来自`trackFrame:inScene:`(`0x100036cbc`,`ev_e798c4e6e032e085812f81831ecc16196bd3c2278bf634961379669ee1308f7e`),分析入口`effectAnalysis:analyzeFrame:session:error:`(`0x10005b47c`,`ev_1dd68409d431d9e81875b6032a81dd89f7f237ea5501d3db1d7ca92ba32e6323`)。
| 阶段 | 可独立重建的调用合同 |
| --- | --- |
| 完整帧 | 宿主tiles收齐完整帧;IOSurface转换,分析最大3840×2160;转8bit灰度。原版调用cvtColor代码11,按OpenCV颜色枚举对应RGBA2GRAY;需匹配实际源通道序,不能对BGRA盲用 |
| 形状区域 | 形状像素顶点转int,convexHull(clockwise=false,returnPoints=true),fillPoly(mask8UC1,255,LINE_AA,shift0) |
| 特征重选 | 全局分析计数<2或偶数帧;goodFeaturesToTrack(max300,q.03,minDistance10,blockSize3,Harris=false,k.04) |
| 亚像素 | cornerSubPix(winSize10×10,zeroZone(-1,-1),COUNT|EPS,20,.03) |
| 光流 | 相邻灰度帧前后calcOpticalFlowPyrLK,21×21,maxLevel3,COUNT|EPS30/.01,flags0,minEigThreshold1e-4 |
| 筛点 | 成功status并FB欧氏距离严格<1像素;有效点不足4失败;位移≥max(w,h)×.01的点若严格超过当前有效点半数,使用该子集 |
| 仿射 | 前后点先减当前形状中心;estimateAffine2D(RANSAC=8,reprojection3,maxIters2000,confidence.99,refine10) |
| 作者输出 | sx=hypot(a,c),theta=atan2(c,a),sy=det/sx;每步围绕旧中心更新形状,center加拟合平移,theta累加,sx/sy逐步相乘;输出position按分析w/h归一化、rotation、scaleXY,并用effectTime持久化 |
公开API参考:[特征与亚像素](https://docs.opencv.org/4.5.1/dd/d1a/group__imgproc__feature.html)、[金字塔LK](https://docs.opencv.org/4.5.1/dc/d6b/group__video__track.html)、[仿射RANSAC](https://docs.opencv.org/4.5.1/d9/d0c/group__calib3d.html)。本表是参数/行为合同,不包含原版实现源码。
原报告“空仿射矩阵必失败”需修正:当前反编译中empty分支只跳过变换,而后仍可返回1,未独立汇编/运行复核,不能把该静默成功视为正确行为。大鱼应明确在空fit、非法数值、反射、离画及置信不足时停止并保留可信段;该保护差异必须记录。
## 迁移与验证缺口
需要从旧自研特征/LK/RANSAC切到独立编译的OpenCV管线,不能只把阈值改成相同数字;300点与21窗口本身不建立算法等价。必须补齐灰度系数/8位量化、分析分辨率、凸包区域、周期重选、运动主体筛选、中心化拟合与逐步QR作者输出。既有宿主冻结目标、精确CMTime、一次撤销、手工键保留、取消可信段、旧实例隔离继续沿用。
同视频同路径同范围的原版/大鱼完整轨迹尚未运行对照;图像通道/色彩空间、OpenCV编译优化、分块帧调度与数值细节可能影响结果。静态重建、合成运动检查及正式宿主测试应各自报告,不得宣称逐帧或逐像素完全等价。
## 本轮独立实现结果
`dy::OpenCVTracker`现使用独立编译的官方4.5.1库,12项已知运动检查通过(`verification/TrackingOpenCV-20261105.json`):300点、旋转及双轴缩放、框外路径12帧亚像素、周期重选静止、换景、平坦区、运动多数子集、实例隔离、坏帧几何保留、非有限输入及完整4K。中心误差约0.0033px(旋转/缩放)、0.0148px(12帧路径)、0.00011px(4K平移);这些是生成素材结果,不是实拍或原版轨迹对照。只依赖系统zlib/Accelerate/libc++/System,插件运行不需要研究目标或另一APP。宿主接入、共享mask作者同步、正式版本实际跟踪仍由主任务验收。
@@ -0,0 +1,72 @@
# 统一工作区、共享蒙版和现有跟踪链路审计
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警告。运行结果待主交付的正式安装自检记录;本文件不预写运行“通过”。