TDFunctions

From TouchDesigner Documentation
Revision as of 17:07, 15 March 2019 by Ivan (talk | contribs)
Jump to: navigation, search

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>(...)


Methods[edit]

clamp(value, inMin, inMax)float:

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)OP 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)OP or None:

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. The expression will incorporate Parent Shortcuts and Global OP Shortcuts.

Note: because there are multiple ways to create a shortcut expression, the result of this function will always be a best guess.

  • fromOp - the operator to generate expression from.
  • toOp - the operator to generate expression to.

panelParentShortcut(panel, parentShortcut)Panel COMP or None:

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.
  • parentShortcut - 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)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)dict or None:

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)float:

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)None:

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)None:

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

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

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)float:

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)list of ints:

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)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)dict:

Returns a parInfo dict for sourceOp. The format of a parInfo dict is {<parName>:(par.val, par.expr, par.mode string, par.bindExpr, par.default)...}

  • 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.

applyParDefaults(targetOp, parInfo)float:

Apply par defaults from parInfo dict to targetOp. The format of a parInfo dict is {<parName>:(par.val, par.expr, par.mode string, par.bindExpr, par.default)...}

  • targetOp - The operator to apply values to.
  • parInfo - The parInfo dict.

applyParInfo(targetOp, parInfo, setDefaults=False)float:

Apply par values, expressions, and modes from parInfo dict to targetOp. The format of a parInfo dict is {<parName>:(par.val, par.expr, par.mode string, par.bindExpr, par.default)...}

  • targetOp - The operator to apply values to.
  • parInfo - The parInfo dict.
  • setDefaults - if True, set the par.default as well

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.

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.