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

  • other – Param

  • dimension – int

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

  • time – float

  • dimension – int

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

dimension – int

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

  • min – float

  • max – float

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

  • min – float

  • max – float

  • time – float

  • seed – unsigned 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

  • min – int

  • max – int

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

  • min – int

  • max – int

  • time – float

  • seed – unsigned 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

a – bool

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

NatronEngine.Param.setAnimationEnabled(e)
Parameters

e – bool

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

NatronEngine.Param.setEnabled(enabled[, dimension=0])
Parameters

  • enabled – bool

  • dimension – int

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

enabled – bool

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

eval – bool

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

icon – str

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

help – str

Tooltip help string for the parameter. See getHelp()

NatronEngine.Param.setPersistant(persistant)
Parameters

persistant – bool

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

visible – bool

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

NatronEngine.Param.setVisibleByDefault(visible)
Parameters

visible – bool

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

NatronEngine.Param.setAsAlias(otherParam)
Parameters

otherParam – Param

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

  • otherParam – Param

  • thisDimension – int

  • otherDimension – int

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

dimension – int

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.