A big part of developing projects in TouchDesigner, whether you’re a beginner or experienced developer, is troubleshooting and debugging issues when they (inevitably) arise. Though you’ll eventually develop a sense of best practices and things to avoid through experience, as a beginner it can be very hard to figure out where to start when looking to fix issues in your project! In this post, we’ll look at troubleshooting and debugging TouchDesigner projects, including a number of built-in tools and techniques for troubleshooting TouchDesigner networks, Python scripts, and more.
Note
A quick note before we get started: much of the information in this post has been adapted from the Troubleshooting in TouchDesigner page of the TouchDesigner wiki. It’s an invaluable resource for learning how to troubleshoot and debug your TouchDesigner projects, and is well worth checking out!
First Steps: Check the Documentation and Forums
Running into issues, but not entirely clear on how an operator functions or should be used? There are a couple of key resources to start with.
Accessing Help
If you’re unclear about an operator’s functionality, including what each parameter does, click on the Help… link (outlined in green box above) in the header of the parameter window. This will open up the TouchDesigner documentation page for that particular operator.
Accessing Python Help
The documentation also has a Python class page for each operator, which can be accessed by clicking the Python Help… link (outlined in green box above). This will give you Python members and methods for that specific operator, as well as the members and methods that it inherits.
Live Examples of OPs in Use: OP Snippets
For examples of how an operator might be used, most (but not all) operators have examples available in OP Snippets, which can be accessed in a few different ways:
- right click on an existing operator in the network, and select Operator Snippets… (if available)
- right click on operator name in OP Create dialog and select Operator Snippets…
- open the Help menu dropdown -> Operator Snippets
Another Great Resource: The TouchDesigner Forums
If you’re still running into questions, check out the TouchDesigner forum: forum.derivative.ca! As on any forum, search for answers first before posting your questions, and when you do post be as clear and concise as possible.
Troubleshooting and Debugging TouchDesigner Networks
Error Flags
It’s generally not too difficult to find out which operators are running into issues in your project, as they will show an error marker (a red circle with a black x in the center) in the upper right of the operator.
You can view information about the error by clicking directly on the error marker, or middle-mouse clicking anywhere on the operator.
In general, the error should give you an idea of what to do to rectify the issue (such as supplying input textures for the Displace TOP above), but if you’re not sure how to solve the issue, check the resources we looked at earlier, especially the forums. It’s likely that more than one person has run into the issue before!
Once you’ve fixed the issue, generally the error flag will disappear.
The Error Dialog and Error DAT
To get a picture of all of the errors in your entire project, check out the Error Dialog, (accessible via the Dialogs dropdown -> Errors), shown above at left. The parameters in this window allow you to filter errors by Operator type, specific operator, and error message.
The Error DAT, show above at right, outputs very similar information, but also includes callbacks functionality, allowing you to work with Python to log or respond to the particular issue.
The Info CHOP and Info DAT
The Info CHOP (shown above left) can be a useful tool for keeping track of some additional properties of an operator while working on troubleshooting. In the example above, you’ll notice that the Info CHOP contains a wide variety of information about the Movie File In TOP that’s not immediately accessible from interacting with the operator directly. These additional CHOP channels can be very useful to watch as you’re troubleshooting issues with video file loading and playback, for example.
Likewise, the Info DAT (shown above right), also shows some additional information for some operators, and can provide useful insight into the issues you face. In the example above, the Info DAT shows both the error message and error code that the Web Render DAT is currently outputting. In this case, the URL has been deliberately misspelled to produce the error, but these messages could provide crucial troubleshooting info in a project’s developement.
Print Debug Messages with an Info CHOP and a CHOP Execute DAT
It’s often helpful to use a CHOP Execute DAT along with the Info CHOP to print a debug message as soon an error or warning message appears. Although the CHOP Execute DAT can’t tell you what caused the issue, it can tell you when the issue occurs, which can be helpful for troubleshooting.
Troubleshooting and Debugging Issues in Perform Mode
When trying to troubleshoot issues in Perform mode, there are still options for accessing specific operators or parts of your network even though the Network Editor is not visible.
One option is to open a floating viewer of a particular operator. To open a floating viewer, right click on the operator in the Network Editor and choose the View… option. This floating viewer will stay open even when you enter Perform Mode.
If you’re looking to keep track of debug messages in Perform Mode, it’s also possible to open the Textport as a floating window as well. This can be done either via clicking the Textport and DATs option in the Dialogs drop-down menu, or pressing Alt+t on the keyboard.
Another option is to use the F9 and F10 keys when in Perform Mode to view areas of your network relating to the panels that your cursor is over top of in the Perform Window. Hitting the F10 key will take you to the particular area of the network that contains the panel, and the F9 key will take you to the parent of that panel.
In the example below, F10 takes us to the TOP network that is shown in the Perform Window, and F9 takes us to the parent component, which is a Container COMP named project1.
Troubleshooting Poor Performance
Optimizing your TouchDesigner Project for best performance is another topic in itself! Here are a number of great resources to help get you started.
First, check out the official TouchDesigner documentation! It has a great, very detailed page on optimization best practices: Optimize – TouchDesigner Documentation
Here on the HQ Blog, I wrote a post illustrating some basic tips & tricks for optimizing your TouchDesigner projects: TouchDesigner Optimization Strategies. Also check out our post Python Optimization in TouchDesigner, where Elburz and Matthew Ragan cover some handy tips on optimizing your Python code in TouchDesigner.
If you’re looking for some in-depth video content, Ben Voigt of Derivative recorded a great three part tutorial series covering TouchDesigner optimization with TDSW back in 2020:
1/3 TouchDesigner Vol.035 Cooking, Optimization, & SceneChanger
2/3 TouchDesigner Vol.035 Cooking, Optimization, & SceneChanger
3/3 TouchDesigner Vol.035 Cooking, Optimization, & SceneChanger
Optimization is a big topic, but these resources should get you started with improving your project’s performance!
Troubleshooting and Debugging Python
The Textport will be one of your main tools for troubleshooting and debugging Python in TouchDesigner. Python errors are printed to the Textport (and will also cause an Error Flag to show on the associated operator, as seen previously). It’s also possible to print your own debug messages to the Textport as well, which can be very helpful for sorting out issues.
Since TouchDesigner runs in real time, the method for getting debug information from your Python scripts is to output it as they run. In practice, this usually consists of using the debug() command to output information to the Textport.
Tip: Use debug() instead of print()
In general, it’s considered a best practice to use the debug() function rather than the typical print() function, as debug() will give you more specific information, including the operator that contained the script (along with its location) and the specific line number where debug() was called. The image above shows the difference between the results of print() and debug() in the Textport.
Raising Exceptions
To stop code execution at a certain point, a Python Exception can be raised. The code will stop executing, the error flag will appear, and the error will be printed to the textport.
For example, in the above example, the CHOP Execute DAT contains the code raise Exception("Width set to zero in " + parent().path)
which will be run if the parent COMP’s Width parameter is ever set to zero. When this situation occurs, the error flag appears on the CHOP Execute DAT, and the exception is printed to the Textport.
Logger COMP
Before we close out this post, here’s a somewhat recent addition to TouchDesigner that can be a helpful aid in troubleshooting and debugging your project: the Logger COMP!
Added with the introduction of the 2023.10k series (released December 2023), the Logger COMP, which can be found in the Palette->Tools, is a wrapper around the Python Logging Library, making it very easy to add logging functionality to your project. Once you add the Logger COMP to your project, you can simply call logger.Error( or 'Some Error Message')logger.Warning( to log issues to a file in your project’s directory. The functionality is also completely customizable, if you find yourself needing some additional features.'Some Warning Message')
Logging errors and warnings to an external file can be a very helpful way to keep a long term record of issues with your project as they appear. Although printing to the Textport can be useful for immediate testing, the output displayed there is not persistent (as in, it will not be cleared when the project is closed) and messages limited in length.
Check out the TouchDesigner Documentation page for more info: palette:Logger – TouchDesigner Documentation.
Wrap-Up
That’s a wrap! Troubleshooting and debugging TouchDesigner projects is a big topic, but a process that will get more manageable with knowledge and experience. We hope that this post is a useful resource for troubleshooting and debugging TouchDesigner projects of your own!
