Quickstart Guide
This is a quickstart guide aimed at getting you up and running with Heilan as quickly as possible. It's primarily aimed at Windows and OSX users who have downloaded the binary executables rather than the source code package, but the instructions apply more or less equally to Linux users etc.
What is Heilan?
Heilan is an X3D browser focused on audiovisual performance. It is intended for displaying 3d scenes (together with a 3d soundfield) which may then be interacted with, both using X3D's interactivity capabilities, and Heilan's own Open Sound Control capabilities.
What is X3D?
X3D is a file format designed for virtual world-type applications, and is the successor to VRML. Essentially an X3D file describes a complex 3D environment, primarily focusing on the visual aspect, though with the ability to also describe various possible interactions. As it stands, Heilan is only capable of reading X3D files - in order to create your own environments you will have to read up on the X3D specification and create them by hand. The example files included in the downloads should be helpful in this regard. There's also a basic tutorial included on this site.
How to use Heilan
-
The easiest way to use Heilan is via the Front End program, which
provides graphical access to all of Heilan's browser options. So,
double-click on the HeilanFrontEnd(.exe on Windows) executable to
start it. You should see the following (click to enlarge):
-
The first time you run the Front End you'll need to set a couple of
options. The most important one is the path to the Heilan browser
executable, so click the '...' button along from the 'Browser Path:'
control to navigate to it and select it. You should end up with
something like the following (click to enlarge):
-
Next check that the Audio Device is set correctly with the 'Audio
Device:' combo box:
-
If you want to use the additional node types I developed for Heilan
myself, add the libheilanextras(.dll/.dylib/.so) to the list in the
'Libraries' section with the '+' button (click to enlarge):
-
Finally, select an X3D file to view in the 'X3D File' section, and
click the 'Go' button. The browser should start up and display the
file's X3D scene. (click to enlarge)
- Note: If the Heilan Browser window appears and quickly disappears when you click 'Go', it means something went wrong. On Windows, Heilan will generate a 'stdout.txt' file which should give you some hints as to what happened. On Linux the information will be output straight to the command line, and on OSX you'll be able to see it if you open your Console application. In any case, if you have problems, be sure to report them to the forum.
Interesting Features of Heilan
The 'Speaker Configuration' Option
Heilan uses Ambisonics to generate its 3d soundfield. What this means is that the soundfield can be (more or less) reproduced on any number of speakers, in any configuration. Heilan currently allows for a number of preset configurations to be used. The default is Stereo, but the Surround1 preset is intended for use with a standard 5.1 setup. Note that the accuracy of the resultant soundfield will depend on your speakers being arranged in the same configuration as the preset assumes (note to self: I need to find out what the presets assume...).
Open Sound Control
The 'OSC Port' control determines which port Heilan will listen on for OSC messages. Heilan acts as an OSC server. If you want to save a performance you've made using OSC to control Heilan, specify a file in the 'Record OSC to:' control for your data to be saved to. To play this data back, you then need to add an OscPlayback node to your scene, and pass it the path to your saved file as its 'url' attribute.
Note: Whenever the 'Record OSC to:' control is not empty, the browser will save any incoming OSC data to the selected file. This means that if you've just recorded some data and are going to play it back, you should make sure to clear the 'Record OSC to:' control, or you'll overwrite the file you just saved.
Offline
If you click the 'Offline' button, Heilan will save its visual and sonic output (for a specified length of time) to your hard disk, instead of running in realtime. Note that Heilan will save each speaker feed as a separate .wav file, and each visual frame as a separate jpeg. It's up to you to then combine them into a video file (there are instructions on how to do this over here).