音视频视频处理图形学桌面应用【免费下载链接】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 的Int3DTuple工具类它是NatronEngine模块内置的返回值容器用于承载三维整数参数Int3DParam的[x, y, z]值。文章以 Int3DTuple.rst 文档为主线结合 Int3DParam.rst 与 Engine/PyParameter.cpp 源码实现系统讲解它的数据结构、成员访问方式、与参数读写方法的配合使用以及底层调用链。读完本文你将能够在 Natron 的 Python 脚本中熟练地通过get().x / get().y / get().z读取三维整数参数并用set(x, y, z[, frame])写入值或关键帧。Int3DTuple 是什么三维整数的返回值容器根据官方 API 参考文档的 SynopsisInt3DTuple.rst描述Int3DTuple是Utility class to return pair of integers values——一个用于返回整数数值组合的工具类。它本身不是参数对象而是 NatronEngine 中一类特殊的元组Tuple类型专为三维整数参数设计。在 Natron 的 Python 绑定体系中NatronEngine模块由引擎原生加载任何 Python 脚本包括 PyPlugs、表达式与交互脚本都可以无需 import 直接使用其中全部类参见 NatronEngine 模块索引Int3DTuple即是其中之一。从源码角度看Int3DTuple在 Engine/PyParameter.h 中定义为一个极简的结构体struct Int3DTuple { int x, y, z; };它与同文件中定义的Int2DTupleEngine/PyParameter.h、Double2DTuple、Double3DTuple、ColorTuple属于同一族返回值小助手结构体。头文件注释明确说明了这类结构体的设计初衷Engine/PyParameter.hSmall helper struct that is returned by the get() function of all params type so the user can write stuff likemyParam.get().x即让用户能够写出myParam.get().x这样直观的取值代码这正是Int3DTuple存在的核心意义。类成员与访问方式Int3DTuple.rst 文档定义了类的完整接口包含两个属性与一个方法成员类型说明NatronEngine.Int3DTuple.xattribute第一维整数值NatronEngine.Int3DTuple.yattribute第二维整数值NatronEngine.Int3DTuple.zattribute第三维整数值NatronEngine.Int3DTuple.__getitem__(index)method方括号运算符[]按下标返回对应维度的值属性访问.x/.y/.z这是最常用、最推荐的访问方式。由于Int3DTuple对应的 C 结构体直接暴露了x、y、z三个int字段Engine/PyParameter.hPython 侧可以直接以属性方式读取# 假设 translate 是一个 Int3DParam 类型的参数 val translate.get() print(val.x, val.y, val.z)下标访问__getitem__(index)文档中的方法签名为Int3DTuple.rst__getitem__(index) :param index: PySide.QtCore.int :rtype: PyObject它实现的是 Python 的方括号运算符[]即在 Python 侧可以直接书写val[0]、val[1]、val[2]。其行为由 Shiboken 类型系统注入代码实现定义在 Engine/typesystem_engine.xml 中逻辑要点如下下标0返回x下标1返回y下标2返回z下标越界index 0或index 3时调用PyErr_BadArgument()抛出参数错误而不是静默返回错误值返回值经%CONVERTTOPYTHON[int]转换为 Python 原生int因此rtype为PyObject。val translate.get() print(val[0], val[1], val[2]) # 等价于 val.x, val.y, val.z对比同族类型可见这是统一的设计模式Int2DTuple的下标注入代码允许0..1Engine/typesystem_engine.xml 附近Double3DTuple的注入代码与Int3DTuple结构完全相同Engine/typesystem_engine.xml只是返回类型换为double。Int3DTuple 的诞生地Int3DParam 的 get() 方法Int3DTuple几乎总是由三维整数参数Int3DParam的get()方法返回。在 Int3DParam.rst 中get()被定义如下Returns aInt3DTuplecontaining the [x,y,z] value of this parameter at the timelines current time.即返回当前时间线上该参数的[x, y, z]值封装为Int3DTuple。另有带帧参数的重载get(frame)返回指定帧上的值Int3DParam.rst。查看其底层实现Engine/PyParameter.cppget()的实际行为是依次调用KnobInt::getValue(0 / 1 / 2)填充结构体的三个字段Int3DTuple Int3DParam::get() const { KnobIntPtr knob _intKnob.lock(); Int3DTuple ret {0, 0, 0}; if (!knob) { return ret; // 底层旋钮失效时返回全零元组 } ret.x knob-getValue(0); ret.y knob-getValue(1); ret.z knob-getValue(2); return ret; }而带帧参数的版本Engine/PyParameter.cpp则使用getValueAtTime(frame, dimension)在每个维度上求值Int3DTuple Int3DParam::get(double frame) const { Int3DTuple ret {0, 0, 0}; KnobIntPtr knob _intKnob.lock(); if (!knob) { return ret; } ret.x knob-getValueAtTime(frame, 0); ret.y knob-getValueAtTime(frame, 1); ret.z knob-getValueAtTime(frame, 2); return ret; }两个值得注意的实现事实动画感知getValueAtTime与getValue都遵循 IntParam 的文档约定——若该维度被动画化则按用户选择的插值方式插值类型见 AnimatedParam 文档在关键帧之间插值若未被动画化则直接返回静态值。空指针防护当底层KnobInt已失效时两个get()均返回{0, 0, 0}全零元组保证脚本不会因访问空对象而崩溃。参数类继承链IntParam → Int2DParam → Int3DParam要正确使用Int3DTuple有必要理解它的生产者Int3DParam在类体系中的位置。根据 Int3DParam.rst 与 Int2DParam.rst 的继承声明IntParam ← 一维整数参数基础类见 IntParam.rst └─ Int2DParam ← 二维整数参数返回 Int2DTuple └─ Int3DParam ← 三维整数参数返回 Int3DTuple这一继承链在源码 Engine/PyParameter.h 中得到完全印证Int2DParam : public IntParam新增get()、get(frame)、set(x, y)、set(x, y, frame)Int3DParam : public Int2DParam在二维基础上增加z维度并隐藏private 声明了父类的set(int x)与set(int x, int y)单维/二维重载Engine/PyParameter.h强制调用方使用完整的三维set(x, y, z)避免维度缺失造成歧义。IntParam.rst 也明确指出An int param can have 1 to 3 dimensions一维的getDefaultValue(dimension)等方法的dimension参数正是为Int2DParam、Int3DParam这类多维子类准备的IntParam.rst。也就是说除了元组式get()你始终可以用getValue(dimension)/getValueAtTime(time, dimension)按维度索引读取任意一维的值IntParam.rst。写入三维整数set(x, y, z) 与 set(x, y, z, frame)Int3DTuple描述的是读取侧的数据结构与之对应的写入侧是Int3DParam的set()方法。文档定义了两个重载Int3DParam.rst方法参数行为set(x, y, z)x, y, z: int在当前时间线时间设置三维值若参数已动画化则自动在当前时间添加关键帧继承自 IntParam.set(x) 的语义set(x, y, z, frame)x, y, z: intframe: float在指定frame设置关键帧源码实现展示了写入时的事务性处理Engine/PyParameter.cppvoid Int3DParam::set(int x, int y, int z) { KnobIntPtr knob _intKnob.lock(); if (!knob) { return; } knob-beginChanges(); // 开启批量修改 knob-setValue(x, ViewSpec::current(), 0); // 维度 0 knob-setValue(y, ViewSpec::current(), 1); // 维度 1 knob-setValue(z, ViewSpec::current(), 2); // 维度 2 knob-endChanges(); // 一次性提交触发一次求值/UI 刷新 }beginChanges()/endChanges()包裹三维写入确保 x、y、z 三处赋值作为一个原子事务提交避免中间态被渲染线程或 UI 观察到。带帧的重载则直接调用底层批量关键帧写入setValuesAtTime(frame, x, y, z, ViewSpec::current(), eValueChangedReasonNatronInternalEdited)Engine/PyParameter.cpp。典型脚本示例以下是一个在 Natron Python 控制台中操作三维整数参数的完整流程以创建插件时注册的Int3DParam类型参数为例# 读取返回 Int3DTuple属性与下标两种方式等价 val myNode.my3DIntParam.get() print(val.x, val.y, val.z) # 属性访问 print(val[0], val[1], val[2]) # 下标访问越界会抛参数错误 # 按帧读取自动按插值方式计算 val_at_frame myNode.my3DIntParam.get(50.0) # 写入当前时间线位置 myNode.my3DIntParam.set(10, 20, 30) # 写入关键帧在指定帧打点 myNode.my3DIntParam.set(10, 20, 30, 1.0) myNode.my3DIntParam.set(20, 40, 60, 50.0) myNode.my3DIntParam.set(30, 60, 90, 100.0) # 按维度单独访问IntParam 继承而来的能力 x_only myNode.my3DIntParam.getValue(0) y_at_time myNode.my3DIntParam.getValueAtTime(50.0, 1)边界情况与使用注意事项结合文档与源码使用Int3DTuple时有几点值得注意越界下标val[3]或val[-1]会触发PyErr_BadArgument()Engine/typesystem_engine.xml在 Python 侧表现为参数错误异常脚本中应先确认维度数量再取下标。维度数量不匹配三维元组只适用于三维整数参数二维整数参数返回的是Int2DTupleInt2DParam.rst浮点参数则对应Double2DTuple/Double3DTuple颜色参数对应ColorTuple四维r/g/b/a见 Engine/PyParameter.h使用时注意类型对应。返回类型语义文档中__getitem__的rtype声明为PyObject是因为返回的 Python 对象类型由下标动态决定但实际返回值均为intC 侧%CONVERTTOPYTHON[int]转换。失效防护底层旋钮失效时get()返回{0, 0, 0}Engine/PyParameter.cpp因此在节点被删除等异常场景下脚本得到的是全零元组而非崩溃。扩展阅读Int3DTuple API 参考本篇主题的原始文档Int3DParam API 参考三维整数参数的get/set完整签名Int2DParam API 参考 与 Int2DTuple API 参考二维对应类型IntParam API 参考一维基础类与getValue(dimension)系列方法Param API 参考所有参数类型的公共基类NatronEngine 模块索引全部内置 Python 类列表核心实现Engine/PyParameter.h 与 Engine/PyParameter.cpp、Engine/typesystem_engine.xml赞分享音视频视频处理图形学桌面应用【免费下载链接】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 详解Int3DParam 三维整数参数的使用与底层实现Natron Python 脚本 API 详解Int3DParam 三维整数参数的使用与底层实现 本文以 Natron 开源仓库中 NatronEngine音视频视频处理图形学桌面应用Natron Python API 深度解析Int2DParam 二维整数参数Natron Python API 深度解析Int2DParam 二维整数参数 Int2DParam 是 Natron 节点式合成软件中表示 二维整数参数 的音视频视频处理图形学桌面应用Natron Python API 详解Int2DTuple 二维整型参数返回值容器Natron Python API 详解Int2DTuple 二维整型参数返回值容器 导读 Int2DTuple 是 Natron 的 Python 绑定模块音视频视频处理图形学桌面应用上一篇30分钟快速搭建个人博客基于GitHub Pages的零基础教程下一篇快速上手CoreUI免费Angular管理模板终极安装与配置指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考