From Derivative
(Redirected from Python)
Jump to navigation Jump to search

Python In TouchDesigner[edit]

TouchDesigner uses Python for scripting tasks. A custom Python build is included, with most of the features of a standard Python installation and a huge number of tools and utilities specific to working in the software.

In addition to these links, a number of working examples can be accessed by selecting Help -> Python Examples in the TouchDesigner UI.

Learning Python[edit]

If you don't know Python, here are some good resources for learning:

Python Classes and Modules Available in TouchDesigner[edit]

TouchDesigner includes all the modules in a standard Python installation plus the following:

td: TouchDesigner's Main Python Module[edit]

All td module members and methods are available in scripts, expressions, and the textport. There is no need to import the module or its members explicitly. This is especially important in expressions, which don't allow import statements.

The following can be found in the td module:

  • Main TouchDesigner utilities - the most basic starting points for interacting with TouchDesigner, such as me and op().
  • TouchDesigner Python helper classes - important helper objects used to organize functions and information pertaining to a specific part of TouchDesigner.
  • Operator related classes - every Operator in TouchDesigner has an associated Python class in the td module. Their wiki pages can be accessed by clicking on the Python Help button in their parameter dialog. There are also a number of associated Python objects that are used when working with Operators.
  • Useful standard Python modules - the td module also automatically imports a number of helpful standard modules (e.g. math), allowing them to be accessed in expressions through their namespace.

TouchDesigner Utility Modules[edit]

TouchDesigner also contains utility modules for advanced Python programming. Utility modules are not imported into the td module automatically. Instructions for their use can be found on their wiki pages.

3rd Party Packages[edit]

TouchDesigner includes a number of 3rd party Python packages that are generally useful when working with the software. These are not included in the td module so must be imported explicitly.

Installing Custom Python Packages[edit]

Part of the great power of Python is its access to the countless number of modules that have been created. If you want to use modules that are not included in the above, use the following steps:

  1. Install a parallel copy of the same version of Python to the hard disk. The current version of Python shipped with TouchDesigner is 3.7. It can also be found here..
  2. Install the package to the parallel python installation, following its normal installation procedure.
  3. Launch Python and import the module manually to make sure there are no errors.

Once the module is successfully installed, it will automatically be visible in TouchDesigner by default. This option is found under the Edit->Preferences menu as "Add External Python to Search Path". Alternatively you can add the search path by modifying the Preference labelled "Python 32/64 bit Module Path". Multiple paths are separated by semicolons (;). Finally you can modify the search path directly by either modifying the system environment variable PYTHONPATH or by executing a script which appends the path to sys.path as in the example below.

import sys
mypath = "C:/Python37/Lib/site-packages"
if mypath not in sys.path:

Examples of other useful Python modules are here. Unofficial precompiled modules found on Christoph Gohlke's website.

Overriding Built-In Modules[edit]

TouchDesigner comes with many specific modules pre-installed. If you require a different version, find the TouchDesigner folder where the original is included and remove it from the search path before importing. For example:

import sys
sys.path.remove('C:\\Program Files\\Derivative\\TouchDesigner\\bin\\lib\\site-packages')

Python Gotchas[edit]

There are a few things in standard Python that can trip you up in TouchDesigner. If you find anything that's not included here, post in the forum!

  • Some TouchDesigner objects (especially parameters and CHOP channels) will try to act as the correct data type for their context. For example, a Float parameter object (myOp.par.Float1) will act like a floating point number in most cases, but it is still a parameter object. For example round(myOp.par.Float1) will not work. To get the actual value of a parameter or channel, use its .eval() method. If you think you may be encountering this problem, you can tell the difference by using the repr function. For example repr(myOp.par.Float1) will show that this is a parameter and not a number.
  • same goes with operator parameter types. if a parameter is a path to a CHOP, n.par.Chop usually works, but to be safe, n.par.Chop.eval() always works.
  • subprocess.Popen doesn't work with file-like objects. See this forum post for details.
  • Python threads don't have access to TouchDesigner objects. Search "threading" in the forum to see some workarounds.

More In The Python Category[edit]