Vicon DataStream SDK Quick Start Guide for Python

About this guide

This guide is for new users of the Vicon DataStream SDK on Windows who want to get started with the Python client. Use of the C++, .NET and C APIs is very similar, but the details are outside the scope of this guide.

This guide is for you if you are new to both Python and the DataStream to help you to get started receiving DataStream data from Vicon products.

For full documentation, see the Vicon DataStream SDK Developer's Guide.

Choose the correct version

The Python client is installed as part of the DataStream installer for Microsoft Windows and can be found in:

• For 64-bit Windows:
  ..\Program Files\Vicon\DataStream SDK\Win64\Python
• For 32-bit Windows:
  ..\Program Files (x86)\Vicon\DataStream SDK\Win32\Python

Make sure that the version of Python you are using matches the installation: for 32-bit Python, the 32-bit installation is required, and correspondingly, for 64-bit python, the 64-bit version is required. To check your OS version, please refer to Microsoft's FAQ.

The SDK 1.11 installer offers you the choice of installing Python 2.7 or Python 3.2 and later, or both. Currently, only a Windows client is available.

If you don't have Python installed, you can download it from the Python website. For new users (and if you do not have a specific requirement for an earlier version), the latest version of Python is recommended.

Install the software

You can install the DataStream SDK Python package with the Python pip utility. This utility is included by default with current Python distributions.

Some convenience batch files are included with the DataStream Python module.

To install into your default Python distribution:

• Run install_vicon_dssdk.bat, which is located in the Python directory.

If you have more than one Python distribution installed and need to choose which one is targeted, run pip manually with the following command:

<path to required python>\python -m pip install <Program Files>\Vicon\DataStream SDK\Win64\Python\vicon_dssdk

To check that the package is installed correctly:

• Launch a python command shell and import the vicon_dssdk module:
  c:\python.exe
>>> import vicon_dssdk

If no error is shown, the module is loaded correctly.

Get started

If you want to get started straight away, you can use the supplied sample script in <DataStreamInstallation>\Python\example_scripts.

To use this script, launch a Vicon application supporting DataStream output, such as Shogun, Evoke, Tracker, or Nexus, and ensure that either live data is being received or offline data is playing back.

In Shogun Post, DataStream output is optional for playback. For how to enable this, see the manual.

For the remainder of this document, the Vicon application is referred to as the server application, and the Python script that you run is referred to as the client.

If you are running the capture application and the Python client on the same computer, you can see output data by running the example script without any arguments.
It will connect to the server and print out information about the stream to the console.

If you are running the capture application and the Python client on separate computers, you must pass the name or IP address of the computer running the server to the example client script.

For example, the following command connects to localhost automatically:

c:\python example_scripts\TestClientPython.py

The following command connects to a computer with IP address 192.168.1.23, running a server application on port 801 (the default Vicon DataStream port):

c:\python example_scripts\TestClientPython.py 192.168.1.23:801

Create a client

The main DataStream client is the Client class in the ViconDataStream module.

Create it as follows from within the Python terminal:

>>> from vicon_dssdk import ViconDataStream
>>> client = ViconDataStream.Client()

When you have a client, you can query some methods on it, such as version:

>>> client.GetVersion()
1.11.0

However, you can only perform most operations can only be performed after the client has been connected to the server application. If you try to call a function on the client that requires a connection, the client will throw an exception. This is the way that all errors are reported by the Client class. For example:

>>> client = ViconDataStream.Client()
>>> client.GetFrame()
...
vicon_dssdk.ViconDataStream().DataStreamException: NotConnected

To connect to the server, use the Connect() method. When connected, request frames with GetFrame():

>>> client.Connect( 'localhost:801' )
>>> client.GetFrame()
>>> client.GetFrameNumber()
2000

GetFrame() is a blocking call; its behavior differs depending on the streaming mode, which you can set with SetStreamingMode. However, the usual usage pattern is to call it in a loop, where you will receive frames at the frame rate of the server. For example:

from vicon_dssdk import ViconDataStream

client = ViconDataStream.Client()

print( 'Connecting' )
while not client.IsConnected():
print( '.' )
client.Connect( 'localhost:801' )

try:
  while client.IsConnected():
if client.GetFrame():
  print( 'Frame Number', client.GetFrameNumber() )
  
except ViconDataStream.DataStreamException as e:
  print( 'Error', e )

Best practice for more complex examples is to not perform unnecessary calls while connected, but to perform any processing after data collection is complete. For example:

from vicon_dssdk import ViconDataStream

client = ViconDataStream.Client()
frames = []

print( 'Connecting' )
while not client.IsConnected():
print( '.' )
client.Connect( 'localhost:801' )

try:
while client.IsConnected():
if client.GetFrame():
#store data here
frames.append(client.GetFrameNumber() )

except ViconDataStream.DataStreamException as e:
print( 'Error', e )

#do something here
print(frames)

Get more help with Vicon DataStream SDK

You can find further documentation on available functionality in the SDK in the For full documentation, see Vicon DataStream SDK Developer's Guide.

Further Python examples and detailed documentation can be found inline in the Python SDK directory (the default installation path is C:\Program Files\Vicon\DataStream SDK\Win64\Python).

FAQ and troubleshooting

• Why do I get "Error importing CoreClient / CoreClient3"? This error is typically caused by an incorrect DSSDK version being installed with Python 2 or Python 3. Check that your installed version is compatible with your Python version.