Param

Inherited by: ParametricParam, PageParam, GroupParam, ButtonParam, AnimatedParam, StringParamBase, PathParam, OutputFileParam, FileParam, StringParam, BooleanParam, ChoiceParam, ColorParam, DoubleParam, Double2DParam, Double3DParam, IntParam, Int2DParam, Int3DParam

Synopsis

This is the base class for all parameters. Parameters are the controls found in the settings panel of a node. See details here.

Functions

Detailed Description

The Param object can be used to control a specific parameter of a node. There are different types of parameters, ranging from the single checkbox (boolean) to parametric curves. Each type of parameter has specific functions to control the parameter according to its internal value type. In this base class, all common functionalities for parameters have been gathered.

Warning

Note that since each child class has a different value type, all the functions to set/get values, and set/get keyframes are specific for each class.

Note that most of the functions in the API of Params take a dimension parameter. This is a 0-based index of the dimension on which to operate. For instance the dimension 0 of a RGB color parameter is the red value.

Various properties controls the parameter regarding its animation or its layout or other things. Some properties are listed here, but the list is not complete. Refer to the reference on each parameter type for all accessible properties.

  • addNewLine: When True, the next parameter declared will be on the same line as this parameter
  • canAnimate: This is a static property that you cannot control which tells whether animation can be enabled for a specific type of parameter
  • animationEnabled: For all parameters that have canAnimate=True, this property controls whether this parameter should be able to animate (= have keyframes) or not
  • evaluateOnChange: This property controls whether a new render should be issued when the value of this parameter changes
  • help: This is the tooltip visible when hovering the parameter with the mouse
  • enabled: Should this parameter be editable by the user or not. Generally, disabled parameters have their text drawn in black.
  • visible: Should this parameter be visible in the user interface or not
  • persistent: If true then the parameter value will be saved in the project otherwise it will be forgotten between 2 runs

Note that most of the properties are not dynamic and only work for user created parameters. If calling any setter/getter associated to these properties, nothing will change right away. A call to refreshUserParamsGUI() is needed to refresh the GUI for these parameters.

For non user-parameters (i.e: parameters that were defined by the underlying OpenFX plug-in), only their dynamic properties can be changed since refreshUserParamsGUI() will only refresh user parameters.

The following dynamic properties can be set on all parameters (non user and user):

Name: Type: Dynamic: Setter: Getter: Default:
visible bool yes setVisible getIsVisible True
enabled bool yes setEnabled getIsEnabled True

Note

animates is set to True by default only if it is one of the following parameters:

IntParam Int2DParam Int3DParam DoubleParam Double2DParam Double3DParam ColorParam

Note that ParametricParam , GroupParam, PageParam, ButtonParam, FileParam, OutputFileParam, PathParam cannot animate at all.

Parameter in-viewer interface

In Natron, each Effect may have an interface in the Viewer, like the Roto or Tracker nodes have.

You may add parameters on the viewer UI for any Effect as well as edit it. This also apply to the Viewer node UI as well, so one can completely customize the Viewer toolbars. The user

guide covers in detail how to customize the Viewer UI for an Effect.

To add a parameter to the Viewer UI of an Effect, use the function insertParamInViewerUI(parameter, index). You may then control its layout, using the setViewerUILayoutType(type) function and the spacing between parameters in pixels with setViewerUIItemSpacing(spacingPx). You may set the text label or icon of the parameter specifically in the viewer UI by calling setViewerUIIconFilePath(filePath,checked) and setViewerUILabel(label).

Member functions description

NatronEngine.Param.beginChanges()

This can be called before making heavy changes to a parameter, such as setting thousands of keyframes. This call prevent the parameter from doing the following: - Trigger a new render when changed - Call the paramChanged callback when changed - Adjusting the folded/expanded state automatically for multi-dimensional parameters.

Make sure to call the corresponding endChanges() function when done

NatronEngine.Param.copy(other[, dimension=-1])
Parameters:
  • otherParam
  • dimensionint
Return type:

bool

Copies the other parameter values, animation and expressions at the given dimension. If dimension is -1, all dimensions in min(getNumDimensions(), other.getNumDimensions()) will be copied.

Note

Note that types must be convertible:

IntParam,DoubleParam, ChoiceParam, ColorParam and BooleanParam can convert between types but StringParam cannot.

Warning

When copying a parameter, only values are copied, not properties, hence if copying a choice parameter, make sure that the value you copy has a meaning to the receiver otherwise you might end-up with an undefined behaviour, e.g:

If ChoiceParam1 has 3 entries and the current index is 2 and ChoiceParam2 has 15 entries and current index is 10, copying ChoiceParam2 to ChoiceParam1 will end-up in undefined behaviour.

This function returns True upon success and False otherwise.

NatronEngine.Param.curve(time[, dimension=-1, view="Main"])
Parameters:
  • timefloat
  • dimensionint
  • viewstr
Return type:

float

If this parameter has an animation curve on the given dimension, then the value of that curve at the given time is returned. If the parameter has an expression on top of the animation curve, the expression will be ignored, ie.g: the value of the animation curve will still be returned. This is useful to write custom expressions for motion design such as looping, reversing, etc…

NatronEngine.Param.endChanges()

To be called when finished making heavy changes to a parameter, such as setting thousands of keyframes.

A call to endChanges should always match a corresponding previous call to beginChanges() Note that they can be nested.

NatronEngine.Param.getAddNewLine()
Return type:bool

Returns whether the parameter is on a new line or not.

NatronEngine.Param.getCanAnimate()
Return type:bool

Returns whether this class can have any animation or not. This cannot be changed. calling setAnimationEnabled(True) will not enable animation for parameters that cannot animate.

NatronEngine.Param.getEvaluateOnChange()
Return type:bool

Returns whether this parameter can evaluate on change. A parameter evaluating on change means that a new render will be triggered when its value changes due to a call of one of the setValue functions.

NatronEngine.Param.getHelp()
Return type:str

Returns the help tooltip visible when hovering the parameter with the mouse on the GUI;

NatronEngine.Param.getIsAnimationEnabled()
Return type:bool

Returns whether animation is enabled for this parameter. This is dynamic and can be changed by setAnimationEnabled(bool) if the parameter can animate.

NatronEngine.Param.getIsEnabled()
Return type:bool

Returns whether parameter is enabled or not. When disabled the parameter cannot be edited from the user interface, however it can still be edited from the Python A.P.I.

NatronEngine.Param.getIsPersistent()
Return type:bool

Returns whether this parameter should be persistent in the project or not. Non-persistent parameter will not have their value saved when saving a project.

NatronEngine.Param.getIsVisible()
Return type:bool

Returns whether the parameter is visible on the user interface or not.

NatronEngine.Param.getLabel()
Return type:str

Returns the label of the parameter. This is what is displayed in the settings panel of the node. See this section for an explanation of the difference between the label and the script name

NatronEngine.Param.getNumDimensions()
Return type:int

Returns the number of dimensions. For exampel a Double3DParam has 3 dimensions. A ParametricParam has as many dimensions as there are curves.

NatronEngine.Param.getParent()
Return type:NatronEngine.Param

If this param is within a group, then the parent will be the group. Otherwise the param’s parent will be the:doc:page<PageParam> onto which the param appears in the settings panel.

NatronEngine.Param.getParentEffect()
Return type:NatronEngine.Effect
If the holder of this parameter is an effect, this is the effect.

If the holder of this parameter is a table item, this will return the effect holding the item itself.

NatronEngine.Param.getParentItemBase()
rtype:

NatronEngine.ItemBase

If the holder of this parameter is a table item, this is the table item.

getApp()
Return type:NatronEngine.App
If the holder of this parameter is the app itself (so it is a project setting), this is

the app object. If the holder of this parameter is an effect, this is the application object containing the effect. If the holder of this parameter is a table item, this will return the application containing the effect holding the item itself.

NatronEngine.Param.getScriptName()
Return type:str

Returns the script-name of the param as used internally. The script-name is visible in the tooltip of the parameter when hovering the mouse over it on the GUI. See this section for an explanation of the difference between the label and the script name

NatronEngine.Param.getTypeName()
Return type:str

Returns the type-name of the parameter.

NatronEngine.Param.getViewerUILayoutType()
Return type:ViewerContextLayoutTypeEnum

Returns the layout type of this parameter if it is present in the viewer interface of the Effect holding it.

NatronEngine.Param.getViewerUIItemSpacing()
Return type:int

Returns the item spacing after this parameter if it is present in the viewer interface of the Effect holding it.

NatronEngine.Param.getViewerUIIconFilePath([checked=False])
param checked::class:`bool<PySide.QtCore.bool>
rtype:str

Returns the icon file path of this parameter if it is present in the viewer interface of the Effect holding it. For buttons, if checked it false, the icon will be used when the button is unchecked, if checked it will be used

when the button is checked.

NatronEngine.Param.getHasViewerUI()
Return type::class:`bool<PySide.QtCore.bool>

Returns whether this parameter has an interface in the Viewer UI of it’s holding Effect.

NatronEngine.Param.getViewerUIVisible()
Return type::class:`bool<PySide.QtCore.bool>

Returns whether this parameter is visible in the Viewer UI. Only valid for parameters with a viewer ui

NatronEngine.Param.getViewerUILabel()
Return type:str

Returns the label of this parameter if it is present in the viewer interface of the Effect holding it.

NatronEngine.Param.isExpressionCacheEnabled()
Return type::class:`bool<PySide.QtCore.bool>

Returns whether caching of expression results is enabled for this knob. By default this is enabled, it can be disabled with setExpressionCacheEnabled(False)

NatronEngine.Param.random([min=0., max=1.])
Parameters:
  • minfloat
  • maxfloat
Return type:

float

Returns a pseudo-random value in the interval [min, *max*[. The value is produced such that for a given parameter it will always be the same for a given time on the timeline, so that the value can be reproduced exactly.

Note

Note that if you’re calling multiple times random() in the same parameter expression, each call would return a different value, but they would all return the same value again if the expressions is interpreted at the same time, e.g:

# Would always return the same value at a given timeline's time.
random() - random()

Note that you can ensure that random() returns a given value by calling the overloaded function random(seed) instead.

NatronEngine.Param.random(seed)
Parameters:seedunsigned int
Return type:float

Same as random() but takes a seed in parameter to control the value returned by the function. E.g:

ret = random(2) - random(2)
# ret == 0 always
NatronEngine.Param.randomInt(min, max)
Parameters:
  • minint
  • maxint
Return type:

int

Same as random(min,max) but returns an integer in the range [min,*max*[

NatronEngine.Param.randomInt(seed)
Parameters:seedunsigned int
Return type:int

Same as random(seed) but returns an integer in the range [0, INT_MAX] instead.

NatronEngine.Param.setAddNewLine(a)
Parameters:abool

Set whether the parameter should be on a new line or not. See getAddNewLine()

NatronEngine.Param.setAnimationEnabled(e)
Parameters:ebool

Set whether animation should be enabled (= can have keyframes). See getIsAnimationEnabled()

NatronEngine.Param.setEnabled(enabled)
Parameters:enabledbool

Set whether the parameter should be enabled or not. When disabled, the parameter will be displayed in black and the user will not be able to edit it. See getIsEnabled(dimension)

NatronEngine.Param.setEvaluateOnChange(eval)
Parameters:evalbool

Set whether evaluation should be enabled for this parameter. When True, calling any function that change the value of the parameter will trigger a new render. See getEvaluateOnChange()

NatronEngine.Param.setIconFilePath(icon[, checked])
Parameters:
  • iconstr
  • checkedbool

Set here the icon file path for the label. This should be either an absolute path or a file-path relative to a path in the NATRON_PLUGIN_PATH. The icon will replace the label of the parameter. If this parameter is a ButtonParam then if checked is True the icon will be used when the button is down. Similarily if checked is False the icon will be used when the button is up.

NatronEngine.Param.setLabel(label)
Parameters:labelstr

Set the label of the parameter as visible in the GUI See getLabel()

NatronEngine.Param.setHelp(help)
Parameters:helpstr

Set the help tooltip of the parameter. See getHelp()

NatronEngine.Param.setPersistent(persistent)
Parameters:persistentbool

Set whether this parameter should be persistent or not. Non persistent parameter will not be saved in the project. See getIsPersistent

NatronEngine.Param.setVisible(visible)
Parameters:visiblebool

Set whether this parameter should be visible or not to the user. See getIsVisible()

NatronEngine.Param.setViewerUILayoutType(type)
Parameters:typeNatronEngine.Natron.ViewerContextLayoutTypeEnum

Set the layout type of this parameter if it is present in the viewer interface of the Effect holding it.

NatronEngine.Param.setViewerUIItemSpacing(spacing)
Parameters:spacingint

Set the item spacing after this parameter if it is present in the viewer interface of the Effect holding it.

NatronEngine.Param.setViewerUIIconFilePath(filePath[, checked=False])
param filePath:str
param checked:bool

Set the icon file path of this parameter if it is present in the viewer interface of the Effect holding it. For buttons, if checked it false, the icon will be used when the button is unchecked, if checked it will be used

when the button is checked. This function only has an effect on user created parameters.

NatronEngine.Param.setViewerUILabel(label)
Parameters:labelstr

Set the label of this parameter if it is present in the viewer interface of the Effect holding it. This function only has an effect on user created parameters.

NatronEngine.Param.setViewerUIVisible(visible)
Parameters:visiblebool

Set this parameter visible or not in the Viewer UI. Only valid for parameters for which the function getHasViewerUI() returns True.

NatronEngine.Param.setExpressionCacheEnabled(enabled)
Parameters:enabledbool

Set whether caching of expression results is enabled. By default this is True. This can be turned off if an expression is set on a parameter but the expression depends on external data (other than parameter values, such as a file on disk). These external data would be unknown from Natron hence the expression cache would never invalidate.

NatronEngine.Param.linkTo(otherParam[, thisDimension=-1, otherDimension=-1, thisView="All", otherView="All"])
Parameters:
  • otherParamParam
  • thisDimensionint
  • otherDimensionint
  • thisViewstr
  • otherViewstr
Return type:

bool

This parameter will share the value of otherParam. They need to be both of the same type but may vary in dimension, as long as thisDimension is valid according to the number of dimensions of this parameter and otherDimension is valid according to the number of dimensions of otherParam. If thisDimension is -1 then it is expected that otherDimension is also -1 indicating that all dimensions should respectively be slaved.

If this parameter has split views, then only view(s) specified by thisView will be slaved to the otherView of the other parameter. If thisView is “All” then it is expected that otherView is also “All” indicating that all views should be respectively slaved. If not set to “All” then the view parameters should name valid views in the project settings.

This parameter thisDimension will be controlled entirely by the otherDimension of otherParam until a call to unlink(thisDimension) is made

Parameters:
  • dimensionint
  • viewstr

If the given dimension of this parameter was previously linked, then this function will remove the link and the value will no longer be shared with any other parameters. If dimension equals -1 then all dimensions will be unlinked. If view is set to “All” then all views will be unlinked, otherwise it should name valid views in the project settings.

Note

The animation and values that were present before the link will remain.