Skip to content

Clarisse Extensions#

Clarisse extends SeExpr with specific functions in order to query the values of attributes, the name of the object in which the expression is being executed and the path of its context, find items in the project, etc...

Outputting Values#

Clarisse provides a simple log_info function used to output values in the application Log. This function is very useful for debugging expressions.

Function Description
FP log_info(STRING str1, … , STRING str N) Output values to the application log. Accept one or more arguments. Note that each argument is automatically converted to string then concatenated, and printed to the log as a single line. The function always returns 0.0

Examples#

var = rand();
a = log_info("var is : ", var);
a = log_info("some other tests: ", cos(T), "   ", cos(F));
cos(T) * sin(F)

Since SeExpr requires functions to always return a value, log_info always returns 0.0, so you can use it like this for instance:

var = rand();
not_used = log_info("var is : ", var);
var

Attribute Types and Return Values#

Most of Clarisse’s attribute types are mapped to SeExpr native types (FP, FP[3] - ie. VECTOR, STRING). Based on the SeExpr type, you can decide which of the following getter functions to use to query an attribute value:

FP get_double(STRING path)                      # Return a floating-point number
VECTOR get_vec3(STRING path)                    # Return a 3D vector
STRING get_string(STRING path)                  # Return a string

These getter functions take only one argument: the path to the attribute value. Paths follow the Clarisse item path syntax and can be either absolute or relative:

"project://path/to/object.attribute[index]"
# Absolute paths always start from the project’s root.
# Each context is separated using ‘/’ down to the object.
# Attribute names are separated from object names using a `.`.
# Value index is specified using brackets `[ ]` like C arrays.
"path/to/object.attribute[index]"
# Relative paths always start from the context in which the
# object that contains the expression.
# They follow the same syntax as absolute paths.

Examples#

"project://scene/lighting/light.translate[0]"
# Absolute path to attribute value translate[0] of object light
# in context scene/lighting.
"project://scene/lighting/light.exposure[0]"
# Absolute path to attribute value exposure[0] of object light
# in context scene/lighting.
"project://scene/lighting/light.exposure"
# Absolute path to attribute value exposure[0] of object light
# in context scene/lighting. The value index can be ignored
# as exposure has only one value.
"project://scene/lighting/light.translate"
# Absolute path to attribute translate of object light
# in context scene/lighting.
"lighting/light.translate[0]"
# Relative path to attribute value translate[0] of object light
# in context scene/lighting from context scene.
"light.translate[0]"
# Relative path to attribute value translate[0] of object light
# in context scene/lighting from context scene/lighting.
"translate[0]"
# Relative path to attribute value translate[0] of object light
# in context scene/lighting from object scene/lighting/light.

Attribute Types Mapping#

Clarisse’s expression system uses the following mapping between attribute types and SeExpr types:

Attribute Type SeExpr Type Getter Function Comments
BOOL FP get_double Return 0 is the attribute is false, 1 otherwise.
COLOR FP[3] get_vec3 Return the RGB color as a 3D vector.
CURVE n/a n/a Unsupported attribute type.
DOUBLE FP get_double Return the attribute value as a floating-point number
ENUM STRING get_string Return the name of the current enum.
FILE STRING get_string Return the filename as a string.
GROUP STRING get_string Return the path of the referenced group.
LONG FP get_double Return the attribute value as a floating-point number
OBJECT n/a n/a Unsupported attribute type
PRESET FP get_double Return the index of the current preset.
REFERENCE STRING get_string Return the path of the referenced object.
SCRIPT STRING get_string Return the script as a string.
STRING STRING get_string Return the attribute value as a string.
TAG STRING get_string Return the current tag name as a string.
VEC3D FP[3] get_vec3 Return the attribute value as a 3D vector.

Examples#

get_double("project://scene/lighting/light.enable")
# Returns 1 if the enable attribute of item light
# is true, or 0 otherwise.
get_double("project://scene/lighting/light.exposure")
# Returns the exposure of the light
get_double("project://scene/lighting/light.translate[0]")
# Returns the 1st component of the translation
# vector of item light.
get_string("project://scene/lighting/light.parent")
# Returns the path to the parent item of light.
get_vec3("project://scene/lighting/light.translate")[0]
# Returns the 1st component of the translation
# vector of item light.
v = get_vec3("project://scene/lighting/light.translate");
# Stores the translation vector of item light in variable v.

v[0] + v[1] + v[2]
# Returns the sum of all components of v.

Using Global Variables#

In Clarisse, global variables can be defined from the command-line environment (System variables), built-in values from Clarisse like $T, $F, $PDIR... (Built-in variables) or user-defined variables (Custom variables).

In Clarisse’s expression system, all global variables are automatically exposed as predefined variables to SeExpr scripts and they follow the same name as the global variable but without the $ symbol.

For instance, the global time variable $T is exposed as T and is directly usable without any declaration.

Examples#

fcurve(T)
# Evaluates the f-curve at time $T and returns its value
frame = T * FPS;
# Converts global time $T into frames using global variable $FPS
filename = PDIR + "my_archive.abc";
# Concatenate the project directory variable with "my_archive.abc"

Note

Assigning a value to a global variable is allowed but will only change its value locally. You can think of it like a local override of a global value. Example:

T = 2;
# Assuming global time $T = 0s, local T is now 2.

fcurve(T)
# Evaluates the f-curve at time 2s and returns its value.
# Note that the global time remains unchanged at 0s.

Constants and Functions Reference#

Function Description
FP fcurve(FP time, STRING path = "") Evaluate the f-curve bound the the attribute value given as path for the given time. Note that an empty path will evaluate the f-curve of the attribute for which the expression is being executed.
STRING find_item(STRING rule,STRING type) Return the absolute path of the 1st item corresponding to the given rule and the given type.

rule is a rule that follow the same rule syntax as in Groups.
type is either a class name (the function returns an object's path) "Context" (the function returns a path to a context, whatever its type) or "Reference" (you've guessed it: returns a path to reference contexts only)

If nothing matches, an empty string is returned.
Example:
find_item("project://scene/*", "Light") which returns the 1st light found in project://scene/*

find_item("project://scene/*", "Context") which returns the 1st context found in project://scene/*

find_item("project://scene/*", "Reference") which returns the 1st reference found in project://scene/*
STRING get_context(STRING path = "") When path is empty, return the path of the context of the current object in which the expression is being executed.When path is not empty, split the path according to / in N tokens and return the first N-1 tokens corresponding to the context path containing the item.
Example:
path = "A/B/C/D", get_context returns "A/B/C"
FP get_double(STRING path) Return the floating-point value of the attribute value given as path.
Example:
get_double("project://scene/light.translate[0]")
FP get_name(STRING path = "") When path is empty, return the name of the current object in which the expression is being executed. When path is not empty, split the path according to / and return the last token corresponding to the name of the item.
Example:
path = "A/B/C/D" returns "D"

Note that path = get_context(path) + "/" + get_name(path)
FP get_obj_var(STRING var)
FP get_obj_var(STRING var, FP index)
FP get_obj_var(STRING path, STRING var)
FP get_obj_var(STRING path, STRING var, FP index)
Returns the value of a Clarisse object's variable. For instance, if you're loading an Alembic file where objects have a foo property with 10 values, if you want to retrieve the first value, here are the 4 variants of this function:
1. get_obj_var("foo")[0]
2. get_obj_var("foo", 0)
3. get_obj_var("project://bar", "foo")[0]
4. get_obj_var("project://bar", "foo", 0)

Variants 1 and 2 will retrieve the variable from the object the expression is bound to, while 3 and 4 retrieve the variable from another object by its address.

Note that variants 1 and 3 return an array of the value, while 2 and 4 return a single value. Finally please note that returning a single value is a lot more efficient and should be privileged.
STRING get_string(STRING path) Return the string value of the attribute value given as path.

Example:
get_string("project://scene/light.parent")
VECTOR get_vec3(STRING path) Return the vector value of the vector attribute given as path.

Example:
get_vec3("project://scene/light.translate")
STRING join_path(STRING path1, … , STRING path N) Concatenate all path and insert a platform specific file path separator between each path.

Example:
on Linux:join_path("A", "B") returns "A/B"
On Windows: join_path("A", "B") returns "A\B"
STRING to_string(FP x)
STRING to_string(FP x, FP decimals)
Return a string representing the given number.

Example:
to_string(3.14) returns "3.14"
to_string(3.14, 1) returns "3.1"
to_string(3.14, 0) returns "3"