Working with DATs in Python

From TouchDesigner Documentation
Jump to: navigation, search

The main documentation for the methods and classes you use to work with DATs are the DAT Class and Cell Class articles. This article gives examples of using those methods and classes.

Getting Started[edit]

The main class type describing any Operator is the base OP Class. You will need a reference to one of these to do anything. There are two global operator objects are always available (except for in the Textport):

  • me refers to the operator that is currently being evaluated or executed. For example, when executing a script, me refers to the containing DAT. When evaluating an expression, me refers to the containing operator.
  • root refers to the top level component /.

To get references to other OPs (for example, a node named 'wave1' sitting next to the node 'constant1') the most common functions to use are: op() and ops(), for example op('wave1').

op() returns a single OP object, while ops returns a (possibly empty) list of OPs. They are described in td Module.

These functions search for operators from the current component, so both relative and absolute paths are supported. The current component is defined as: The OP that me is inside.

Note that the OP Class itself, also contains an op() and ops() method. In this case, nodes are searched from the OP.

For example: me.op('..') will always return its own parent, while op('..') will return the parent of the current component.

If you are typing a python expression in a parameter of a node 'constant1', and you wish to get a reference to 'wave1', you would type


If you are in a script you can assign this reference to a variable for easier repeated access.

n = op('wave1')

In this case op() will search relative to the DAT that is executing the script.

An OP also has a parent() method that can be use to get the parent COMP of it.


If you are putting a Python statement in a parameter of a COMP and want to refer to a child of that COMP, you can use the op() method for the OP, which is available as me in the parameters.


TIP: To find out quickly what members and methods you have access to for any node, select that node and on its parameter dialog, click the Python Help icon. You will go the wiki for the python classes for that node. There you can find out what info you can get about a node, and what methods are available for it. The documentation can also be arrived at by right clicking on the node and selecting "Python Help..." from the menu.

Refer to Working with OPs in Python for more details about this section.

Using DATs in scripts[edit]

To use a DAT in a script you would first get a reference to the DAT(s) you are interested in using op(). Ideally this would be assigned to a variable which you can use multiple times in the script without having to re-search for the OP every time you need it. Then you can use the []s on the DAT reference to refer to a specific cell. You can use either labels or indices to refer to a cell. For example this script copies cells from one table to another.

 # get a reference to a DAT named 'table1'
 n1 = op('table1')
 # get a reference to a DAT named 'table2'
 n2 = op('table2') 
# now get references to the two cells we are interested in c1 = n1['month', 'sales'] #Get cell in row labelled 'month' and column labelled 'sales' c2 = n2[3,6] # Get row 3 and column 6. (Note indices start at 0, not 1).
# Concatenate them as strings and update the cell with the new value total = c1 + c2 n2[3,6] = total

Python and TScript Equivalents[edit]

Here are some Tscript equivalent statements to help you convert to Python.


Python TScript
Get a cell value by index op('table1')[2,3] tab("table1", 2, 3)
Get a cell value by label op('table1')['r1', 'c1'] tabrc("table1", r1, c1)
Get a cell value by row index, col label op('table1')[2, 'product'] tabc("table1", 2, "product")
Cast cell to integer and float int(op('table1')['month', 3])
float(op('table1')['speed', 4])
Get the number of table rows op('table1').numRows tabnr("table1")
Get the number of table columns op('table1').numCols tabnc("table1")
Set a cell value by indeces or labels op('table1')[3,4] = 'hello'
op('table1')[2, 'answer'] = 'hello'
op('table1')['month', 3] = 'july'
tabcell table1 rc 3 4 hello
tabcell table1 rC 2 answer hello
tabcell table1 Rc month 3 july
Set a cell value by label op('table1')['r1', 'c1'] = 'abc' tabcell "table1" RC r1 c1 "abc"
Copy a table to another table op('table1').copy(op('fromTable')) type fromTable >table1
Append a row to a table op('table1').appendRow(['s1','s2', num]) echo string1 string2 num >table1
Append a column to a table op('table1').appendCol(['s1','s2', num])
Access current cell in an Evaluate DAT me.inputCell $V
Access neighboring cells in an Evaluate DAT me.inputCell.offset(1,2) v($R+1,$C+2)

A dialog box in which commands and scripts can entered manually. Script errors and python print() messages are also output to the textport.

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.

Any of the procedural data operators. OPs do all the work in TouchDesigner. They "cook" and output data to other OPs, which ultimately result in new images, data and audio being generated. See Node.

An Operator Family that contains its own Network inside. There are twelve 3D Object Component and eight 2D Panel Component types. See also Network Path.

TouchDesigner's original built-in Command scripting language prior to Python.