Skip to content

Global Variables#

Clarisse supports custom, built-in and system variables. Variables can be used in most attribute text fields and they are very useful if you wish to constraint attribute path resolution according to a global variable for example.

They also can be used to load sequence of geometries. Please refer to time variables section for more information on this subject.

Variables are managed using the Variable Editor widget. They can be promoted in the main application toolbar for faster access and used in expressions.

Basic Usage#

To use a variable in an attribute value, simply insert its name in the string of the text field. The expression system uses separator characters to read the variable names from the expression.

Any character that is not a separator is considered valid to be used to name a variable. All supported separator characters are listed below:

/ ? , . < > ' " ; : [ ] { } \ | = ( ) * & ^ % $ # @ ! ` ~

Note

Separators marks automatically the end of a variable name.

Naming Limitations#

Variables have the following naming limitations:

  • they can't start with a digit
  • they support only underscore and alphanumeric characters

For example FIRST_JOB is a valid variable name whereas 1ST_JOB is invalid.

Strings/Filenames#

The : separator is extremely useful when working with strings or filenames. You must use it when you have to mark the end of the variable name to remove any unambiguity. Just consider the following filename:

c:\my_image_25_final.exr.

If we want to use the $F variable to automatically generate the frame number we would naively write:

c:\my_image_$F_final.exr.

However, here that wouldn't work. Clarisse would fail to recognize $F and consider instead the undefined variable:

$F_final

Indeed, there's no way for Clarisse to know that the input variable is indeed $F instead of $F_final as the later is also a perfectly valid variable name. To resolve this issue, you can use the : seperator to tell Clarisse where the variable ends.

c:\my_image_$F:_final.exr.

Variable Types#

Clarisse provides 3 kinds of variables:

In the event of a naming collision, for example a custom variable sharing the same name with a system one, variable lookup is performed like this.

First Clarisse checks if the custom variable exists, if not then it looks for a built-in then for the system one. This allows users to easily override system or built-in variables.

System Variables#

System variables are read-only variables imported upon Clarisse launch. System variables are variables defined in the shell environment or in the clarisse.env file. Please note Clarisse skips variables with invalid names.

Built-in Variables#

Built-in variables are read-only variables automatically declared by Clarisse. These variables can't be deleted and their values are automatically set by Clarisse during execution. Typical built-in variables are F, FPS, T, PDIR. For a complete list of built-in variables please check the Variable Editor widget.

Built-in Variable Description
F Clarisse current frame.
T Clarisse current time.
PDIR Current project directory.
PNAME Current project name. (with no extension)
FPS Frame per second value. This value can be changed in the Preferences Panel.
CTEMP Clarisse temp directory.
CDIR Clarisse content directory.

Time Variables#

Clarisse provides 3 time-dependent built-in variables that can be used to write basic expressions in filename type attribute fields.

Variable Description
$F Returns the current frame
$T Returns the current time (in seconds)
$FPS Returns the current frames per second

For example you can use F variable to load a sequence of Wavefront OBJ file. Just set the filename field of your polyfile to:

/data/seq_0089/sh_009/geometry/collapse_$4F.obj

When time changes, the filename will be automatically expanded with current frame number formatted with a padding of 4.

Padding#

If you want to pad a variable value, you can insert a number between the $ character and the name of the variable. The number represents the padding of the variable value. Padding applies only if the length of the variable value string is smaller than the given padding. By default, padding value is 0.

Example Expanded Version with $F = 25
c:\my_image_$F.exr c:\my_image_25.exr
c:\my_images_$4F.exr c:\my_images_0025.exr
c:\my_image_$F$F.exr c:\my_image_2525.exr
c:\my_image_$F:_final.exr c:\my_image_25_final.exr
c:\my_images\frame_$F\image.exr c:\my_images\frame_25\image.exr

Custom Variables#

Custom variables are user-defined variables that are saved in the project. When reloading a project, variables and their values are automatically recreated.

Variables and Evaluation#

Variable values are tracked in real-time. If the value of a variable is changed somehow during an evaluation, and the running evaluation somehow depends on the variable value, the evaluation will be automatically restarted.

For example, let's say you've defined the directory of your texture maps in a variable: MY_MAPS_PATH. Now, during a rendering, you decide to change MY_MAPS_PATH value. All textures that were using this variable get notified so they can update their new path. Then rendering gets interrupted and restarts automatically.