Optimized Python Expressions

From Derivative
Jump to navigation Jump to search

Overview[edit]

Optimized Python Expressions[edit]

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 Expressions[edit]

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 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), as long as both arguments aren't integers.
    • // (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
    • fetch(), in some cases.
  • TOP Class methods and members:
    • width
    • height
    • aspectWidth
    • aspectHeight
  • 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
  • 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

Python Math Module constants and functions :

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