Documentation: OSC (Open Sound Control) and parameter tags


NI mate makes extensive use of the OSC protocol. This protocol is used for similar tasks as the MIDI protocol, but allows a much more modern method of transportation.

The OSC format works by specifying an address and its content. The address refers to the value the OSC message should control in the receiving software. In NI mate, a good example is the name of some skeleton joint. The content is a list of values that can be strings or numbers.

An OSC message look as follows:

/skeleton_left_hand 5.2 2.1 -20.7 0.97 0.2 0.5810 0.062

This is the default path for the skeleton joint basic + orientation mode in NI mate’s skeleton tracker. The message contains the address, beginning with the protocol compliant forward slash symbol, with the content being 3 position floats and 4 orientation floats.

OSC address fields

The assorted OSC address fields in NI mate can be used for specifying not only the address for the OSC message in question, but also the values that are sent out. By default, all the OSC messages will be sent with the data most users expect to be sent out. For skeleton joints, this is the joint’s name, position and orientation. However, the address fields can also be used for customizing what data is sent out.

Inserting the value /hello_world to the OSC path for some skeleton joint will send out the position and orientation data with the address “/hello_world.” However, what about if you only require the Z coordinate and the orientation? We’ve implemented a scripting system for this purpose.

NI mate allows you to type special sequences of characters into the OSC address. These are called parameter tags. All of them are listed in either square or curly brackets, for example [I] {X} {Y} {Z} {OW} {OX} {OY} {OZ}.

Consider the path: /skeleton_left_hand {Z} {OW} {OX} {OY} {OZ}

This will output only the z coordinate and the orientation data for the left hand. The interesting part is that the tags support arithmetic operations:

   /skeleton_left_hand {Z / 100} {OW + 0.5} {OX * 2} {OY} {OZ}

The above message will divide the Z coordinate by 100, add 0.5 to the orientation W component and multiply the orientation X component by 2.

The parameter tags are integers if they’re enclosed in square brackets and floats if enclosed in curly brackets.

The full list of parameter tags is as follows:

  • [I]: Some user’s index, from 1 to 20
  • [U]: Some user’s activation number as defined by the user settings
  • [A]: Area activity number, describing the area where some action took place
  • {D}: Some user’s distance to some area, in meters.
  • {R}: Some user’s relative distance to some area (factor of radius). This results in 1 if the user is right at the area’s edge.
  • {W}: Activation weight for some user in some area. Describes how close to the center of the area the user is.
  • {V}: Face shape or trigger value.
  • {X} {Y} {Z}: Some skeleton joint’s position, modified by the skeleton tracker’s offset parameters.
  • {x} {y} {z}: Some skeleton joint’s raw position in milimeters without any modification performed by the skeleton tracker’s offset parameters.
  • {OW} {OX} {OY} {OZ}: Some joint’s orientation quaternion in world space
  • {EX} {EY} {EZ}: Some joint’s orientation in radian angles.
  • {ex} {ey} {ez}: Some joint’s orientation in euler degree angles.

In addition to the square and curly brackets, NI mate allows using quotation symbols. If it’s required to send out an OSC message with a square or curly bracket in it, NI mate will by default parse the square bracket as a parameter tag and will try to evaluate it. If you wish to send out the following type of message:['cube'].position[0]= {X}

then it’s required to enclose the square brackets in quotations to avoid them being parsed as a parameter tag:"['cube']".position"[0]"= {X}

It’s also possible to nest the quotation marks:"[someArray'["cube"]']".position"[0]"= {X}

Documentation: Skeleton tracking
Range in OSC XY values?
Documentation: Table of contents
Documentation: Face Shapes
Documentation: Controller tracking
Can someone point me to what I need next? (skeleton set up)
Documentation: User detection
My rig is backwards when attempting copy rotation
Face tracking / Blender/ all points jump on 0.0.0
Does NI Mate really works?
3 Axis with Blender
Blender plugin recording speeds up