企业官网建设流程全解析

• 音视频
• 视频处理
• 图形学
• 桌面应用

本篇技术指南以 Natron 官方文档《Python API》（APIReference.rst）为骨架，系统梳理 Natron 暴露给 Python 的两大模块NatronEngine（核心引擎、任何模式下可用）与NatronGui（仅 GUI 模式可用），并深入讲解PyCoreApplication、App、Effect、Param等核心类的成员函数、参数语义与底层实现依据。读完本文，你将能够直接编写可运行的 Natron Python 脚本：创建与连接节点、读写参数与关键帧、设置表达式、添加用户参数，并在命令行背景模式（Natron -b/NatronRenderer）下完成自动化渲染流程。

一、Natron Python API 的总体架构

Natron 在启动时将自身的 Python 接口划分为两个原生加载的内置模块，所有类与全局对象都罗列在官方 API 参考中：

• NatronEngine：核心模块，任何执行模式下都会由 Natron 原生加载，即无需任何import即可在脚本中访问其中的类。参考 NatronEngine/index.rst。该模块包含App、Effect、Param、PyCoreApplication、Roto、Tracker等全部 43 个类页面。
• NatronGui：仅在 GUI 模式下加载的扩展模块，包含GuiApp、PyGuiApplication、PyModalDialog、PyPanel、PyTabWidget、PyViewer等 6 个类页面，参考 NatronGui/index.rst。

两个模块之间通过继承关系衔接：NatronGui.GuiApp继承自NatronEngine.App，NatronGui.PyGuiApplication继承自NatronEngine.PyCoreApplication，因此 GUI 对象天然拥有引擎模块的全部能力。

1.1 全局对象 natron 与导入规范

Natron 进程内存在唯一的natron变量，分别指向NatronEngine.PyCoreApplication或NatronGui.PyGuiApplication，具体取决于你导入哪个模块。官方文档（natronobjects.rst）明确给出以下导入规则：

# 错误：同时导入会导致 natron 指向不符合预期 # from NatronEngine import * # from NatronGui import * # 正确：分别导入模块 import NatronEngine import NatronGui # 方便起见，可以给两个 natron 取别名 from NatronEngine import NatronEngine.natron as NE from NatronGui import NatronGui.natron as NG

如果你只使用from NatronEngine import *，则natron指向PyCoreApplication；如果需要 GUI 功能，必须改用from NatronGui import *获取PyGuiApplication。

1.2 GUI 与背景模式的守卫写法

由于NatronGui在命令行背景模式下并不存在，任何"既要后台跑又要 GUI"的脚本都必须先查询运行模式。官方推荐写法：

if not NatronEngine.natron.isBackground(): # 仅在 GUI 模式下执行的代码放在这里 pass

这一模式贯穿所有需要区分执行环境的 API 调用（如Effect.setPosition、getPosition等 GUI 相关函数在背景模式中无效）。

二、自动声明变量：script-name 与 label

Natron 为Effect、Param、Layer、BezierCurve、App、Track、PyCoreApplication、PyTabWidget、PyViewer、PyPanel等对象在创建时自动声明 Python 变量（详见 scriptvslabel.rst），使得可以直接用变量访问：

node = app1.Blur1 # 而不是 app1.getNode("app1.Blur1")

为了满足 Python 语法，每个对象都有两个名字：

1. script-name：用于自动声明变量的名字，只含字母数字、不以数字开头、创建后不可更改、全局唯一；
2. label：显示在界面上的名字，可含任意字符、可重名。

函数传参（如getParam(name)、createNode的pluginID）一律使用 script-name。script-name 的获取途径：GUI 中悬停节点标签的工具提示（见 nodeScriptName.png）、参数工具提示（paramScriptName.png），或代码中调用getScriptName()。

三、PyCoreApplication：进程级全局 API

PyCoreApplication（参考 PyCoreApplication.rst）代表唯一的Natron 后台进程实例，通过预声明的natron访问。它不承载项目数据，只提供环境、版本、插件与回调管理能力。对应的 C++ 实现位于 Engine/PyAppInstance.cpp。

3.1 环境与版本查询

3.2 插件发现

ids = natron.getPluginIDs() # 全部已加载插件 ID ids = natron.getPluginIDs("Blur") # 仅包含 "Blur"（不区分大小写）

3.3 回调注册与搜索路径

natron.setOnProjectCreatedCallback("myOnProjectCreated") # 等价于 NatronEngine.settings.afterProjectCreated.set(...) natron.setOnProjectLoadedCallback("myOnProjectLoaded") # 等价于 NatronEngine.settings.defOnProjectLoaded.set(...) natron.appendToNatronPath("/path/to/plugins") # 追加插件搜索路径 paths = natron.getNatronPath()

回调函数注册可覆盖 Preferences → Python 中对应项，官方推荐在init.py中利用它完成"所有项目通用初始化"（例如批量添加格式）。

3.4 实例访问

app = natron.getInstance(0) # 0 基索引，返回 app1 app = natron.getActiveInstance() # 用户最后交互的项目 count = natron.getNumInstances()

注意getInstance的索引是0 基的：取app1要传 0。

四、App：项目实例 API

App（参考 App.rst）代表一个打开的项目，继承自Group。每打开一个新项目自动创建一个 App，由 Natron 预声明为app1、app2……背景模式下永远只有一个项目，Natron 会自动执行app = app1，因此脚本无需关心实例编号。

4.1 创建节点

createNode(pluginID[, majorVersion=-1[, group=None[, properties=None]]])是核心入口：

reader = app.createNode("fr.inria.openfx.ReadOIIO") # 最高版本 group = app.createNode("fr.inria.built-in.Group") reader = app.createNode("fr.inria.openfx.ReadOIIO", -1, group) # 放入 group

majorVersion=-1表示实例化插件最高可用版本。便捷封装createReader(filename)/createWriter(filename)会依据文件名自动挑选"最佳"解码/编码插件（多个插件可处理同格式时，如 ReadPSD 与 ReadOIIO 均可读 .psd，Natron 按 Preferences 中的设置选择；若需指定，则改用createNode加精确插件 ID）。相关 C++ 实现可参见 Engine/PyAppInstance.cpp 的App::createNode。

4.1.1 createNode 的 properties 字典

properties是一个字典，键为下述属性名，值为对应的包装类型实例：BoolNodeCreationProperty、IntNodeCreationProperty、FloatNodeCreationProperty、StringNodeCreationProperty。官方完整示例：

app.createNode( "net.sf.cimg.CImgBlur", -1, app, dict([ ("CreateNodeArgsPropSettingsOpened", NatronEngine.BoolNodeCreationProperty(True)), ("CreateNodeArgsPropNodeInitialParamValues", NatronEngine.StringNodeCreationProperty("size")), ("CreateNodeArgsPropParamValue_size", NatronEngine.FloatNodeCreationProperty([2.3, 5.1])) ]) )

全部受支持属性（未知属性会在 Script Editor 打印警告）：

其中"初始参数值"机制对应 C++ 端CreateNodeArgs的属性系统（见 Engine/CreateNodeArgs.cpp 与 Engine/CreateNodeArgs.h）。

4.2 项目格式与图层管理

app.addFormat("HD 1920x1080 1") # 名称(无空格) 宽x高 像素宽高比；格式错误会被忽略并打印警告 app.addProjectLayer(ImageLayer) # 追加项目级图层，名字唯一，各节点图层菜单需手动刷新 names = app.getViewNames() # 项目设置 Views 标签页中定义的所有视图名

4.3 渲染

两种重载形式：

# 形式一：渲染单个 effect 的帧范围 app.render(effect, 1, 10, 2) # 渲染帧 1,3,5,7,9；frameStep 默认取 Write 节点的 Frame Increment # 形式二：任务列表，各任务并发渲染（多 Writer 后台渲染即走此路径） app.render([(writer1, 1, 10, 1), (writer2, 1, 10, 1)])

render仅在背景模式下是阻塞调用（渲染结束才返回），且官方限定仅用于 Write 节点或 DiskCache 节点。GUI 模式下请使用NatronGui.GuiApp.renderBlocking。

4.4 时间线与项目存取

lb = app.timelineGetLeftBound() # 项目帧范围左边界 rb = app.timelineGetRightBound() # 右边界 t = app.timelineGetTime() # 当前时间（全部 Viewer 共享同一条时间线） appid = app.getAppID() # 0 基实例编号 ok = app.saveProject("path.ntp") # 保存；GUI 模式下 filename 为空则弹窗询问 ok = app.saveProjectAs("path.ntp") # 另存为 ok = app.saveTempProject("path.ntp") # 保存副本但不更新项目路径/最后保存时间等项目属性 newApp = app.loadProject("path.ntp") # GUI 下当前窗口有改动时开新窗口；背景模式下替换当前项目 ok = app.resetProject() # 关闭当前项目不关窗口；GUI 下用户可取消 ok = app.closeProject() # 同 resetProject 但关闭窗口；最后一个 App 关闭时 Natron 退出 newApp = app.newProject() # 新建项目

项目参数与全局偏好设置均为Param类型：

param = app.getProjectParam("frameRange") # 项目设置参数 settings = natron.getSettings() # 全部偏好设置（AppSettings 对象）

app.writeToScriptEditor(message)可向 Script Editor 面板输出信息、警告或错误，是脚本与用户交互的重要通道。

五、Effect：节点 API

Effect（参考 Effect.rst）继承Group与UserParamHolder，代表节点图中一个插件实例。节点创建后，Natron 自动为它声明同名变量并暴露全部参数与输入。

5.1 输入管理

输入以0 基索引映射：

inp = node.getInput(0) # 或按输入名 node.getInput("Source") ok = node.connectInput(0, otherNode) # 内部先调用 canConnectInput 校验 node.disconnectInput(0) # 断开输入 n = node.getMaxInputCount() # 输入箭头数量 lab = node.getInputLabel(0) # 节点图中输入箭头上的标签

canConnectInput(inputNumber, node)返回 False 的情形包括：该输入位已有连接、node 为 None、输入位越界、node 不可被连接（如 BackDrop/Output）、存在循环引用等。

5.2 参数访问

p = node.getParam("size") # 按 script-name 取参数，不存在返回 None ps = node.getParams() # 全部参数序列

5.3 变更批处理

beginChanges()/endChanges()构成阻塞评估的括号：括号内所有setValue、输入连接变化都不会触发渲染与onParamChanged回调，直到endChanges()将全部变更压缩为一次求值：

node.beginChanges() param1.setValue(...) param2.setValue(...) node.connectInput(0, otherNode) node.endChanges() # 此刻才触发一次新渲染

这是避免"改多个参数导致多次无效渲染"的标准手段，对应引擎层求值抑制机制。

5.4 节点信息与销毁

pid = node.getPluginID() # 该节点实例化的插件 ID bd = node.getBitDepth() # 输出位深（ImageBitDepthEnum） pm = node.getPremult() # 输出预乘状态 fmt = node.getOutputFormat() # 输出格式（RectI，像素单位） fps = node.getFrameRate() par = node.getPixelAspectRatio() rod = node.getRegionOfDefinition(time, view) # 规范坐标下输出包围盒（RectD），即设置面板 Info 标签页的 Output 值 layers = node.getAvailableLayers() # dict: ImageLayer -> 产生该图层的最上游 Effect node.destroy(autoReconnect=True) # 永久移除节点；autoReconnect=True 时下游自动改接本节点输入

另有判定类函数：isReaderNode()、isWriterNode()、isOutputNode()（无输出的输出节点）。

5.5 节点图外观控制（仅 GUI 有效）

node.setPosition(x, y) # 背景模式下无效（getPosition 恒返回 [0,0]） node.setSize(w, h) node.setColor(r, g, b) # [R,G,B] 三元组 node.setLabel(name) # 显示名 node.setScriptName(name) # 内部名；重命名后旧变量失效，需用新名访问 node.isUserSelected()

setScriptName有重要副作用：会删除旧 script-name 声明的变量并新建新变量，例如把app1.Blur1改为BlurOne后，app1.Blur1会抛出NameError。

5.6 自定义输出平面

node.addUserPlane("MyLayer", ["R", "G", "B", "A"])

planeName不得含空格或非 Python 合规字符；通道数至少 1、至多 4。成功后，最终用户可在节点设置面板的 Channels 选择器中选用该平面输出。

5.7 子图与页面控制

node.setSubGraphEditable(False) # 禁止用户在 GUI 中编辑该 group 子图，防止误破坏 node.setPagesOrder(["Settings", "User"]) # 按 script-name 重排设置面板页面顺序 node.getUserPageParam() # 用户页面参数（PageParam），不存在返回 None

六、Param 体系：参数基类与属性语义

Param（参考 Param.rst）是所有参数的基类：节点设置面板中的每个控件、项目设置、偏好设置都是一个 Param。其继承树为：

• Param→ParametricParam、PageParam、GroupParam、ButtonParam
• Param→AnimatedParam→StringParamBase（→StringParam、FileParam、OutputFileParam、PathParam）、BooleanParam、ChoiceParam、ColorParam、DoubleParam/Double2DParam/Double3DParam、IntParam/Int2DParam/Int3DParam

6.1 参数属性总表

官方文档给出完整属性表（下表为精简整合，完整表见 Param.rst）：

重要语义：

• 带(*)的 Setter只能作用于用户参数，对 OpenFX 插件声明的参数无效；
• 非动态属性必须在调用refreshUserParamsGUI()之前设置，GUI 生成后不可再改；
• 注(1)：animates默认仅在 IntParam/Int2DParam/Int3DParam、DoubleParam/Double2DParam/Double3DParam、ColorParam 上为 True；ParametricParam、GroupParam、PageParam、ButtonParam、FileParam、OutputFileParam、PathParam 完全不可动画；
• enabled=False时参数文字变黑且不可编辑；visible=False时从界面隐藏。

6.2 常用方法

p.copy(otherParam) # 复制值/动画/表达式；dimension=-1 时复制 min(两个参数维度数)；类型需可转换（StringParam 不可转换） val = p.curve(time) # 取动画曲线在该时间的值；忽略叠加的表达式 p.slaveTo(otherParam, thisDim, otherDim) # 本参数 thisDim 受控于 otherParam 的 otherDim，直到 unslave(thisDim) p.unslave(dimension) ok = p.setAsAlias(otherParam) # 别名：完全控制 otherParam（同类型同维度）；Choice 菜单会同步更新

copy与slaveTo要求类型匹配；copy只复制值而不复制属性，跨 ChoiceParam 复制时需保证索引对接收方有意义，否则会产生未定义行为。

6.3 可复现随机数

r = p.random(min=0., max=1.) # 同一参数在同一时间点恒返回相同值 r = p.random(min, max, time, seed) # 显式 time+seed 精确复现：random(0,1,frame,2)-random(0,1,frame,2) 恒为 0 i = p.randomInt(min, max) # 整数版 i = p.randomInt(min, max, time, seed)

多次在同一表达式调用random()会返回不同值，但同一时间点再次求值结果一致——这是制作循环、循环动画等程序化表达式的基石。底层实现见 Engine/PyParameter.cpp（Param::random/randomInt委托给 Knob 的random）。

七、动画与表达式：AnimatedParam

AnimatedParam（参考 AnimatedParam.rst）是所有可动画参数的基类。参数至少有 1 个关键帧才可动画，两个关键帧后 Natron 自动插值；新关键帧默认 Smooth 插值；表达式优先级高于动画曲线（表达式存在时参数值由表达式计算）。

p.setValueAtTime(value, time, dimension) # 派生类中具体实现，添加关键帧 p.deleteValueAtTime(time, dimension=0) p.getNumKeys(dimension=0) # 关键帧数量 idx = p.getKeyIndex(time, dimension=0) # 关键帧索引，不存在返回 -1 ok, t = p.getKeyTime(index, dimension) # (是否存在, 关键帧时间) p.removeAnimation(dimension=0) # 清除动画，但不清除表达式 p.setInterpolationAtTime(time, NatronEngine.Natron.KeyframeTypeEnum.eKeyframeTypeConstant, 0) p.getIsAnimated(dimension=0) # 曲线是否有 1+ 关键帧 d = p.getDerivativeAtTime(time, dimension=0) # 曲线导数（有表达式时无意义） v = p.getIntegrateFromTimeToTime(t1, t2) # 曲线区间积分（有表达式时无意义） expr = p.getExpression(dimension) p.setExpression("ret = frame * 0.5", False, 0) # hasRetVariable=False 时 Natron 自动声明 ret

setExpression的hasRetVariable决定表达式是否自带ret变量；若为 False，Natron 替你声明。C++ 端实现在 Engine/PyParameter.cpp（AnimatedParam::setExpression/getExpression）。

八、常用参数类型速览

• IntParam / Int2DParam / Int3DParam（参考 IntParam.rst）：1~3 维整数。get()/get(frame)、set(x)（已动画时自动在当前位置打关键帧）、set(x, frame)、setValue、setValueAtTime、getValueAtTime、getDefaultValue/setDefaultValue、getMinimum/setMinimum/getMaximum/setMaximum（硬边界，越界被 clamp）与getDisplayMinimum/setDisplayMinimum（滑块显示边界，内部值可超）。UI 截图见 doubleParam.png（Int 与 Double 界面相同）、double2DParam.png、double3DParam.png。
• DoubleParam / Double2DParam / Double3DParam：浮点版本，方法签名与 Int 系列对称（get、set、setValueAtTime、getValueAtTime、min/max/displayMin/displayMax 全套）。
• BooleanParam：复选框，set/get。
• ChoiceParam（参考 ChoiceParam.rst）：下拉菜单，内部存 0 基索引；addOption(option, help)、setOptions(list)、getOptions()、getNumOptions()、getOption(index)、set(label)（不区分大小写匹配选项，未命中无操作）、set(x)、setValueAtTime。
• ColorParam：RGBA 颜色（useAlpha控制是否含 Alpha 维），配合ColorTuple使用。
• StringParam / StringParamBase：文本；setType可切换类型（默认eStringTypeDefault）。
• FileParam / OutputFileParam / PathParam：文件/输出文件/目录路径，setSequenceEnabled控制序列对话框。
• GroupParam / PageParam / ButtonParam：分组（可折叠、可setAsTab变成选项卡）、设置面板页面（Tab）、按钮（点击回调见下文回调机制）。
• ParametricParam（参考 ParametricParam.rst）：参数化曲线，如 ColorLookup 节点或 ColorCorrect 节点的 Ranges 标签页。维度数等于曲线数（由createParametricParam(name,label,nbCurves)静态指定），操作方式与动画曲线类似：

status = curve.addControlPoint(dim, key, value) # 默认 Smooth 插值 status = curve.addControlPoint(dim, key, value, lDeriv, rDeriv) # 带左右导数 status = curve.setNthControlPoint(dim, nthCtl, key, value, lDeriv, rDeriv) status = curve.setNthControlPointInterpolation(dim, nthCtl, NatronEngine.Natron.KeyframeTypeEnum.eKeyframeTypeConstant) n = curve.getNControlPoints(dim) info = curve.getNthControlPoint(dim, nthCtl) # [status, key, value, 左导数, 右导数] y = curve.getValue(dim, parametricPosition) # X 轴上某位置的曲线 Y 值 curve.deleteControlPoint(dim, nthCtl) curve.deleteAllControlPoints(dim) curve.setCurveColor(dim, r, g, b) curve.setDefaultCurvesFromCurrentCurves()

所有增删控制点类函数返回NatronEngine.Natron.StatusEnum.eStatusOK（成功）或eStatusFailed（失败）。

九、用户参数：UserParamHolder

UserParamHolder（参考 UserParamHolder.rst）是Effect与PyModalDialog的抽象基类，提供createXParam系列工厂：

createBooleanParam、createButtonParam、createChoiceParam、createColorParam(name,label,useAlpha)、createDoubleParam、createDouble2DParam、createDouble3DParam、createFileParam、createGroupParam、createIntParam、createInt2DParam、createInt3DParam、createOutputFileParam、createPageParam、createParametricParam(name,label,nbCurves)、createPathParam、createStringParam。

关键规则：

node = app.createNode("net.sf.cimg.CImgBlur") p = node.createDoubleParam("mySize", "My Size") # (script-name, label) # ... 设置属性、默认值 ... node.refreshUserParamsGUI() # 必须调用，否则界面不更新 node.removeParam(p) # 只能移除用户参数，不能移除 OpenFX 插件参数

refreshUserParamsGUI()重建用户参数 GUI，开销较大，官方建议一次性批量修改后再调用一次；参数基类中的非动态属性也必须在此调用前设置完毕。

十、特殊上下文：Roto 与 Tracker

• Roto（参考 Roto.rst）：封装 Roto 节点的图层与形状管理，通过Effect.getRotoContext()获取（目前仅 Roto 节点有，其余节点返回 None）。

roto = app1.Roto1.roto layer = roto.createLayer() bezier = roto.createBezier(x, y, time) # 单控制点+关键帧 ellipse = roto.createEllipse(x, y, diameter, fromCenter, time) # fromCenter=True 时 (x,y) 为中心 rect = roto.createRectangle(x, y, size, time) # 边长 size 的正方形 base = roto.getBaseLayer() # 顶层父图层 item = roto.getItemByName("Bezier1") # 按 script-name 取项

形状可经自动声明变量访问：Roto1.roto.Layer1.Bezier1。Layer、BezierCurve、ItemBase详见各自参考页。

• Tracker（参考 Tracker.rst）：Effect.getTrackerContext()获取跟踪上下文，管理Track对象（目前仅 Tracker 节点有）。

十一、AppSettings：偏好设置编程访问

AppSettings（参考 AppSettings.rst）通过natron.getSettings()获取，行为与Effect的参数接口一致：

settings = natron.getSettings() p = settings.getParam("pluginID") # 按 script-name 取偏好参数 all = settings.getParams() # 全部偏好参数 settings.restoreDefaultSettings() # 恢复出厂默认 settings.saveSettings() # 持久化到磁盘，下次启动生效

十二、NatronGui 模块：GUI 专属 API

GUI 模式下natron指向PyGuiApplication（继承PyCoreApplication），项目对象为GuiApp（继承App）。参考 GuiApp.rst。

12.1 系统对话框

app.getFilenameDialog(filters, location) # 打开已存在文件；filters 为扩展名列表 app.getSequenceDialog(filters, location) # 序列文件版 app.getDirectoryDialog(location) app.saveFilenameDialog(filters, location) # 保存对话框，文件已存在时警告覆盖 app.saveSequenceDialog(filters, location) app.getRGBColorDialog() # 返回 ColorTuple

location为空时显示上次打开的位置。

12.2 选择、复制与布局

sel = app.getSelectedNodes(group) # group=None 用最后交互的 NodeGraph；传 app 取顶层 app.selectNode(node, clearPreviousSelection) app.deselectNode(node) app.setSelection(nodes) # 所有节点须在同一 NodeGraph app.selectAllNodes(group) / app.clearSelection(group) app.copySelectedNodes(group) / app.pasteNodes(group) tab = app.getTabWidget(scriptName) # 按 script-name 取选项卡（script-name 见 "Manage layout" 按钮提示） ok = app.moveTab(tabScriptName, pane) viewer = app.getViewer(scriptName) # viewer 的 script-name 即其关联节点的 script-name，如 app1.pane1.Viewer1 panel = app.getUserPanel(scriptName)

12.3 自定义面板与模态对话框

dialog = app.createModalDialog() # 模态对话框：可加用户参数或原生 PySide Qt 控件，exec() 弹出 panel = PyPanel(...) # 自定义 Python 面板（子类 PyPanel 或基于用户参数构建） app.registerPythonPanel(panel, "createPanelFunction") # 注册后随项目布局保存，并出现在 Panes 菜单 app.unregisterPythonPanel(panel)

面板重建依赖你提供的无参 Python 函数（pythonFunction）。相关类参考 PyModalDialog.rst、PyPanel.rst、PyTabWidget.rst、PyViewer.rst。

12.4 GUI 模式阻塞渲染

app.renderBlocking(effect, 1, 10, 2) # 与 App.render 语义一致，但任何模式都阻塞 app.renderBlocking([(w1, 1, 10), (w2, 1, 10)]) # 多任务并发渲染

十三、与命令行模式的衔接

掌握 API 后，最常见的落地场景是背景模式自动化（完整命令行说明见 natronexecution.rst）。Natron 有三种执行模式：执行.ntp项目、执行 Python 脚本、交互式解释器（-t）。

一个可复用的转码脚本模板：

# myStartupScript.py reader = app.createReader("/Users/Toto/Sequences/Sequence__####.exr") writer = app.createWriter("/Users/Toto/Sequences/Sequence.mov") writer.setScriptName("MyWriter") # 便于命令行 -w 引用 reader.setScriptName("MyReader") writer.getParam("formatType").setValue(0) # Input Stream Format，按输入尺寸输出 writer.connectInput(0, reader) # 背景模式下渲染由命令行参数触发；GUI 下需显式 app.render(writer, 10, 20)

命令行用法：

# 背景模式渲染指定 Writer 的帧范围 10-20 NatronRenderer /path/to/myStartupScript.py -w MyWriter 10-20 # 覆盖 Reader/Writer 文件路径（仅接受绝对路径） NatronRenderer /path/to/myStartupScript.py -i MyReader /Users/Toto/Sequences/AnotherSeq__####.exr -w MyWriter /Users/Toto/Sequences/mySeq.mov 10-20 # -c/--cmd 注入 Python 代码，多次给出按顺序执行 NatronRenderer /path/to/myStartupScript.py -c "fpsValue=60" -w MyWriter 10-20 # 用 -o/--output 将脚本中的 Output1 替换为 Write 节点 NatronRenderer -o /FastDisk/Pictures/sequence###.exr 1-100 /Users/Me/MyNatronScripts/MyScript.py # 渲染统计（每帧生成 -stats.txt，不含视频文件） NatronRenderer -s -w MyWriter /path/to/myProject.ntp # 交互式解释器 NatronRenderer -t /path/to/myStartupScript.py

关键提醒：背景模式下一旦脚本中无createInstance(app, group)函数，脚本全文按原生 Python 执行并拥有全部自动声明变量；若存在createInstance，则脚本以模块方式导入，只能访问传入的 app/group 参数。-l/--onload指定的脚本在项目创建/加载后、回调之后执行，与回调同规则。

十四、结语：从参考手册到工程实践

Natron 的 Python API 是一套自洽的对象模型：进程级PyCoreApplication→ 项目级App→ 节点级Effect→ 参数级Param/AnimatedParam，再加上 GUI 专属的NatronGui扩展。官方 API 参考（APIReference.rst）是唯一的权威索引，配套的 natronobjects.rst 讲解对象层次、scriptvslabel.rst 讲解命名体系、natronexecution.rst 讲解执行模式，三份文档与源码（如 Engine/PyAppInstance.cpp、Engine/PyParameter.cpp、Engine/CreateNodeArgs.cpp）相互印证。写脚本时牢记三条铁律：GUI 函数必须守卫isBackground()、用户参数修改后必须refreshUserParamsGUI()、批量改参务必包裹beginChanges()/endChanges()，即可在 GUI 与命令行两种模式下写出稳定、可复现的自动化流程。

• 音视频
• 视频处理
• 图形学
• 桌面应用