Accessing a node’s parameters:¶
Note that you can also access a parameter with the
param = app.BlurCImg1.getParam("size")
but you should not ever need it because Natron pre-declared all variables for you.
The script-name of a parameter is visible in the user interface when hovering the parameter in the settings panel with the mouse. This is the name in bold:
Each parameter has a type to represent internally different data-types, here is a list of all existing parameters:
- IntParam to store 1-dimensional integers
- Int2DParam to store 2-dimensional integers
- Int3DParam to store 3-dimensional integers
- DoubleParam to store 1-dimensional floating point
- Double2DParam to store 2-dimensional floating point
- Double3DParam to store 3-dimensional floating point
- BooleanParam to store 1-dimensional boolean (checkbox)
- ButtonParam to add a push-button
- ChoiceParam a 1-dimensional drop-down (combobox)
- StringParam to store a 1-dimensional string
- FileParam to specify an input or output file
- PathParam to specify a path to a single or multiple directories
- ParametricParam to store N-dimensional parametric curves
- GroupParam to graphically gather parameters under a group
- PageParam to store parameters into a page
Retrieving a parameter’s value:¶
Since each underlying type is different for parameters, each sub-class has its own version of the functions.
To get the value of the parameter at the timeline’s current time, call the
If the parameter is animated and you want to retrieve its value at a specific time on the timeline,
you would use the
Note that when animated and the given frame time is not a time at which a keyframe exists, Natron will interpolate the value of the parameter between surrounding keyframes with the interpolation filter selected (by default it is smooth).
Modifying a parameter’s value:¶
You would set the parameter value by calling the
If the parameter is animated (= has 1 or more keyframe) then calling this function would
create (or modify) a keyframe at the timeline’s current time.
To add a new keyframe the
setValueAtTime(value,frame,dimension) function can be used.
To remove a keyframe you can use the
If you want to remove all the animation on the parameter at a given dimension, use the
Note that the dimension is a 0-based index referring to the dimension on which to operate. For instance a Double2DParam has 2 dimensions x and y. To set a value on x you would use dimension = 0, to set a value on y you would use dimension = 1.
More information on parameter animation, multi-view and expressions can be found in the documentation of the AnimatedParam class.
Controlling other properties of parameters:¶
See the documentation for the Param class for a detailed explanation of other properties and how they affect the parameter.
In a project setup to have multiple views (such as a stereo project), parameters may have different values and animation per view. Typically you may not want to apply the same strength of an effect on the left view and on the right view.
By default a parameter is not multi-view and all its views have the same value and animation curve.
You can split-off specific views by calling
in which case the given view will be split from the other views and can be assigned different values.
By default the main view controlling all views that are not split yet is called Main. Any function that return a value will by default return the value for the Main view. Any function that change the state of the parameter will by default be applied on all views , even those that are split-off should receive the change. This is done with the keyword All.
Function that return values may not take the special All keyword and will error if an invalid parameter is supplied.
To unsplit a given view and re-group it under the Main view you can call the
Creating new parameters:¶
In Natron, the user has the possibility to add new parameters, called User parameters. They are pretty much the same than the parameters defined by the underlying OpenFX plug-in itself.
In the Python API, to create a new user parameter, you would need to call one of the
createXParam(name,label,...) of the Effect class.
These parameters can have their default values and properties changed as explained in the documentation page of the Param class.
To remove a user created parameter you would need to call the
of the Effect class.
Only user parameters can be removed. Removing parameters defined by the OpenFX plug-in will not work.