NatronEngine
Inherits: Group
, UserParamHolder
This object represents a single node in Natron, that is: an instance of a plug-in. See Effectdetails
- def
addUserPlane<NatronEngine.Effect.addUserPlane>
(planeName,channels) - def
endChanges<NatronEngine.Effect.endChanges>
() - def
beginChanges<NatronEngine.Effect.beginChanges>
() - def
canConnectInput<NatronEngine.Effect.canConnectInput>
(inputNumber, node) - def
connectInput<NatronEngine.Effect.connectInput>
(inputNumber, input) - def
destroy<NatronEngine.Effect.destroy>
([autoReconnect=true]) - def
disconnectInput<NatronEngine.Effect.disconnectInput>
(inputNumber) - def
getAvailableLayers<NatronEngine.Effect.getAvailableLayers>
() - def
getBitDepth<NatronEngine.Effect.getBitDepth>
() - def
getColor<NatronEngine.Effect.getColor>
() - def
getCurrentTime<NatronEngine.Effect.getCurrentTime>
() - def
getOutputFormat<NatronEngine.Effect.getOutputFormat>
() - def
getFrameRate<NatronEngine.Effect.getFrameRate>
() - def
getInput<NatronEngine.Effect.getInput>
(inputNumber) - def
getInput<NatronEngine.Effect.getInput>
(inputName) - def
getLabel<NatronEngine.Effect.getLabel>
() - def
getInputLabel<NatronEngine.Effect.getInputLabel>
(inputNumber) - def
getMaxInputCount<NatronEngine.Effect.getMaxInputCount>
() - def
getParam<NatronEngine.Effect.getParam>
(name) - def
getParams<NatronEngine.Effect.getParams>
() - def
getPluginID<NatronEngine.Effect.getPluginID>
() - def
getPosition<NatronEngine.Effect.getPosition>
() - def
getPremult<NatronEngine.Effect.getPremult>
() - def
getPixelAspectRatio<NatronEngine.Effect.getPixelAspectRatio>
() - def
getRegionOfDefinition<NatronEngine.Effect.getRegionOfDefinition>
(time,view) - def
getRotoContext<NatronEngine.Effect.getRotoContext>
() - def
getTrackerContext<NatronEngine.Effect.getTrackerContext>
() - def
getScriptName<NatronEngine.Effect.getScriptName>
() - def
getSize<NatronEngine.Effect.getSize>
() - def
getUserPageParam<NatronEngine.Effect.getUserPageParam>
() - def
isUserSelected<NatronEngine.Effect.isUserSelected>
() - def
isReaderNode<NatronEngine.Effect.isReaderNode>
() - def
isWriterNode<NatronEngine.Effect.isWriterNode>
() - def
isOutputNode<NatronEngine.Effect.isOutputNode>
() - def
setColor<NatronEngine.Effect.setColor>
(r, g, b) - def
setLabel<NatronEngine.Effect.setLabel>
(name) - def
setPosition<NatronEngine.Effect.setPosition>
(x, y) - def
setScriptName<NatronEngine.Effect.setScriptName>
(scriptName) - def
setSize<NatronEngine.Effect.setSize>
(w, h) - def
setSubGraphEditable<NatronEngine.Effect.setSubGraphEditable>
(editable) - def
setPagesOrder<NatronEngine.Effect.setPagesOrder>
(pages)
The Effect object can be used to operate with a single node in Natron. To create a new Effect, use the app.createNode(pluginID)<NatronEngine.App.createNode>
function.
Natron automatically declares a variable to Python when a new Effect is created. This variable will have a script-name determined by Natron as explained in the autovar
section.
Once an Effect is instantiated, it declares all its Param
and inputs. See how to manage <userParams>
user parameters below
To get a specific Param
by script-name, call the getParam(name) <NatronEngine.Effect.getParam>
function
Input effects are mapped against a zero-based index. To retrieve an input Effect given an index, you can use the getInput(inputNumber) <NatronEngine.Effect.getInput>
function.
To manage inputs, you can connect them and disconnect them with respect to their input index with the connectInput(inputNumber,input)<NatronEngine.Effect.connectInput>
and then disconnectInput(inputNumber)<NatronEngine.Effect.disconnectInput>
functions.
If you need to destroy permanently the Effect, just call destroy() <NatronEngine.Effect.destroy()>
.
For convenience some GUI functionalities have been made accessible via the Effect class to control the GUI of the node (on the node graph):
- Get/Set the node position with the
setPosition(x,y)<NatronEngine.Effect.setPosition>
andgetPosition()<NatronEngine.Effect.getPosition>
functions- Get/Set the node size with the
setSize(width,height)<NatronEngine.Effect.setSize>
andgetSize()<NatronEngine.Effect.getSize>
functions- Get/Set the node color with the
setColor(r,g,b)<NatronEngine.Effect.setColor>
andgetColor()<NatronEngine.Effect.getColor>
functions
See this section<userParams.details>
NatronEngine.Effect.addUserPlane(planeName,channels)
- param planeName
str<NatronEngine.std::string>
- param channels
sequence
- rtype
bool<PySide.QtCore.bool>
Adds a new plane to the Channels selector of the node in its settings panel. When selected, the end-user can choose to output the result of the node to this new custom plane. The planeName will identify the plane uniquely and must not contain spaces or non python compliant characters. The channels are a sequence of channel names, e.g.:
addUserPlane("MyLayer",["R", "G", "B", "A"])
Note
A plane cannot contain more than 4 channels and must at least have 1 channel.
This function returns True if the layer was added successfully, False otherwise.
NatronEngine.Effect.beginChanges()
Starts a begin/End bracket, blocking all evaluation (=renders and callback onParamChanged) that would be issued due to a call to setValue<NatronEngine.IntParam.setValue>
on any parameter of the Effect.
Similarly all input changes will not be evaluated until endChanges() is called.
Typically to change several values at once we bracket the changes like this:
node.beginChanges()
param1.setValue(...)
param2.setValue(...)
param3.setValue(...)
param4.setValue(...)
node.endChanges() # This triggers a new render
A more complex call:
node.beginChanges() node.connectInput(0,otherNode) node.connectInput(1,thirdNode) param1.setValue(...) node.endChanges() # This triggers a new render
NatronEngine.Effect.endChanges()
Ends a begin/end bracket. If the begin/end bracket recursion reaches 0 and there were calls made to setValue<NatronEngine.IntParam.setValue>
this function will effectively compresss all evaluations into a single one. See beginChanges()<NatronEngine.Effect.beginChanges>
NatronEngine.Effect.canConnectInput(inputNumber, node)
- param inputNumber
int<PySide.QtCore.int>
- param node
Effect<NatronEngine.Effect>
- rtype
bool<PySide.QtCore.bool>
Returns whether the given node can be connected at the given inputNumber of this Effect. This function could return False for one of the following reasons:
- The Effect already has an input at the given inputNumber
- The node is None
- The given inputNumber is out of range
- The node cannot have any node connected to it (such as a BackDrop or an Output)
- This Effect or the given node is a child of another node (for trackers only)
- Connecting node would create a cycle in the graph implying that it would create infinite recursions
NatronEngine.Effect.connectInput(inputNumber, input)
- param inputNumber
int<PySide.QtCore.int>
- param input
Effect<NatronEngine.Effect>
- rtype
bool<PySide.QtCore.bool>
Connects input to the given inputNumber of this Effect. This function calls internally canConnectInput()<NatronEngine.Effect.canConnectInput>
to determine if a connection is possible.
NatronEngine.Effect.destroy([autoReconnect=true])
- param autoReconnect
bool<PySide.QtCore.bool>
Removes this Effect from the current project definitively. If autoReconnect is True then any nodes connected to this node will try to connect their input to the input of this node instead.
NatronEngine.Effect.disconnectInput(inputNumber)
- param inputNumber
int<PySide.QtCore.int>
Removes any input Effect connected to the given inputNumber of this node.
NatronEngine.Effect.getAvailableLayers()
- rtype
dict
Returns the layer available on this node. This is a dict with a ImageLayer<NatronEngine.ImageLayer>
as key and Effect<NatronEngine.Effect>
as value. The Effect is the closest node in the upstream tree (including this node) that produced that layer.
For example, in a simple graph Read --> Blur, if the Read node has a layer available named "RenderLayer.combined" but Blur is set to process only the color layer (RGBA), then calling this function on the Blur will return a dict containing for key "RenderLayer.combined" the Read node, whereas the dict will have for the key "RGBA" the Blur node.
NatronEngine.Effect.getBitDepth()
- rtype
ImageBitDepthEnum<NatronEngine.Natron.ImageBitDepthEnum>
Returns the bit-depth of the image in output of this node.
NatronEngine.Effect.getColor()
- rtype
tuple
Returns the color of this node as it appears on the node graph as [R,G,B] 3-dimensional tuple.
NatronEngine.Effect.getCurrentTime()
- rtype
int<PySide.QtCore.int>
Returns the current time of timeline if this node is currently rendering, otherwise it returns the current time at which the node is currently rendering for the caller thread.
NatronEngine.Effect.getOutputFormat()
- rtype
RectI<NatronEngine.RectI>
Returns the output format of this node in pixel units.
NatronEngine.Effect.getFrameRate()
- rtype
float<PySide.QtCore.float>
Returns the frame-rate of the sequence in output of this node.
NatronEngine.Effect.getInput(inputNumber)
- param inputNumber
int<PySide.QtCore.int>
- rtype
Effect<NatronEngine.Effect>
Returns the node connected at the given inputNumber.
NatronEngine.Effect.getInput(inputName)
- param inputName
str<PySide.QtCore.QString>
- rtype
Effect<NatronEngine.Effect>
Same as
getInput(inputNumber)<NatronEngine.Effect.getInput>
except that the parameter in input is the name of the input as displayed on the node-graph. This function is made available for convenience.
NatronEngine.Effect.getLabel()
- rtype
str<NatronEngine.std::string>
Returns the label of the node. See this section<autoVar>
for a discussion of the label vs the script-name.
NatronEngine.Effect.getInputLabel(inputNumber)
- param inputNumber
int<PySide.QtCore.int>
- rtype
str<NatronEngine.std::string>
Returns the label of the input at the given inputNumber. It corresponds to the label displayed on the arrow of the input in the node graph.
NatronEngine.Effect.getMaxInputCount()
- rtype
int<PySide.QtCore.int>
Returns the number of inputs for the node. Graphically this corresponds to the number of arrows in input.
NatronEngine.Effect.getParam(name)
- param name
str<NatronEngine.std::string>
- rtype
Param<Param>
Returns a parameter<Param>
by its script-name or None if no such parameter exists.
NatronEngine.Effect.getParams()
- rtype
sequence
Returns all the Param<NatronEngine.Param>
of this Effect as a sequence.
NatronEngine.Effect.getPluginID()
- rtype
str<NatronEngine.std::string>
Returns the ID of the plug-in that this node instantiate.
NatronEngine.Effect.getPosition()
- rtype
tuple
Returns the current position of the node on the node-graph. This is a 2 dimensional [X,Y] tuple. Note that in background mode, if used, this function will always return [0,0] and should NOT be used.
NatronEngine.Effect.getPremult()
- rtype
ImagePremultiplicationEnum<NatronEngine.Natron.ImagePremultiplicationEnum>
Returns the alpha premultiplication state of the image in output of this node.
NatronEngine.Effect.getPixelAspectRatio()
- rtype
float<PySide.QtCore.float>
Returns the pixel aspect ratio of the image in output of this node.
NatronEngine.Effect.getRegionOfDefinition(time,view)
- param time
float<PySide.QtCore.float>
- param view
int<PySide.QtCore.int>
- rtype
RectD<NatronEngine.RectD>
Returns the bounding box of the image produced by this effect in canonical coordinates. This is exactly the value displayed in the "Info" tab of the settings panel of the node for the "Output". This can be useful for example to set the position of a point parameter to the center of the region of definition.
NatronEngine.Effect.getRotoContext()
- rtype
Roto<NatronEngine.Roto>
Returns the roto context for this node. Currently only the Roto node has a roto context. The roto context is in charge of maintaining all information relative to Beziers<BezierCurve>
and Layers<Layer>
. Most of the nodes don't have a roto context though and this function will return None.
NatronEngine.Effect.getTrackerContext()
- rtype
Tracker<NatronEngine.Tracker>
Returns the tracker context for this node. Currently only the Tracker node has a tracker context. The tracker context is in charge of maintaining all information relative to Tracks<Track>
. Most of the nodes don't have a tracker context though and this function will return None.
NatronEngine.Effect.getScriptName()
- rtype
str<NatronEngine.std::string>
Returns the script-name of this Effect. See this<autoVar>
section for more information about the script-name.
NatronEngine.Effect.getSize()
- rtype
tuple
Returns the size of this node on the node-graph as a 2 dimensional [Width,Height] tuple. Note that calling this function will in background mode will always return [0,0] and should not be used.
NatronEngine.Effect.getUserPageParam()
- rtype
PageParam<NatronEngine.PageParam>
Convenience function to return the user page parameter if this Effect has one.
NatronEngine.Effect.isUserSelected()
- rtype
bool<PySide.QtCore.bool>
Returns true if this node is selected in its containing nodegraph.
NatronEngine.Effect.isReaderNode()
- rtype
bool<PySide.QtCore.bool>
Returns True if this node is a reader node
NatronEngine.Effect.isWriterNode()
- rtype
bool<PySide.QtCore.bool>
Returns True if this node is a writer node
NatronEngine.Effect.isOutputNode()
- rtype
bool<PySide.QtCore.bool>
Returns True if this node is an output node (which also means that it has no output)
NatronEngine.Effect.setColor(r, g, b)
- param r
float<PySide.QtCore.double>
- param g
float<PySide.QtCore.double>
- param b
float<PySide.QtCore.double>
Set the color of the node as it appears on the node graph. Note that calling this function will in background mode will do nothing and should not be used.
NatronEngine.Effect.setLabel(name)
- param name
str<NatronEngine.std::string>
Set the label of the node as it appears in the user interface. See this<autoVar>
section for an explanation of the difference between the label and the script-name.
NatronEngine.Effect.setPosition(x, y)
- param x
float<PySide.QtCore.double>
- param y
float<PySide.QtCore.double>
Set the position of the node as it appears on the node graph. Note that calling this function will in background mode will do nothing and should not be used.
NatronEngine.Effect.setScriptName(scriptName)
- param scriptName
str<NatronEngine.std::string>
- rtype
bool<PySide.QtCore.bool>
Set the script-name of the node as used internally by Natron. See this<autoVar>
section for an explanation of the difference between the label and the script-name.
Warning
Using this function will remove any previous variable declared using the old script-name and will create a new variable with the new script name if valid.
If your script was using for instance a node named:
app1.Blur1
and you renamed it BlurOne, it should now be available to Python this way:
app1.BlurOne
but using app1.Blur1 would report the following error:
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'Blur1' is not defined
NatronEngine.Effect.setSize(w, h)
- param w
float<PySide.QtCore.double>
- param h
float<PySide.QtCore.double>
Set the size of the node as it appears on the node graph. Note that calling this function will in background mode will do nothing and should not be used.
NatronEngine.Effect.setSubGraphEditable(editable)
- param editable
bool<PySide.QtCore.bool>
Can be called to disable editing of the group via Natron's graphical user interface. This is handy to prevent users from accidentally breaking the sub-graph. This can always be reverted by editing the python script associated. The user will still be able to see the internal node graph but will not be able to unlock it.
NatronEngine.Effect.setPagesOrder(pages)
- param pages
sequence
Given the string list pages try to find the corresponding pages by their-script name and order them in the given order.