Script

The Script node evaluates an output value using an expression written in an embedded script. The script syntax is similar to Python 3. Compiled on-the-fly in native machine code, the evaluation speed is similar to that of a C++ plug-in.

Create a script node

In the node editor, press Tab, then type Script. Right click the new node and choose Edit Script.

Type your script and press CTRL+Space to compile it. Input and output plugs are then created and the node is ready to use. Modify the script and re-compile it if needed.

Main differences with Python 3

In order to be efficient, the script language has differences with Python 3:

  • The language is strongly typed. Each variable has a type.

  • The main function’s arguments must be explicitly typed.

  • Changing the type of a variable is forbidden.

a = 1.0
a = "str"
>>> Error

  • All the class members must be initialized in __init__. Changing their type is forbidden.

class MyClass:
    def __init__(self, a, b):
        self.a = a
        self.b = b

  • No global variables

  • No module except the one listed below.

  • No type except the one listed below. (no list, no dict for the moment)

  • No None keyword, exception, lambda function nor local function definition

Syntax

The language is a subset of Python 3. Here is a list of the supported syntax features:

  • Statements: if, else, elif, for, while, in, continue, break, return, pass, def, class, import, from, as

  • Operators: +, -, , |, ^, &, <<, >>, @, /, %, //, ==, !=, <, <=, >=, >, *, and, or, is, is not, in, not in

  • Augmented assignments (+=, *=, etc..)

  • User defined functions, multiple returned values, var args support

  • User defined classes (no inheritance)

  • Ternary operator: a if condition else b

Types

Here is a list of the basic types:

  • bool

  • int

  • float (a 32 bits floating point number) a = float(123.0) # a is single precision

  • double (a 64 bits floating point number) a = 123.0 # a is double precision

  • str

  • tuple a = (1,"foo",3.0) return 1,"foo",3.0

  • class

  • module

  • type

The main function

A valid script must contain at least a main function with typed arguments.

def main(b:bool, i:int, f:float, s:str):
    ...

The main function must return a single value.

Here are the supported types for the main function arguments and returned value : bool, int, float, double, str, Imath.V2i, Imath.V3i, Imath.V4i, Imath.V2f, Imath.V3f, Imath.V4f, Imath.M33f, Imath.M44f, Imath.Quatf, Imath.V2d, Imath.V3d, Imath.V4d, Imath.M33d, Imath.M44d, Imath.Quatd, rumba.Value, rumba.Array, rumba.Scene (other Rumba Values to come soon).

Exemples

Here is a first basic node which adds two numbers:

def main(x:float, y:float):
    return x+y

A parent constraint example:

import Imath

# Compute a parent constraint matrix. The returned matrix is the constrained node's local matrix.
# parent_world is the constrained node's parent world matrix
# target_world is the target world matrix to match
def main(parent_world:Imath.M44d, target_world:Imath.M44d):
    return target_world * parent_world.inverse(True)

A matrix interpolation example:

import Imath

# Linear interpolation of two matrices, using a decomposition in scale,
# shear, quaternion, translation
# Similar with rumba.lerp(a:M44d, b:M44d, t:double)
def main(a:Imath.M44d, b:Imath.M44d, r:double):
    # Decompose a
    a_t = a.translation()   # Translation
    a_s = Imath.V3d(1.0)    # Scale
    a_h = Imath.V3d(0.0)    # Shear
    Imath.extractAndRemoveScalingAndShear(a, a_s, a_h, False)
    a_q = Imath.extractQuat(a) # Quaternion

    # Decompose b
    b_t = b.translation()   # Translation
    b_s = Imath.V3d(1.0)    # Scale
    b_h = Imath.V3d(0.0)    # Shear
    Imath.extractAndRemoveScalingAndShear(b, b_s, b_h, False)
    b_q = Imath.extractQuat(b) # Quaternion

    # Linear interpolation of the matrix components
    s = Imath.lerp(a_s, b_s, r)
    h = Imath.lerp(a_h, b_h, r)
    # Interpolate the quaternions using the shortest arc
    q = Imath.slerpShortestArc(a_q, b_q, r)
    t = Imath.lerp(a_t, b_t, r)

    # Recompose the final matrix
    result = Imath.M44d() # Identity
    result.translate(t)
    result = q.toMatrix44() * result
    result.shear(h)
    result.scale(s)

    return result

Library Reference