Heilan X3D Browser

Open Sound Control Tutorial

This is a tutorial demonstrating how to control objects in Heilan via Open Sound Control (OSC) messages. It only focuses on receiving OSC messages in Heilan. For more information about transmitting OSC messages from Heilan, see here. For this tutorial, we're going to be using Pure Data Extended (see wikipedia for a quick overview if you're unfamiliar with PD).

  1. We're going to start by creating an X3D file very similar to the one in the Sound tutorial:
    <?xml version='1.0' encoding='utf-8'?>
    <!DOCTYPE X3D>
    <X3D profile='Immersive'>
            <NavigationInfo type='EXAMINE'/>
            <Transform DEF='bob'>
                <Sound minFront='10' maxFront='20' minBack='10' maxBack='20'>
                    <AudioClip url='osctutorial.ogg' loop='true'/>
                        <Material diffuseColor='1 0 0'/>
  2. The important thing to note here is that we have assigned the Transform node a name using the DEF keyword. The Transform node is called bob. This name is going to form part of the node's OSC address.
  3. OSC messages follow a simple formula; the address to which they are sent, followed by the data to be sent to that address. For example, to move the Sound and Box in the above file one unit to the left, you would send the message '/heilan/bob/translation -1 0 0' to Heilan.
  4. In Heilan, any node can be manipulated with OSC messages, by sending data to the address '/heilan/<node name>/<node attribute>'. With <node name> being the name you've assigned the node with the DEF keyword, and <node attribute> being the attribute of that node which you want to manipulate.
  5. With that explained, it's time to move on to the program we're going to use to manipulate the 'bob' node: Pure Data. We're using the Extended version because it includes the OSC objects we're interested in.
  6. To begin with, create a new patch in PD, and add the following objects to it:
    OSC Tutorial 1
  7. This is the basic infrastructure needed by any PD patch which outputs OSC messages. The sendOSC object transmits OSC messages when it receives a particular signal at its inlet. The connect and disconnect buttons are used to connect and disconnect from the OSC server we are transmitting messages to (in this case the server is Heilan).
  8. localhost is an alias for the ip address of the computer the software is running on (since we will be running PD and Heilan on the same computer). It can be replaced with the address of any computer you are networked to. The 5678 is the port to transmit messages to. Heilan defaults to listening on the 5678 port, but it can of course be changed to any valid port number.
  9. Next, add the following:
    OSC Tutorial 2
  10. Here we have three sliders which we can use to move the Sound and the Box around Heilan's 3d space. At the bottom is the message object which composes the OSC message to be passed on to sendOSC. send tells the sendOSC object to transmit the following data, /heilan/bob/translation is the address to send it to, and $1 $2 $3 represents the data itself, which the message object gets from its inlet.
  11. What the pack object does is turn the slider's 3 individual values into a packed message - the format the message object requires its input to be in. So when one of the sliders' value changes, pack takes that single value and combines it with the values of the other two sliders to create a single message (something along the lines of '1.5 -0.25 2'). The message box then substitutes the first value into the $1 position, the second value into the $2 position, and so on.
  12. Finally, the bang object is there because pack only outputs when it is banged or receives a new value on its first inlet. The above setup means that an OSC message gets sent when any of the 3 sliders change, rather than just the first one.
  13. To get up and running, just hook the two groups up:
    OSC Tutorial 3
  14. Now all you need to do is start up Heilan with the above X3D file (making sure Heilan's Disable OSC option is not checked, and the OSC port is set to 5678), click connect on the PD patch, and start playing with the sliders. You should see and hear the Sound and Box moving around the scene.

Of course, PD is capable of a lot more than the simple patch described here. You could easily hook up a MIDI controller or a joystick, and devise complex mappings between them and Heilan. And PD is not the only program that can transmit OSC messages (e.g. Bidule, Quartz Composer, Max/MSP...).

You can download the files used in this tutorial (again released under the Creative Commons Sampling Plus License) here. The included PD patch also has sliders for manipulating bob's rotation.