PlaySpace Reference Documentation

PlaySpace is an piece of software developed by Rob King at the Sonic Arts Research Centre of Queens University Belfast, that can create OSC responsive animated musical scores simply by scanning the files in a directory.

See:
          Description

Packages
additv  
additv.animation  
additv.brushes  
additv.controllers.osc  
additv.controls  
additv.core  
additv.drawables  
additv.echochamber  
additv.effects  
additv.modifiers  
additv.oscschema  
additv.shaders  
additv.utils  
additv.utils.net  
com.eteks.sweethome3d.j3d  
org.comedia  

 

PlaySpace is an piece of software developed by Rob King at the Sonic Arts Research Centre of Queens University Belfast, that can create OSC responsive animated musical scores simply by scanning the files in a directory. It was built as a interface to the more general AdditvCore visuals library for Java to make some of it's capabilities accessable to non-programmers.

Installation

PlaySpace requires Java 1.6. This is the default version in Mac OS 10.6. In 10.5, you need to change the default Java by opening "Applications>Utilities>Java Preferences" and dragging Java 6 to the top of the list for applications. You can confirm the version of Java you are using by entering java -version at the command prompt.
See also: http://www.deliciouscoding.com/post.cfm?entry=change-default-leopard-java-jdk-1-5-to-1-6-the-easy-way

PlaySpace also required the NVidia CGToolkit to be installed. This can be found at http://developer.nvidia.com/object/cg_toolkit.html.

Setup

PlaySpace automatically generates a set of 3D scenes, animations, and OSC mappings for files placed in the /data directory. The data directory is divided into the following subdirectories.

/models

This directory is where the bulk of the loading is done from. It uses the filenames to define scenes, and styles, and uses the hierarchy in the files to define an OSC control scheme. It loads all the 3DS files in this directory.

All files in this directory should be named under the following convention:
SceneNumber_RenderStyle_ModelName.3ds
Where SceneNumber is an integer, and RenderStyle is either "solid" or "sketch".
For example:

1_solid_myscene1.3ds
2_sketch_whatever.3ds

The solid render mode simply renders objects with a slightly shiny solid surface.

The sketch render mode takes the edges from the objects and renders them using a sketchy filter. The type of stroke can be set using the /stroke command.

Each file and mesh within a file that is loaded is assigned a set of properties accessable from OSC. See Default Properties for more information.

See the Exporting From Sketchup section below for more info on the file structure.

/fonts

All .vlw fonts placed in this directory are usable using the /overlay/text message.

/images

The Images directory contains two types of images: strokes and a background texture. The background image is papertexture.jpg, and can be toggled with the /background OSC message. If a scene is set to the sketchy renderer, you can change the stroke style to one of these files using the /stroke osc message.

Running

PlaySpace is packaged with a script called "runme.command" which should allow you to run PlaySpace simply by double clicking this file.

Alternately you can run PlaySpace from the command line by entering:
java -Xmx1024M -jar PlaySpace.jar

The -Xmx1024M argument sets the amount of memory allocated to PlaySpace. If you ever run into a OutOfMemory error, you can solve it by increasing this number.

If you have two displays connected (i.e. a projector) PlaySpace will automatically run fullscreen on the second display. PlaySpace expects the second display to be to the right of the primary display and aligned with the top of the primary display (in Display Preferences). If there is only one display detected, it will display fullscreen on that display.

Exporting from Sketchup

3DS models for PlaySpace can be exported from Google SketchUp. To export properly though you need to make sure all your objects are converted to components. To do this you can select the object you want to convert, and choose Edit>Make Component... Sketchup doesn't export the name you set here, so once converting to a component, you need to change the "Definition" in the Entity Info pane: Window>Entity Info.

The name that you set as the Definition will be set in PlaySpace as a part of the OSC messaging system.

To export to 3ds go to File > Export > 3d Model. In the format drop-down select 3ds.
Click on options and make sure that export is set to full hierarchy, and only the "export standalone edges" is
ticked off in the geometry section. Units should be in centimeters.

Animation Paths

PlaySpace allows you to use special names for components within sketchup to enable them as animation paths. Any animation path you define should have their "definition" field in sketchup set with the prefix "_P" (for example _PCircle). To define which component will follow a path, you set their definition field to be "_FP", so _FPCircle would follow _PCircle.

To define a path in sketchup select the edges you want to make into a path, and go to Edit > Make Component
In the Name field begin your name with "_P" followed by your name.

To define an object that follows a path, make it into a component as above, and name it "_FP" + your path name.
For example _FP1 will follow _P1 .

(note the 3ds file format has a 10 character limit on mesh names, so keep your path names <= 7 characters )

To check that an object is a component you can look at the "entity info" (window>entity info), and first seeing if an object is a component and second checking that the Definition is set correctly (REMEMBER: In order for things to export correctly, you must name things in this definition field, not the name field).


OSC Control

PlaySpace listens for OSC Messages on UDP port 5000. You can see the complete OSC Schema for any given set of data by running PlaySpace, then opening the OSCSchema.yaml file which is written on launch.

Message Types

The OSC schema supports a few different basic types of messages:

Toggles

Toggles are basic boolean messages. To switch them you can send either a float (1 or 0), an integer (1 or 0), or nothing to toggle them on or off. For example sending:

/background 1

/background 0.

/background

Would turn the background image on, off, then on again.

Floats

Floats expect a single floating point argument. For example:

/scale 2.0

Would double the scale parameter.

Vectors

There are two types of vectors: Vector3 and Vector4, which expect 3 and 4 float arguments respectively. For example:

/camera/rotspeed 0.4 0.2 0.0

/scene1/obj1/colour 0.9 0.1 0.1 0.5

Would set the camera spinning on the X and Y axes, and set the colour of an object to a 50% transparent red.

Default Properties

Each loaded file and mesh is assigned a standard set of properties for manipulation via OSC. So for example, if you load the file 1_sketch_scene1.3ds with a single mesh in it called "obj1", you would get the following default set of OSC messages you can send:

Base messages for any set of objects

/enablebloom: {Type: Toggle, Default: 'true'} - Playspace has a light bloom effect enabled by default to create a slightly soft image.
/exposure: {Type: Float, Max: '0.3', Min: '0.0010', Default: '0.03'} - Exposure for the bloom effect
/brightness: {Type: Float, Max: '0.6', Min: '0.0010', Default: '0.14'} - Brightness for the bloom effect
/scale: {Type: Float, Max: '10.0', Min: '0.1', Default: '1.0'} - Global scaling value
/drawaxis: {Type: Toggle, Default: 'false'} - Draws an axis for debugging
/drawfloor: {Type: Toggle, Default: 'false'} - Draws a floor for debugging
/imagealpha: {Type: Float, Max: '255.0', Min: '0.0', Default: '255.0'} - Changes the transparency of the background image
/backgroundcolor: {Type: Float, Max: '255.0', Min: '0.0', Default: '100.0'} - Changes the colour of the background
/localbg: {Type: Toggle, Default: 'true'} - Changes the method for showing the background
/background: {Type: Toggle, Default: 'false'} - Enables the background image
/camera/rotx: {Type: Float, Max: '6.2831855', Min: '0.0', Default: '0.0'} - Global camera rotation controls
/camera/roty: {Type: Float, Max: '6.2831855', Min: '0.0', Default: '0.0'}
/camera/rotz: {Type: Float, Max: '6.2831855', Min: '0.0', Default: '0.0'}
/camera/x: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '0.0'} - Global camera position controls
/camera/y: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '0.0'}
/camera/z: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '0.0'}
/camera/scalex: {Type: Float, Max: '6.2831855', Min: '0.01', Default: '1.0'} - Global camera scaling controls
/camera/scaley: {Type: Float, Max: '6.2831855', Min: '0.01', Default: '1.0'}
/camera/scalez: {Type: Float, Max: '6.2831855', Min: '0.01', Default: '1.0'}
/camera/rotxspeed: {Type: Float, Max: '0.2', Min: '-0.2', Default: '0.0'} - Animates camera rotation
/camera/rotyspeed: {Type: Float, Max: '0.2', Min: '-0.2', Default: '0.0'}
/camera/rotzspeed: {Type: Float, Max: '0.2', Min: '-0.2', Default: '0.0'}
/camera/rotspeed: {Type: Vector3, MaxX: '0.2', MinX: '-0.2', DefaultX: '0.0', MaxY: '0.2', - Animated camera rotation in vector format
MinY: '-0.2', DefaultY: '0.0', MaxZ: '0.2', MinZ: '-0.2', DefaultZ: '0.0'}
/camera/rot: {Type: Vector3, MaxX: '6.2831855', MinX: '0.0', DefaultX: '0.0', MaxY: '6.2831855', - Camera rotation in vector format
MinY: '0.0', DefaultY: '0.0', MaxZ: '6.2831855', MinZ: '0.0', DefaultZ: '0.0'}
/camera/translate: {Type: Vector3, MaxX: '1500.0', MinX: '-1500.0', DefaultX: '0.0', - Camera position in vector format
MaxY: '1500.0', MinY: '-1500.0', DefaultY: '0.0', MaxZ: '1500.0', MinZ: '-1500.0',
DefaultZ: '0.0'}
/camera/scale: {Type: Vector3, MaxX: '6.2831855', MinX: '0.01', DefaultX: '1.0', MaxY: '6.2831855', - Camera scale in vector format
MinY: '0.01', DefaultY: '1.0', MaxZ: '6.2831855', MinZ: '0.01', DefaultZ: '1.0'}
/camera/center: {Type: Vector3, MaxX: '1500.0', MinX: '-1500.0', DefaultX: '0.0', - Camera center in vector format
MaxY: '1500.0', MinY: '-1500.0', DefaultY: '0.0', MaxZ: '1500.0', MinZ: '-1500.0',
DefaultZ: '0.0'}
/camera/enabled: {Type: Toggle, Default: 'true'} - Toggles the camera

Messages for each scene (file)

/scene1/enabled: {Type: Toggle, Default: 'false'} - Shows or hides a scene
/scene1/camera/rotx: {Type: Float, Max: '6.2831855', Min: '0.0', Default: '0.0'}
/scene1/camera/roty: {Type: Float, Max: '6.2831855', Min: '0.0', Default: '0.0'}
/scene1/camera/rotz: {Type: Float, Max: '6.2831855', Min: '0.0', Default: '0.0'}
/scene1/camera/x: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '0.0'}
/scene1/camera/y: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '0.0'}
/scene1/camera/z: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '0.0'}
/scene1/camera/scalex: {Type: Float, Max: '6.2831855', Min: '0.01', Default: '1.0'}
/scene1/camera/scaley: {Type: Float, Max: '6.2831855', Min: '0.01', Default: '1.0'}
/scene1/camera/scalez: {Type: Float, Max: '6.2831855', Min: '0.01', Default: '1.0'}
/scene1/camera/centerx: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '0.0'}
/scene1/camera/centery: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '0.0'}
/scene1/camera/centerz: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '0.0'}
/scene1/camera/rotxspeed: {Type: Float, Max: '0.2', Min: '-0.2', Default: '0.0'}
/scene1/camera/rotyspeed: {Type: Float, Max: '0.2', Min: '-0.2', Default: '0.0'}
/scene1/camera/rotzspeed: {Type: Float, Max: '0.2', Min: '-0.2', Default: '0.0'}
/scene1/camera/rotspeed: {Type: Vector3, MaxX: '0.2', MinX: '-0.2', DefaultX: '0.0',
MaxY: '0.2', MinY: '-0.2', DefaultY: '0.0', MaxZ: '0.2', MinZ: '-0.2', DefaultZ: '0.0'}
/scene1/camera/rot: {Type: Vector3, MaxX: '6.2831855', MinX: '0.0', DefaultX: '0.0',
MaxY: '6.2831855', MinY: '0.0', DefaultY: '0.0', MaxZ: '6.2831855', MinZ: '0.0',
DefaultZ: '0.0'}
/scene1/camera/translate: {Type: Vector3, MaxX: '1500.0', MinX: '-1500.0', DefaultX: '0.0',
MaxY: '1500.0', MinY: '-1500.0', DefaultY: '0.0', MaxZ: '1500.0', MinZ: '-1500.0',
DefaultZ: '0.0'}
/scene1/camera/scale: {Type: Vector3, MaxX: '6.2831855', MinX: '0.01', DefaultX: '1.0',
MaxY: '6.2831855', MinY: '0.01', DefaultY: '1.0', MaxZ: '6.2831855', MinZ: '0.01',
DefaultZ: '1.0'}
/scene1/camera/center: {Type: Vector3, MaxX: '1500.0', MinX: '-1500.0', DefaultX: '0.0',
MaxY: '1500.0', MinY: '-1500.0', DefaultY: '0.0', MaxZ: '1500.0', MinZ: '-1500.0',
DefaultZ: '0.0'}
/scene1/camera/centered: {Type: Toggle, Default: 'false'}
/scene1/camera/enabled: {Type: Toggle, Default: 'true'}

Messages for each mesh (component)

/scene1/obj1/rotatealongpath: {Type: Toggle, Default: 'true'} - Changes animation mode.
/scene1/obj1/red: {Type: Float, Max: '1.0', Min: '0.0', Default: '0.0'} - Object colour
/scene1/obj1/green: {Type: Float, Max: '1.0', Min: '0.0', Default: '0.0'}
/scene1/obj1/blue: {Type: Float, Max: '1.0', Min: '0.0', Default: '0.0'}
/scene1/obj1/alpha: {Type: Float, Max: '1.0', Min: '0.0', Default: '1.0'}
/scene1/obj1/colour: {Type: Vector4, MaxX: '1.0', MinX: '0.0', DefaultX: '0.0', MaxY: '1.0', - Object colour in vector format
MinY: '0.0', DefaultY: '0.0', MaxZ: '1.0', MinZ: '0.0', DefaultZ: '0.0', MaxW: '1.0',
MinW: '0.0', DefaultW: '1.0'}
/scene1/obj1/linethickness: {Type: Float, Max: '10.0', Min: '0.5', Default: '1.0'} - Line thickness for sketch mode
/scene1/obj1/enabled: {Type: Toggle, Default: 'true'} - Shows or hides an object
/scene1/obj1/drawn: {Type: Toggle, Default: 'true'}
/scene1/obj1/transform/rotx: {Type: Float, Max: '6.2831855', Min: '0.0', Default: '0.0'}
/scene1/obj1/transform/roty: {Type: Float, Max: '6.2831855', Min: '0.0', Default: '0.0'}
/scene1/obj1/transform/rotz: {Type: Float, Max: '6.2831855', Min: '0.0', Default: '0.0'}
/scene1/obj1/transform/x: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '0.0'}
/scene1/obj1/transform/y: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '0.0'}
/scene1/obj1/transform/z: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '0.0'}
/scene1/obj1/transform/scalex: {Type: Float, Max: '6.2831855', Min: '0.01', Default: '1.0'}
/scene1/obj1/transform/scaley: {Type: Float, Max: '6.2831855', Min: '0.01', Default: '1.0'}
/scene1/obj1/transform/scalez: {Type: Float, Max: '6.2831855', Min: '0.01', Default: '1.0'}
/scene1/obj1/transform/centerx: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '-117.82955'}
/scene1/obj1/transform/centery: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '-4.6220884'}
/scene1/obj1/transform/centerz: {Type: Float, Max: '1500.0', Min: '-1500.0', Default: '-49.163864'}
/scene1/obj1/transform/rotxspeed: {Type: Float, Max: '0.2', Min: '-0.2', Default: '0.0'}
/scene1/obj1/transform/rotyspeed: {Type: Float, Max: '0.2', Min: '-0.2', Default: '0.0'}
/scene1/obj1/transform/rotzspeed: {Type: Float, Max: '0.2', Min: '-0.2', Default: '0.0'}
/scene1/obj1/transform/rotspeed: {Type: Vector3, MaxX: '0.2', MinX: '-0.2', DefaultX: '0.0',
MaxY: '0.2', MinY: '-0.2', DefaultY: '0.0', MaxZ: '0.2', MinZ: '-0.2', DefaultZ: '0.0'}
/scene1/obj1/transform/rot: {Type: Vector3, MaxX: '6.2831855', MinX: '0.0', DefaultX: '0.0',
MaxY: '6.2831855', MinY: '0.0', DefaultY: '0.0', MaxZ: '6.2831855', MinZ: '0.0',
DefaultZ: '0.0'}
/scene1/obj1/transform/translate: {Type: Vector3, MaxX: '1500.0', MinX: '-1500.0',
DefaultX: '0.0', MaxY: '1500.0', MinY: '-1500.0', DefaultY: '0.0', MaxZ: '1500.0',
MinZ: '-1500.0', DefaultZ: '0.0'}
/scene1/obj1/transform/scale: {Type: Vector3, MaxX: '6.2831855', MinX: '0.01', DefaultX: '1.0',
MaxY: '6.2831855', MinY: '0.01', DefaultY: '1.0', MaxZ: '6.2831855', MinZ: '0.01',
DefaultZ: '1.0'}
/scene1/obj1/transform/center: {Type: Vector3, MaxX: '1500.0', MinX: '-1500.0', DefaultX: '-117.82955',
MaxY: '1500.0', MinY: '-1500.0', DefaultY: '-4.6220884', MaxZ: '1500.0', MinZ: '-1500.0',
DefaultZ: '-49.163864'}
/scene1/obj1/transform/centered: {Type: Toggle, Default: 'true'}
/scene1/obj1/transform/enabled: {Type: Toggle, Default: 'true'}

Aside from these basic message types, there are a few messages that have special functions (outlined below).

Text Overlay

PlaySpace implements a special message that allows users to display text on screen by sending an OSC message. It is in the format:

/overlay/text "Hello World" myID LiGothicMed-48.vlw 0. 0. 1. 1. 100. 150.

(OSC format sssffffff)
the parameters are:
1. s - Your text
2. s - An ID so you can change the displayed text later
3. s - The name of the font file to use. Processing fonts are used, so you need to use processing to make your font files. To build a processing font open processing and go to Tools > Create Font, change the settings appropriately, then use sketch > show sketch folder to grab the created.vlw font. You put this file in the data/fonts/ directory.
4-7. f - RGBA (0 - 1)
8, 9. f - XY - (Note though that the coordinate system is from the top left, but the text is rendered from the bottom left, so 0,0 is offscreen. )

To change text use:

/overlay/text "My second text" myID
(format ss)
1. s - Your text;
2. s - The id you used to originally create the text;

You can also use
/overlay/clear
to clear the text overlay.

Animating

PlaySpace also supports tween based animations using OSC. You can use the /animate message to create an animation and /stopanimation to remove one. Both of these take the OSC address of the parameter to be animated as their first parameter (this is the only parameter for the /stopanimation message).
The basic order of parameters for animation is:

OSCAddress, DestinationVaule(s), AnimationTime(ms), DelayBeforeStartingAnimation(ms), Easing in speed(0.-1.), Easing out speed(0.-1.), looping (0 = none, 1=loop, 2=bounce)

It can take either normal values, 3 tuples, 4 tuples, or toggles in the destination values slot.

So, a basic example (in max format):

/animate /scene1/_pcircle1/transform/rotx 2. 1000. 0. 0. 0. 2
(typetag: sfffffi)
will animate the value of /scene1/_pcircle1/transform/rotx to 2, over the course of a second, immediately, linearly (no easing), and bounce back and forth between the original value and 2.

/stopanimation /scene1/_pcircle1/transform/rotx
would stop the animation

/animate /scene1/_pcircle1/transform/rot 2. 1. 3. 5000. 10000. 0.5 0.5 1
(typetag: sfffffffi)
will animate xrot to 2, yrot to 1 and zrot to 3. over 5 seconds, ten seconds from now, with a nice ease in and out, and loop.

/animate /scene1/_fp3_1/colour 1. 0.9 0. 0.5 3000. 0. 0.8. 0. 0.
(typetag: sffffffffi)
will animate the red to 1, blue to 0.9, green to 0 and alpha to 0.5 over the course of 3 seconds accellerating towards the end.

Finally:

/animate /scene1/enabled 1 20000.
(typetag: sif)
will cause scene1 to appear in 20 seconds.

The toggle functionality and the delayed start functionality is included so that it's would be possible to actually sequence the whole set of events right from the start of a performance. Just send out a set of messages with delayed starts, and you've got yourself a timeline!

Don't forget the trailing "." for most of the parameters, only the first is a string, and the last is an int. everything else is float.

Strokes

Just send the /stroke message with a string argument of the filename in the images directory. For example:

/stroke stroke2.png