DJV 插件开发完整指南：看懂 4 个扩展入口，简单写出第一个工具面板

DJV 插件开发完整指南看懂 4 个扩展入口简单写出第一个工具面板【免费下载链接】DJVFree EXR file viewer. DJV is a free, open-source high bit-depth image sequence player built for professional film, VFX animation workflows. Use it for frame-accurate dailies, shot review, and A/B comparisons. Available for Linux, macOS, and Windows.项目地址: https://gitcode.com/gh_mirrors/djv/DJVDJV 是一款面向电影、VFX 与动画工作流的高位深图像序列播放器EXR 查看器支持逐帧看片、A/B 对比。它附带一个完全用 Python 编写、可定制的播放器应用djv-python你可以通过它的插件式扩展机制往里面加自己的工具面板和菜单动作而不用去啃 C。这篇教程带你从搭环境、看懂 4 个扩展入口到从零写出第一个可运行的DJV 插件开发实例。一、先判断这类需求该用插件解决吗不是所有改动都适合走加插件这条路。先花一分钟对号入座能帮你省下后面很多弯路。适合用扩展实现Python 层就能搞定加一个右侧可停靠的功能面板比如镜头备注质检清单加一条菜单命令比如把当前帧信息写入日志调整默认快捷键、面板显示顺序只是改界面和交互不碰解码与渲染不适合走这条路得进 C / 构建层新增图像格式、换解码器 —— 要动 tlRender / OIIO改播放引擎或时间线核心逻辑跨平台打包、签名、发版 —— 用sbuild-*.sh/package-*脚本一句话记住只动界面 状态就用扩展动数据怎么读进来就要进底层。下面先把手下的环境搭起来。二、动手前的准备搭建 DJV 插件开发环境扩展全部长在 Python 应用上所以第一步是让djv-python能跑起来。整个应用由四个 Python 模块堆叠而成ftkPy界面控件、tlRenderPy时间线与播放、djvPy数据模型、opentimelineio标准时间线包。你写代码时这四者基本都会用到。先克隆仓库到本地git clone https://gitcode.com/gh_mirrors/djv/DJV cd DJV默认构建里 Python 绑定是关着的。在etc/Config/local.cmake里打开这一个开关超构建会顺带把 pybind11、各 Python 模块一起编出来set(TLRENDER_PYTHON ON CACHE BOOL )再执行你平台的构建脚本Linux 用./sbuild-linux.shmacOS / Windows 各有对应脚本编出全部东西。构建完成后产物目录里会有一个知道解释器和模块路径在哪的启动器。下面这条命令用它打开一张样例图并把设置文件指到临时目录避免污染你平时的配置./build-Release/bin/djv-python -settingsFile /tmp/djv-test.json etc/SampleData/Charlie.jpg窗口正常弹出、能看到画面就说明环境通了。接下来不用碰构建改的都会是examples/python里的 Python 文件。现在去把代码的地图看清楚。三、看懂代码地图DJV 的 4 个扩展入口Python 应用的写法是一个文件管一件事djv.py是入口App.py建模型MainWindow.py建窗口其余文件就是动作、菜单、工具栏、工具。想扩展无非是在下面四个地方动刀扩展入口作用白话对应文件 / 目录工具面板 Tool右侧可停靠的功能面板如 Files、Colorexamples/python/Tools.py继承IToolWidget注册进FACTORY动作 Action一个能被菜单 / 工具栏触发的命令examples/python/*Actions.py建ftk.Action菜单 / 工具栏给动作挂上入口菜单位、图标、快捷键examples/python/Menus.py、ToolBars.py数据模型 Model存 UI 状态、被观察者读取的数据源lib/djv/Models/CPython 经djv.models访问其中有个关键约定模型存状态控件只观察模型、不直接改它。控件通过 setter 改模型再靠观察者从模型拿更新这样同一份状态的每个视图都能保持同步。记住这两条后面写什么都顺观察者对象要留一个引用赋给self丢掉了就断开。回调里要用弱引用捕获selfweakref因为模型比控件活得久。看懂了这四个入口就可以动手写第一个插件了。四、实战从零写出第一个可运行的 DJV 插件我们不造一个全新概念而是选一个模型里已登记、但 Python 版还没实现的工具——Diagnostics诊断面板。它已经躺在数据模型的工具清单里有名字、图标、排序只是 Python 应用还没给它配实现。你只要补上实现、注册进FACTORY菜单和工具栏就会自动把它列出来完全不用碰 C。第 1 步写面板类。在examples/python/Tools.py里新增一个继承IToolWidget的类基类已经帮你画好标题行和关闭按钮你只管放内容。这里先放一个等宽字体的标签class DiagnosticsTool(IToolWidget): def __init__(self, context, app, parent None): IToolWidget.__init__( self, context, app, Diagnostics, DiagnosticsTool, parent) self._label ftk.Label(context) self._label.font ftk.FontType.Mono self._label.marginRole ftk.SizeRole.MarginSmall self._setContent(self._label) selfWeak weakref.ref(self) self._playerObserver tl.PlayerObserver( app.observePlayer(), lambda player: selfWeak()._playerUpdate(player)) def _playerUpdate(self, player): self._label.text player.path.get() if player else (无文件)注意selfWeak弱引用 把观察者存到self这是上一节那两条约定的落地。第 2 步注册进工厂。在Tools.py底部的FACTORY字典里加一行。菜单和工具栏的动作是用模型清单 ∩ FACTORY生成的所以这一加入口就自动出现FACTORY { Files: FilesTool, # ... 其余已有工具 ... Diagnostics: DiagnosticsTool, }第 3 步运行并验证。用临时设置文件重新打开一张图./build-Release/bin/djv-python -settingsFile /tmp/djv-test.json etc/SampleData/Charlie.jpg打开顶部Tools 菜单你会看到新出现的Diagnostics点一下右侧停靠出你的面板标签里显示当前文件路径。跑通这一步你就拥有了一个真正能用的扩展。想用一个模型里根本没有的全名那就多一步在App.run()里创建完toolsModel之后用addTool登记一个ToolInfo名字、图标、排序、是否上工具栏再走上面两步即可。Diagnostics 之所以零模型改动正是因为它早已登记。下一步让这个插件更稳。五、让插件更稳配置、异常处理、性能三板斧能跑只是开始下面三件事决定它经不经得住用。配置别写死交给模型。工具里的开关、数值都走模型存取。DJV 的选项是值拷贝——要改一个字段得读出来、改、再写回settings getattr(model, cache) settings.videoGB 32.0 setattr(model, cache, settings)命令行层面用-settingsFile、-logFile把测试配置隔离出去-resetSettings一键还原-screenshot可在不弹窗的情况下直接落一张截图方便你留证据。异常处理别让回调把异常抛进 UI 主循环。回调交给 C 侧时被一个std::function攥着Python 的垃圾回收看不见这条边如果你强引用self就会形成永远收不掉的引用环——控件活到最后设置也就写不回磁盘。项目里提供了Util.weak帮你包一层弱引用回调里一律用它clearButton.setClickedCallback( lambda: Util.weak(self._doClear)())同时给重逻辑套一层try/except出错只记日志、不影响主程序。性能主线程别干重活。解析大文件、生成缩略图这类耗时操作放到后台线程别在观察者回调里做大规模重建能增量刷新就别整块重画。面板更新频繁时这一步最容易被忽略也最容易让播放卡住。把这三点做扎实就可以去看进阶方向了。六、进阶方向自选菜单第一个面板跑通后按你团队的真实痛点挑一个深入即可方向解决什么问题难度导出 / 批处理面板批量落盘、多格式导出替代手动逐个存中镜头元数据质检交付前自动核对帧率、分辨率、时长低 - 中自定义颜色 / OCIO 工作流统一色彩交付流程一键切换 LUT中定制循环 / 时间码规则特殊放映、回放、评审节奏中每个方向都能先按第四节的套路起一个最简面板再逐步填控制项。建议从镜头元数据质检下手它最接近现成的只读面板最容易出成果。七、避坑清单新手几乎都会踩这几个坑照着陷阱 → 原因 → 怎么绕来排陷阱原因怎么绕勾选项点击没反应checkedCallback被当位置参数传绑定到了普通回调必须用关键字参数checkedCallback ...UI 不再跟着模型更新观察者对象用完就丢被回收后观察断开把观察者赋给self留住控件关不掉、设置没落盘回调强引用self形成引用环用weakref/Util.weak弱引用改了选项却没生效只改了取出来的副本忘了写回模型读 → 改 → 写回那一步别省播放掉帧、界面卡顿在主线程做了解析 / 缩略图耗时活移后台线程测试把正式配置改坏了直接用了默认设置文件用-settingsFile指向临时文件排完这些坑就按清单走发布流程。八、发布上线 Checklist合入前逐项打勾别漏代码遵循观察者 弱引用模式无引用环回调异常不冒泡到 UI代码Diagnostics之类的新工具已注册进FACTORY全新名字已在模型登记测试手动开一次窗口验证菜单 / 面板用-screenshot留一张证据图跑通tests/djvPyTest文档给工具补上tooltip和 docstring在 README 写清用途与快捷键版本在变更日志里按语义化版本记一笔注明新增 / 修改清单全绿就可以推给团队用了。接下来规划一下学习节奏。九、下一步学习路径不必一上来就追大而全按这个顺序台阶一步步走每级都有可交付的东西先跑通把djv-python完整编出来打开样例图把官方 Python 示例docs/python.html通读一遍弄懂模型存状态、控件只观察这条主线。再扩面照第四节做一个只读面板 一条菜单动作再给它加一个受模型控制的开关体会读→改→写回。后沉淀把改动整理成可提交的小 PR配好截图与文档跟着tests/djvPyTest的写法补个最小用例让下一个接手的同事也能快速上手。每完成一级你就离能维护这套扩展更近一步。结尾现在立刻可以做的 3 件事打开开关、跑起来在etc/Config/local.cmake打开 Python 构建开关编出djv-python用样例图开一次窗口。写你的第一个面板照第四节做出Diagnostics确认它出现在 Tools 菜单并能停靠。给它加一条动作按动作 菜单入口加一条命令跑一遍配置 / 异常 / 性能三板斧按发布清单走一遍。扩展的本质很简单模型管状态控件管呈现你负责把它们接起来。跑通第一个面板之后你会发现加第二个、第三个几乎只是复制粘贴加改名。现在就从打开那个构建开关开始吧。【免费下载链接】DJVFree EXR file viewer. DJV is a free, open-source high bit-depth image sequence player built for professional film, VFX animation workflows. Use it for frame-accurate dailies, shot review, and A/B comparisons. Available for Linux, macOS, and Windows.项目地址: https://gitcode.com/gh_mirrors/djv/DJV创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考