AddOSC

AddOSC is now replaced by AddRoutes for Blender 2.8

Introduction

OSC is a well known protocol for communications between multimedia applications. This Add-on allows you to bind easily Blender properties to OSC messages and see the result in real-time in the viewport interface.

NEW: Now this Add-on installs a module for the Blender Game Engine, see this page. 

Disclaimer

This Add-on uses the UDP Internet protocol but is mostly intended to work on local networks. Be warned that letting the server to listen to an interface connected to the Internet may expose you to security risks. I could not be held as responsible if whatever bad happened using this Add-on.

Usage

Setting the OSC parameters

  • Start/Stop: Theses buttons control the OSC engine of the Add-on, you will of course need to have it running in order to send/receive OSC events.
  • Running status: The state of the modal timer operator.
  • Input Address: The IP address of the machine sending to Blender.
  • Output Address: The IP address of the machine receiving from Blender.
  • Input/Output port: The IP port for each direction.
  • Update rate(ms): This is the rate at which the modal timer operator run, 1 millisecond is the lowest possible value. Lower values give better granularity but may cause higher CPU usage. 
  • Start at launch: The OSC engine will start as soon as the Blender project is opened. 

All theses settings are stored in the Blend file and are not scene dependent. Changes in OSC settings are not applied while the engine is running, you will have to restart it.

Basic Principles

  • Default Adress: A keyword with a slash (it's not an IP address), each key will receive an OSC address based on this. However this is a simple commodity, you are still free to edit by hand individually each key address. 
  • Monitoring: Will display for each key in your selection the actual value (works only if OSC is running). An added bonus is that you will see in the shell console problematic messages, if you have troubles to receive them.
  • Last OSC address: This block will appear only if Monitoring is enabled. It shows the last received message in real time.
  • Last OSC message: Idem, but with the associated content.
  • Import Keying Set: This Add-on exploits the Keying Set feature of Blender. Once you have built your own Keying Set, the next step is to import it using the button "Import Keying Set". You will then see your keys displayed as a list with various informations. 

  • Data path: The chosen property path.
  • ID: The name of the property. Its native type is showed between parentheses as an indication. Any mismatch will be ignored but will yield (if "Monitoring" is enabled) a warning in the console.
  • Address: Its OSC address, a number after the default address allows to distinguish the various keys. Can be edited by hand if your remote software or device forces specific keywords. 
  • Pick: This allows to automatically fill the Address with the one of the last received OSC message.
  • Value (optional): This data will only appear if Monitoring is enabled and be current while the engine is running. It reflects the current value of the property. 
  • Index: If a list of values is incoming, allows you to select which one will be routed to the given property. Though, if Index > 0 AddOSC won't in turn send any OSC message currently. 

In a script

You might want one day to add or remove AddOSC items by scripting. 

The items are stored in the collection property (OSC_keys) belonging to a scene. Each item has several fields:

  • data_path (string): Blender path before the property name
  • id (string): property name
  • address (string): the OSC address 
  • osc_type (string): the type of the property in Blender (str, float, etc).  
  • value (string): the last content received for this property
  • idx (integer): Index of the value to get if a list is received

Let's define a shortcut in our script to that scene, you can either point to the current active scene or to a given scene by its name :

import bpy 
scene = bpy.context.scene (or : scene = bpy.data.scenes['Scene'])

To clean up a previous collection if needed:

scene.OSC_keys.clear() 

To create a new item: 

item = scene.OSC_keys.add()
item.data_path = "bpy.data.objects['Cube']"
item.id = "location[1]"
item.address = "/blender/0"
item.osc_type = "float"

You can if you need define item.idx:

item.idx = 1

...but there is no need to define item.value as it is recalculated automatically. 

Since scene.OSC_keys is a collection you can access each element like an array:

scene.OSC_keys[-1].id = "location[0]"
scene.OSC_keys[-1].idx = 0

 ...the value -1 given for the item in the collection is a python trick to point to the last.

To remove an item (here the first):

scene.OSC_keys.remove(0) 

Let's make a scrpt for Animation Nodes

To ease the access of the values received by AddOSC we are going to write a custom script node in AN.

But fisrt and foremost, import a Keying Set in AddOSC and configure correctly the items so that they actually receive some OSC data.

Open the Blender script editor, copy/paste theses lines:

sce = bpy.context.scene
try:
    String = sce.OSC_keys[Integer].value
except:
    pass 



Rename your script as "OSC_get.py"

Add a Script node (in "Subprograms") in the node editor of AN.

Click "New input" and chose "Integer", it will allow to choose the item from your AddOSC collection.

Click "New output" and chose "String", it will output the last content received for the item (remember it is only refreshed when AddOSC is running and receive something).

With the selector chose your script "OSC_get.py" and below change the name to "OSC_get".

Now in "Subprgrams/Invoke Subprrograms", pick "OSC_get".

Connect a Debug node to the String output of this node, and change the integer value to pick the item imported in AddOSC .  That's it !  

Things to know

If you re-import a Keying Set, manual edition(s) of the OSC addresses will be preserved.

The first OSC 1.0 standard didn't implement boolean parameters natively however it was supported as an extension. Nowadays, every client/server should support them. It is the case of AddOSC but it could be a problem if you use an old software (or device ?) supporting only OSC version 1.0. Mail me if it's happen. Blender has boolean properties and they are sent as such without conversion currently, but a workaround could be implemented. 

Enum properties (you know the drop-down menus to pick a value) are presented as string, just send the name of the item as it would appear in the Blender interface to select the good choice.

Blender treats angles in radians internally despite showing them in degrees in the user interface ! So to rotate an object by 180° you have to send the Pi value from your OSC source.

Blender has a tolerance concerning types:

  • You can send a number (0/1) for boolean properties (instead of True/False), but not a string, even "True" or "False" won't work. 
  • You send a float number to an integer property, it will be truncated "on the fly". An integer to a float property will work too. 

Installation

This Add-on is now as easy to install as another Blender Add-on. It currently includes the pyhton-osc module (author: Thimote Faudot), on which it relies, for the sake of simplicity. 

Grab the zip archive from my Github page (Download ZIP on the right), then do "install from file" in the "User Preferences/Add-ons" screen and enable it with the check-box once it is listed.

Misc

License 

GPL v3

Planned

  • OSC controls for the Blender operators ?

Shortcomings / Troubleshooting

  • An OSC event is sent only when a Blender property changes. Consequently when you rewind the sequencer, there is no message sent if there has been no change in the meantime.
  • If you had used AddOSC in a project prior to version 0.12 some changes may prevent the Add-on to update the Keying Set when you click "Import Keying Set". Go in the Scene tab and in the "Custom Properties" region, delete "OSC_keys" (and may be OSC_keys_tmp), then re-import the Keying Set.

Example

AddOSC doesn't currently allow to bind OSC messages to Blender operators but you can use update function in a script as a workaround, as shown in this simple example. Value 10 and 11 will toggle the mode between EDIT and OBJECT.

Links

There is a thread on the BlenderArtist forum.

Thanks

Thanks to MisterCroche and Winzs for their support, inspiration, testing, ideas. :)

JPfeP