TDFunctions

From TouchDesigner 099 Wiki

Summary

The TDFunctions module provides a variety of Python utility functions for TouchDesigner. To use TDFunctions put the following line at the top of your Python script:

TDF = op.TDModules.mod.TDFunctions

You can now use any of the following functions by calling:

TDF.<function name>(...)

Functions

clamp(value, inMin, inMax)clamped value

returns the value clamped between inMin and inMax.
  • value - the value to be clamped.
  • inMin - the minimum value.
  • inMax - the maximum value.

parentLevel(parentOp, childOp)depth of parenthood or None

determines if parentOp is a parent of childOp at any depth. Returns None or the depth of parenthood. i.e. childOp.parent(<returnValue>) will yield parentOp. This method returns None if childOp is not a child of parentOp. Note: childOp.parent(<returnValue>) will error in that case.
  • parentOp - the parent to be evaluated.
  • childOp - the child to be evaluated.

sharedParent(op1, op2)closest parent

Returns the nearest shared parent of op1 and op2. Returns None if root is result.
  • op1 - the first operator.
  • op2 - the second operator.

getShortcutPath(fromOp, toOp)path expression

Return a shortcut path expression from fromOp to toOp. This expression is suitable for use in any OP parameter expression on fromOp.
Return value will be the first of:
  1. op.<opshortcut>
  2. me
  3. parent.<parentshortcut>
  4. parent(#)
  5. op('./<path>')
  6. op.opshortcut('<path>')
  7. parent.parentshortcut('<path>')
  8. parent(#).op('<path>')
  9. op('<toOp.path>')
  10. op('<toOp.path>')
  • fromOp - the operator to generate expression from.
  • toOp - the operator to generate expression to.

panelParentShortcut(panel, parentShortcut)Panel Comp

Return the first panelParent of panel that has the provided parentShortcut. Returns None if no panelParent with shortcut is found.
  • panel - the panel to start searching at.
  • parentShortut - the parent shortcut to look for.

parMenu(menuNames, menuLabels=None)menuSource object

Returns an object suitable for menuSource property of parameters.
  • menuNames - a list of strings for menu values.
  • menuLabels - (Optional) a list of strings for menu labels. Defaults to menuNames.

incrementStringDigits(string, min=1)new string

Method for iterating a string with digits on the end, or adding digits if none are there. This simulates the automatic naming of duplicate operators.
  • string - the string to add digits to.
  • min - (Optional) the number to add if string doesn't have a number already.

findNetworkEdges(comp, ignoreNodes=None)info dictionary

A utility for placing nodes in a network. Returns a dictionary of 'nodes' and 'positions' at extremes of network. Returns None if no nodes found. Dictionary keys are 'top', 'left', 'right', 'bottom'.
  • comp - the network to analyze.
  • ignoreNodes - (Optional) a list of nodes to ignore during analysis.

arrangeNode(node, position='bottom', spacing=20)

Place a node according to the other nodes in the network.
  • node - the node to move.
  • position - (Optional) can be 'bottom', 'top', 'left' or 'right'. left, right will be placed parallel with top nodes. top, bottom will be placed parallel with left nodes.
  • spacing - (Optional) distance from network edge.

createProperty(classInstance, name, value=None, attributeName=None, readOnly=False, dependable=False)

Use this method to add a property to a class. WARNING: the property is added to the class of instance, so all objects of instance's class will now have this property.
  • classInstance - an instance of the class to add a property to. This is usually 'self' in the __init__ method of the class.
  • name - the name of the property. Must be a valid Python object name.
  • value - (Optional) the starting value of the property.
  • attributeName - (Optional) the attribute name used to store the value of the property. Defaults to _<name>.
  • readOnly - (Optional) if True, the property will be read only. A read only property can be changed via the attributeName. If the property is dependable, use attributeName.val.
  • dependable - (Optional) if True, the value will be dependable. If set to "deep", collections will be deeply dependable.

makeDeepDependable(value)dependency object

returns a deeply dependable object out of the provided python object. Deeply dependable collections will cause cooks when their contents change.
  • value - the value of the deep dependable object.

forceCookNonDatOps(comp)

Recursively force cook op and all children of comp, unless they are DATs

showInPane(operator, pane='Floating', inside=False)pane

Open an operator for viewing in a chosen editor pane. The pane will be focused on the chosen operator unless inside is True, in which case it will show the inside if possible.
  • operator - the operator to view.
  • pane - (Optional) a ui.pane or 'Floating' for a new floating pane.
  • inside - (Optional) if inside is True, try to show view inside comps.

tScript(cmd)

Run a tscript command. This is slow because it creates and destroys an operator. If you need this to be faster, build an optimized network with its own tscript DAT.
  • cmd - tScript command to run.

parStringToIntList(parString)int list

Convert a space delimited string to a list of ints.
  • parString - space delimited list of ints.

listToParString(l)space delimited string list

Convert a list to a space delimited string.
  • l - a python list.

replaceOp(dest, source=None)

Replace dest with an exact copy of source. If source is None and dest is a comp, try to use dest's clone parameter.
  • dest - the OP to be replaced.
  • source - (Optional) the OP to replace with. If None, use dest's clone source.

getParInfo(sourceOp, pattern='*', names=None, includeCustom=True, includeNonCustom=True)parInfo dict

Returns a parInfo dict for sourceOp. The format of a parInfo dict is {<parName>:(parVal, parExpr, parMode)...}
  • sourceOp - the operator to look for pars on.
  • pattern - (Optional) a pattern match string for par names.
  • names - (Optional) a list of specific names to include. None means include all.
  • includeCustom - (Optional) include custom parameters.
  • includeNonCustom - (Optional) include non-custom parameters.

applyParInfo(targetOp, parInfo)

Apply par values, expressions, and modes from parInfo dict to targetOp. The format of a parInfo dict is {<parName>:(parVal, parExpr, parMode)...}
  • targetOp - the operator to apply values to.
  • parInfo - the parInfo dict.