V1.X Frequently Asked Questions (FAQ)

WHAT IS NI MATE?
WHERE CAN I FIND DOCUMENTATION FOR NI MATE?
HOW CAN I HAVE MY LICENCE EMAIL RE-SENT?
FEATURE REQUESTS AND OFFICIAL ADD-ONS?
HOW DO I REPORT A BUG IN NI MATE?
WINDOWS 8 SUPPORT
WILL MY KINECT FOR WINDOWS WORK WITH NI MATE?
WHAT KIND OF REQUIREMENTS ARE THERE FOR USING NI MATE?
NI MATE WON’T START UP CORRECTLY, WHAT CAN I DO?
HOW TO GET NI MATE’S MIDI MESSAGES TO OTHER PROGRAMS ON OS X?
HOW TO GET NI MATE’S MIDI MESSAGES TO OTHER PROGRAMS ON WINDOWS?
HOW CAN I EXPORT A CHARACTER FROM BLENDER TO UNITY?
HOW CAN I USE NI MATE LIVE FEED FUNCTIONALITY IN UNITY IF I DON’T HAVE UNITY PRO?
WHAT TO DO IF NI MATE FREEZES OR STARTS VERY SLOWLY?

WHAT IS NI MATE? top

NI (Natural Interaction) mate is a small but powerful software that takes real-time motion capture data from an OpenNI compliant device such as the Microsoft Kinect, Asus Xtion or PrimeSense Carmine and turns it into two industry standard protocols: OSC (Open Sound Control) and MIDI (Musical Instrument Digital Interface). Available for Windows, Mac OS X and Ubuntu Linux, NI mate offers users easy installation and a powerful, yet user-friendly configuration interface. Keeping to standard protocols for output makes NI mate an extremely flexible piece of software that can be applied in a vast number of scenarios. You can read more about the software from here.

WHERE CAN I FIND DOCUMENTATION FOR NI MATE? top

We are in the process of creating proper documentation for NI mate and all officially supported add-ons. You can always find the latest version of the documentation here.

HOW CAN I HAVE MY LICENCE EMAIL RE-SENT? top

You can have your licence email re-sent by going to the re-send licence email page. Enter your email and sensor device serial(s), and an email containing your licence key should be re-sent. If you are still having problems after that, please use the feedback button on the right side of the page.

FEATURE REQUESTS AND OFFICIAL ADD-ONS? top

We’re constantly looking to build new features and add support for NI mate in to software where it previously isn’t. Please make any such requests using the Feedback button found on the (right side of the) web pages. All requests and ideas will be taken seriously while the most requested ones will be given priority.

HOW DO I REPORT A BUG IN NI MATE? top

We invite you to report any unexpected behavior or bugs in NI mate to us as soon as you find them. We can best solve your issue if you describe what is the problem and what you were doing at the time of the occurrence of the bug in to the special Bug Report field inside NI mate. After finishing your description, click the “Copy bug report to clipboard” button on the page, open up your email program, write a relevant topic (ie. "NI mate crashes after I change settings), paste the whole clipboard in to the email body and just send your bug report to the email address beta [at] ni-mate [dot] com.

WINDOWS 8 SUPPORT top

NI mate supports Windows 8. See the documentation about how to install NI mate successfully in Windows 8.

WILL MY KINECT FOR WINDOWS WORK WITH NI MATE? top

A OpenNI V2.0 compliant build of NI mate is available for Windows machines through the OpenNI Arena. This version of NI mate is reported to work with Kinect for Windows devices. In order to get your device functioning with NI mate, you might be required to install the Kinect for Windows runtime drivers or SDK from Microsoft. We strongly advise you to read all the relevant licensing terms prior to doing so.

WHAT KIND OF REQUIREMENTS ARE THERE FOR USING NI MATE? top

The minimum recommended specifications for a computer running NI mate are a 32 bit (x86) or 64 bit (x64) dual-core 2.66-GHz or faster processor, dedicated USB 2.0 bus and at least 2 GB RAM. The required minimum space for capturing the full armature in NI mate is about 2x4 meters, while the maximum space a sensor device such as the Microsoft Kinect is able to track from is about 3x6 meters.

NI MATE WON’T START UP CORRECTLY, WHAT CAN I DO? top

First checks:

  1. Is the device a Microsoft kinect and is its power plug connected
    (There is a steady green light on the Microsoft Kinect USB cable is
    this is true.)

  2. Is the Microsoft Kinect connected to a USB 2 port (the plastic part
    in the usb port is black, not blue)? (In addition to the power plug,
    the Microsoft Kinect needs power from the USB port, so it has to be
    connected to a powered USB port on the computer or a powered USB
    hub. Many USB 3 ports have been found to be incompatible with the
    Microsoft Kinect.)

  3. Does the Microsoft Kinect blink a green light when connected?

  4. On Windows: Check the device manager (click the windows start menu
    and write “device manager”) to see if there is a category
    "PrimeSense" and under it “Kinect Motor” and “Kinect Camera”?

If all of the previous things check out proceed with the following:

  1. Try connecting the sensor device to a different usb port.

  2. Unplug any other “big” USB devices from the computer. The Kinect
    requires most of the bandwidth a USB 2 controller can provide, so
    all other devices requiring significant bandwidth (for example a web
    camera) should be disconnected.

  3. Uninstall any of the following software if it’s currently installed:
    OpenNI, PrimeSense - NITE, PrimeSense Sensor KinectMod, or any other
    sensor device driver.

  4. On Windows: Uninstall NI mate and the sensor device driver (Windows
    Driver Package - PrimeSense (psdrv3) PrimeSense/PrimeSensor).

  5. On Windows: Reinstall NI mate and make sure to enable the driver
    installation if it’s unchecked at the installation screen for some
    reason.

On Windows even after uninstalling any other sensor device related things it could be that for some reason the drivers installed by NI mate have been overridden by some other sensor drivers. You can change the drivers manually by following these steps:

  1. Go to the Windows Device Manager and locate the Kinect camera and
    Kinect Motor devices.
  2. Right click on the Kinect Motor and select “Properties”.
  3. From the driver tab select “Update Driver…”.
  4. Select “Browse my computer for driver software”.
  5. Select “Let me pick from a list of device drivers on my computer”.
  6. To use NI mate you should choose the “Kinect Motor” driver without
    the signature logo.
  7. Clicking “Next” will make the selected driver the active one.
  8. Repeat the above steps for the “Kinect camera” device.

HOW TO GET NI MATE’S MIDI MESSAGES TO OTHER PROGRAMS ON OS X? top

To make NI mate’s MIDI available to other programs you have to create a virtual midi port from the OS X MIDI settings:

  1. Open up the MIDI settings from Spotlight -> Audio MIDI Setup,
    Window-menu -> Show MIDI Window.
  2. Double-click the IAC Driver to show it’s properties, make sure to
    enable “Device is online” and click on the arrow for “More
    Information”.
  3. Add a new port with the + button and give it a name you can remember
    (for example “NI mate”).
  4. Launch NI mate and select the MIDI port you just created as the NI
    mate midi port for the data you want to send.
  5. Launch the other program and select the same port as the MIDI input
    there.

HOW TO GET NI MATE’S MIDI MESSAGES TO OTHER PROGRAMS ON WINDOWS? top

Windows doesn’t support virtual MIDI ports natively, so you’ll need to install an external program to act as one. Here are a couple of programs we have tried succesfully:

  • MIDI Yoke is a completely free one, but it could have problems on
    Windows 7.
  • LoopBe1 allows for one virtual port for non-commercial use and works
    very well on Windows 7. The developer also has a commercial LoopBe30
    available, which is much more versatile than the “1” version.

Both of these programs create a virtual midi port in the same way as the OS X MIDI setup. Once installed this port can simply be chosen in NI mate and the client program.

HOW CAN I EXPORT A CHARACTER FROM BLENDER TO UNITY? top

Each character can require some custom tricks, but here is a general workflow using the “simple bunny” example character:

Download the Delicode_NI_mate_Simple_Bunny.blend from the NI mate Blender page and open it in Blender.

The main difference in the way Blender and Unity work is that while in Blender the data from NI mate will be used to move the empties under the Kinect object (which are used to drive the bone motion with constraints) in Unity the bones themselves will be moved directly. For this reason we can strip out everything from the .blend file other than what’s under the Bunny_armature object.

Delete everything in the scene except for the Bunny_armature object.

Some of the bones in the simple bunny blender scene are rigged in a too complicated way for Unity to understand them, so they can be removed also. This includes the eye tracking bones and the ear targets. To get the same functionality in Unity would require some custom scripting, but that is beyond the scope of this tutorial.

Unparent the eye spheres with Alt-a -> Clear and Keep Transformation.

Delete the following objects from under Bunny_armature:

  • Eye armature
  • Ear parent and it’s child objects
  • Left hand collision
  • Right hand collision

Re-parent the eye spheres to the Bunny_armature Head bone.

Unity can’t use the model’s textures if they are packed to the .blend, so all of them need to be unpacked before importing the model in Unity.

Unpack the textures by selecting File -> External data -> Unpack into Files -> Use files in current directory. This will create a textures folder under the folder where the .blend file is.

Save the .blend file with a new name, for example Delicode_NI_mate_Simple_Bunny_Unity_Export.blend.

Start Unity and import the new .blend file by right clicking the Assets list and selecting Import New Asset…

To correctly assign the textures to the imported bunny drag the textures folder where you unpacked the textures into the unity assets window and select the rabbit object. Select Bumped Diffuse for the material shader and select the bunny_col_lite.png to be the Base color, and the bunny_nor_lite.png to be the normalmap.

The specular map will be left unused, but if you wish you can modify the bunny_col_lite.png in an external image editor to include the specular map as the alpha channel and change the Unity material shader to be Bumped Specular instead.

Drag the whole bunny object to the Unity scene and add a Camera if you don’t have one in the scene. You can also add some lights to make the bunny visible better.

Open the Unity Asset Store and search for “NI mate”. Import the “NI mate Unity Plugin” asset. You can uncheck the Bunny Example Scene and the Plugins folders in the import screen as they are not needed in this tutorial.

Select the camera and add the Scripts -> NImateReceiver component to the camera.

Start NI mate and enable Full Skeleton. Make sure that the OSC port matches the one in the Unity receiver script (7000 by default) and set the joint names in NI mate to correspond with the bunny joint names in Unity i.e. Head, Neck, Body, Shoulder_L, Shoulder_R, Elbow_L… You should also enable the Orientation skeleton OSC format as only the joint orientations are needed.

You should only use the joint orientation from NI mate as the bones in the Unity character create a chain where each bone’s location is dependent on the location and orientation of the previous bone. The orientations will propagate properly along the chain, but as the location data from NI mate is in global coordinates the bone chain will be broken completely if this data is applied to the bones.

Play the Unity scene and you should have a moving Bunny in Unity!

HOW CAN I USE NI MATE LIVE FEED FUNCTIONALITY IN UNITY IF I DON’T HAVE UNITY PRO? top

If you don’t have Unity Pro the Plugins folder is not supported. In this case you have to copy the plugin file for your platform to an external location:

OS X:
copy DelicodeUnityLibrary.bundle to /usr/lib and rename it to libDelicodeUnityLibrary.bundle
Windows:
A. add DelicodeUnityLibrary.dll to a directory that’s in the “PATH” environment variable
or
B. add the directory DelicodeUnityLibrary.dll is to the “PATH” environment variable

WHAT TO DO IF NI MATE FREEZES OR STARTS VERY SLOWLY? top

If your sensor is connected to a USB 3 port, then you should enable the low bandwidth mode from the NI mate preferences. However if the software doesn’t start at all or is very slow this can be very difficult or impossible. You can enable the low bandwidth mode manually by editing the necessary files next to the NI mate executable:

Open the sensor settings file in a text editor:

On OS X: Delicode_NI_mate.app/Contents/Frameworks/GlobalDefaults.ini (or PS1080.ini)
On Windows: Delicode_NI_mate_install_directory/Data/GlobalDefaults.ini (or PS1080.ini)

Find the line that reads “;UsbInterface=2” and remove the semicolon at the beginning of the line. If there is no such line add the line “UsbInterface=2” below the “[Device]” line.

Save the file and restart NI mate.

Note: on Windows you have to start the text editor with “Run as admin” if NI mate is installed under the “Program files (x86)” folder.