One of the most useful features of TouchDesigner that might not be particularly obvious to beginners is its tight integration with Python. Besides enabling the use of Python for scripting, this integration gives access to a large amount of TouchDesigner-specific Python tools and utilities, as well as the ability to utilize Python’s extensive collection of built-in and third-party libraries. In this article, we’ll take a look at various Python libraries that are useful when building projects in TouchDesigner, including TouchDesigner-specific utilities, Python’s standard library and third-party Python libraries.
Differences between Python Modules, Packages and Libraries
In this article, we’re going to be referencing a variety of different Python modules, packages and libraries. If you’re new to Python, you might be wondering what all of these words mean. For our purposes, we’re not going to get overly complex with the definitions:
- A module is a collection of related functions/variables/etc. that are collected together into a single .py file
- A package is a collection of related modules. Packages are useful because they allow a large amount of functionality to be bundled together and organized hierarchically. Besides modules, packages can also contain subpackages, which are complete packages themselves.
- A library is often defined as a collection of packages. You’ll hear this sometimes used interchangeably with Python package, as packages can contain subpackages themselves, but for our purposes we’ll assume that it is a collection of packages.
In any case, the main idea here is that modules, packages, and libraries allow easy integration and access to a wide variety of advanced functionality within your project. Now that we’ve got that out of the way, let’s take a look at some examples!
Info adapted from: https://learnpython.com/blog/python-modules-packages-libraries-frameworks/
Useful Built-In Modules from the Standard Python Library
There are many, many extremely useful modules that are included in the Python standard library, which comes bundled with Python. These are just a small taste of what’s available. To see the full list, check out: https://docs.python.org/3.9/library/index.html
re – Allows the use of regular expression matching operations. Useful for parsing through data.
datetime – A module enabling you to work with dates, times, and time intervals. Functions include formatting dates as strings, time zone information, current date/time information, calculating time differences, and more.
math – A very useful module containing advanced mathematical functions. Trigonometric functions (sine, cosine, tangent, etc.), degree/radian conversion functions, floor and ceiling functions, exponential functions, square roots, modulo operations and more are all accessible via math.
random – The random module includes a variety of functions to generate pseudo-random numbers. Besides the ability to generate a random float value between 0 and 1, random includes a number of useful alternatives that can help to save you from writing some additional code, such as generating random integer values in a specific range, selecting a random element from a sequence, or shuffling the items in the sequence.
pathlib – A newer (Python 3.4) addition that makes dealing with files and the computer’s file system a breeze compared to old string-based methods.
subprocess – allows a Python script to be run as a parallel process. This is very useful in TouchDesigner, where certain Python functions can cause freezing/pauses as they complete (not ideal if you need to display moving visuals at the same time!). Check out Matthew Ragan’s blog for more info on implementing subprocess within TouchDesigner: https://matthewragan.com/2019/08/14/touchdesigner-python-and-the-subprocess-module/.
TouchDesigner-Specific Python Utilities
At first glance, the title of this section might be a bit of a head-scratcher. Aren’t we looking at Python Utilities for TouchDesigner throughout this article?? In this case, we’re talking specifically about Python utilities specifically developed/extended by Derivative for TouchDesigner. Included by default (they wouldn’t be of much use outside of TouchDesigner), they incorporate some very useful functionality that beginners may not be familiar with.
TDFunctions – This module provides a variety of useful utility functions, which include clamping values within a certain range, iterating strings with digits on the end, arranging nodes in the network, and many more.
TDJSON – A module of utility functions for JSON features in TouchDesigner, which are mainly focused around custom parameters and parameter pages. For example, there are functions that allow conversion of parameters or pages of parameters to JSON, and for adding parameters from JSON files.
TDStoreTools – Module that contains functionality for making Storage easy to use within Python Extensions.
Useful Third-Party Python Libraries
Python is known for its extensive collection of third-party libraries, which cover topics as wide ranging as scientific calculations, linguistics, and parsing data from the web. While all of the following libraries are developed by third parties, a number of them are automatically installed with TouchDesigner, which we’ll take a look at first.
Third-Party Libraries included with TouchDesigner
This is just a selection of the many great and useful libraries that are included with the installation of TouchDesigner. Check out the full list here: https://docs.derivative.ca/Python_Classes_and_Modules#3rd_Party_Packages
NumPy – Library that supports large multi-dimensional arrays and matrices, along with mathematical functions to perform calculations on this type of data. Often used in conjunction with OpenCV. In TouchDesigner, CHOP and TOP data can be converted to and from NumPy arrays.
OpenCV – OpenCV (Open Source Computer Vision) is an open source library focused on real-time computer vision. In TouchDesigner, it’s used in the Script TOP, Blob Track TOP, and camSchnappr.
Requests – A library for making HTTP requests easily. Very useful for getting all kinds of information from the web.
Get Our 7 Core TouchDesigner Templates, FREE
We’re making our 7 core project file templates available – for free.
These templates shed light into the most useful and sometimes obtuse features of TouchDesigner.
They’re designed to be immediately applicable for the complete TouchDesigner beginner, while also providing inspiration for the advanced user.
Additional Third-Party Libraries Worth Checking Out
These libraries are not included with TouchDesigner, but are still very much worth looking into!
BeautifulSoup – a great parsing library for HTML and XML. Allows for specific extraction of information from webpages.
NLTK – a library for working with human language. It allows for all kinds of processing of language that can be surprisingly useful even if you’re not a linguist.
Scrapy – Scrapy is a web crawling and scraping framework, which you can use to extract information from webpages.
SciPy – Open-source library for scientific computing which includes modules for statistics, optimization, integration, linear algebra, Fourier transforms, signal and image processing, ODE solvers, and more.
As usual, all of the third party libraries mentioned in this section are just a handful of many, many more that are worth checking out. If you’re interested in taking a deeper dive into what’s available, check out the Awesome Python list at: https://github.com/vinta/awesome-python
Wrap Up
Although we’ve covered quite a few popular and useful libraries here, it’s worth saying again that there are so many more out there — take some time to explore! Hopefully this article has given you some insight into why the integration of Python with TouchDesigner is such a huge benefit, and has provided you with some inspiration to start taking advantage of Python libraries in projects of your own.
