Param — Natron 2.5.0 documentation

# 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

- def `copy` (param[, dimension=-1])

- def `curve` (time[, dimension=-1])

- def `getAddNewLine` ()

- def `getCanAnimate` ()

- def `getEvaluateOnChange` ()

- def `getHelp` ()

- def `getIsAnimationEnabled` ()

- def `getIsEnabled` ([dimension=0])

- def `getIsPersistant` ()

- def `getIsVisible` ()

- def `getLabel` ()

- def `getNumDimensions` ()

- def `getParent` ()

- def `getScriptName` ()

- def `getTypeName` ()

- def `random<NatronEngine.Param.random()` ([min=0.,max=1.])

- def `random<NatronEngine.Param.random()` (seed)

- def `randomInt<NatronEngine.Param.randomInt()` (min,max)

- def `randomInt<NatronEngine.Param.randomInt()` (seed)

- def `setAddNewLine` (a)

- def `setAnimationEnabled` (e)

- def `setEnabled` (enabled[, dimension=0])

- def `setEnabledByDefault` (enabled)

- def `setEvaluateOnChange` (eval)

- def `setIconFilePath` (icon)

- def `setHelp` (help)

- def `setPersistant` (persistant)

- def `setVisible` (visible)

- def `setVisibleByDefault` (visible)

- def `setAsAlias` (otherParam)

- def `slaveTo` (otherParam, thisDimension, otherDimension)

- def `unslave` (dimension)

## 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.