YAML Settings Files in TouchDesigner

There are many different ways to externalize settings for an installation. You could use CSV, Excel files, text files, and more. These are all simple and easy to use, but what happens if you want to store data that’s a bit more complex? We usually end up turning to either JSON, XML, or YAML. Personally I find XML to be a bit of a burden and I use JSON regularly. YAML is a new tool I’ve added to my arsenal because I find it presents a good middle ground between human-readability (like CSV/Excel files) with programmatic ease of use (like JSON). Let’s dive into how to use YAML in TouchDesigner!

Setup your YAML

Let’s dive right into it. First we need a YAML file. If you’ve done a lot of web work, you might be familiar with YAML files already. If you haven’t, don’t worry we’ll start slow. Let’s open a text editor and make the most basic form of YAML layout, which is a keyname followed by a colon and then the value. This is what I’m going to add to my file and save it as intro.yaml to my Desktop:

test: 1
another_var: 2
last_var: hello

That’s it for setup! That’s why YAML is a nice format to use, it’s easy to read and edit as a human without a ton of scripts of parsing necessary.

Loading your YAML

Loading the YAML file in TouchDesigner is surprisingly easy because we have access to the PyYAML Python library that is included by default with every installation of TouchDesigner. We can start by making a Text DAT and adding the code below:

import yaml

with open('intro.yaml') as f:
	data = yaml.load(f, Loader=yaml.FullLoader)
	print(data)

Let’s break it down. First we import the yaml library for reading .yaml files with import yaml

Then with open(‘intro.yaml’) as f: is a common way to open files in Python. It’s not specific to yaml, it could be any kind of file. In this case, since I saved intro.yaml to my desktop and my default project is saved on the desktop, then I don’t need to put the full file path here. If you do end up saving your project file and yaml file in different places you’ll need to replace ‘intro.yaml’ with something like ‘C:\Users\Projects\intro.yaml’ or similar. The as f piece on the end means that we can now drop with statement loop and refer to this open file simply as f.

From there, we make a new variable called data and use the yaml.load() function on the file variable f we just created. The last element, Loader=yaml.FullLoader , tell the yaml library to look for and parse the full range of yaml supported options and features.

Finally we have our yaml loaded and we can print it! If you go ahead and run that you should see the following returned in the textport:

python >>> 
{'test': 1, 'another_var': 2, 'last_var': 'hello'}

Great! We’re already seeing that great combination in action. We have the programmability that we’d get with JSON but we have the ease of manually editing the YAML file that you’d get with something like CSV.

Using the data

Now that we’ve got out data variable, it’s a regular old Python dictionary! Nothing strange here and we can use it in many ways. We can access the values directly and write them to parameters. We could take them and dump them into a Constant CHOP, some customer parameters, or even a DAT table that we make.

One easy way to deal with this is to use a few lines of Python to iterate over the dictionary and dump the keys and values into a table. Go ahead and create a new Table DAT, which in my empty project is called table1. To do this we can add these lines of code:

import yaml

with open('intro.yaml') as f:
	data = yaml.load(f, Loader=yaml.FullLoader)
	print(data)

op('table1').clear()

for key, value in data.items():
	op('table1').appendRow([key,value])

Not much crazy added here! First we have op(‘table1’).clear() which will clear your table out before we write new data to it.

Then we have a nice line for key, value in data.items() which is a great way to iterate through a dictionary and have a separate variable for the key names and another one for the values. Then once we’re inside that for loop going through every item in the dictionary, we can use op(‘table1’).appendRow([key, value]) to add new rows to our table (after we cleared it!) with the key names in the first column, and the value in the second column. It’ll look like this:

More advanced data!

YAML can certainly handle more advanced kinds of data than what we used in this example. To learn more about YAML you can check the link below:

Wrap up

While there are lots of ways of holding settings data for your projects, YAML is quickly becoming one that I use more and more. It has the benefits of being easy to ready and edit in a text editor, like CSV or XML, but it also has the benefits of being very easy to use programmatically like JSON. Now you have the tools to use it yourself!