Experimental:td Module

The td module contains all TouchDesigner related Python classes and utilities. All td module members and methods are imported when the application launches and are automatically available in scripts, expressions, and the textport.

For additional helpful Python classes and utilities not directly related to TouchDesigner, see the TDU Class

Members

me → OP (Read Only):

Reference to the current operator that is being executed or evaluated. This can be used in parameter expressions, or DAT scripts.

absTime → AbsTime (Read Only):

Reference to the AbsTime object.

app → App (Read Only):

Reference to the application installation.

debug(*args)→ None:

Print all args and extra debug info (default is DAT and line number) to texport. To change behavior, use the debugControl component or tdu.debug.setStyle function. See debug module for more info
TIP: Use debug instead of print when debugging Python scripts in order to see object types and the source of the output.

ext → Ext (Read Only):

Reference to the extension searching object. See extensions for more information.

families → dict (Read Only):

A dictionary containing a list of operator types for each operator family.
for a in families['SOP']:
	# do something with a

licenses → Licenses (Read Only):

Reference to the currently installed licences.

mod → MOD (Read Only):

Reference to the Module On Demand object.

monitors → Monitors (Read Only):

Reference to the group of available monitors.

op → OPShortcut (Read Only):

The operator finder object, for accessing operators through paths or shortcuts. Note: a version of this method that searches relative to a specific operator is also in OP Class.
op(pattern1, pattern2..., includeUtility=False) → OP or None
Returns the first OP whose path matches the given pattern, relative to root. Will return None if nothing is found. Multiple patterns may be specified which are all added to the search. Numeric OP ids may also be used.

pattern - Can be string following the Pattern Matching rules, specifying which OP to return, or an integer, which must be an OP Id. Multiple patterns can be given, the first matching OP will be returned.

includeUtility (Optional) - if True, allow Utility nodes to be returned. If False, Utility nodes will be ignored.
b = op('project1')
b = op('foot*', 'hand*')
b = op(154)
op.shortcut → OP
An operator specified with by a Global OP Shortcut. If no operator exists an exception is raised. These shortcuts are global, and must be unique. That is, cutting and pasting an operator with a Global OP Shortcut specified will lead to a name conflict. One shortcut must be renamed in that case. Furthermore, only components can be given Global OP Shortcuts.
shortcut - Corresponds to the Global OP Shortcut parameter specified in the target operator.
b = op.Videoplayer
To list all Global OP Shortcuts:
for x in op:
	print(x)

opex → OPEXShortcut (Read Only):

An operator finder object, for accessing operators through paths or shortcuts. Works like the op() shortcut method, except it will raise an exception if it fails to find the node instead of returning None as op() does. This is now the recommended way to get nodes in parameter expressions, as the error will be more useful than, for example, NoneType has no attribute "par", that is often seen when using op(). Note: a version of this method that searches relative to '/' is also in the global td module.
op(pattern1, pattern2..., includeUtility=False) → OP

Returns the first OP whose path matches the given pattern, relative to the inside of this operator. Will return None if nothing is found. Multiple patterns may be specified which are all added to the search. Numeric OP ids may also be used.

pattern - Can be string following the Pattern Matching rules, specifying which OP to return, or an integer, which must be an OP Id. Multiple patterns can be given, the first matching OP will be returned.

includeUtility (Optional) - if True, allow Utility nodes to be returned. If False, Utility operators will be ignored.

ops → OPsShortcut (Read Only):

Returns a (possibly empty) list of OPs that match the patterns, relative to root.
Multiple patterns may be provided. Numeric OP ids may also be used.

pattern - Can be string following the Pattern Matching rules, specifying which OPs to return, or an integer, which must be an OP Id. Multiple patterns can be given and all matched OPs will be returned.

includeUtility (Optional) - if True, allow Utility nodes to be returned. If False, Utility operators will be ignored.
Note a version of this method that searches relative to an operator is also in the OP Class.
newlist = n.ops('arm*', 'leg*', 'leg5/foot*')

parent → ParentShortcut (Read Only):

The Parent Shortcut object, for accessing parent components through indices or shortcuts.
Note: a version of this method that searches from a specific operator is also in OP Class.
parent(n) OP or None
The nth parent of the current operator. If n not specified, returns the parent. If n = 2, returns the parent of the parent, etc. If no parent exists at that level, None is returned.

n - (Optional) n is the number of levels up to climb. When n = 1 it will return the operator's parent.
p = parent(2) #grandfather
parent.shortcut OP
A parent component specified with a shortcut. If no parent exists an exception is raised.

shortcut - Corresponds to the Parent Shortcut parameter specified in the target parent.
   n = parent.Videoplayer
See also Parent Shortcut for more examples.

iop → IOPShortcut (Read Only):

The Internal Operator Shortcut object, for accessing internal shortcuts. Note: a version of this method that searches from a specific operator is also in OP Class.

ipar → IparShortcut (Read Only):

The Internal Operator Parameter Shortcut object, for accessing internal shortcuts. Note: a version of this method that searches from a specific operator is also in OP Class.

project → Project (Read Only):

Reference to the project session.

root → baseCOMP (Read Only):

Reference to the topmost root operator.

runs → Runs (Read Only):

Reference to the runs object, which contains delayed executions.

sysinfo → SysInfo (Read Only):

Reference to the system information.

tdu → TDU (Read Only):

Access to TDU, TouchDesigner Utility functions and members.

ui → UI (Read Only):

Reference to the ui options.

Methods

passive(OP)→ OP:

Returns a passive version of the operator. Passive OPs do not cook before their members are accessed.

run(script, *args, endFrame=False, fromOP=None, asParameter=False, group=None, delayFrames=0, delayMilliSeconds=0, delayRef=None)→ Run:

Run the script, returning a Run object which can be used to optionally modify its execution. This is most often used to run a script with a delay, as specified in the delayFrames or delayMilliSeconds arguments. See Run Command Examples for more info.
script - A string that is the script code to execute.

args - (Optional) One or more arguments to be passed into the script when it executes. They are accessible in the script using a tuple named args.

endFrame - (Keyword, Optional) If True, the execution will be delayed until the end of the current frame.

fromOP - (Keyword, Optional) Specifies an optional operator from which the execution will be run relative to.

asParameter - (Keyword, Optional) When fromOP used, run relative to a parameter of fromOP.

group - (Keyword, Optional) Can be used to specify a string label for the group of Run objects this belongs to. This label can then be used with the td.runs object to modify its execution.

delayFrames - (Keyword, Optional) The number of frames to wait before executing the script.

delayMilliSeconds - (Keyword, Optional) The number of milliseconds to wait before executing the script. This value is rounded to the nearest frame.

delayRef - (Keyword, Optional) Specifies an optional operator from which the delay time is derived. You can use your own independent time component or op.TDResources, a built-in independent time component. If no delayRef is provided, uses root

fetchStamp(key, default)→ Any:

Return an object from the global stamped parameters. If the item is not found, the default is returned instead. Parameters can be stamped with the Copy SOP.
key - The name of the entry to retrieve.

default - If no item is found then the passed value is returned instead.
v = fetchStamp('sides', 3)

var(varName)→ str:

Find the value for the given variable.

varExists(varName)→ bool:

Returns true if the variable is defined.

varOwner(varName)→ OP | None:

Returns the operator that defines the variable, or None if it's not defined.

isMainThread()→ bool:

Is True when called from the main application editing thread. Any calls that access operators, etc., must be called from the main thread.

clear()→ None:

Clear the textport of all text.

Python Classes and Modules

More detailed information about the contents of td module:

The following list of important Python classes and modules is roughly grouped together by subject.

Python Reference has an alphabetical list of all TouchDesigner Python pages on this wiki.

Operator Related Classesedit

The following classes are Python interfaces for operators and objects that operators use. Individual operator classes (e.g. TextTOP Class and RampTOP Class) are not listed but do exist in the td module, and links to each can be found here or by clicking on the Python Help button in their parameter dialog. These classes are found in the td module so do not need to be imported.

OP Class - a TouchDesigner operator.
- Connector Class - a wire connector for an OP. Lists of these can be found in OP.inputConnectors and OP.outputConnectors. Components also have COMP.inputCOMPConnectors and COMP.outputCOMPConnectors.
- Page Class - a parameter page. Lists of these can be found in OP.pages and, on components and script operators, OP.customPages.
- ParCollection Class (OP.par) - holds all the parameters for an OP.
  - Par Class - an individual parameter.
- ParGroupCollection Class (OP.par) - holds all the parameter groups for an OP.
  - ParGroup Class - an individual parameter group.
- SequenceCollection Class (OP.seq) - holds all the sequences for an OP.
  - Sequence Class - describes and controls a set of sequential parameters. Sequential parameters will have a reference to one of these objects in their sequence member.
    - SequenceBlock Class - used to access the parGroups of a specific block (set of parGroups) in a sequence.
- CHOP Class - subclass of OPs defining CHOP operators.
  - Channel Class - a channel object. Accessed through a CHOP index or other CHOP members such as chan, chans etc.
  - Segment Class - describes a single segment from a Timer CHOP.
- COMP Class - a subclass of OPs defining component operators.
  - ObjectCOMP Class - a subclass of COMPs defining Objects, used to create and render 3D scenes.
  - PanelCOMP Class - a subclass of COMPS defining Panel Components, used to create 2D UI elements.
    - Panel Class - a member of panelCOMPs containing all associated panel values. Accessed through panelCOMP.panel.
      - PanelValue Class - individual panel values. Accessed through the panel member of panelCOMPS and also in callbacks in the Panel Execute DAT.
    - ListAttributes Class - a collection of list attributes used in a ListCOMP.
      - ListAttribute Class - contains attributes defining a cell in a ListCOMP.
    - Actors Class - describes the set of all Actor COMPs used by the Bullet Solver COMP and Nvidia Flex Solver COMP. used in a BulletsolverCOMP or flexsolverCOMP.
    - Bodies Class - a collection of bodies used in an ActorCOMP.
      - Body Class - a single body (physics object) used in an ActorCOMP.
  - VFS Class - a COMP's Virtual File System
    - VFSFile Class - a virtual file contained within a Virtual File System.
- DAT Class - a subclass of OPs defining DAT operators.
  - Cell Class - defines an individual cell of a DAT table.
  - Peer Class - describes the network connection originating a message in the callback functions found in oscinDAT, tcpipDAT, udpinDAT, udtinDAT.
- MAT Class - a subclass of OPs defining MAT operators.
- SOP Class - a subclass of OPs defining SOP operators.
  - Attributes Class - a collection of SOP attributes
    - Attribute Class - information about an entity such as its color, velocity, normal, and so on.
      - AttributeData Class - contains specific geometric Attribute values, associated with a Prim Class, Point Class, or Vertex Class.
  - Group Class - describes groups lists of Prim Class or Point Class.
  - Points Class - a collection of points.
    - Point Class - a single geometry point.
      - InputPoint Class - a special point object used in Point SOP parameters.
  - Prims Class - a collection of primitives.
    - Prim Class - a single geometry primitive.
      - Poly Class - a subclass of Prim defining a geometry polygon.
      - Mesh Class - a subclass of Prim defining a geometry mesh.
      - Bezier Class - a subclass of Prim defining a set of Bezier curves.
      - Vertex Class - a member of Prim defining a single geometry vertex.
- TOP Class - a subclass of OPs defining TOP operators.
  - CUDAMemory Class - holds a reference to CUDA memory.
    - CUDAMemoryShape Class - describes the shape of a CUDA memory segment.
  - TextLine Class - a line of text in the Text TOP or Text SOP, after it has been formatted. Contains various members about the line such as it's text, position etc.

Helper Classesedit

The following helper objects are part of the td module and can thus be accessed anywhere, including expressions, without imports (e.g. absTime.frame).

AbsTime Class (absTime) - information about absolute time
App Class (app) - information about the TouchDesigner app, including version, installation folders, etc.
Project Class (project) - information about the current TouchDesigner session
Tdu Module (tdu) - generic utilities for TouchDesigner not relating directly to TD objects.
- ArcBall Class (tdu.ArcBall) - encapsulates many aspects of 3D viewer interaction.
- Camera Class (tdu.Camera) - maintains a 3D position and orientation for a camera and provides multiple methods for manipulating the camera's position and direction.
- Color Class (tdu.Color) - holds a 4 component color
- Dependency Class (tdu.Dependency) - used to create Dependable Python data.
- Matrix Class (tdu.Matrix) - holds a single 4x4 matrix for use in transformations. See ObjectCOMP Class for transforms of 3D objects.
- Position Class (tdu.Position) - holds a 3 component position
- Quaternion Class (tdu.Quaternion) - holds a quaternion object for 3D rotations
- Timecode Class (tdu.Timecode) - holds a timecode value
- Vector Class (tdu.Vector) - holds a 3 component vector

Licenses Class (licenses) - information about installed license objects
- DongleList Class (licenses.dongles) - list of attached dongles
  - Dongle Class - an individual dongle connected to the system
- License Class - a single instance of an installed license
  - - ProductEntry Class - a dongle entry for a single dongle connected to the system
MOD Class (mod) - access to modules located in TouchDesigner DATs
Monitors Class (monitors) - access to information about all connected display devices
- Monitor Class - an individual display device
Runs Class (runs) - information about all delayed run objects
- Run Class - an individual delayed run object
SysInfo Class (sysInfo) - current system/hardware information
UI Class (ui) - information about application ui elements
- Colors Class (ui.colors) - application colors
- Options Class (ui.options) - configurable ui options
- Panes Class (ui.panes) - collection of all panes open in the editor
  - Pane Class - an individual pane object
    - NetworkEditor Class - subclass of Pane that displays a network editor
- Preferences Class (ui.preferences) - collection of TouchDesigner preferences
- Undo Class (ui.undo) - tools for interacting with the undo system, including creating script-based undo steps

Standard Python Modulesedit

The td module also automatically imports a number of helpful standard modules, allowing them to be accessed in expressions through their namespace (e.g. math.cos(math.pi)):

collections - container datatypes
enum - support for enumerations
inspect - inspect live objects
math - mathematical functions
re - regular expression operations
sys - OS specific data and functions
traceback - stack utilities
warnings - warning control

TouchDesigner Utility Modules and Python Utilitiesedit

The following contain extended Python utilities for use with TouchDesigner.

TDFunctions - A variety of utilities for advanced Python coding in TouchDesigner.
TDJSON - JSON utilities specific to TouchDesigner.
TDStoreTools - utilities for use with TouchDesigner's Storage and Dependency system.
TDResources (op.TDResources...) - not a module, but does contain system resources that can be accessed via Python. It includes system pop-up menu, button pop-up menu, pop-up dialog, and mouse resources.

3rd Party Packagesedit

The following 3rd party packages are automatically installed with TouchDesigner. They are not in the td module, so must be imported explicitly to be used in scripts. The name in parentheses is the actual package name used (e.g. to use OpenCV, write this at top of script: import cv2). For information on adding or installing other Python modules, see Importing Modules.

asn1crypto (asn1crypto) - Parsing and serializing ASN.1 structures.
attrs (attr) - Classes without boilerplate.
Certifi (certifi) - Root Certificates for validating the trustworthiness of SSL certificates while verifying the identity of TLS hosts.
CFFI (cffi) - Interaction with C code.
Chardet (chardet) - The Universal Character Encoding Detector.
charset-normalizer (charset_normalizer) - A library that helps you read text from an unknown charset encoding.
Cryptography (cryptography) - High level recipes and low level interfaces to common cryptographic algorithms.
decorator (decorator) - Define signature-preserving function decorators and decorator factories.
OAuthlib (oauthlib) - Library to build OAuth and OpenID Connect servers.
opencv-python (cv2) - Pre-built CPU-only OpenCV packages for Python.
depthai (depthai) - Python bindings for C++ depthai-core library.
idna (idna) - Support for the Internationalised Domain Names in Applications (IDNA) protocol.
jsonpath (jsonpath_ng) - JSONPath tools for accessing and altering JSON structures.
jsonschema (jsonschema) - jsonschema is an implementation of the JSON Schema specification for Python.
MWParserFromHell (mwparserfromhell) - An easy-to-use and outrageously powerful parser for MediaWiki wikicode.
NumPy (numpy) - Fundamental package for scientific computing with Python.
OpenCV (cv2) - Open source computer vision.
packaging (packaging) - Package tools including version handling, specifiers, markers, requirements, tags, utilities. Used for version string comparison.
pip (pip) - pip is the package installer for Python. You can use pip to install packages from the Python Package Index and other indexes.
ply (ply) - Parsing tools for lex and yacc.
Pygments (pygments) - A syntax highlighting package written in Python.
pyparsing (pyparsing) - A library of classes that client code uses to construct parsing grammar directly in Python code.
pyrankvote (pyrankvote) - PyRankVote is a python library for different ranked-choice voting systems (sometimes called preferential voting systems) created by Jon Tingvold in June 2019.
pyrsistent (pyrsistent) - Pyrsistent is a number of persistent collections (by some referred to as functional data structures). Persistent in the sense that they are immutable.
PyYAML (yaml) - YAML parser and emitter.
Requests (requests) - The only Non-GMO HTTP library for Python, safe for human consumption
Requests OAuthlib (requests_oauthlib) - Easy-to-use Python interface for building OAuth1 and OAuth2 clients
six (six) - Python 2 and 3 compatibility utilities.
smartypants (smartypants) - a Python fork of SmartyPants.
tabulate (tabulate) - Pretty-print tabular data in Python.
urllib3 (urllib3) - HTTP client.
whats-that-code (whats_that_code) - programming language detection library.

Installing Custom Packages and Modulesedit

You can also install your own Python packages that are not included with TouchDesigner. For instructions, go here.

TouchDesigner Build:

Privacy policy

Follow us