Vicon Tracker Python API Quick Start Guide

About this guide

This document enables you to get started with the Vicon Tracker API.

The Tracker API enables you to control certain features of Tracker via a Python API. The API enables you to automate some common functions of Tracker, such as loading, playing and exporting trial data, activating or deactivating different objects, or triggering parts of the workflow.

For full documentation, see the inline documentation guide within the API itself.

Choose the correct version

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

• For 64-bit Windows: <Program Files>\Vicon\Tracker 3.10\SDK\Win64\Python
  For 32-bit Windows: <Program Files (x86)>\Vicon\Tracker 3.10\SDK\Win32\Python

To check your OS version, see Microsoft's FAQ .

Ensure that the version of Python you are using matches the installation: for 32-bit Python, the 32-bit installation is required, and correspondingly, the 64-bit version is required for 64-bit python.

The installer provides support for Python 2.7 and Python 3.

If you are not sure what version of Python you are using, note that the version is printed when you enter an interactive session, for example:

c:\>python
Python 2.7.15 (v2.7.15:ca079a3ea3, Apr 30 2018, 16:22:17) [MSC v.1500 32 bit (Intel)] on win32 
Type "help", "copyright", "credits" or "license" for more information. 
>>>

If you do not have Python installed, it may be downloaded from https://www.python.org/downloads/. Python 3 is recommended for new users, and if you do not have a specific requirement for Python 2.

Install the Tracker API package

You can install the Tracker API python package with the Python pip utility. This is included by default with current Python distributions.

For convenience, some batch files are included with the DataStream Python module. To install into your default Python distribution, run install_vicon_tracker_api.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:

<path to required python>\python -m pip install <Program Files>\Vicon\Tracker 3.10\SDK\Win64\Python\vicontrackerapi

To check the package is installed correctly, launch a Python command shell and import the vicontrackerapi module:

c:\python.exe 
>>> import vicontrackerapi

Create a client

The main Tracker client is the ViconTracker class in the vicontracker module. It is created as follows:

>>> from vicontrackerapi import vicontracker
>>> client = vicontracker.ViconTracker()

When you have a client, connect to the Tracker instance:

>>> client.connect()

When it is connected, you can call methods on the Tracker instance.

For example, to toggle the active status of an object, call:

>>> client.toggle_object_active( 'objectname' )

If there is an error, an exception of type ViconTrackerException is thrown. For example, if Tracker is not running:

>>> client.toggle_object_active( 'objectname' )
...
vicontrackerapi.vicontracker.ViconTrackerException: Unable to communicate with the host application.

To display a list of all available functions and documentation:

>>> help( vicontracker)

Example scripts

You can find example scripts showing the use of common API functions at:

<Program Files>\Vicon\Tracker 3.10\SDK\Win64\Python\example_scripts

All the scripts have documentation and take a --help option that gives details of the relevant arguments.

calibrate_camera.py

This script demonstrates how to use API functions to control the calibration process of starting and stopping the wand wave.

>>> calibrate_camera.py

capture_trial.py

This script shows how to set up a trial filename and capture live data.

>>> capture_trial.py --trial-name CapturedName

playback.py

This script shows how to use Tracker to perform offline data analysis, including loading and playing back a captured trial, and exporting the trial data to csv.

>>> playback.py --trial "path/to/my/x2d.x2d" --csv "path/to/my/csv.csv"