Natron Python API 深度解析：Int2DParam 二维整数参数-北京尧图网络

音视频视频处理图形学桌面应用【免费下载链接】NatronOpen-source video compositing software. Node-graph based. Similar in functionalities to Adobe After Effects and Nuke by The Foundry.项目地址https://gitcode.com/gh_mirrors/na/Natron点击查看免费下载Int2DParam 是 Natron 节点式合成软件中表示二维整数参数的 Python 绑定类常用于描述坐标、裁剪尺寸、栅格步长等成对出现的整数值如 [x, y]。本文以官方 Python API 参考文档Int2DParam.rst为骨架结合 Engine/PyParameter.cpp 与 Engine/PyParameter.h 的源码实现完整讲解 Int2DParam 的继承关系、get/set 四个重载方法、返回值类型 Int2DTuple以及它在用户自定义参数UserParamHolder中的创建方式帮助脚本开发者准确读写二维整数参数并在时间轴上打关键帧。一、Int2DParam 在 NatronEngine 模块中的定位Int2DParam 属于NatronEngine模块。根据 index.rst 的说明该模块由 Natron原生加载脚本中无需import即可直接访问其中的类。其继承关系见 Int2DParam.rst 头部Param ── AnimatedParam ── IntParam ── Int2DParam ── Int3DParam父类 IntParam一维整数参数提供get()、set(x)、getValue(dimension)、getValueAtTime(time, dimension)、setValue、setValueAtTime、setDefaultValue、getDefaultValue、restoreDefaultValue、setMinimum/getMinimum、setMaximum/getMaximum、setDisplayMinimum/setDisplayMaximum等一整套按维度操作的接口详见 IntParam.rst。Int2DParam两维整数参数即文档所述 An int param can have 1 to 3 dimensions 中的二维形态内部对应两个整数值 x 与 y。被继承者 Int3DParam三维整数参数x, y, z继承自 Int2DParam。在 C 侧的类定义中Engine/PyParameter.hInt2DParam公开继承IntParam额外声明了四个方法class Int2DParam : public IntParam { public: Int2DParam(const KnobIntPtr knob) : IntParam(knob) {} Int2DTuple get() const; Int2DTuple get(double frame) const; void set(int x, int y); void set(int x, int y, double frame); private: void set(int x); // 私有屏蔽父类一维 set };注意其中private: void set(int x);—— 二维参数在 Python 层屏蔽了父类的一维 set 调用强制脚本通过set(x, y)或set(x, y, frame)写入从编译层面杜绝只写一半值的误用。二、创建 Int2DParamUserParamHolder.createInt2DParamInt2DParam 通常作为用户自定义参数出现。Effect与Group等节点对象都实现了UserParamHolder接口可在节点的 User 页上动态创建二维整数参数p node.createInt2DParam(myOffset, My Offset)源码实现位于 Engine/PyNode.cppInt2DParam* UserParamHolder::createInt2DParam(const QString name, const QString label) { KnobIntPtr knob _holder-createIntKnob(name.toStdString(), label.toStdString(), 2); if (knob) { KnobPagePtr userPage _holder-getOrCreateUserPageKnob(); if (userPage) { userPage-addKnob(knob); } return new Int2DParam(knob); } else { return 0; } }关键点内部调用createIntKnob(name, label, 2)维度参数传入 2得到一个底层的KnobInt见 Engine/KnobTypes.h参数会被自动挂到节点的User 页getOrCreateUserPageKnobaddKnob因此在 GUI 的 User 面板中即可看到它返回的 Python 对象由 Shiboken 绑定Engine/typesystem_engine.xml 中声明了createInt2DParam(QString,QString)的返回值所有权归 target。作为对比createIntParam的维度是 1、createInt3DParam的维度是 3Engine/PyNode.cpp三者共用同一个createIntKnob工厂仅维度不同。三、读取二维整数get() 与 get(frame)文档为 Int2DParam 定义了两个 get 重载返回值均为Int2DTuple3.1 get() —— 当前时间点的值def get() # - Int2DTuple返回包含该参数在当前时间线timeline当前时间下的 [x, y] 值的Int2DTuple。3.2 get(frame) —— 指定帧的值def get(frame: float) # - Int2DTuple返回该参数在给定frame时刻的 [x, y] 值。3.3 返回值类型 Int2DTupleInt2DTuple是一个轻量辅助结构体用于成对返回整数值。其定义在 Engine/PyParameter.h/** * brief Small helper struct that is returned by the get() function of all params type * so the user can write stuff like myParam.get().x **/ struct Int2DTuple { int x, y; };在 Python 中可通过两种方式访问元素见 Int2DTuple.rst属性访问t.x、t.y下标访问t[0]、t[1]__getitem__(index)重载下标访问由 Shiboken 在 Engine/typesystem_engine.xml 中注入实现越界索引_i 0 || _i 2会抛出PyErr_BadArgument因此下标只能在 0 和 1 之间取值。3.4 源码级实现Engine/PyParameter.cpp 中两个 get 的实现Int2DTuple Int2DParam::get() const { Int2DTuple ret {0, 0}; KnobIntPtr knob _intKnob.lock(); if (!knob) { return ret; } ret.x knob-getValue(0); ret.y knob-getValue(1); return ret; } Int2DTuple Int2DParam::get(double frame) const { Int2DTuple ret {0, 0}; KnobIntPtr knob _intKnob.lock(); if (!knob) { return ret; } ret.x knob-getValueAtTime(frame, 0); ret.y knob-getValueAtTime(frame, 1); return ret; }从源码结构可以确认x 对应维度 0y 对应维度 1get(frame)分别对两个维度调用getValueAtTime(frame, dim)。如果曲线已设置动画可通过AnimatedParam.getIsAnimated(dimension)判断返回值将按该维度曲线的插值方式interpolation进行插值若未设置动画则返回该维度的静态值这一语义继承自 IntParam.rst 对getValueAtTime的描述源码注释见 Engine/PyParameter.h。四、写入二维整数set(x, y) 与 set(x, y, frame)文档定义了两个 set 重载4.1 set(x, y) —— 在当前时间点写入def set(x: int, y: int)同IntParam.set(x)的语义但作用于二维整数设置当前时间下的 x、y 两个值。若该参数已动画化getIsAnimated会自动在时间线当前时间处添加关键帧。源码Engine/PyParameter.cppvoid Int2DParam::set(int x, int y) { KnobIntPtr knob _intKnob.lock(); if (!knob) { return; } knob-beginChanges(); knob-setValue(x, ViewSpec::current(), 0); knob-setValue(y, ViewSpec::current(), 1); knob-endChanges(); }注意这里使用了beginChanges() / setValue / endChanges()的事务式写入确保两个维度在同一个变更块内提交GUI 只刷新一次避免中间态闪烁。4.2 set(x, y, frame) —— 在指定帧写入关键帧def set(x: int, y: int, frame: float)同IntParam.set(x, frame)的语义但作用于二维整数在给定frame处写入新的关键帧若该帧已存在关键帧则修改之。源码Engine/PyParameter.cppvoid Int2DParam::set(int x, int y, double frame) { KnobIntPtr knob _intKnob.lock(); if (!knob) { return; } knob-setValuesAtTime(frame, x, y, ViewSpec::current(), eValueChangedReasonNatronInternalEdited); }与set(x, y)逐个 setValue 不同带 frame 的版本直接调用底层KnobInt::setValuesAtTime(frame, x, y, ...)一次性写入两维关键帧并以eValueChangedReasonNatronInternalEdited标记为脚本编辑。4.3 Shiboken 绑定说明Shiboken 类型系统对这两个重载进行了显式声明Engine/typesystem_engine.xmlobject-type nameInt2DParam modify-function signatureset(int,int).../modify-function modify-function signatureset(int,int,double).../modify-function /object-type这意味着 Python 侧只能调用set(x, y)与set(x, y, frame)两个签名父类的set(x)被私有化屏蔽符合二维参数必须成对写入的设计。五、继承自 IntParam 的维度级接口实战常用Int2DParam 虽屏蔽了一维set但仍完整继承 IntParam 的维度化接口可直接以dimension0 或 1精确控制 x/y 分量。以下方法详见 IntParam.rst方法签名说明取值getValue([dimension0])当前时间下指定维度的值取值getValueAtTime(time[, dimension0])指定时间下指定维度的值动画则插值写值setValue(value[, dimension0])同set(value, dimension)当前时间写关键帧setValueAtTime(value, time[, dimension0])指定时间写关键帧默认值setDefaultValue(value[, dimension0])/getDefaultValue([dimension0])/restoreDefaultValue([dimension0])管理各维度默认值硬边界setMinimum(minimum[, dimension0])/setMaximum(maximum[, dimension0])设置 clamp 边界越界值会被钳制显示边界setDisplayMinimum/setDisplayMaximum仅限制滑块可见范围内部值可超出关于边界语义Engine/PyParameter.h 注释明确setMinimum/setMaximum不会限制用户在 GUI 输入更小/更大的值但getValue()/getValueAtTime()返回的结果会被钳制到该范围而 display 边界只影响滑块显示。这与 IntParam 一维语义完全一致只是维度参数 0/1 分别对应 x/y。六、完整实战示例结合上文一个典型的二维整数参数读写脚本如下在 Natron 脚本编辑器或 PySide 面板中执行# 在节点上创建二维整数参数自动挂到 User 页 p node.createInt2DParam(cropSize, Crop Size) # 设置默认值与边界 p.setDefaultValue(0, 0) # x 维度默认 0 p.setDefaultValue(0, 1) # y 维度默认 0 p.setMinimum(-10000, 0) p.setMaximum(10000, 0) p.setMinimum(-10000, 1) p.setMaximum(10000, 1) p.setDisplayMinimum(-1000, 0) p.setDisplayMaximum(1000, 0) # 当前时间写入 p.set(1920, 1080) # 在指定帧打关键帧 p.set(960, 540, 1) p.set(1920, 1080, 24) # 读取 t p.get() # 当前时间 - Int2DTuple print(t.x, t.y) # 属性访问 print(t[0], t[1]) # 下标访问仅限 0/1 t1 p.get(12.5) # 第 12.5 帧插值结果 print(t1.x, t1.y) # 按维度精确读写 p.setValue(1280, 0) # 仅写 x p.setValueAtTime(720, 24, 1) # 第 24 帧仅写 y vx p.getValue(0) # 读 x vy p.getValueAtTime(24.0, 1) # 第 24 帧的 y需要注意的限制set(x, y, frame)中 frame 为float类型对应 Python 的 float /PySide.QtCore.float即使传入整数帧号也应使用浮点语义理解Int2DTuple 下标越界会报参数错误请始终使用 0/1若节点不存在或参数已删除get()内部会因_knob失效返回{0, 0}的零元组见源码空指针分支脚本中建议先判空节点再访问。七、与 Int3DParam 及 UI 形态的呼应Int3DParam继承自Int2DParamEngine/PyParameter.h把 x/y 扩展为 x/y/z维度 0/1/2get()返回Int3DTupleset(x, y, z)/set(x, y, z, frame)同理Engine/PyParameter.cpp。三者共用KnobInt底层与IntParam的维度接口差异仅是维度数与 tuple 结构。在 GUI 中二维整数参数的控件形态与 Double2DParam 相同IntParam.rst 明确说明 Screenshots are the same than for the DoubleParam because the user interface is the same呈现为两个并排的整数输入框X、Y支持输入和打关键帧八、总结Int2DParam 是 Natron Python API 中处理成对整数参数的专用类通过createInt2DParam创建get()/get(frame)读取为Int2DTuple支持.x/.y属性与[0]/[1]下标set(x, y)与set(x, y, frame)实现当前时间写入与指定帧关键帧写入同时完整继承 IntParam 的维度化接口getValue、setValueAtTime、边界与默认值管理并屏蔽一维set以保证成对写。其源码实现集中在 Engine/PyParameter.cpp 与 Engine/PyParameter.h类型绑定声明位于 Engine/typesystem_engine.xml创建入口在 Engine/PyNode.cpp可结合 IntParam.rst、Int2DTuple.rst 与 Int3DParam.rst 继续深入阅读。赞分享音视频视频处理图形学桌面应用【免费下载链接】NatronOpen-source video compositing software. Node-graph based. Similar in functionalities to Adobe After Effects and Nuke by The Foundry.项目地址https://gitcode.com/gh_mirrors/na/Natron点击查看免费下载相关推荐Natron Python API 深度解析Double2DParam 二维浮点参数详解Natron Python API 深度解析Double2DParam 二维浮点参数详解导读 Double2DParam 是 Natron开源节点式视频合音视频视频处理图形学桌面应用Natron Python API 深度解析Double3DParam 三维浮点参数的使用与底层实现Natron Python API 深度解析Double3DParam 三维浮点参数的使用与底层实现 Double3DParam 是 Natron 节点图合成音视频视频处理图形学桌面应用Natron 布尔参数BooleanParamPython API 深度解析从函数用法到源码实现Natron 布尔参数BooleanParamPython API 深度解析从函数用法到源码实现 BooleanParam 是 Natron 开放 Pyt音视频视频处理图形学桌面应用上一篇webdav5分钟部署独立WebDAV服务器下一篇GHelper卸载Armoury Crate之后华硕笔记本还能怎么管创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Natron Python API 深度解析：Int2DParam 二维整数参数

相关推荐

Dev Container Feature 依赖解析规范：`dependsOn` 硬依赖与安装顺序算法详解

ant-design-blazor Table 自定义行样式实战：RowClassName 与 ExpandedRowClassName 全解析

mruby-array-ext 深入指南：为 mruby 的 Array 补齐标准库级数组能力

更多资讯

roLabelImg源码解析：旋转框标注工具从安装到二次开发

数据库图书管理系统实训全流程：从E-R图到JDBC事务与并发控制

图像质量评估模型Python实战：PSNR/SSIM/BRISQUE量化指南

CLion搭建树莓派Pico C/C++开发环境：从零到断点调试全攻略

ESP32 上实现 ONVIF 相机：从组件搭建到 NVR 添加实战

UC网盘下载不限速办法：亲测有效的免费提速思路与操作指南

今日更新

Susi AI API实战指南：susi_alexa_skill如何用Node.js调用chat.json获取智能回答

换新电脑了？KeyStats 恢复码数据找回完全指南，端到端加密统计一键重建

重建二叉树：由前序与中序遍历序列还原二叉树的原理与 Java 实现（YCBlogs 剑指 Offer 精讲）

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？