chopexecuteDAT Class

From TouchDesigner 099 Wiki


This class inherits from the DAT class. It references a specific CHOP Execute DAT.

The first argument to the functions in the CHOP Execute DAT is channels, which refers to the Channel class. For instance, the channel number is channels.index.


Members

No operator specific members.


Methods

No operator specific methods.


Callbacks

The following python callbacks are associated with this operator:

# me is this DAT.
#
# channel is the Channel object which has changed.
# sampleIndex is the index of the channel thats changed.
# val is the numeric value of the changed sample.
# prev is the previous sample value.
#
# Make sure the corresponding toggle is enabled in the CHOP Execute DAT.

def offToOn(channel, sampleIndex, val, prev):
    return

def whileOn(channel, sampleIndex, val, prev):
    return

def onToOff(channel, sampleIndex, val, prev):
    return

def whileOff(channel, sampleIndex, val, prev):
    return

def valueChange(channel, sampleIndex, val, prev):
    return

DAT Class

For more information on using DATs in Python, refer to Working with DATs in Python.

Members

export Get or set export flag
module (Read Only) Retrieve the contents of the DAT as a module. This allows for functions in the module to be called directly. E.g n.module.function(arg1, arg2)
numCols (Read Only) Number of columns in the DAT table.
numRows (Read Only) Number of rows in the DAT table.
text Get or set contents. Tables are treated as tab delimited columns, newline delimited rows.
locals (Read Only) Local dictionary used during python execution of scripts in this DAT. The dictionary attribute is read only, but not its contents. Its contents may be manipulated directly with scripts, or with an Examine DAT.


Methods

run(arg1, arg2..., endFrame=False, fromOP=None, group=None, delayFrames=0, delayMilliSeconds=0, delayRef=me)Run

Run the contents of the DAT as a script, returning a Run object which can be used to optionally modify its execution.
  • arg - (Optional) Arguments that will be made available to the script in a local tuple named args.
  • endFrame - (Keyword, Optional) If set to 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.
  • group - (Keyword, Optional) Can be used to specify a group label string. This label can then be used with the td.runs object to modify its execution.
  • delayFrames - (Keyword, Optional) Can be used to delay the execution a specific amount of frames.
  • delayMilliSeconds - (Keyword, Optional) Can be used to delay the execution a specific amount of milliseconds. This value is rounded to the nearest frame.
  • delayRef - (Keyword, Optional) Specifies an optional operator from which the delay time is derived.


save(filepath, append=False)string

Saves the content of the DAT to the file system. Returns the file path that it was saved to.
  • filepath - (Optional) The path and filename to save the file to. If this is not given then a default named file will be saved to project.folder
  • append - (Keyword, Optional) If set to True and the format is txt, then the contents are appended to the existing file.
   name = n.save() #save in native format with default name
   n.save('output.txt') #human readable format without channel names

write(args)string

Append content to this DAT. Can also be used to implement DAT printing functions.
   # grab DAT
   n = op('text1')
   # append message directly to DAT
   n.write('Hello World')  
   # use print method
   print('Hello World', file=n) 


Modifying Contents

The following methods can be used to modify the contents of a DAT. This can be done when the DAT is a Text DAT, or Script DAT for example, or a DAT that is Locked.

clear(keepSize=False, keepFirstRow=False, keepFirstCol=False)

Remove all rows and columns from the table.
  • keepSize - (Keyword, Optional) If set to True, size is unchanged, but entries will be set to blank, dependent on other options below.
  • keepFirstRow - (Keyword, Optional) If set to True, the first row of cells are retained.
  • keepFirstCol - (Keyword, Optional) If set to True, the first column of cells are retained.
   n.clear() #remove all rows and columns
   n.clear(keepSize=True) #set all table cells to blank
   n.clear(keepFirstRow=True) #remove all rows, but keep the first
   n.clear(keepFirstRow=True, keepFirstCol=True) #keep the first row, first column, and set remaining cells to blank

copy(DAT)

Copy the text or table from the specified DAT operator.
  • OP - The DAT operator whose contents should be copied into the DAT.

Modifying Text Contents

When the DAT is not a table, but a block of text, its contents can be simply accessed through its text member.

t = op('merge1').text
op('text2').text = 'merge1 contains:' + t
op('text3').text = "Hello there!"

Modifying a Single Cell of a Table

To modify a single cell, where inside the [], integers are the row/column numbers starting at 0, and strings are row or columns names:

tab = op('table1')
tab[0,0] = 'corner'
tab[1,'select'] = 'yes'
tab['Monday',1] = 'day1'

Modifying Table Contents

The following methods can be used to modify the contents of a table type DAT containing rows and columns. This can be done when the DAT is a basic Table DAT, or Script DAT. It can also be used to append rows to FIFO-style DATs such as the Serial DAT.

appendRow(vals, nameOrIndex, sort=None)int

Append a row to the end of the table, or after the specified row name/index. Returns the integer index of the new row.
  • vals - (Optional) If specified, will fill the row with the given values. It should be a list of items that can be expressed as strings. Each item will be copied to one cell.
  • nameOrIndex - (Optional) If specified will determine where the new row will be appended. If it's a numeric value it represents the numeric index of the row. If it is a string it represents a row label.
  • sort - (Keyword, Optional) If specified will determine the column to keep sorted after the insertion. If it's a numeric value it represents the numeric index of the column. If it is a string it represents a column label.
   n.appendRow()
   n.appendRow( [1,2,3], 'January' )  #append with values (1,2,3) after the row labelled 'January'
   n.appendRow( [1,2,3], 5 )  #append row with values (1,2,3) after the row 5.
   n.appendRow( [1,2,3], sort='Month' )  #append row with values (1,2,3) keeping column 'Month' sorted.

appendCol(vals, nameOrIndex, sort=None)int

Append a column to the end of the table. See appendRow for similar usage.

insertRow(vals, nameOrIndex, sort=None)int

Insert a row to the beginning of the table or before the specified row name/index. See DAT.appendRow() for similar usage.

insertCol(vals, nameOrIndex, sort=None)int

Insert a column to the beginning of the table or before the specified row name/index. See DAT.appendRow() for similar usage.

deleteRow(nameOrIndex)

Delete a single row at the specified row name or index.
  • nameOrIndex - May be a string for a row name, or numeric index for rowindex.

deleteCol(nameOrIndex)

Delete a single column at the specified column name or index.
  • nameOrIndex - May be a string for a column name, or numeric index for column index.


setSize(numrows, numcols)

Set the exact size of the table.
  • numrows - The number of rows the table should have.
  • numcols - The number of columns the table should have.

Accessing Table Contents

[rowNameOrIndex, colNameOrIndex]Cell

cells in a table may be accessed with the [] subscript operator.
The NameOrIndex may be an exact string name, or it may be a numeric index value. Pattern Matching is not supported.
  • rowNameOrIndex - If a string it specifies a row name, if it's numeric it specifies a row index.
  • colNameOrIndex - If a string it specifies a column name, if it's numeric it specifies a column index.
   c = n[4, 'June']
   c = n[3, 4]

cell(rowNameOrIndex, colNameOrIndex, caseSensitive=True)Cell or None

Find a single cell in the table, or None if none are found.
  • rowNameOrIndex/colNameOrIndex - If a string it specifies a row/column name. If it's numeric it specifies a row/column index. Pattern Matching is supported for strings.
  • caseSensitive - (Optional) Specifies whether or not case sensitivity is used.
   c = n.cell(5, 'June') #Return a cell under row 5, column 'June'.
   c = n.cell('A*', 2) #Find a cell under any row beginning with an A, in column 2.

cells(rowNameOrIndex, colNameOrIndex, caseSensitive=True)list

Returns a (possibly empty) list of cells that match the given row/column names or indices. See DAT.cell method for similar usage.

col(nameOrIndex1, nameOrIndex2..., caseSensitive=True)list

Returns a list of all the cells in a column, or None if nothing is found.
  • nameOrIndex - If a string it specifies a column name, if it's numeric it specifies a column index. Pattern Matching is supported.
  • caseSensitive - (Optional) Specifies whether or not case sensitivity is used.
   r = op('table1').col(3, caseSensitive=False)
   r = op('table1').col('June')
   r = op('table1').col('A*', 'B*') #returns first column beginning with A or B

cols(nameOrIndex1, nameOrIndex2..., caseSensitive=True)list of lists

Returns a (possibly empty) list of columns (each being a list themselves). See DAT.col for similar usage. If no arguments are given then all columns in the table are returned.
  • nameOrIndex - (Optional) If a string it specifies a column name, if it's numeric it specifies a column index. Pattern Matching is supported.
  • caseSensitive - (Optional) Specifies whether or not case sensitivity is used.
   for c in op('table1').cols():
       # do something with each column 'c'


row(nameOrIndex1, nameOrIndex2..., caseSensitive=True)list

Returns a list of cells from the row matching the name/index, or None if nothing is found.
See DAT.col() for similar usage.

rows(nameOrIndex1, nameOrIndex2..., caseSensitive=True)list of lists

Returns a (possibly empty) list of rows (each row being a list of cells). If no arguments are given it returns all rows in the table.
See DAT.rows() for similar usage.
   for r in op('table1').rows():
       # do something with row 'r'

OP Class

Refer to Working with OPs in Python for examples on how to work with CHOPs in Python.

Members

General

valid (Read Only) True if the referenced operator currently exists, False if it has been deleted.
id (Read Only) Unique id for the operator. This id can also be passed to the op() and ops() methods. Id's are not consistent when a file is re-opened, and will change if the OP is copied/pasted, changes OP types, deleted/undone. The id will not change if the OP is renamed though. Its data type is integer.
name Get or set the operator name.
path (Read Only) Full path to the operator.
digits (Read Only) Returns the numeric value of the last consecutive group of digits in the name, or None if not found.
base (Read Only) Returns the beginning portion of the name occurring before any digits.
passive (Read Only) If true, operator will not cook before its access methods are called. To use a passive version of an operator n, use passive(n).
time (Read Only) Time Component that defines the operator's time reference.
ext (Read Only) The object to search for parent extensions. Example: me.ext.MyClass
mod (Read Only) Get a module on demand object that searches for DAT modules relative to this operator.
par (Read Only) An intermediate parameter collection object, from which a specific parameter can be found. Example: n.par.tx
customPars (Read Only) A list of all custom parameters.
customPages (Read Only) A list of all custom pages.
customTuplets (Read Only) A list of all parameter tuplets, where a tuplet is a set of parameters all drawn on the same line of a dialog, sharing the same label.
replicator (Read Only) The replicatorCOMP that created this operator, if any.
storage (Read Only) Storage is dictionary associated with this operator. Values stored in this dictionary are persistent, and saved with the operator. The dictionary attribute is read only, but not its contents. Its contents may be manipulated directly with methods such as OP.fetch() or OP.store() described below, or examined with an Examine DAT.
tags Get or set a set of user defined strings. Tags can be searched using OP.findChildren() and the OP Find DAT.

The set is a regular python set, and can be accessed accordingly:
Example: n.tags = ['effect', 'image filter']
Example: n.tags.add('darken')

children (Read Only) A list of operators contained within this operator. Only component operators have children, otherwise an empty list is returned.
op (Read Only) The OPFinder object, for accessing operators through paths or shortcuts.
Note a version of this method that searches relative to the current operator is also in the global td module.

op(pattern1, pattern2...)OP or None

Returns the first OP whose path matches the given pattern, relative to this OP, or 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.
   b = n.op('project1')
   b = n.op('foot*', 'hand*')
   b = n.op(154)  #or alternatively op(154), as its not relative to this operator.

op.shortcutOP

An operator specified with by a 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 = me.op.Videoplayer   #or alternatively op.Videoplayer, as its not relative to this operator.

To list all Global OP Shortcuts:

   for x in op:
       print(x)

parent (Read Only) The ParentFinder object, for accessing parent components through indices or shortcuts.
Note a version of this method that searches relative to the current operator is also in the global td module.

parent(n)OP or None

The nth parent of this 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 = me.parent(2) #grandfather

parent.shortcutOP

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 = me.parent.Videoplayer

See also Parent Shortcut for more examples.

Common Flags

The following methods get or set specific operator flags. Note specific operators may contain other flags not in this section.

activeViewer Get or set viewer active flag.
allowCooking Get or set cooking flag. Components only.
bypass Get or set bypass flag.
cloneImmune Get or set clone immune flag.
current Get or set current flag.
display Get or set display flag.
expose Get or set the expose flag which hides a node from view in a network.
lock Get or set lock flag.
selected Get or set selected flag. This controls if the node is part of the network selection. (yellow box around it).
python Get or set parameter expression language as python.
render Get or set render flag.
showCustomOnly Get or set the Show Custom Only Flag which controls whether or not non custom parameters are display in parameter dialogs.
showDocked Get or set show docked flag. This controls whether this node is visible or hidden when it is docked to another node.
viewer Get or set viewer flag.

Appearance

color Get or set color value, expressed as a 3-tuple, representing its red, green, blue values. To convert between color spaces, use the built in colorsys module.
comment Get or set comment string.
nodeHeight Get or set node height, expressed in network editor units.
nodeWidth Get or set node width, expressed in network editor units.
nodeX Get or set node X value, expressed in network editor units, measured from its left edge.
nodeY Get or set node Y value, expressed in network editor units, measured from its bottom edge.
nodeCenterX Get or set node X value, expressed in network editor units, measured from its center.
nodeCenterY Get or set node Y value, expressed in network editor units, measured from its center.
dock Get or set the operator this operator is docked to. To clear docking, set this member to None.
docked (Read Only) The (possibly empty) list of operators docked to this node.

Connection


See also the OP.parent methods. To connect components together see COMP_Class#Connection section.
inputs (Read Only) List of input operators to this operator. To get the number of inputs, use len(OP.inputs).
outputs (Read Only) List of output operators from this operator.
inputConnectors (Read Only) List of input connectors asssociated with this operator.
outputConnectors (Read Only) List of output connectors associated with this operator.

Cook Information

cookFrame (Read Only) Last frame at which this operator cooked.
cookTime (Read Only) Duration of the last measured cook (in milliseconds).
cookAbsFrame (Read Only) Last absolute frame at which this operator cooked.
cookStartTime (Read Only) Last offset from frame start at which this operator cook began, expressed in milliseconds.
cookEndTime (Read Only) Last offset from frame start at which this operator cook ended, expressed in milliseconds. Other operators may have cooked between the start and end time. See the cookTime member for this operator's specific cook duration.
cookedThisFrame (Read Only) True when this operator has cooked this frame.
cookedPreviousFrame (Read Only) True when this operator has cooked the previous frame.
childrenCookTime (Read Only) The total accumulated cook time of all children of this operator during the last frame. Zero if the operator is not a COMP and/or has no children.
childrenCookAbsFrame (Read Only) The absolute frame on which childrenCookTime is based.
totalCooks (Read Only) Number of times the operator has cooked.
cpuMemory (Read Only) The approximate amount of CPU memory this Operator is using, in bytes.
warning Get or set the warning message associated with this OP.
error Get or set the error message associated with this OP.

Type

type (Read Only) Operator type. Example: oscin
subType (Read Only) Operator subtype. Currently only implemented for components. May be one of: panel, object, or blank in the case of base components.
label (Read Only) Operator type label. Example: 'OSC In'.
family (Read Only) Operator family. Example: CHOP. Use the global dictionary families for a list of each operator type.
isFilter (Read Only) True if operator is a filter, false if it is a generator.
minInputs (Read Only) Minimum number of inputs to the operator.
maxInputs (Read Only) Maximum number of inputs to the operator.
isMultiInputs (Read Only) True if inputs are ordered, false otherwise. Operators with an arbitrary number of inputs have unordered inputs, example Merge CHOP.
visibleLevel (Read Only) Visibility level of the operator. For example, expert operators have visibility level 1, regular operators have visibility level 0.
isBase (Read Only) True if the operator is a Base (miscellaneous) component.
isCHOP (Read Only) True if the operator is a CHOP.
isCOMP (Read Only) True if the operator is a component.
isDAT (Read Only) True if the operator is a DAT.
isMAT (Read Only) True if the operator is a Material.
isObject (Read Only) True if the operator is an object.
isPanel (Read Only) True if the operator is a Panel.
isSOP (Read Only) True if the operator is a SOP.
isTOP (Read Only) True if the operators is a TOP.
licenseType (Read Only) Type of License required for the operator.



Methods

General

NOTE: create(), copy() and copyOPs() is done by the parent operator (a component). For more information see COMP.create, COMP.copy and COMP.copyOPs methods.

pars(pattern)list

Returns a (possibly empty) list of parameter objects that match the pattern.
  • pattern - Is a string following the Pattern Matching rules, specifying which parameters to return.
   newlist = op('geo1').pars('t?', 'r?', 's?') #translate/rotate/scale parameters

cook(force=False, recurse=False)

Cook the contents of the operator if required.
  • force - (Keyword, Optional) If True, the operator will always cook, even if it wouldn't under normal circumstances.
  • recurse - (Keyword, Optional) If True, all children and sub-children of the operator will be cooked.

ops(pattern1, pattern2..)list

Returns a (possibly empty) list of OPs that match the patterns, relative to this OP.
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.
Note a version of this method that searches relative to '/' is also in the global td module.
   newlist = n.ops('arm*', 'leg*', 'leg5/foot*')

copyParameters(OP)

Copy all of the parameters from the specified operator. Both operators should be the same type.
   op('geo1').copyParameters( op('geo2') )

clearScriptErrors(recurse=False)

Clear any errors generated during script execution. These may be generated during execution of DATs, Script Nodes, Replicator COMP callbacks, etc.
  • recurse - Clear script errors in any children or subchildren as well.
   op('/project1').clearScriptErrors(recurse=True)

changeType(OPtype)OP

Change referenced operator to a new operator type. After this call, this OP object should no longer be referenced. Instead use the returned OP object.
  • OPtype - The python class name of the operator type you want to change this operator to. This is not a string, but instead is a class defined in the global td module.
   n = op('wave1').changeType(nullCHOP) #changes 'wave1' into a Null CHOP
   n = op('text1').changeType(tcpipDAT) #changes 'text1' operator into a TCPIP DAT

dependenciesTo(OP)list

Returns a (possibly empty) list of operator dependency paths between this operator and the specified operator. Multiple paths may be found.

evalExpression(str)value

Evaluate the expression from the context of this OP. Can be used to evaluate arbitrary snippets of code from arbitrary locations.
  • str - The expression to evaluate.
   op('wave1').evaluateExpression('me.digits')  #returns 1
If the expression already resides in a parameter, use that parameters evalExpression() method instead.

destroy()

Destroy the operator referenced by this OP. An exception will be raised if the OP's operator has already been destroyed.

var(name, search=True)str

Evaluate a variable. This will return the empty string, if not found. Most information obtained from variables (except for Root and Component variables) are accessible through other means in Python, usually in the global td module.
  • name - The variable name to search for.
  • search - (Keyword, Optional) If set to True (which is default) the operator hierarchy is searched until a variable matching that name is found. If false, the search is constrained to the operator.

Appearance

resetNodeSize()

Reset the node tile size to its default width and height.

Viewers

closeViewer(topMost=False)

Close the floating content viewers of the OP.
  • topMost - (Keyword, Optional) If True, any viewer window containing any parent of this OP is closed instead.
   op('wave1').closeViewer()
   op('wave1').closeViewer(topMost=True) # any viewer that contains 'wave1' will be closed.

openViewer(unique=False, borders=True)

Open a floating content viewer for the OP.
  • unique - (Keyword, Optional) If False, any existing viewer for this OP will be re-used and popped to the foreground. If unique is True, a new window is created each time instead.
  • borders - (Keyword, Optional) If true, the floating window containing the viewer will have borders.
   op('geo1').openViewer(unique=True, borders=False) #opens a new borderless viewer window for 'geo1'

resetViewer(recurse=False)

Reset the OP content viewer to default view settings.
  • recurse - (Keyword, Optional) If True, this is done for all children and sub-children as well.
   op('/').resetViewer(recurse=True) # reset the viewer for all operators in the entire file.

openParameters()

Open a floating dialog containing the operator parameters.

Storage

Storage can be used to keep data within components. Storage is implemented as one python dictionary per node.

When an element of storage is changed by using n.store() as explained below, expressions and operators that depend on it will automatically re-cook. It is retrieved with the n.fetch() function.

Storage is saved in .toe and .tox files and restored on startup.

Storage can hold any python object type (not just strings as in Tscript variables). Storage elements can also have optional startup values, specified separately. Use these startup values for example, to avoid saving and loading some session specific object, and instead save or load a well defined object like None.

See the Examine DAT for procedurally viewing the contents of storage.

fetch(key, default, search=True, storeDefault=False)value

Return an object from the OP storage dictionary. If the item is not found, and a default it supplied, it will be returned instead.
  • key - The name of the entry to retrieve.
  • default - (Optional) If provided and no item is found then the passed value/object is returned instead.
  • storeDefault - (Keyword, Optional) If True, and the key is not found, the default is stored as well.
  • search - (Keyword, Optional) If True, the parent of each OP is searched recursively until a match is found
  v = n.fetch('sales5', 0.0)

fetchOwner(key)OP

Return the operator which contains the stored key, or None if not found.
  • key - The key to the stored entry you are looking for.
   who = n.fetchOwner('sales5') #find the OP that has a storage entry called 'sales5'

store(key, value)value

Add the key/value pair to the OP's storage dictionary, or replace it if it already exists. If this value is not intended to be saved and loaded in the toe file, it can be be given an alternate value for saving and loading, by using the method storeStartupValue described below.
  • key - A string name for the storage entry. Use this name to retrieve the value using fetch().
  • value - The value/object to store.
   n.store('sales5', 34.5) # stores a floating point value 34.5.
   n.store('moviebank', op('/project1/movies')) # stores an OP for easy access later on.

unstore(keys1, keys2..)

For key, remove it from the OP's storage dictionary. Pattern Matching is supported as well.
  • keys - The name or pattern defining which key/value pairs to remove from the storage dictionary.
   n.unstore('sales*') # removes all entries from this OPs storage that start with 'sales'


storeStartupValue(key, value)

Add the key/value pair to the OP's storage startup dictionary. The storage element will take on this value when the file starts up.
  • key - A string name for the storage startup entry.
  • value - The startup value/object to store.
   n.storeStartupValue('sales5', 1) # 'sales5' will have a value of 1 when the file starts up.

unstoreStartupValue(keys1, keys2..)

For key, remove it from the OP's storage startup dictionary. Pattern Matching is supported as well. This does not affect the stored value, just its startup value.
  • keys - The name or pattern defining which key/value pairs to remove from the storage startup dictionary.
   n.unstoreStartupValue('sales*') # removes all entries from this OPs storage startup that start with 'sales'

Miscellaneous

__getstate__()dict

Returns a dictionary with persistent data about the object suitable for pickling and deep copies.

__setstate__(dict)

Reads the dictionary to update persistent details about the object, suitable for unpickling and deep copies.