226 行
30 KiB
Markdown
226 行
30 KiB
Markdown
# 大鱼调色自定控件开发交接
|
||
|
||
> 当前正式版本、最新控件行为和待验收事项见 [开发交接.md](开发交接.md)。下文保留 1.12.0 及更早版本的实现与研究记录。
|
||
|
||
更新日期:2026-11-05,Asia/Shanghai。
|
||
|
||
当前正式安装为 **1.12.0(79)统一工作区与共享蒙版**,编译源码beccf2fc01f8dc06c5d3d505f88289885d209bc8,834项正式原生检查及本轮FCP反馈验收通过。实际交付进度以 `verification/Delivery.json`、`HostFeedback78.json`、`HostFeedback79.json`、`Package.json`、`Release.json` 为准;正式安装包签名、公证、20项验包、Release389草稿与发布后完整下载校验均完成。新增最近LUT快捷缩略图与左下横排画布图标,肤色线、片尾时间修复和真实跟踪误差见research/WorkspaceFeedback-20261105.md。
|
||
|
||
画布**左侧**常驻矩形、椭圆、钢笔蒙版入口,另有曲线、畸变、肤色、LUT;底部“控制面板”打开统一工作区。HSL、蜘蛛盘、色轮和通用参数浮卡已退出画布。曲线只显示透明曲线/直方图及必要通道,畸变直接操作网格,肤色切换真实保护范围显示,LUT直接进入原缩略图浏览器。
|
||
|
||
工作区横排15种工具,点击创建真实UUID层;左侧模块与蒙版引用,右侧选中模块调整或蒙版编辑/跟踪。四页为调整、蒙版、LUT、示波器,普通检查器与工作区共用宿主数据,增删、启停、参数、蒙版双向同步。LUT沿用原文件夹、缩略图和异步加载,目标绑定所选风格层的look0,保留过期回调取消和跨层冲突保护。
|
||
|
||
默认请求720×300至1440×360窄条,右上可扩大或收为窄条;左右分隔线比例保存为界面偏好。FxRemoteWindow未公开FCP内嵌/停靠和屏幕定位接口,窗口位置由宿主和用户拖移管理,不宣称已真正嵌入检视器。禁止恢复对本机代理NSWindow的强制frame/自动定位,避免1.7.2/1.7.3的远程坐标错误。
|
||
|
||
共享蒙版采用工具文档schema3:`sharedMasks`保存唯一对象,`baseMasks[type]`和UUID层`masks`仅保存`{sharedID: UUID}`。可先画后勾选模块,也可先选模块再画,再添加其它模块。多个模块引用同一形状和轨迹;解除关联或删除一个模块不删除对象,删除对象移除所有引用。最多64对象,每模块16引用。旧schema2、预设v7、1344字节Uniform保持兼容。渲染快照临时展开,不能作为编辑源。
|
||
|
||
新增关键入口:
|
||
|
||
| 范围 | 代码/资料 |
|
||
| --- | --- |
|
||
| 统一工作区及图层、关联列表 | `大鱼调色/Plugin/DYColorWorkspace.mm`、`DYWorkspaceTools.inc.h` |
|
||
| 单模块编辑及四通道曲线 | `DYInspector.mm`的workspaceType初始化、`DYToolInspector.inc.h` |
|
||
| 共享对象 | `DYToolState.h/.mm`:DYAddSharedMask、DYSetSharedMaskAssigned、DYShareToolMask、DYRemoveSharedMask、DYMasksForTool |
|
||
| 蒙版编辑与跟踪身份 | `DYMaskPanel.inc.h`、`DYToolHostMethods.inc.h`;全局node=shared+maskID |
|
||
| 矩形/椭圆直接拖框 | `DYToolCanvasEditing.inc.h`、`DYToolOSC.inc.h`,Esc/零面积/时间变化取消 |
|
||
| 分析专用预处理 | `DYToolGrayCapture.inc.h`,正常渲染不做4K跟踪读回,完成释放工作纹理 |
|
||
| OpenCV核心与构建 | `Plugin/MaskCore/DYOpenCVTracker.hpp`、`tools/tracking/DYOpenCVTracker.cpp`、`tools/build_tracking_opencv.py` |
|
||
| 原版证据与实施合同 | `research/ColorFinaleWorkspaceEvidence-20261105.md`、`research/UnifiedWorkspace-20261105.md` |
|
||
|
||
未写完整前缀的控件文件在`大鱼调色/Plugin/`。共享对象在画布/编辑器/跟踪统一定位,从HSL切换到蜘蛛盘同一对象或删除最初关联的模块不会丢弃共享轨迹。修改仍通过主队列宿主action、时间/UUID/外部改值复核和一次手势一次撤销。
|
||
|
||
本机ColorFinale2.16.2(625)只读研究已形成证据链,仓库不含商业二进制、图标或反编译源码。跟踪使用官方锁定OpenCV4.5.1静态构建:凸包抗锯齿区域、300角点、亚像素细化、21×21金字塔LK、前后向误差小于1、运动点多数分支、中心化RANSAC仿射、逐步QR和重检测。全部许可证在ThirdParty/OpenCV并随包复制。原版空仿射可能继续,大鱼失配时停止并保留可信轨迹前缀。
|
||
|
||
原版请求宿主Gamma2.2,大鱼调色请求linear;分析路径为linear→Gamma2.2→MPS Lanczos→RGBA8→OpenCV整数Gray8,最高3840×2160,保持像素网格。12项生成运动参考通过,不能代替原版同视频完整轨迹对照。宿主实际颜色请求、alpha、非方形像素跨插件逐点等价仍缺完整证据,不宣称完全等价。原版数据解析器`tools/tracking/read_colorfinale_preset.py`尚无真实轨迹导出fixture;普通.cflook未证明包含trackerScene,旧Export Preset菜单默认隐藏。
|
||
|
||
锁屏期间进一步核对了ColorFinaleUtils的原生集合format1/预设format2/版本format5及StorageData内联流,新增`tools/tracking/read_colorfinale_collection.py`。它仅解析明确提取的原生payload并拒绝外部masks哈希引用;最终UI导出文件外层封装和真实fixture尚未取得,不能自动猜测文件头或宣称整条原版导出链已通过。静态证据和生成样本验证见`verification/ColorFinaleTrackReaders-20261105.json`及研究报告补充章节。该辅助解析器没有改变已公证APP的编译源码。
|
||
|
||
新宿主fixture由`tools/create_workspace_host_fixture.py`生成,缓存`fcp-qa/workspace-1.12.0/`含XML及“共享矩形_HSL_蜘蛛盘.json”。FCP验收库不变,新事件“大鱼调色_1.12.0_74_统一工作区与共享蒙版”,含人像编辑和真实运动两项目。通过文件→导入→XML,不直接修改fcpbundle数据库。正式安装、公证与验收流程仍用下方deliver.py;若存在等待complete的进程,先核对其状态,不能重复取得同一产品锁。
|
||
|
||
## 1.11.0历史交接(以下不是当前界面合同)
|
||
|
||
下方保留旧版坐标、桥接和交付细节供追溯;涉及15工具画布栏、半透明HSL/蜘蛛盘浮卡、旧版本与发布状态,以本页上方和1.12.0验证报告为准。
|
||
|
||
## 工程和正式版本
|
||
|
||
| 项目 | 交接基线 |
|
||
| --- | --- |
|
||
| 实际工程根目录 | `/Volumes/备份/大鱼调色/大鱼调色`,不是上一级同名目录 |
|
||
| 工程与方案 | 根目录 `大鱼调色.xcodeproj`;`Wrapper Application`;Release |
|
||
| 技术 | AppKit、Objective-C++、FxPlug 4、Metal;控件沿用现有实现 |
|
||
| 交接前 main | `1144a89214f87c27228db01946b52d431b413c22`;本交接文档另作后续提交 |
|
||
| APP 实际编译源码 | `49d35cb49ab93f5ab6ca3411eaea80f7219be346`;其后提交为验收、辅助项目与交付记录 |
|
||
| 发布标签及提交 | `v1.11.0-canvas-spatial-20261105` → `5f8fb13fceb0c4d4ead447b8b5694ce269e95749` |
|
||
| 源码远程 | `https://dayu.media/git/dayu/dayu-color.git`,分支 `main`;保持现有可见性 |
|
||
| 唯一正式 APP | `/Library/Plug-Ins/FxPlug/大鱼调色.app`,1.11.0(73) |
|
||
| 产品身份 | 外层 `com.dayu.color`;服务 `com.dayu.color.XPC` |
|
||
| FCP 模板 | `/Users/mac/Movies/Motion Templates.localized/Effects.localized/大鱼调色/大鱼调色/大鱼调色.moef` |
|
||
| 固定构建缓存 | `/Users/mac/Library/Caches/CodexBuilds/com.dayu.color`;Release 使用其中的 `DerivedData` |
|
||
| 产品交付锁 | `/Users/mac/.codex/app-delivery-locks/com.dayu.color.lock`;本次交接核对时未占用 |
|
||
| 开发与验收环境 | 交付记录为 Xcode 27.1、FxPlug SDK 4.3.5、Apple Silicon、macOS 14.6+;实际宿主验收为 FCP 12.4 |
|
||
|
||
下一会话先核对工作区、分支、远端引用与交付锁,保护其它会话尚未提交的改动。当前正式版本不再等待宿主验收,也没有仍需输入 `complete` 的交付进程。凭据与签名私钥不属于源码恢复内容。
|
||
|
||
## 当前控件能力
|
||
|
||
| 区域 | 已实现 | 优化时保留的边界 |
|
||
| --- | --- | --- |
|
||
| 主检查器 | 新实例默认显示一级、蜘蛛、基础、HSL 四张折叠卡;其它工具由添加模块或画布工具条进入;全部还原恢复四卡折叠 | 旧工程有效调色、蒙版和实际 LUT 选择会自动显示,不能因简化界面而丢失 |
|
||
| 纵向画布工具条 | 15种工具入口,小画布分页,工作区入口和收起全部面板 | 工具条锚定实际图像可交互区域;同一工具再次点击会关闭并移除面板 |
|
||
| 浮动面板 | 半透明背景、标题点击折叠、标题拖动移动、关闭、点击置顶、同类图层切换、参数分页 | 每个工具类型最多一个面板;同类多个图层通过图层目录选择,尚无同类型多面板 |
|
||
| 曲线 | RGB/红/绿/蓝通道,加点、选点、拖点、删除选中点;同区直方图叠层;可切参数页 | 点位使用既有有限槽位;直方图为渲染分析参考,不是每一独立曲线层的即时输入 |
|
||
| HSL | 八色、色相/饱和度/明亮度三轴,画布内纵向拖动颜色点 | 自定义色选及其它精确参数仍在参数页和检查器 |
|
||
| 蜘蛛盘 | 画布网格拖点、同列自由点联动、固定点、还原选中点、全盘复位、6/12/24网格规格切换 | 自定义网格资产有专用写入桥;不能当作普通 float 参数写入 |
|
||
| 颜色分级 | 阴影、中间调、高光、全局四个色轮,直接调色相和饱和度 | 其它分级参数仍使用参数页 |
|
||
| 通用参数页 | 已公开参数的滑杆、开关、循环选项、数值显示、单项复位 | 画布中的数值显示尚不是可编辑文本框;并非所有资产选择与检查器自定义操作都在画布提供 |
|
||
| 肤色保护 | 默认开启人脸限定;实际保护区域以灰度权重显示;支持基础层及UUID独立层 | 当前帧无脸或识别失败时为空;关闭人脸限定可恢复全图颜色筛选 |
|
||
| 镜头畸变修复 | 正负径向强度、缩放、光学中心;接入独立层、蒙版、完整预设及撤销 | 独立反向径向实现,未证明与目标插件逐像素等价;不是新增局部液化工具 |
|
||
| 画布外工作区 | FxRemoteWindow 窗口;亮度波形、RGB分列、直方图、风格1 LUT浏览及真实帧预览 | LUT操作目标为绑定实例的 `look0`;不是任意LUT槽选择器 |
|
||
|
||
工具类型顺序来自 `DYToolTypes()`:`primary, spider, base, skin, look, hsl, curve, grading, primaries, levels, blackwhite, balance, mixer, film, lens`。前14项顺序保持不变,`lens` 在末尾;工具名称数组与类型目录需同步维护。
|
||
|
||
画布面板背景当前 alpha 为0.66;系统开启“降低透明度”时改为实色。面板位置采用视口归一化坐标,但只存于当前面板对象;关闭重建、插件重建或重启后不恢复布局。
|
||
|
||
## 代码入口
|
||
|
||
下列文件都属于当前工程。`*.inc.h` 多为在 `.mm` 中展开的实现片段,不作为独立编译单元重复加入目标。
|
||
|
||
| 要优化的部分 | 源码入口 | 主要方法或职责 |
|
||
| --- | --- | --- |
|
||
| 宿主画布坐标和鼠标路由 | [DYToolOSC.inc.h](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYToolOSC.inc.h) | `DYToolOSC`、`drawOSC`、`partAtPoint:`;保留蒙版和钢笔路由 |
|
||
| 工具条和多面板管理 | [DYViewerControls.inc.h](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYViewerControls.inc.h) | `prepareWithSize:scale:atTime:`、`activateTool:`、`event:point:atTime:`;置顶与捕获 |
|
||
| 面板布局和通用交互 | [DYViewerParameterPanel.inc.h](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYViewerParameterPanel.inc.h) | `prepareWithSize:scale:atTime:`、`clickArea:`、`movePanelToPointer:`、`finishCapture` |
|
||
| 曲线 HSL 蜘蛛 色轮图形 | [DYViewerGraphics.inc.h](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYViewerGraphics.inc.h) | `layoutGraphicAt:`、`drawGraphic:`、`beginGraphicAt:`、`updateGraphicAt:`、`spiderAction:` |
|
||
| 写回 撤销 冲突保护 | [DYViewerParameterBridge.inc.h](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYViewerParameterBridge.inc.h) | `snapshotAtTime:`、`beginParameters:`、`changeValues:`、`beginSpider:`、`changeSpider:`、`endGesture` |
|
||
| 插件快照和渲染后采集 | [DYPlugIn.mm](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYPlugIn.mm) | `pluginState:atTime:` 发布参数与资产;成功渲染后发布直方图并采集示波器 |
|
||
| 实例绑定和生命周期 | [DYToolHostMethods.inc.h](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYToolHostMethods.inc.h) | `initializeToolHost`、`tearDownToolHost`、`scheduleToolCanvasRegistration`、`viewerParameterBridge` |
|
||
| 检查器布局和原生图形 | [DYInspector.mm](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYInspector.mm) | 四卡折叠、有效参数自动显示、`resetAll:`;`DYCurvePanel`与色轮 |
|
||
| 模块添加和画布入口联动 | [DYToolInspector.inc.h](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYToolInspector.inc.h) | `revealViewerTool:`、`visible:<type>`;已删除类型的恢复与中性替代 |
|
||
| 参数和工具文档 | [DYModel.mm](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYModel.mm)、[DYToolState.mm](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYToolState.mm) | `DYDescriptors()`、`DYSections()`、`DYToolTypes()`、`DYToolDisplayOrder()`、`DYToolManager` |
|
||
| 原生蜘蛛盘和网格数学 | [DYSpiderDisc.inc.h](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYSpiderDisc.inc.h)、[DYSpiderMesh.hpp](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/SpiderCore/DYSpiderMesh.hpp) | `DYSpiderPanel`、`dy::moveMesh`;状态格式见 `DYSpiderState.h` |
|
||
| 肤色人脸和畸变渲染 | [DYFaceRender.inc.h](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYFaceRender.inc.h)、[DYToolRender.inc.h](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYToolRender.inc.h) | 当前帧人脸检测、几何覆盖、镜头采样和独立层接入 |
|
||
| GPU选区和Uniform | [DYGrade.metal](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYGrade.metal)、[DYToolGPU.h](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYToolGPU.h)、[DYUniforms.h](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYUniforms.h) | 肤色权重输出、人脸覆盖元数据、CPU/GPU布局 |
|
||
| 画布外工作区 | [DYColorWorkspace.mm](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYColorWorkspace.mm) | `showRelativeToView:`、`layoutWorkspace`、`selectionContextAtTime:`、LUT提交与关闭 |
|
||
| 示波器采集和统计 | [DYScopeCapture.inc.h](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYScopeCapture.inc.h)、[DYScopeMath.hpp](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYScopeMath.hpp) | 小幅GPU读回,后台统计,最新帧合并 |
|
||
| 主题和表面 | [DYTheme.mm](/Volumes/备份/大鱼调色/大鱼调色/大鱼调色/Plugin/DYTheme.mm) | 复用 `DYThemeColor`、`DYDrawThemeSurface`、`DYDrawSoftControl` |
|
||
|
||
画布基本链路:宿主OSC → `DYToolOSC` → `DYViewerControls` → 面板及图形 → `DYViewerParameterBridge` → 主队列宿主action → 原参数或UUID对应的 `DYToolManager` → 渲染快照返回面板。
|
||
|
||
## 交互和数据约定
|
||
|
||
**坐标与命中。** 使用真实 OBJECT→CANVAS 图像矩形与画布的交集。绘制、命中、拖动共用几何;工具条先命中,面板逆序命中,按下面板后置顶。原蒙版、钢笔和新增控件共享OSC根路由。不能只看“画得出来”来判定宿主可交互。
|
||
|
||
**捕获与释放。** 按下时记录节点、时间、起点和原值;超过 `2 × scale` 位移进入拖动。图形或滑杆捕获后允许移出轨道继续拖动,松开补算最终位置并结束手势。普通按钮在原命中区释放才触发;拖标题后松开不能再次折叠。`mouseExited` 仅清理悬停。
|
||
|
||
**同帧快照。** OSC只读取当前帧快照,不同步等待主队列,不直接写宿主模型。缺帧时保留UUID选择并暂缓编辑。主队列写入前复核时间、节点、原值和关联开关;遇外部修改或目标消失结束手势并保留外部结果。
|
||
|
||
**一次手势一次撤销。** 曲线X/Y、色轮H/S通过 `beginParameters:` 与完整 `changeValues:` 成组提交。蜘蛛盘通过 `beginSpider:` 与 `changeSpider:` 提交自定义资产。一次手势共享一个撤销组,松开及失败均收尾;空闲面板不能关闭另一面板的写入组。宿主API无 `abortAction`,失败要按现有逻辑尝试恢复并结束action。
|
||
|
||
**图层目标。** 基础层使用 `base:<type>`,独立层使用真实UUID,不能按面板或列表序号定位。蜘蛛基础层来自 `DYAssetState.spiderMesh`,独立层来自层文档的 `spider`;桥接器在 `DYToolManager` 提交action后回读实际保存结果,并检查外部网格和拓扑冲突。
|
||
|
||
**显示状态。** 面板位置、开合、置顶、分页、图形页、颜色轴及通道选择属于显示状态,不写调色参数,不制造调色撤销。若增加布局持久化,应明确采用用户偏好或实例界面状态,避免写入调色Uniform、网格资产或LUT内容。
|
||
|
||
**兼容与生命周期。** 保留既有参数ID、完整预设v7、CMS nil/v2/v3语义及工具顺序。Uniform原1312字节前缀保持,1.11.0只追加32字节,总计1344;CPU/GPU两侧同步修改并保留断言。播放头变化、面板销毁、manager失效时关闭捕获和撤销组;异步提交校验会话。工程采用手动内存管理,注意retain/release和block的生命周期。
|
||
|
||
## 四类图形的参数映射
|
||
|
||
- 曲线:`output = x + curveY × 0.01`,写回 `curveY = (output - x) × 100`。RGB为4个基础槽加4个额外槽,单色通道为2个基础槽加4个额外槽;`x < 0`表示未启用,删除写 `x=-1, y=0`。固定端点及单调Hermite插值沿用已有实现。
|
||
- HSL:`hsl{axis}_{color}`,axis为0色相、1饱和度、2明亮度,color为0至7。当前画布按所在颜色列选目标,将垂直位置映射至-100至100;不要将绘制坐标误当成参数相对增量。
|
||
- 色轮:`grade{i}_0`为角度制色相,`grade{i}_1`为0至100饱和度;i为0至3,依次阴影、中间调、高光、全局。注意画布Y轴与数学Y轴方向相反。
|
||
- 蜘蛛盘:拖动以按下时冻结的网格为起点,归一化位移经 `dy::moveMesh` 计算;固定、还原和重采样也经过同一桥接器,不直接改渲染缓存。
|
||
|
||
## 直方图和空间工具的边界
|
||
|
||
曲线直方图来自320×180分析缓存、256档、最多约2Hz,成功渲染更新后才发布至同时间快照,播放头不匹配时不展示上一帧。它沿用现有分析采样阶段,不等同于每个独立曲线层的输入;具体采样阶段随原流程/CMS设置而异,见README中曲线直方图说明。
|
||
|
||
外部工作区示波器另用 `DYScopeCapture` 采集当前效果的处理输出,不含后续效果和宿主显示转换。已知ICC时转扩展sRGB,未知空间显示宿主RGB原值参考;保留分块标注,不能把它作为精确HDR/IRE测量。不要用 `_renderer histogram` 代替该输出采样。GPU读回在宿主纹理仍有效时完成,CPU统计放后台;保留根视图、面板裁剪和顶栏越界重绘回归。
|
||
|
||
人脸限定使用当前帧Vision revision3/76点,支持轮廓和额头区域并排除眼、眉、唇,与原肤色筛选及用户蒙版相乘。输入长边最多960像素;MTLTexture转CIImage时按 `TOP_LEFT` 翻转归一化,两种原点输出一致已经回归。仅复用完全相同的像素,不复用上一镜头人脸;检测失败时为空。肤色区域预览读取真实皮肤阶段的保护权重,不另画一张近似脸框。
|
||
|
||
人脸选区、镜头几何及调试预览属于空间处理,静态Cube无法保存;活跃时按现有逻辑拒绝不适用的Cube导出,完整预设继续保存。畸变修复为独立反向径向采样,保留透明度、边界、像素宽高比和光学中心原点处理。
|
||
|
||
`DYRenderer.mm` 的 `notifyPreviewChanged` 独立方法用于安排主队列预览通知。此前C++引用捕获中的异步block泄漏self栈地址已修复,不要恢复旧写法。完整ASAN运行无内存错误;插桩下旧主队列响应阈值失败,正常Release通过,未放宽阈值。
|
||
|
||
## 后续优化候选
|
||
|
||
具体优先级由用户下一次需求决定,以下均为尚未实施的候选,不作为已有缺陷或新增功能承诺。
|
||
|
||
| 候选 | 涉及范围 | 应先明确的交互 |
|
||
| --- | --- | --- |
|
||
| 面板位置和开合恢复 | `DYViewerControls`、`DYViewerParameterPanel`及界面状态存储 | 是关闭重开恢复,还是重启恢复;是否按插件实例独立保存;缩放或分辨率变化后的回位 |
|
||
| 曲线和HSL操作手感 | `DYViewerGraphics`、参数桥 | 选点命中半径、拖动灵敏度、细调修饰键、选中态及数值反馈;保留现有参数语义 |
|
||
| 画布精确数值输入 | 面板、OSC、宿主焦点路由 | 单击/双击进入、确认/取消、超范围处理,以及FCP快捷键和钢笔工具冲突 |
|
||
| 蜘蛛盘编辑反馈 | 网格图形和专用资产桥 | 选中/固定状态、同列联动提示、网格密度和窄画布可读性 |
|
||
| 工具条和多面板布局 | 工具条分页、面板层次及边界约束 | 15工具可发现性、重叠时选择、遮挡画面程度;同类多面板需另行设计 |
|
||
| 外部工作区 | `DYColorWorkspace`、`DYScopeCapture` | LUT目标图层/槽位扩展或示波器布局,保留异步取消和真实目标冲突检测 |
|
||
|
||
推荐每次先完成一个工具或一组明确交互,连接真实参数和UUID层,再做窄画布、主题和宿主验证。已有曲线、HSL、蜘蛛盘均可在画布编辑,后续应在当前实现上优化。
|
||
|
||
## 验证入口和宿主项目
|
||
|
||
正式安装版原生检查为 **724项通过**,包含真实Metal/IOSurface和模拟宿主回调。用户于2026-11-05实鼠确认“三项均正常”:画布曲线含直方图、HSL、蜘蛛盘拖动和一次撤销;人脸肤色区域;畸变网格调整。记录见 [HostCanvasTools1.11.0.json](/Volumes/备份/大鱼调色/大鱼调色/verification/HostCanvasTools1.11.0.json) 与 [CanvasAcceptance1.11.0.json](/Volumes/备份/大鱼调色/大鱼调色/verification/CanvasAcceptance1.11.0.json)。这次验收为FCP 12.4,不扩写为Motion也逐项实测。
|
||
|
||
| 修改范围 | 原生回归入口 |
|
||
| --- | --- |
|
||
| 新三工具、真实人脸、畸变GPU/CPU对照 | `大鱼调色/Plugin/DYCanvasToolsDiagnostics.inc.h`,1.11.0新增29项 |
|
||
| 工具条、布局、图形捕获 | `大鱼调色/Plugin/DYViewerControlsDiagnostics.inc.h` |
|
||
| 参数组写入、UUID、时间和外部冲突 | `大鱼调色/Plugin/DYViewerParameterDiagnostics.inc.h` |
|
||
| 四卡折叠、移除和重新添加 | `大鱼调色/Plugin/DYCompactUIDiagnostics.inc.h`、`DYToolDeletionDiagnostics.inc.h`、`DYToolInsertionDiagnostics.inc.h` |
|
||
| 外窗、LUT异步提交、越界重绘 | `大鱼调色/Plugin/DYWorkspaceDiagnostics.inc.h` |
|
||
|
||
上述回归由 `DYDiagnostics.mm` 集成。重跑正式安装自检需提供版本化真人fixture,避免被误判为人脸功能失败:
|
||
|
||
```sh
|
||
cd '/Volumes/备份/大鱼调色/大鱼调色'
|
||
DY_DIAGNOSTIC_FACE_FIXTURE='/Volumes/备份/大鱼调色/大鱼调色/tools/fixtures/astronaut.png' \
|
||
'/Library/Plug-Ins/FxPlug/大鱼调色.app/Contents/PlugIns/大鱼调色 XPC Service.pluginkit/Contents/MacOS/大鱼调色 XPC Service' --self-test
|
||
```
|
||
|
||
宿主验收库在 `/Users/mac/Library/Caches/CodexBuilds/com.dayu.color/fcp-qa/大鱼调色_验收.fcpbundle`;事件为“大鱼调色_1.11.0_73_画布与空间工具”,含画布曲线/HSL/蜘蛛盘、人脸肤色保护、镜头畸变修复三个项目。辅助资料可重建:
|
||
|
||
```sh
|
||
python3 '/Volumes/备份/大鱼调色/大鱼调色/tools/create_canvas_host_fixture.py'
|
||
```
|
||
|
||
输出位于 `/Users/mac/Library/Caches/CodexBuilds/com.dayu.color/fcp-qa/canvas-1.11.0/`,含验收FCPXML、网格、肤色区域预览及畸变预设。该脚本当前固定1.11.0命名;新增版本需按实际版本调整,不要把旧验收记录当作新版本通过。通过FCP“文件→导入→XML”导入,不直接修改fcpbundle数据库。
|
||
|
||
新增或修改交互至少核对:基础层和两个同类独立UUID层;按下、拖动、轨道外捕获及释放;一次撤销/重做;检查器同步;播放头和片段切换;拖动期间外部改值或删层;面板重叠、关闭、重建;深浅主题、降低透明度、小画布及不同缩放;保存重开。按变更补充必要检查,避免复制实现的无效测试。
|
||
|
||
上一轮自动点击未能可靠触发原生OSC,最终三项结果来自用户实鼠确认。电脑自动化遇此限制时保留事实并请用户完成相应步骤,不以绘制截图或模拟宿主通过替代实鼠验收。对宿主发送退出后不要马上再次取该APP状态,以免工具重新启动它;先确认保存并正常退出,避免强杀用户工程。
|
||
|
||
## 构建和交付
|
||
|
||
功能改动继续沿用 [tools/deliver.py](/Volumes/备份/大鱼调色/大鱼调色/tools/deliver.py)。正常保存并退出FCP/Motion后运行;脚本取得产品锁,显式禁用ASAN,清理专用构建目录并Release构建,逐层Developer ID签名,原生检查,Apple公证Accepted,粘附及验证票据,替换唯一正式安装,核对PluginKit。用户可见验收运行正式安装路径的已公证版本。
|
||
|
||
脚本在正式安装后等待 `complete` 或 `leave`。仅在真实宿主验收通过后输入 `complete`,以清理旧版恢复APP并将Delivery记为verified;有问题时保留诊断和可恢复状态。脚本会重写Delivery记录,额外宿主证据在完成后补齐。
|
||
|
||
修改参数描述、模板默认值或注册信息时同步 `template/sources/RegisteredParameters.json`、原生模板和模板校验;入口为 `tools/build_template.py --refresh-model --overwrite`。单纯控件文档修改不重建插件。正式PKG通过 [Packaging/build_pkg.py](/Volumes/备份/大鱼调色/大鱼调色/Packaging/build_pkg.py) 与PKG工坊技能生成;构建器要求正式APP交付已验证。不要覆盖已发布的同名版本包,也不移动既有标签。
|
||
|
||
新版本Release沿用 [Packaging/publish_beta.py](/Volumes/备份/大鱼调色/大鱼调色/Packaging/publish_beta.py):先有已推送标签、匹配的Package报告和最终发布说明,创建草稿并上传,经完整下载核对大小及SHA-256后发布,发布后再次完整下载核验。草稿API下载404时使用已登录浏览器下载,再传 `--verified-download`;必须是真实远端下载文件,不能复制本地原包冒充。保留现有公测标志和仓库可见性。
|
||
|
||
源码阶段提交使用 [tools/checkpoint.py](/Volumes/备份/大鱼调色/大鱼调色/tools/checkpoint.py),只传本任务审查过的文件。脚本自带Git仓库锁,不嵌套同一把锁;当前实现按main核验远端,切到其它工作分支时先适配。最终按 [RECOVERY.md](/Volumes/备份/大鱼调色/大鱼调色/RECOVERY.md) 完成源码推送、版本标签、远端独立恢复与本产品生成副本清理。额度重置由用户手动操作。
|
||
|
||
## 发布和恢复记录
|
||
|
||
1.11.0 APP公证 `348c6e9b-f5d9-4661-bc7f-f192fa770ecf` Accepted;PKG公证 `ffbdb4fb-f573-411e-99fc-166c4a829121` Accepted。签名、票据、Gatekeeper、唯一位置安装及PluginKit发现通过。原生724项与20项展开验包通过,PKG本轮未重复执行安装脚本,APP由交付流程独立正式安装。
|
||
|
||
正式包为 `/Volumes/备份/大鱼调色/发行包/大鱼调色-1.11.0.pkg`,43,128,845字节,SHA-256 `2dd5166902ebdaae50dd897057459cbe7e5ea611dbdeb571bd688e843c59768e`。[Release388](https://dayu.media/git/dayu/dayu-color/releases/tag/v1.11.0-canvas-spatial-20261105)及附件32已经发布,草稿与发布后完整下载均校验一致。记录见 `verification/Package.json`、`Release.json`。
|
||
|
||
远端独立检出发布标签的555个跟踪文件逐字节一致,程序与模板和实际编译49d35cb一致,full/strict fsck通过,无LFS及子模块。恢复到正式发布源码可克隆上述仓库,再执行 `git switch --detach 5f8fb13fceb0c4d4ead447b8b5694ce269e95749`;继续开发使用盘点后的最新main。详见 `verification/CanvasFinalRecovery1.11.0.json`。
|
||
|
||
旧版恢复APP、编译产生的松散APP、公证提交ZIP、临时验证下载及恢复clone均已清理;源码、QA媒体/用户库、历史安装包保留。扫描仅覆盖交付记录中的明确目录,见 `verification/CanvasCleanup1.11.0.json`。不按旧记录中的进程PID或临时下载路径继续操作。
|
||
|
||
旧1.10.0 Release387/附件31保持原草稿,不属于本轮未完成事项,不影响1.11.0已完成交付。网站文章15792此前停留在1.10.0,本轮未更新文章、网站下载或NAS后端;如要上架1.11.0,按新的发布需求另行处理。
|
||
|
||
## 参考资料
|
||
|
||
- [本轮实现研究](/Volumes/备份/大鱼调色/大鱼调色/research/CanvasTools-20261105.md):功能范围、研究证据、算法与验证。
|
||
- [画布工作区实现](/Volumes/备份/大鱼调色/大鱼调色/research/ViewerWorkspace-20261104.md):前一轮框架和工作区。
|
||
- [原始屏幕控件研究](/Volumes/备份/大鱼调色/大鱼调色/research/mFilmLookOSC-20261104.md):交互参考和历史阶段。
|
||
- 演示素材 `/Volumes/备份/6524bdcd3a33f6bd0128a340b9c7fadc_raw.mp4`;只读研究,不上传用户视频到源码仓库。
|
||
- 人脸算法参考 [FCP-BeautyGirl](https://github.com/dayumeida/FCP-BeautyGirl),研究提交 `42fecaa3b55471fea928339127d53484663d4057`;许可保留在 `research/FCPBeautyGirl-MIT.txt`。测试真人 `tools/fixtures/astronaut.png` 的公共领域来源见同目录README,不随APP交付。
|
||
|
||
## 给下一会话的接续说明
|
||
|
||
> 继续优化大鱼调色的画布自定控件。先读取 `/Volumes/备份/大鱼调色/大鱼调色/自定控件开发交接.md`,盘点最新main、工作区和交付锁,以已验收的正式1.11.0(73)为基础。曲线含直方图、HSL、蜘蛛盘已在半透明画布面板中可编辑,主检查器默认四卡折叠,人脸肤色区域和畸变修复均已完成。按我随后指定的控件问题或交互目标继续改进,保留UUID图层、同帧快照、主队列写回、一次手势一次撤销、原蒙版钢笔路由及兼容格式。文档中的候选优化尚未实施,不自动扩成全部任务。功能修改继续按Release签名公证、唯一正式安装、实际宿主验收、源码推送、PKG和Release下载校验交付;额度重置由我手动处理。
|