Heilan X3D Browser - documentation

about - news - screenshots - videos - documentation - download - forum - contact

Open Sound Control Support

As of v0.15, Heilan can act as both an OSC server and an OSC client. This means you can potentially have multiple instances of Heilan (on multiple computers), all interacting in the same X3D scene.

Browser Options

You'll likely need to set some of these options if you want to work with OSC in Heilan. Command line options are in italics. All the options here can be set from the Heilan Front End GUI.

Input Port: (--OSCPort [val] | -op [val]) Sets the port to listen for OSC messages on. You'll need to match the port you're sending OSC messages from to this.
Input Multicast Address: (--OSCMulticastAddress [val] | -om [val]) Heilan can receive OSC messages unicast (meaning there can be only one client connected to it), or multicast (meaning there can be any number of clients connected). To work unicast, leave this blank (clients will send OSC messages to the ip address of your computer). Otherwise, set it to the multicast group ip address you're using (anything in the range 239.0.0.0 to 239.255.255.255).
Output Port: (--OSCOutputPort [val] | -oop [val]) Sets the port to send OSC messages to. You'll want this to match the port of the server you're sending to.
Output Address: (--OSCOutputAddress [val] | -ooa [val]) Sets the ip address to send OSC messages to.

As an OSC Server:

First, make sure the browser's input port matches that of the client you're sending OSC messages from. If you're working in multicast, make sure the input multicast address and the ip address you're sending to from your client both match.

In Heilan you can control any attribute of an X3D node in the current scene by simply assigning an OSC address to the node. To do this, simply name the node with DEF - this will set the node's OSC address to '/heilan/<whatever_you_named_it>. To then control it from an OSC client, you just send messages to '/heilan/<node address>/<node attribute>'. If you are trying to control an attribute that may have multiple values (e.g. a position vector), you can control it by adding the index of the value you want to control to the end of the address, e.g. '/heilan/bob/position.0' (the first four indices can also be replaced with x, y, z, r respectively). This also extends to nodes with multiple vector values (e.g. '/heilan/bob/keyValues.0.1' refers to the Y coordinate of the first key value).

Example Usage

The box may now be moved, rotated and resized via OSC, by sending messages to '/heilan/bob/translation', '/heilan/bob/rotation' and '/heilan/bob/scale' respectively.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE X3D>
<X3D profile="Full">
	<Scene>
		<Transform DEF="bob" translation="0.0 0.0 -5.0">
			<Shape>
				<Appearance>
					<Material diffuseColor="1 0 0"/>
				</Appearance>
				<Box size="1.0 1.0 1.0"/>
			</Shape>
		</Transform>
	</Scene>
</X3D>

You may want to look at my MouseToOSC program for a simple way to send OSC messages to Heilan.

Controlling the Camera

You can also control Heilan's camera/listening position via OSC, by sending messages to the hard-coded addresses '/heilan/camera/position' and '/heilan/camera/rotation'.

As an OSC Client:

Again, first make sure that the output port and output ip address both match that of the OSC server you want to send OSC messages to.

For Heilan to send OSC messages to an OSC server, we need to use the special OSCOutput node, in the libheilanextras library. We add one of these for each OSC address we want to send data to. Any data which is ROUTEd to one of these nodes will automatically be forwarded on to the connected OSC server.

Example Usage

This example demonstrates how to send OSC messages to another Heilan instance.

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE X3D>
<X3D profile='Full'>
	<Scene>

		<Transform translation='0 0 0'>
			<Shape>
				<Appearance>
					<Material DEF='matt'/>
					<ImageTexture url='TestTexture.png'/>
				</Appearance>
				<Box/>
			</Shape>
		</Transform>

		<TimeSensor DEF='timmy' cycleInterval='5' loop='true'/>
		<ScalarInterpolator DEF='scaly' key='0 0.5 1' keyValue='1 0 1'/>

		<OSCOutput DEF='oo' oscAddress='/heilan/matt/transparency'/>

		<ROUTE fromNode='timmy' fromField='fraction_changed' toNode='scaly' toField='set_fraction'/>
		<ROUTE fromNode='scaly' fromField='value_changed' toNode='matt' toField='transparency'/>
		<ROUTE fromNode='scaly' fromField='value_changed' toNode='oo' toField='sffloatOutput'/>

	</Scene>
</X3D>

In this case we modulate the transparency of a Box node with a ScalarInterpolator, and also pass this modulation onto another instance of Heilan (running the same file minus the OSCOutput, TimeSensor and ScalarInterpolator nodes). OSCOutput has an oscAddress attribute which specifies the OSC address any data it receives should be sent to, and it has a number of input fields to which different types of data may be ROUTEd (currently sffloatOutput or sfintOutput).