Optimized Python Expressions

Overviewedit

Optimized Python Expressionsedit

Starting with the 2018.20000 series of builds, a custom Python expression execution engine has been incorporated 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. The Perform CHOP has a parameter to monitor the number of optimized expressions.

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.

Cached Python Expressionsedit

In addition to optimized expressions, a new system that caches expression results will keep them from re-calculating every frame. The Perform CHOP has a parameters to monitor the number cached expressions.

What can the engine evaluateedit

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), as long as both arguments aren't integers.
  • // (floor division)

• single line if expressions

• Global td module functions:
  • op()
  • parent()
  • passive()

• Tdu Module functions:
  • remap()
  • rand()

• AbsTime Class methods and members:
  • frame
  • seconds

• OP Class methods and members:
  • name
  • par
  • digits
  • time
  • path
  • inputs
  • inputCOMPs
  • outputCOMPs
  • fetch(), in some cases.

• TimeCOMP Class methods and members:
  • frame
  • seconds
  • rate

• CHOP Class methods and members:
  • rate
  • numSamples
  • start
  • end
  • [] operator to access a Channel Class object.

• DAT Class methods and members:
  • [] operator access a Cell Class object.

• TOP Class methods and members:
  • width
  • height
  • aspectWidth
  • aspectHeight

• Panel Class methods and members:
  • width
  • height

• ParCollection Class methods and members:
  • . operator to get a Par Class object.
  • [] operator to get a Par Class object.

• Par Class methods and members:
  • eval()
  • evalNorm()
  • normVal
  • default
  • menuIndex
  • 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

• Python list class methods and members:
  • [] operator
  • any(list)
  • len(list)
  • all(list)

• Python math module functions:
  • abs()
  • max()
  • min()
  • round()

• Python global functions:
  • pow()
  • int()
  • str()
  • bool()
  • float()
  • getattr() (In limited cases)

• Project Class methods and members:
  • cookRate (get only)

• SOP Class methods and members:
  • center
  • numPrims
  • numPoints

• primitiveSOP Class the me.inputPrim Prim Class has these members optimized:
  • me.inputPrim.index
  • me.inputPrim.center
  • me.inputPrim.direction
  • me.inputPrim.weight
  • me.inputPrim.normal
  • len(me.inputPrim)

• pointSOP Class has these special cases optimized:
  • 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 :
  • [] operator
  • x, y and z members

• Position Class :
  • [] operator
  • x, y and z members

• Color Class :
  • [] operator
  • r, g, b and a members

• Panel Class :
  • Access to Panel Values.

• PanelValue Class
  • Automatic casting
  • val member

• expressionCHOP Class methods and members :
  • inputVal
  • chanIndex
  • sampleIndex

• waveCHOP Class methods and members :
  • chanIndex
  • sampleIndex

Python Math Module constants and functions :

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