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 information is included:
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 https://www.python.org/downloads/. 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:
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:
>>> import vicon_dssdk
If no error is shown, the module is loaded correctly.
If you want to get started straight away, you can use the supplied sample script in
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:
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:
When you have a client, you can query some methods on it, such as version:
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:
To connect to the server, use the
Connect() method. When connected, request frames with
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:
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:
Get more help with Vicon DataStream SDK
You can find further documentation on available functionality in the SDK in the 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.