Sequential Parameters in TouchDesigner

The release of the 2023.10000 Series of TouchDesigner back in December brought with it a slew of exciting changes, far too many to be thoroughly explored in a single post! In the list of updates in new features is a notable update for Sequential Parameters, which includes support (finally!) for creating custom sequential parameters. In this post, we’ll take a closer look at Sequential Parameters in TouchDesigner, including what the updates from the 2023.11290 release have brought to the table.

What are Sequential Parameters in TouchDesigner?

If you’re not already familiar with sequential parameters, let’s take a look at the official definition. According to the TouchDesigner wiki: Sequential Parameters are sets of parameters (sequence blocks) that can be dynamically repeated multiple times.¹

Let’s take a look at this in practice. One of the operators where you’ll find Sequential Parameters is the Add SOP. In the case of the Add SOP, you’re able to dynamically insert and remove points to the Point sequence.

With the 2023.10000 series release, Sequential Parameter names are now generated in the following format: <sequence name><sequence index><parameter name>, where sequence name is the sequence name, which is also the name of the sequence’s header parameter, block index is the zero-based index of the block in the sequence, and parameter name is the descriptive name of the parameter.¹

To see this in practice, let’s take a look at the image above.
For the name of the Position X parameter of the second point, we first find the sequence name, which is point. This is the second parameter block, so following zero-based numbering, this would be index 1. Finally, the parameter name itself is posx.
Put that all together, and you have: <sequence name><sequence index><parameter name> –> point1posx.

Working with this parameter is the same as any typical parameter in TouchDesigner. To get or set this parameter’s value via Python, we can use the following expression: op('add1').par.point1posx.

Accessing Sequential Parameters in Python

Working with parameter sequences in Python is done via the Sequence object (another new addition from the 2023 release). The sequence object can be accessed by the sequence member of parameters in the sequence or the seq member of operators. Continuing with the Add SOP example, we can access the sequence object using:

• op('add1').par.point1posx.sequence

However, we don’t necessarily have to access the sequence object by way of a parameter! We can also use the seq member of operators:

• op('add1').seq.point

Individual blocks can be accessed by providing an index value with the sequence name:

• op('add1').seq.point[1]

To access individual parameters of the block, you can use the par member and the parameter’s base name without the sequence prefix (thanks Greg!). For example, to access the point1weight parameter we can use:

• op('add1').seq.point[1].par.weight

Of course, the possibilities for utilizing Python go much further than this, and it’s well worth having a look at the Sequential Parameters page of the TouchDesigner wiki to see further examples.

Adding and Removing Sequential Parameter Blocks

To add or remove parameter blocks, you now have a couple of options! As before, you can use the plus or minus buttons in the parameter dialog to add or remove blocks. The 2023 release has added two additional options:

• Right click on a block parameter’s name in the parameter dialog and choose Insert Block or Remove Block in the RMB menu.
• Via Python, use the insertBlock(blockIndex) or destroyBlock(blockIndex) methods. Continuing with the Add SOP, you can insert a new block at index 0 with: op('add1').seq.point.insertBlock(0)

Custom Sequential Parameters

Along with the above changes, the 2023.10000 series release also includes support for custom Sequential Parameters! This is an exciting development which allows for dynamic parameter sequences to be built into custom components for the first time.

There are a couple of options for creating custom parameters in the Component Editor window. First, we’ll look at starting with a sequence header and then adding block parameters.

In the parameter type menu, there’s a new Sequence option which will create the Sequence Header. Once you’ve created a Sequence parameter, continue to add custom parameters as usual. When finished, set the blockSize of the Sequence parameter to the number of block parameters that you’ve created, and they’ll be included in the block! Notice how the block parameter names (seen in the parameter dialog on the right side of the image below) automatically update following the <sequence name><sequence index><parameter name> sequence we looked at earlier.

Another option is to create your block parameters first. Then select them all, right click, and choose the Create Sequence option in the RMB menu.

You’ll have the option to give the new sequence a name in the Create Sequence dialog that pops up, and once you click create the results will be identical to those in the first method!

Wrap-Up

With all of the new changes to Sequential Parameters in TouchDesigner, they seem poised to become an integral part of creating custom components in the program. As usual, we’ve only been able to to scratch the surface of what’s possible, so I’d highly recommend having a look at the Sequential Parameters page of the TouchDesigner wiki for further examples. Hopefully this post has gotten you excited to start experimenting with Sequential Parameters yourself!