How to use the TouchOSC iPhone app to control a Vuo composition
or view it on YouTube:
Hey I’m Travis with Team Vuo,
In this tutorial, we’re going to learn how to use TouchOSC with Vuo. TouchOSC is a software platform that provides an array of different touch-control interfaces for the iPhone, iPod, and iPad. Vuo can receive the different forms of controlled output from a TouchOSC display and utilize it for creative input in a composition. Today we’re going to learn how to build this simple composition that uses a TouchOSC display on my iPhone to control the location of a shape within a console window.
We’ll walk through how to build this in a moment. First lets do a quick overview of how it works. Receive OSC Messages and Get Message Values work together to receive data from the OSC device in real time. These two Scale nodes take the values outputted for x and y in OSC and scales them so they’re synchronized with Vuo’s coordinate system. Make 2D point takes the x and y values and converts them into the location of a specific 2 dimensional point that Vuo can work with.
Fire on Start and Make Color Layer work together to produce a square-shaped layer. The location of the 2D point is used to control the location of the center of our square, and Render Layers to Window displays the square and its location within Vuo’s coordinate system on a console window.
Let’s run this and watch it in action. Here is my iPhone with a simple Touch interface that tracks the location of my finger upon the display. Our composition is receiving data about the location of my finger on the display and using it to control the location of our square in Vuo’s coordinate system. This basic composition demonstrates how to input Touch Control into Vuo and is a stepping stone for all kinds of creative control, from gaming to manipulating graphics in a live performance.
Let’s get started. We’ll open up a new composition in Vuo, and the first thing I’ll do is type in “osc” into the node library. Now I’ll drag Receive osc Messages onto the canvas. This will be our main trigger node. Whenever Touch osc outputs a new message of data, Receive osc Messages will fire an event and cause our composition to flow.
Next we’ll put Get Message Values onto the canvas. There are currently 4 options for this node, from top to bottom, each node gains an extra data value. The first one has one data value, and the fourth one has four. A few releases from now, these nodes should be consolidated into one node with a changeable number of ports. The Touch osc interface we’re working with with will be outputting two values, one for x and one for Y, so we’ll choose the second node with two data values.
We’ll drag a cable from received message to message. Now, whenever Touch osc outputs a message of data values, Receive osc Messages will fire an event, which will go on to Get Message Values, which will output the data here. At this point, let's go ahead and run our composition and connect Vuo to Touch osc so we can see what type of values Touch osc will output when I move my finger on the interface. We'll run the composition, and when we do so, Vuo will actively try to connect to Touch osc.
Vuo will automatically show up on Touch osc's connectivity options when Vuo and the Touch osc device are connected to the same Internet network. However, please note that some public networks, like at a performing venue or a library, block this type of extra communication. The most assured and direct way to connect Vuo to Touch osc is to create your own network on your mac, and that's what we'll do today. This is quickly done by clicking on the wireless icon in the toolbar, selecting “Create Network,” it will ask me to name the network and I'll type in “Vuo.” Now my macbook is producing its own network, so I'll connect my iPhone to the Vuo network by selecting “settings,” “wifi,” and choosing the Vuo network.
Now that my iPhone is connected, we'll open up touch-osc, select the very top tab under connectivity and a button that says “Vuo osc Server” appears at the bottom. I'll select that, and now our Vuo composition is connected to my iPhone. Please note that if you stop your and restart your Vuo composition, you’ll have to reconnect Touch osc to the Vuo server again. Next we’ll go back to the previous menu, click the tab for layout options, and today we'll select “Simple.”
Now we can select “done,” and an interface will appear. At the top there are four light colored buttons that give you the option to choose between different interfaces, and we'll choose the third one for today, which basically gives us a square-shaped track pad.
Excellent, our composition is running, Touch osc is connected, now we'll work on observing what type of values Touch osc is outputting. As soon as I start moving my finger on the track pad, events start flowing from Receive osc messages, and Get Message Values starts producing values. To demonstrate this, we'll go up to the “Run” tab and select “Show Events.” In Show Events mode, all the parts of the composition that do not have events flowing through them become opaque, as they are right now. When events start flowing, all the parts that events are flowing through, become darkened.
Let's check it out. Whenever I drag my finger across the trackpad, we can see the receivedMessage port darken, and the entire Get Message Values node darkens because events are flowing completely through it. In addition, when trigger ports are generating events, this is indicated by a radiating effect, as seen here. Great. Show events can be a very handy tool for observing what's happening and when in your composition. We'll go ahead and go back to hide events mode.
Now lets get more specific and hover over the data1 port, and here a popover shows up. If we look at the data type, it currently says generic, that's because we haven't yet connected a cable to anything specific. We want to analyze the most specific number possible, so I'll go ahead and right click the port, select “Set Data Type” and choose “Real.” I'll do this for the data2 port as well. With our data type set as “real,” we can now observe specific values flowing through the port. Excellent.
When we hover over the port for data1, we can observe that as I move my finger about the trackpad, the value doesn't fluctuate much when I move up and down, but when I move all the way to the left side of the window, it produces the value of “0,” and when I move across the screen to the right edge, the value progresses to “1.” This reveals that data1 is producing values for the X axis with the 0 point being at the far left. Now if we observe the data2 port, the same thing occurs, except in relation to moving up and down, along the Y axis with a value of “0” at the top, and “1” at the bottom. Great! Now we know what values Touch osc is outputting, so let’s work on getting Touch osc’s grid system synchronized with Vou’s.
For reference, let's bring up a slide of Vuo's grid coordinate system. Looking at the x axis, notice that instead of spanning left to right from zero to positive one like in Touch osc, Vuo spans from negative one to positive one. And the range of the Y axis in Vuo will vary. Vuo automatically adjusts the range of the Y axis in order to maintain aspect ratio with the X axis. What’s key to notice is that the values flow in opposite directions for the Y axis. Remember that in Touch osc, the values started at zero at the top and increased in value as it went downward. In Vuo, we can see that the values increase as we go upwards, so we’ll have to compensate for that next.
In order for the numbers being outputted from Touch osc to offer accurate control in Vuo’s coordinate system, we need to scale the numbers accordingly. We'll go to the node library, and drag Scale onto the canvas. You'll see that this is the perfect node for the job. We'll input our incoming values from Touch osc here, and set their range, which, as we discovered starts at zero and ends at one. Then we'll set a new range of numbers that we want to offer parallel control in, which is Vuo’s x axis, which betweens with negative one and extends to positive one. That's it. Now the zero to positive one range, controls the negative one to positive one range, in scaled fashion.
We'll go ahead and do the same thing for the Y axis. Our input will be exactly the same: from zero to negative one. However, remember that the Y values for Touch osc and Vuo increase in opposite directions, so we'll compensate for this by flipping the direction our scaled values are moving in. With our incoming values starting at zero and increasing to one, we’ll have our scaled values start with positive one and decrease to negative one. And that’ll do it. Great.
The next thing to do is take the output for x and y, and turn them into a specific 2 dimensional point. I'll go to the node library and type in “2d” and drag Make 2d Point onto the canvas. We'll connect our x value to the x input, and our y value to the y input. Make 2d point will take these independent x and y values and output specific points that we can use for control in Vuo's coordinate system.
Now we need something to control. The next node I'll put on the canvas is Make Color Layer. This node will allow us to create a simple colored layer, and we can control the center point of this layer, with the 2d point that we've refined from our Touch osc output. Currently the width and height of our layer is setup to be exactly the same size as our display — two total units in each direction, so we'll reduce the height and width to be a value of “0.2” Now our color layer will appear as a small square. We'll select the color of our layer, and we'll let the rotation be for now.
Though a stream of events will be flowing into our center point when Touch osc is outputting values, we still need one event to originate our layer, so we’ll put Fire on start onto the canvas and connect it to the refresh port here so that our colored layer is created upon starting our composition.
Lastly, we need to send our layer to a window. So we'll go to the node library and find Render Layers to Window and drag it onto the canvas. The console window automatically shows up since our composition is still running, but you’ll notice that there’s no colored layer being displayed. First we need to connect our layer to the window, and, since we put Fire on Start on the canvas after we started composition, it hasn’t fired an event yet. So we’ll right click the trigger port, and fire an event. And there’s our colored layer. Great! Let’s try it out.
Now you can see that when I move my finger about the Touch osc trackpad, we’re controlling the location of our colored layer in Vuo’s coordinate system. Awesome. That’s it. We’re only controlling a simple colored layer here. The capabilities for what you control and it what context are really unlimited, and we hope this tutorial helps get you going.