Intro to TouchDesigner

From TouchDesigner Documentation
Jump to: navigation, search

Introduction[edit]

Welcome to TouchDesigner. Once you’ve gotten your license installed, graphics drivers updated, and opened the program for the first time, you should see something like this:


TD 088 FullWindow.PNG


This is your new home, your new programming environment, and your new wheelhouse. There’s a lot to understand here, and before we can start making any serious progress programming we first need to take a quick tour of the interface and some of the conceptual ideas that underpin this programming tool. Any program or programming environment is built on ideas and concepts that give you access to a certain granularity of manipulation of data. Adobe’s Photoshop, for example, is built on the idea that you’ll want to manipulate pixel information - but not necessarily individual pixels. Certainly if you zoom in close enough, you can manipulate an image pixel by pixel, but largely, as a tool, it assumes that you want to perform higher level operations - filters, masks, healing tools, a whole bevy of algorithmic operations that allow you to work broadly and quickly. Photoshop is a tool that makes some expansive assumptions about what you want to do, and what you’re allowed to do. It’s not, for example, a very good text editor. If you’re working on a novel, it’s not the right tool for you. It works magic with pixels, but it’s not made for editing sound. You get the idea - it’s built around a set of assumptions and ideas about the world, and the person using using it.


All of that is a strange way to get started, but it’s important to think about this because TouchDesigner isn’t a program like Photoshop; instead it’s a programming environment that allows you to make the tools that you want and need - and in many cases tools that don’t yet exist. One of the big ideas behind Derivative’s approach is that the programmer should have access to the amount of control that they need at any given point. This will mean that sometimes you have access to more parameters than make sense, but it also means that as you grow as a programmer the influence you wield in your code becomes nearly limitless. Before we learn to how to sprint, however we’ll need to learn how to walk; and before we learn how to walk, we need to learn how to see - how to make sense of this tool, and what all of these new exciting multi-colored boxes mean.

Interface Topography[edit]

Let’s start by identifying all of the different control regions in your new workspace. We’ll start by looking at the big picture items, slowly working our way down into the nitty gritty elements of the interface. In our default workspace we have eight different regions that we need to know about:

  • Menu Bar | The menu bar holds all of the typical menu operations you’d find in a program, the save and open dialogue, edit elements, help et cetera. This is also the space that has a toggle to turn Cooking on and off, as well a toggle for Realtime processing.
  • Pane Layout | In TouchDesigner panes are the equivalent of workspace arrangements. Each pane has multiple views and features that allow you to see various parts of your network simultaneously. This is similar to many 3D rendering environments that give you multiple views of your scene at any given time. The Layout bar gives you the ability to quickly toggle between different layouts (horizontal and vertical split for example), as well as the ability to create your own custom view configurations.
  • Pane Bar | While the Layout bar will help you determine the configuration of your windows, the individual pane bar gives you the ability for specific configurations for your workspace.
  • Palette Browser | The Palette Browser servers multiple functions in TouchDesigner. First and foremost here you can find examples of several different kinds of tools and solutions to different problems. This is also a place where you can store frequently used modules that you develop in your own work.
  • Parameters Window | Nearly all of the control of a given operator can be accessed from within the parameters window. This is a window that you’ll use constantly in your programming, and later on we’ll talk about how this window is organized.
  • Network Editor | In TouchDesigner your programs and algorithms are organized into networks of operators. The Network Editor, therefore, is where you do most of your programming. We can think of this space as a two-dimensional space that’s like a desktop or canvas.
  • Time Attributes | Using the time attributes box we can control a number of different elements about how time works in our network. Here we can set our global sample rate expressed as Frames Per Second (FPS), and the length of our composition in Frames. There are some situations where time is very important for playback and programming, and in other non-linear applications you’ll be less concerned about changing the Time Attributes dialogue.
  • Time Line | In addition to being able to set some of the time attributes in our network, we can also access a timeline to control several aspects of how we move through linear sequences. Here you’ll see a play and pause button, single frame forward and reverse buttons as indicated by the + and - signs, as well as arrows that allow you to specify the direction of travel through the timeline.


TD 088 FullWindow label.png

Operators - All in the Family[edit]

There are lots of different ways that information is organized for us in TouchDesigner, and one of the most immediately visible distinctions is the types of operators. For TouchDesigner different kinds of operations are classified by their family affiliation. The heart of this is really about the kind of data that’s embedded in a given operator. If, for example, we think of the difference between cassettes and compact disks, it seems obvious that you can’t play a CD with a tape-player. This is partially because of the nature of the medium, but it’s also due to the encoding method used to store the information. Magnetic tape and optical disk are fundamentally different in how they treat information - even though both contain “sound.”


In TouchDesigner, we can think of the different families has having different organizational systems for their respective data. As long as we keep this in mind, it’s easy to see why we can’t immediately connect unlike families together. In order to help us, visually, we can also see that different families have different colors that are associated with them:

COMPs | Components | Gray

  • Computed on both the GPU and CPU - depends on the COMP
  • Components are high level operators that are often used to “hold” other networks. In addition to having their own set of parameters, COMPs can also contain whole networks of operators. As we build more complex projects, we quickly rely on these operators both for sake of organization and to build modular and reusable networks of operators.


TOPs | Texture Operators | Purple

  • Computed on the GPU
  • Texture operators deal with pixel information. To your graphics card, a texture is what’s applied to a piece of 3D geometry. TouchDesigner uses the GPU as much as possible for processing information, for this very reason images are treated as scenes for the graphics card to render. This is why we think of photos and video as textures - because to our GPU they are textures that are applied to a piece of geometry.

CHOPs | Channel Operators | Green

  • Computed on the CPU
  • Channel operators are linear sequences of floats or integers. These often manifest as animations, signals, inputs, curves, waves, or graphs. Audio, as a linear stream of floats, is also considered to be in the family of Channel Operators. CHOPs are the nervous system of your network. They send control and logic information throughout your project, and are an essential piece of how you drive your program.

SOPs | Surface Operators | Blue

  • Computed on the CPU
  • Surface operators are pieces of 3D geometry. When we want to work with something in 3D space, or render objects we often use Surface operators. While we can do a lot of procedural surface modeling, we have to be wary of the fact that our SOPs are computed by the CPU. Given this, it can be easy to slow your system to a crawl if you suddenly find yourself very ambitiously using SOPs.

MATs | Materials | Yellow

  • Computed on the GPU
  • Materials are applied to 3D geometry. The material determines what the 3D surface will look like when rendered by specifying the color and texture of the object and how light interacts with it.

DATs | Data Operators | Pink

  • Computed on the CPU
  • There are some operations require the manipulation of text, tables, or other types of data, and for those operations we have DATs. We can also use DATs to script sequences of operations, and for some more advanced programming methods.


OpsNodeViewer.png

Connections[edit]

Beyond the workspace itself there are also some other visual cues that help us see what’s happening in our network at a glance. There are two categories of connections that tie our networks together - wires and links. These are presented to us in two different visual styles to help us distinguish between them.


Links Links are represented by dotted lines with a moving arrow head in our network. Links form connections between parameters and between families in our networks. Links can be formed between operators of the same family, and between operators of different families - links between different families are also called references or exported parameters.


Exporting.gif


Wires Wires connect operators from the same family - TOP to TOP, CHOP to CHOP, et cetera. These kinds of connections pass information between operators to form procedural networks - the outcome of one algorithmic operation passed down the network to the next operator. Wires come in two different visual varieties. Moving and Static. This difference is subtle, but recognizing it in your networks will help you read a program faster and more efficiently.

Moving wires tell you that information is actively being passed from one operator to the next. TouchDesigner is a pull based programming environment. This means that an operator only cooks (processes information) when it is requested by another operator in the network. Moving wires help us see at a glance that something is cooking.


ActiveWire.gif


If moving wires help us see that an operator is pulling data down the network, static wires can help us see when information isn’t actively moving in our network. Static wires are solid in their appearance.


StaticWire1.png

Anatomy of an Operator[edit]

Operators are the building blocks of your network, and there are lots of things to know about them. We will start by first taking a look at the anatomy of our operator itself so we know what it’s telling us at a glance. After that we’ll take a closer look at the parameters window, to get a better sense of what we can control and how we can manipulate our building blocks.


Operator Name In TouchDesigner every operator can have a name, and in any given network all operators should have unique names. What does mean, and why do you care? Because the relationships that we form can exist between operators of the same family and operators of different families we need unique names in order to form specific references. If you’ve ever worked on a project with more than one Bob or Jennifer, you know how important it is to develop specific names so you know exactly who you’re talking to - whether in a long email chain, or in the middle of full project meeting.

Another important feature to take note of is the iteration of operator names. We can see in the example below that the operator name is “moviein2” - why two? This means that this is the second Movie In TOP that was added to my network. If I added an additional Movie In TOP it’s default name would be “moviein3.” This because especially useful when we start to build large and complex networks. It’s also important to know that we can ask for an operator’s name, or just it’s digits. In the example below, our operator’s name is “moviein2” and its digits are 2. Later on we’ll see why this is so useful and important, so for now just tuck away this idea in an unused corner of your mind.


088operatorName.png


Operator Viewer One of the most powerful elements you’ll encounter in TouchDesigner is the Operator Viewer. Every operator has a viewer that you can use to view and interact with elements of the operator. In our example here we’re looking at a png of a banana (hey Andy!). In other visual programming environments we might only see a file path, or a string of letters telling us that we have an image file ready to use. In TouchDesigner we can actually see a miniature version of our file. As we start to process our image with different operators we’ll also immediately see what effect those operations are having. This means that we always get to see, in real time, the entire chain of algorithmic operations that are happening in our network. This manifests as the ability to visually debug a network. You might well be concerned with the computational impact this is going to have on your finished program, and you’d be right in thinking that this kind of convenience comes at a cost. It’s true that rendering all of these previews does in fact have a cost - that said, it’s only a cost while you’re viewing the network. As soon as you leave a given network space, or enter perform mode, TouchDesigner stops rendering previews of individual nodes. This means that you sometimes get to have your cake and eat it too - both getting the benefit of seeing what’s happening in your program, each step along the way, without a performance cost when you’re no longer rendering the programming environment.


088operatorViewer.png


Connector Outputs Inputs and Outputs for connectors are how you pass information from operator to operator within a family. In TouchDesigner inputs and outputs live on the left and right (respectively) of the operators. This is different than some other visual programming environments, and also means that networks typically read left to right in terms of the order of their operations. Some operators have multiple inputs with specialized functions - volume, reset, et cetera; others allow for a large stack of inputs (a Merge CHOP, or a Composite TOP are good examples of this).


088operatorConnectors.png


Flags

Flags in TouchDesigner are an indication of the status of an operator. We can use flags not only to see various states of operators, but also to control them. That’s all well and good, but what does that actually mean? Before we can dive into what flags do, it’s important to realize that flags come in two varieties - universal and family specific.


Universal

Universal flags are found on all operators - and always in the same place on all operators. These flags can both be accessed in the visual programming environment, as well as with script commands. The univeral operators that are located on the upper left of operators are:

  • Viewer | The viewer flag allows you to toggle the viewer window on and off. You may find that at some point you don’t need to see every piece of the algorithmic chain that’s happening in your network. You might also find that you want to buy back the resources that rendering a preview of your work costs you. This is the flag to help make that happen.
  • Clone Immune | Clone building is an essential part of making lightweight and reusable network components. At the heart of cloning is the ability to copy the contents of Base or Container Component into another. That said, you may sometimes want every individual operator to copy over, but not the parameters of that operator. The clone immune flag helps solve that problem.
  • Bypass | You will undoubtedly ask yourself, at some point, “What is this operating doing?!” In those cases, the bypass flag can be a tremendous help. The bypass flag acts as a pass through toggle. This means that when bypassing is on the selected operator has no effect on the processing stream - instead it’s as though you have turned off that element in your algorithmic chain. When you toggle bypassing off, the selected node begins to have an effect on the network again.
  • Lock | The lock flag is one of the most understated and yet most powerful flags. The lock flag, when toggled to the on position, will hold the contents of the operator in your project file. This means that the node will not cook, and it will not update when its inputs are changed. Initially this may not seem useful, but it means that you can save information inside of your procedural network that might otherwise be difficult to access.


088operatorUniversalFlags.png


Viewer Active The viewer active flag is also available on every operator, but rather than being located on the upper left, it’s instead located on the lower right. This small plus sign shaped flag toggles on and off the ability for you to directly interact with the contents of your operator. This allows you quick access to a number of different pieces of information in your operator, the ability to change view types, and in some cases the ability to change your viewing angle (this is especially important with Surface Operators).


088operatorViewerActive.png


Family Specific As we’ve already seen, different families of operators do different kinds of information processing, this also means that we sometimes need some different options for displaying information for all of our different families. This is where family specific flags come into play. Next to the viewer active flag on the bottom right, you’ll find flags that are specific to each family. These appear as small circles that are color coded based on their function. Take a chance to look at all the flag types on the Flags page of the wiki.


088operatorFamiliyFlags.png


Parameters [edit]

Anatomy of the Parameters Window

The Parameters Window is where we have access to all of the control features of a given operator. Here you’ll be able to alter how a given element in your network functions, create relationships between operators, and much more. That said, there are a few important features about the Parameters Window that we need to know in order to fully take advantage of a functions of an operator.


Names

The names of our operator are always located in the top-most portion of the window. You’ll notice that I said names, not name. What gives? Any given operator has two names that are associated with it - the name of the type of operator, and the name you (the programmer) assign to the operator. In our example below we can see that this is a Movie In TOP (I know it’s a TOP because of its purple color). I can also see that this operator is named “moviein2” - you’ll see that next to the name of the operator type. Why should you even care about this. There are lots of reasons. The larger your networks become, the more important it will be to name your operators in a method to allow for easy reference building. You might for example, use a series of Composite TOPs in a given network. When you’re finally ready to output your video to a display, if you rely on the default naming in TouchDesigner, you suddenly have to remember if that was “composite4” or “composite8” or maybe even “composite11” that you want to use. If, instead you simply named it “finalComp” it will be easier for you to remember which operator you’re referencing. Let’s say that you give all of your operators descriptive names, when you hand off your network to another programmer (or come back to look at your work in three months), the descriptive names might not be helpful if you’re trying to see what operators were used in your network. This is why it is so useful to have both the name of type of operator, as well as its descriptive name in the top row of the parameters window.


088parameters names.jpg


Help and Info

The next row in the Parameters Window has all sorts of useful materials. Left to right they are:

  • Help | This first help button will take you to the wiki page that’s built for the operator. Here you’ll find a short description of what the operator does, as well as a description of what all of the parameters control for a given operator.
  • Python Help | Python 3 is the scripting language of choice for TouchDesigner, and the Python Help button will take you the corresponding Class page for a given operator. Here you’ll find information about scripting and referencing for that operator. The more you work with TouchDesigner, the more you’ll find reason to use scripting as a means of solving problems. When you’re starting you don’t need to know any Python to get working, but when you’re ready to do more complicated operations the Python Help button becomes invaluable.
  • Info | The Info button reveals all sorts of useful information about an operator - including it’s cook time (how long it takes to process), it’s memory use (if it is a TOP it will also tell you it’s GPU memory use), and much much more.
  • Comment | There are lots of ways to add comments to your TouchDesigner networks, and the comment function of a given operator is one of them. Here you can leave a short comment about what a given operator is doing. Comments left here will show up in the Info window.
  • Copied Values | The copied values button reveals connections between operators. We might imagine a circumstance where we want a change in resolution of one TOP to automatically change the resolution of another TOP, rather than doing all of this by hand. In copying parameters between operators this button can help us quickly see where (the operator and the parameter) those connections exist.
  • Scripting Language | TouchDesigner has two scripting languages - Python and TScript. While Python is now the default scripting language, there are still a lot of users and great methods for solving problems using TScript. If you need to change the scripting method for a given node, this button is how you toggle between languages.
  • Expand / Collapse Parameters | Every parameter in TouchDesigner is scriptable. This means that anything you can control with a slider or a field in the Parameter’s Window is something you can control with a script or with another operator. This is part of what makes TouchDesigner so extremely powerful and flexible. When that’s the case, sometimes you want to expand the scripting areas of all of the parameters. The expand all button does just that. Similarly, it will also collapse all of the parameters to make your programming space a little more tidy.
  • Non-Default Parameters | The non default parameters toggle is your new best friend. When you’re looking at the work of another programmer, or even your own work for that matter, it can be easy to quickly lose sight of what’s configured as a default setting, and what’s been altered by the programmer. This toggle will reveal only changed / non-default parameters. If you’re not sure what’s been changed in a given operator, this toggle makes it easy to see at a glance what’s going on.


088parameters helpandinfo.png


Pages

Any given operator might have just a handful of parameters, or more than will fit on a single screen. For that very reason, they are often split into pages that relate to their function. You may find a piece of documentation, or a portion of the wiki or forum talking about a given page of a parameter. When you see that language, this is where you should look.


088parameters pages.png


Parameters

Finally we’re to the part of the Parameter Window that does all of the exciting work. Here you’ll find all of the control elements for a given operator. One important consideration to thinking about when working with these values is that they come in many different varieties - some of which can be changed, and some which can’t. For example, in our Movie In TOP below we can see that the Cue Point parameter is set to be a % of the video. This normalized value is operating off the assumption that you want to think of a movie’s duration in terms of 0-100%. That being said, you can change this particular parameter to be Index, Frames, Seconds, or Fraction. Working with parameters is a fundamental part of working with TouchDesigner, so don’t be afraid to take some time and experiment to with a given parameter so you can figure out what it’s doing for you.

088parameters parameters.png

The bar at the top of the Designer Mode interface that contains menus, links, status messages and other controls.

(1) The TouchDesigner window is made of a menu bar at the top, a Timeline at the bottom, plus one of a choice of Layouts in the middle. A Layout is made on one or more Panes, each Pane can contain a Network Editor, Viewer, Panel, etc. See Pane and Bookmark. (2) Nodes in a network are arranged using Layout commands in the RMB menu.

A built-in panel in TouchDesigner that contains a library of components and media that can be dragged-dropped into a TouchDesigner network.

Strictly refers to a window in Microsoft Windows. User-created windows are made with Panels inside Window Components, aside from the TouchDesigner editor window and its dialogs.

A pane type where networks of operators can be created and edited.

Information associated with SOP geometry. Points and primitives (polygons, NURBS, etc.) can have any number of attributes - position (P) is standard, and optional are normals (N), texture coordinates (uv), color (Cd), etc.

The frame rate that TouchDesigner's Timeline uses. Equal to the Frames per Second value project.cookRate.

The Operator Families are TOPs, CHOPs, SOPs, MATs (Materials), DATs (data operators) and Components (Panel Gadgets and Objects).

The Graphics Processing Unit. This is the high-speed, many-core processor of the graphics card/chip that takes geometry, images and data from the CPU and creates images and processed data.

An Operator Family that contains its own Network inside. There are twelve 3D Object Component and eight 2D Panel Component types. See also Network Path.

An Operator Family that creates, composites and modifies images, and reads/writes images and movies to/from files and the network. TOPs run on the graphics card's GPU.

An Operator Family which operate on Channels (a series of numbers) which are used for animation, audio, mathematics, simulation, logic, UI construction, and many other applications.

Any of the procedural data operators. OPs do all the work in TouchDesigner. They "cook" and output data to other OPs, which ultimately result in new images, data and audio being generated. See Node.

The viewer of a node can be (1) the interior of a node (the Node Viewer), (2) a floating window (RMB->View... on node), or (3) a Pane that graphically shows the results of an operator.

The notch on the left and right of each Node that lets you connect a Wire from the output of one operator to the input of another operator of the same Operator Family.

Cloning can make multiple components match the contents of a master component. A Component whose Clone parameter is set will be forced to contain the same nodes, wiring and parameters as its master component. Cloning does not create new components as does the Replicator COMP.

Every node has an Immune flag. When the Immune flag is on, and the node is inside a Clone, it is not affected by any change to the clone, so you can store extra data in a clone.

The Container component type is a Panel Component that holds and displays any number of Panel Components (also known as Gadgets) in Panel.

An Operator Family that contains its own Network inside. There are twelve 3D Object Component and eight 2D Panel Component types. See also Network Path.

An operator whose Bypass flag is set does nothing: All data from its first input flows through to its output unaffected.

A state of a node where you can operate the contents of its viewer, like operate the gadgets of a panel in a node viewer, or 3D data in the viewer of a Geometry component. With Viewer Active off you can select, move and delete nodes by clicking/dragging on them, even if the viewer is visible.

Parameters in TouchDesigner are an operator's settings (numbers, menus, flags, strings, paths) which the user can alter. Parameters for any operator can be opened by right-clicking on the operator and selecting "Parameters..." A currently selected operator's parameters can be viewed in a Network Editor by pressing the keyboard shortcut 'p'.

Each SOP has a list of Points. Each point has an XYZ 3D position value plus other optional attributes. Each polygon Primitive is defined by a vertex list, which is list of point numbers.