TDU Python Module in TouchDesigner

TouchDesigner is always growing in its Python capabilities. Whether it’s the newer and shinier, like OpenCV and Script TOP, or more under the hood features like optimized expressions. One TouchDesigner Python feature that has been missed by many TouchDesigner developers is the tdu module. Let’s take a look!

What is the TouchDesigner TDU Python module?

The tdu module is a top level class in TouchDesigner’s implementation. It holds a handful of helper methods and members that don’t particularly fit in any other existing class. It’s imported by default so no need to worry about import statements or anything like that. The cool thing is all the different ways you can use it, so here’s a few examples.

Random number in an expression

Let’s say you have a parameter and you want a random float value between 0 and 1 to be added to it every frame. Without the tdu module, you’d approach this by making a Noise CHOP, and then referencing it’s value in your expression. It’s not a terrible approach but making more operators can end up taxing larger projects. With tdu module you could simply use the tdu.rand() function. All it needs is a seed value and it’ll produce a random float value for you. So your expression could be:

tdu.rand(absTime.frame) 

That’s it! That would get computed as a unique 0 to 1 float every frame. This is also useful in quick 1 line Python scripts if you don’t want to bother importing the Python random library.

Clamping parameter values

You have a value you’re referencing into a parameter and need to clamp it quickly? Without tdu, you would have to go back in your operator chain and drop a Limit CHOP and hope it doesn’t mess up other references. Not terrible but also not seamless! tdu.clamp() to the rescue. Right inside of the expression you can clamp the reference like this:

tdu.clamp(op('constant1')[0], 0, 5)

In this example, I’m referencing a value from op(‘constant1’)[0]. The second and third arguments are the minimum value and maximum value you want to stay within, so in this cause the number wouldn’t leave that range.

Reranging!

This one is a mighty popular one, especially for folks coming from other coding languages like Processing that have a remap function. Without tdu, you’d make a Math CHOP, then go to the Range page and fill in the from and to values. One of my favourite things to do! But if you want a few less Math CHOPs constantly sprinkled around, you could re-range right in place using tdu.remap(). It still needs the same amount of info as the Math CHOP but you can do this right inside of your expression. It would look something like this:

tdu.remap(op('constant1')[0], 0, 1, 0, 10)

The first argument is the value you want to remap, and in this example I’m again referencing the value from a Constant CHOP. The next two arguments are the from minimum and maximum, which you can think about as the input range you’re expecting, which in this case is 0 to 1. The final two arguments are the output range minimum and maximum, in this case 0 to 10. So this quick little expression will take an incoming value from 0-1 and remap it to 0-1 without need to add another Math CHOP to your pipeline. This one is especially helpful in larger Python scripts if you want to remap some value ranges while you’re in the middle of larger scripts!

Get the digits and name

You’re probably familiar with getting the digits off an operator name by using me.digits. We all know how useful this is in so many different contexts. But what if you could quickly use this on any string? Maybe you want to check usernames for numbers similar or alternatively remove digits from the end of a name. You can do this easily with both tdu.digits() and tdu.base(). If you wanted to get the 1642 from a username like elburz1642, you could do something like:

username = 'elburz1642'
my_digits = tdu.digits(username)

This would return 1642 as the value of my digits. Great! What about the inverse? Just as easy.

username = 'elburz1642'
base_name = tdu.base(username)

Same thing, except base_name would return elburz. Both easy and no need for regex or anything like that. Another great tool to keep in the back pocket.

Reference

If you want to learn more about the tdu module, here’s the full wiki reference below:

Wrap up: TouchDesigner TDU Python module

Whether you’re doing simple work or complex work with Python, having easy to use tools you can reach for is valuable. Not needing to always through down tons of new operators to do simple things can be a blessing especially when you’re working with parameter expressions or you’re already deep in a longer extension you’re writing. Being able to stay focused in place and get the results you want easily is what the tdu module is all about.