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.

A Param can have several functions to control some properties, namely:

  • 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 issues 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 in painted in black.
  • visible: Should this parameter be visible in the user interface or not
  • persistant: If true then the parameter value will be saved in the project
  • dimension: How many dimensions this parameter has. For instance a Double3DParam has 3 dimensions. A ParametricParam has as many dimensions as there are curves.

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.

The following table sums up the different properties for all parameters including type-specific properties not listed above.

Note that most of the properties are not dynamic: they need to be set before calling refreshUserParamsGUI() which will create the GUI for these parameters.

Warning

A non-dynamic property can no longer be changed once refreshUserParamsGUI() has been called.

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.

If a Setter function contains a (*) that means it can only be called for user parameters, it has no effect on already declared non-user parameters.

Name: Type: Dynamic: Setter: Getter: Default:
name string no None getScriptName “”
label string no None getLabel “”
help string yes setHelp(*) getHelp “”
addNewLine bool no setAddNewLine(*) getAddNewLine True
persistent bool yes setPersistant(*) getIsPersistant True
evaluatesOnChange bool yes setEvaluateOnChange(*) getEvaluateOnChange True
animates bool no setAnimationEnabled(*) getIsAnimationEnabled See (1)
visible bool yes setVisible getIsVisible True
enabled bool yes setEnabled getIsEnabled True
Properties on IntParam, Int2DParam, Int3DParam, DoubleParam, Double2DParam, Double3DParam, ColorParam only:
min int/double yes setMinimum(*) getMinimum INT_MIN
max int/double yes setMaximum(*) getMaximum INT_MAX
displayMin int/double yes setDisplayMinimum(*) getDisplayMinimum INT_MIN
displayMax int/double yes setDisplayMaximum(*) getDisplayMaximum INT_MAX
Properties on ChoiceParam only:
options list<string> yes setOptions/addOption(*) getOption empty list
Properties on FileParam, OutputFileParam only:
sequenceDialog bool yes setSequenceEnabled(*) None False
Properties on StringParam only:
type TypeEnum no setType(*) None eStringTypeDefault
Properties on PathParam only:
multiPathTable bool no setAsMultiPathTable(*) None False
Properties on GroupParam only:
isTab bool no setAsTab(*) None False

(1): 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.

Member functions description

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])
Parameters:
  • timefloat
  • dimensionint
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.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([dimension=0])
Parameters:dimensionint
Return type:bool

Returns whether the given dimension is enabled or not.

NatronEngine.Param.getIsPersistant()
Return type:bool

Returns whether this parameter should be persistant in the project or not. Non-persistant 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.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.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 are 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(min,max,time,seed) instead.

NatronEngine.Param.random(min, max, time[, seed=0])
Parameters:
  • minfloat
  • maxfloat
  • timefloat
  • seedunsigned int
Return type:

float

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

ret = random(0,1,frame,2) - random(0,1,frame,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(min, max, time[, seed=0])
Parameters:
  • minint
  • maxint
  • timefloat
  • seedunsigned int
Return type:

int

Same as random(min,max,time,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[, dimension=0])
Parameters:
  • enabledbool
  • dimensionint

Set whether the given dimension of 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.setEnabledByDefault(enabled)
Parameters:enabledbool

Set whether the parameter should be enabled or not by default. When disabled, the parameter will be displayed in black and the user will not be able to edit it.

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)
Parameters:iconstr

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.

NatronEngine.Param.setHelp(help)
Parameters:helpstr

Tooltip help string for the parameter. See getHelp()

NatronEngine.Param.setPersistant(persistant)
Parameters:persistantbool

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

NatronEngine.Param.setVisible(visible)
Parameters:visiblebool

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

NatronEngine.Param.setVisibleByDefault(visible)
Parameters:visiblebool

Set whether this parameter should be visible or not to the user in its default state.

NatronEngine.Param.setAsAlias(otherParam)
Parameters:otherParamParam
Return type:bool

Set this parameter as an alias of otherParam. They need to be both of the same type and of the same dimension. This parameter will control otherParam entirely and in case of a choice param, its drop-down menu will be updated whenever the otherParam menu is updated.

This is used generally to make user parameters on groups with the “Pick” option of the “Manage User Parameters” dialog.

NatronEngine.Param.slaveTo(otherParam, thisDimension, otherDimension)
Parameters:
  • otherParamParam
  • thisDimensionint
  • otherDimensionint
Return type:

bool

Set this parameter as a slave 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.

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

NatronEngine.Param.unslave(dimension)
Parameters:dimensionint

If the given dimension of this parameter was previously slaved, then this function will remove the link between parameters, and the user will be free again to use this parameter as any other.

Note

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