Route Parameters

General Principle

A route is the basic element to connect an external source, a remote physical device or software, to a blender property. You can create several routes and organize them as categories. 

Each route has 3 sections:

1. Property (Normal/Multi/Python)
2. Engine (Please see the related pages : MIDI / OSC / Blemote)
3. Action (Keyframe options and IN/OUT mode)

Here is an example:

And, as we will see later there are 2 kinds of routes (Project routes and System routes). 

1) Property

There is 3 ways in AddRoutes to target a property:

1. By picking an ID-block, an item, and by filling a path to the final property. 
2. By using the Multi routing feature which allows to target several objects with the same property or the same object with several similar sub-elements (like bones or shapekeys).
3. By using the Python option, which allows to dynamically set the whole path of the property.

The 2 first types are the fastest as some precalculations are made while configuring the route. The third makes a Python evaluation when a route receives or sends, which can be slower.  

Let see first some common settings for a blender property which relates to the first type:

• ID-block: In the Blender philosophy each object belongs to a category (mesh objects, curves, materials, textures). When you edit manually a route, the first thing is to use the drop-down menu to choose the right category. In the example below the user is using "Key" (which is for shapekeys) :  
• Item: Once the right ID-block is used, you have to select one of its members. Pick one in the drop-down list, or use the search feature by typing a few characters.
• Path: This represents the path toward the final property you want to control. Please see the paragraph "Things to know" below about the particular cases you might encounter.
• Array Index: Some engines cannot address directly arrays and requires an index to target the proper sub value (x/y/z or r/g/b/a for instance) 
• All: This check box is for the engines that can deal with a whole array.
• Deg<->Rad: This checkbox appears when the property is an angle, and will convert for you a degree value into radians (Blender internal preference thru the python API).   

Red Alert !

Note: If a route from the type 1 or 2 is "non functional" and you try to set it for real use, its fields will appear in red, until you fix the issue. This won't happen however with Python route (type 3) because the fault will reveal itself only when receiving. You can use however the Debug options to be informed if there is any trouble. 

More about Multi routes

We have seen basically the first way to define a property but some engines (MIDI or OSC) can actually deal with complex data. This is needed for instance to represent visually a piano keyboard when chords are played or when using the Add-on with a motion capture software. Please see the MIDi and OSC pages for more details. 

For now Blemote cannot deal with multi routes.

Python routes

This is a recent addition in AddRoutes. The secret intent is to be able to use the context dependant properties that the Blender API offers (like bpy.context.object.location for instance).

Theses routes are as well the only one available when defining System Routes that we will see later.

It's not possible currently to mix Multi routes and Python routes.

 

As you see the ID-Block, Item and Path fields have been replaced by theses simple options:

• To eval: This is the python string you want to pass to eval(). C and D are shortcuts for bpy.context and bpy.data
• Context: Unfortunatly invoking bpy.context most of the time requires a specific context. The default string allows to access objects in the 3D scenes. This might not suit in every cases and require a different string. This is not needed for bpy.data however.
• Is Array (use index): Normally the Add-on detects automatically if a property is an array. But as the python evaluation can change dynamically, you need to explicitly check "Is Array" to be able to specify as well an index as a complement or use "All" to deal with a whole array (if OSC is used as engine).
• Is Angle: Normally the Add-on detects automatically if a property is an angle and offers the complementary option Deg<->Rad. You have now to select this option manually first.

2) Engine

Currently 3 choices are offered (MIDI/OSC/Blemote). Once you select one you will see specific options to configurate further the route. Please see the dedicated pages to learn more about them. 

When you select MIDI or OSC, you will see a 'Blemote' checkbox at the right of the drop-down menu. This is an extra option to force such a route to display a slider in Blemote for quick testing. 

3) Action

In this last section there are in turn 3(+1) sub-sections:

• Actualization : Replace or Expression.The default mode is "Replace" which just sets the Blender property with the incoming value. The second mode "Expression" invokes basically a python eval() function where 2 reserved keywords are available: IN and PROP. IN is the incoming value, PROP is the current blender property value. You can use Numpy with the "np" prefix like that: np.log(IN). Note that for an angle, IN reflects the result converted in radians if you use the feature "Deg<->Rad", but Blender still expects your expression to return a result in radians. The conversion stage is before this python evaluation.  

• Keyframe options: Theses appear only when Rec is enabled.

• Enveloppe settings: Intended for MIDIfile conversion, it can in fact serves for OSC as well. However it's based on the succession of positive and null values and won't work well without that. See the MIDI chapter for more.

• Receive/Send/Both/Off and Rec: Should be relativly easy to grasp. However please note that sending is currently active only when Blender is playing the animation. The second condition is that the property value has changed. 

If it's true that project routes can use the 3 methods to target properties, and are saved with the project blend file, system routes however are saved with the Add-on preferences settings and the Add-on can't reference the scene objects.

Therefore system routes can only use the Python method. System routes are always available as soon as Blender starts and remain when you load any project. But you need need to save the preferences globally to find them back when you restart Blender. A short cut has been provided in the Routes Panel.

System routes are mostly intended to control the user interface whereas project routes are to address scenes properties. 

However it's a general rule and if a python route fails to find a scene object, it won't produce any blocking error. 

The 3 engines have now settings than can be stored in the Add-on preferences. However OSC and MIDI engines still have  the option to override the "system" default choice by their own settings stored in the blend project).  

Tools

This new panel will probably grow in the future to offer a few facilities. You can now:

• Set the focus on a category with the drop-down list. 
• Create a new category with the "+" icon
• Remove a category with the "x" icon (the "contained" routes are not deleted but re-affected to 'Default')
• Rename a category (select it first with the drop down menu)
• Copy a category and its routes to a different scene (idem) 

Routes sorting if set to "Category" will display only the routes belonging to it. This option will serve in Blemote as well to organize your sliders. 

System routes belong to their own category 'System' and this cannot be changed (for now). 

The options in the "Extra route parameters" section allow to show/hide some recent new parameters, in order to help readability of the routes settings and keep the presentation simple. The route category is hidden by default. 

Overflows events: The number represents the times an engine has not been to process all the elements in the stack during its cycle of execution.