Optimized Python Expressions

From Derivative
Jump to: navigation, search

Overview[edit]

Starting with the 2018.20000 series of builds, we have incorporated a custom Python expression execution engine into TouchDesigner. This engine will parse Python expressions that are in parameters. Assuming the members and methods used in that expression fall into the range of members and methods the engine is aware of, it will evaluate the expression without having to use Python's engine. This generally results in a the expression evaluating in about 1/4 of the time than it does if it was evaluated through the regular Python engine.

The goal of this feature isn't to evaluate every parameter expression using this engine, but to evaluate the most commonly used expressions. You can determine if an expression is evaluated using this engine by holding the mouse over the parameter name. It will show either (Optimized) or (Unoptimized) in the popup that will show up.

If an expression ever ends up causing an error, the engine will stop being used for that expression and the Python engine will be used instead. If the expression is changed, or on the next time the file is loaded, TouchDesigner will once again try to use the engine to evaluate the parameter.

What can the engine evaluate[edit]

When a Python expression is parsed it is broken up into tokens. A token can be for example a constant boolean value True or a constant string. Tokens are also the methods, members and variable names that are part of an expression. The engine has a set of tokens it recognizes, and if the expression contains only those tokens, then it can evaluate the expression. If there are any tokens it does not recognize in the expression, then it will not try to evaluate the expression and the regular Python engine will be used.

As long as the expression contains only tokens recognized by the engine, the there is no limit to how large the expression and be or how complex the expression can be.

For example this expression can be evaluated by the optimized expression engine:

 op(‘geo1’).par.tx + math.max(parent().par.tx + op(‘speed1’)[0], 10) / int(op('table1')['header', 5])

The types of supported tokens are:

  • the 'me' variable
  • Constants:
    • Strings
    • Booleans (True, False)
    • Integers
    • Floats
  • Comparison operators:
    • ==
    • !=
    • <
    • >
    • >=
    • <=
  • Unary operators:
    • - (negate)
    • +
    • ~ (invert)
  • Boolean operators:
    • and
    • or
  • Binary operators, for numerical and string operations:
    • +
    • -
    • *
    • /
    • % (modulus)
    • ** (power)
    • // (floor division)
  • single line if expressions
  • Global td module functions:
    • op()
    • parent()
    • passive()
  • OP Class methods and members:
    • name
    • par
    • digits
    • time
    • path
    • inputs
    • inputCOMPs
    • outputCOMPs
  • TOP Class methods and members:
    • width
    • height
    • aspectWidth
    • aspectHeight
  • Par Class methods and members:
    • eval()
    • normVal
    • automatic casting to int/float/string
  • Channel Class methods and members:
    • eval()
    • [] operator to get a single sample from a CHOP channel.
    • automatic casting
  • Cell Class methods and members:
    • eval()
    • [r,c] operator to get a cell from a DAT table.
    • automatic casting
  • Project Class methods and members: (Builds 2018.22040 or later)
    • cookRate (get only)
  • SOP Class methods and members (Builds 2018.40000 or later):
    • center
    • numPrims
    • numPoints
  • Primitive SOP the me.inputPrim Prim Class has these members optimized (Builds 2018.40000 or later):
    • me.inputPrim.index
    • me.inputPrim.center
    • me.inputPrim.direction
    • me.inputPrim.weight
    • me.inputPrim.normal
    • len(me.inputPrim)
  • Point SOP has these special cases optimized (Builds 2018.40000 or later):
    • Includes inputPoint2, inputColor2, inputNormal2 and inputTexture2 as well.
    • me.inputPoint.index
    • me.inputPoint.normP
    • me.inputPoint.P
    • me.inputPoint.x
    • me.inputPoint.y
    • me.inputPoint.z
    • me.inputPoint.normal
    • me.inputPoint.color
    • me.inputPoint.sopCenter
    • me.inputColor (Deprecated)
    • me.inputNormal (Deprecated)
    • me.inputTexture


  • Vector Class (Builds 2018.40000 or later):
    • [] operator
    • x, y and z members
  • Position Class (Builds 2018.40000 or later):
    • [] operator
    • x, y and z members
  • Color Class (Builds 2018.40000 or later):
    • [] operator
    • r, g, b and a members
  • Panel Class (Builds 2018.40000 or later):
    • Access to Panel Values.
  • expressionCHOP Class methods and members (Builds 2018.40000 or later):
    • inputVal
    • chanIndex
    • sampleIndex
  • waveCHOP Class methods and members (Builds 2018.40000 or later):
    • chanIndex
    • sampleIndex

Python Math Module constants and functions (Builds 2018.40000 or later):

    • pi
    • sin()
    • cos()
    • tan()
    • asin()
    • acos()
    • ceil()
    • floor()
    • sqrt()
    • degrees()
    • radians()

An Operator Family which operate on Channels (a series of numbers) which are used for animation, audio, mathematics, simulation, logic, UI construction, and many other applications.

An Operator Family that manipulates text strings: multi-line text or tables. Multi-line text is often a command Script, but can be any multi-line text. Tables are rows and columns of cells, each containing a text string.