ParGroup

A ParGroup or Parameter Group is a group of related parameters that you can set and get as a whole instead of its individual parameters.

ParGroup

A ParGroup is a group of related parameters. It is often more natural to work with the ParGroup as a whole instead of its individual parameters.

Often all parameters sharing the same line on a parameter dialog belong to the same ParGroup. For example, in the Transform TOP, Translate is a type of ParGroup, with two primary Par objects: tx, ty and a unit Par.

ParGroups with only single elements are also possible. For example, the Uniform Scale parameter of the Geometry Object belongs to a ParGroup with only one parameter. Note that ParGroups with multiple elements only contain numeric elements. Strings only exist in ParGroups of size 1.

See also ParGroup Execute DAT

Basic Usage

The following example assumes n is a Transform TOP with its translate set to 1, 2 Like n.par, n.parGroup can be used to access individual ParGroup objects:

t = n.parGroup.t     # set t to the Translate ParGroup
t = n.parGroup["t"]  # for convenience, name mapping access also works. Exact names only, no wildcards.

From here, most of the members and methods available to Par objects are also available to ParGroup objects. Instead of returning one value however, they return a tuple of values where applicable.

t.expr   # returns (None, None) if the translate parameter has no expressions set

Evaluation

t.eval()   # returns (1, 2)

Note that if the ParGroup contains only a single element, such as the Uniform Scale parameters, its eval() method still returns a tuple and not a single value:

n.parGroup.scale.eval()  # returns (1.0,)

Size, Mapping and Iteration

len(t)   # returns 2, as this ParGroup contains 2 primary parameters.  The unit parameter is ''not'' included here.

t[1].name   # returns 'ty', since t[1] return Par object ty.

[i.name for i in t] # returns [‘tx’, ‘ty’] #primary parameters only

[i.name for i in t.pars()] # returns [‘tx’, ‘ty’, 'unit'] #all parameters

The pars method is identical to OP.pars, and returns all parameters in this ParGroup, primary or otherwise.

Assignment

ParGroups can be assigned a single value (a scalar) or a tuple of the same size. Note in the following examples, both tuples () and lists [] are interchangeable. In some cases though, using list syntax is less ambiguous: [3] vs (3,), since (3) is not a tuple.

n.parGroup.t = (4, 5)    #assign tx=4, ty=5
n.parGroup.t = [4,5]    # any iterable object of size 2 will do

n.parGroup.t = 5             #assign 5 to tx, ty
n.parGroup.t = n.parGroup.p   #assign pivot values to translate parameter.

n.parGroup.t = (1,2,3)  # error, cannot assign 3 elements to 2.

Note that the above also works when assigning directly to the Parameter val members:

n.parGroup.t.val = (1,2)

Arithmetic

ParGroups can be used in some arithmetic expressions directly, as operations are applied pairwise:

n.parGroup.t + 1  # returns (2.0, 3.0)
n.parGroup.t + (1,2)  #returns (2.0, 4.0)

To ensure forward compatibility though, it is best to create ParGroup objects where applicable:

tdu.Vector(n.parGroup.t) + (1,2)   #returns a Vector with values 2.0  4.0

Unit and Pulse Parameters

Sometimes a ParGroup will end with a parameter of a different type on the same line, such as a unit menu or a pulse button.

In this case, the ParGroup is actually a subclass, such as ParGroupUnit or ParGroupPulse. These subclasses contain members to access these extra parameters:

m = op(‘timer1’)
m.parGroup.length.unit.val = ‘seconds’   # set the unit parameter
m.parGroup.cue.pulse()                   # pulse the applicable parameter

Casting

Casting a ParGroup to a bool will always raise an exception, as the ParGroup will always be a non-empty tuple, thus normally returning True. This could lead to confusion where bool(n.parGroup.button) always returns True, leading one to assume the button value itself is true.

Casting a ParGroup to a float or int however, will only succeed if that ParGroup contains exactly 1 element, as in the case of a Uniform Scale for example:

5 + float(n.parGroup.scale)

This also means op('geo1').parGroup.scale for example, can be used in a single parameter expression expecting a numeric avlue.

Furthermore, the global functions any() and all() work as expected, given that ParGroups behave like tuples:

	any(n.parTuple.t)	# true if any of tx,ty,tz non-zero
	all(n.parTuple.t)	# true if all of tx,ty,tz non-zero

A ParGroup is a group of related parameters that you can set and get as a whole instead of its individual parameters.

A ParGroup is a group of related parameters that you can set and get as a whole instead of its individual parameters.

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.

To "pulse" a parameter is to send it a signal from (1) an exported CHOP channel or (2) a python command or (3) a mouse click that causes a new action to occur immediately. A pulse via python is via the .pulse() function on a pulse-type parameter, such as Reset parameter in a Speed CHOP. A pulse from a CHOP is typically a 0 to 1 to 0 signal in an exported channel.