The PST SDK can be used to receive tracking results and images from a PST Tracker. Implementing the SDK is done by creating an instance of the pstech.pstsdk.tracker.Tracker class. This class provides access to settings on the PST Tracker and enables its user to receive tracking data.

Installation

The Python bindings can be used in two different ways:

Installing it using PyPi.
Running it directly using the source files.

PyPi Installation

The Pyhon bindings come with a setup.py that can be used to install the Python bindings using PyPi by running: pip install . --use-feature=in-tree-build from within the Development\python directory. This will install all Python API files, including dependencies, to the local PyPI packages directory. This way, the Python bindings can be used directly in all Python projects by simply importing it in your Python files: from pstech.pstsdk.tracker import Tracker. Updates can be installed using the same command, and the Python bindings can be uninstalled by running: pip uninstall PST-SDK-Python-API.

Using the Python API directly from source

To use the Python API directly from source, copy the entire Development\python\pstech directory to the location of your python file. The Python API requires the C and C++ distributables in order to communicate with the tracker. Create a directory called lib inside the copied pstech\pstsdk directory. The application searches for the pstsdk_c.dll in the pstech\pstsdk\lib directory. This shared library needs pstsdk_cpp.dll, nlopt.dll, Freeimage.dll, PocoFoundation.dll, PocoJSON.dll, and PocoNet.dll. These files can be found in the Development\Redist directory and should all be copied to pstech\pstsdk\lib. When installing the PST SDK using PyPi, the files are automatically placed in the correct directories. With all files in place the Python API can be imported in your python files by calling: from pstech.pstsdk.tracker import Tracker.

A list of files to use for specific use-cases can be found in the Redistribution section of the PST SDK overview.

Installing the camera plugins

When creating a pstech.pstsdk.tracker.Tracker object, an absolute path tot the configuration file of your PST Tracker has to be supplied as fourth argument. This configuration file can be found in Development\Redist and is one the following:

When running the software with the PST HD or PST Base HD, supply an absolute path to basler_ace as argument.
When running the software with the PST Pico, supply an absolute path to basler_dart as argument.

Next to this, the configuration file has to be slightly altered. The configuration file tells the PST SDK where it can find the necessary camera plugin by supplying a path to the required shared library, for example: $ORIGIN/baslercameraplugin.dll. Here, $ORIGIN is an absolute path to the directory of executable that loads the camera plugin. However for Python, this would point to python.exe and does not therefor not work. Change $ORIGIN to $XML_PATH and place the camera plugin in the same directory as the configuration file. $XML_PATH will be resolved as an absolute path to the directory of the configuration file and the PST SDK will be able to use this to find the required camera plugin.

For more information about the files needed by the PST Tracker, please see the Redistribution section of the PST SDK Overview.

Initialization

Most important runtime settings for the PST Tracker (e.g. setting frame rate and exposure, enabling/disabling tracking targets) can be controlled directly from the PST SDK. However, some steps that are required in order to start working with a new PST Tracker can currently not be performed using the SDK. The main steps are retrieving calibration information and defining tracking targets.

Calibration

Each time a PST Tracker is connected to a new computer, tracker calibration information needs to be provided. When the Tracker object is initialized it checks whether or not calibration information can be found in the specified configuration directory. If no calibration information can be found, a message specifying the download locations of the required files will be printed on the command line. It is also possible to call pstech.pstsdk.tracker.Tracker.get_uncalibrated_camera_urls() to receive a list of download URLs. A single PST Tracker requires two calibration files. The download URL of these files takes the following form: http://www.ps-tech.com/pstsw/calibrations/iris_####.cam, where #### is the identification number of each camera. When the PST Tracker that is going to be used is known on forehand, tracker calibration files can be provided by copying the right files from any medium into the configuration directory.

Tracking Target Setup

A new installation of the PST software will not contain any tracking targets. In order to start tracking, tracking targets need to be added to the model database. This can be done in three different ways.

Train a new tracking target model using the 'New device model' tab in the PST-Client.
Import an existing tracking target model using the 'Edit device model' tab in the PST-Client.
Copy an existing tracking target model database into the configuration directory.

When tracking target models are added using the PST-Client, a shared memory pipeline needs to be available to connect the PST-Client to the PST Tracker. Shared memory access can be enabled using the Python API by calling pstech.pstsdk.tracker.Tracker.enable_shared_memory(). Implementing this function allows the PST-Client to directly connect to an application. This way, tracking target model data will directly be saved to the model database file set in the application.

Alternatively, the PST-Server application can be started to allow the PST-Client to connect to the PST Tracker.

Note: On Windows, an application that implements shared memory access must be run with administrator privileges.; The PST Interface Service will not be available when the PST SDK has been installed.; The PST-Server and the application implementing the PST SDK can not be active at the same time, since only one application can connect to the PST Tracker at any given time.

The PST-Server will store its model database at C:\ProgramData\PS-Tech\PST Iris\models.db on Windows systems and ~/.pstiris/models.db on Linux systems. The application implementing the PST SDK can either use the same configuration directory and model database file, or the model database file can be copied to the configuration directory used by the application.

Usage

A clear example of how to use the PST SDK can be found in the Examples section of this documentation. The first step of connecting to the PST Tracker is creating an instance of the pstech.pstsdk.tracker.Tracker object. It is recommended to keep a global reference to the tracker object, since this will make it possible to ensure safe and clean termination of the PST Tracker on program exit. More on this topic will be discussed in the section Safe Tracker Termination.

Receiving tracker data

Tracking data can be received by creating a callback function and registering it as a listener to the tracker object, using pstech.pstsdk.tracker.Tracker.add_tracker_listener(). After enabling the required tracking targets using pstech.pstsdk.tracker.Tracker.set_target_status() and calling pstech.pstsdk.tracker.Tracker.start(), the callback function will start receiving tracking data in the form of pstech.pstsdk.trackerdata.TrackerData objects. These objects contain the time stamp of the recorded data, a recording id, a list of all detected 3D points that could not be matched to any of the activated tracking targets and a list of detected tracking targets and their poses.

While tracking is in progress, settings like the frame rate and exposure can be adjusted using their corresponding functions. It is also possible to change which tracking targets are active.

Note: When building an application based on the PST SDK, make sure all dependencies are copied to the binary directory of the application. For this, copy the files from the Development\Redist folder to the pstech\pstsdk\lib directory.

Filtering

Settings controlling the amount of filtering that is applied to the tracking data can be adjusted at all times. The filtering strength for the position and orientation can be adjusted independently using pstech.pstsdk.tracker.Tracker.set_position_filter() and pstech.pstsdk.tracker.Tracker.set_orientation_filter() respectively. Filtering using the DESP filter is enabled by default while the tremor filter is disabled by default.

Note: When shared memory is used to connect the PST-Client to the PST SDK, all filtering on the side of the PST SDK will be disabled since the PST-Client performs its own filtering. After closing the PST-Client, filtering should be re-enabled manually by calling pstech.pstsdk.tracker.Tracker.enable_filtering() and pstech.pstsdk.tracker.Tracker.enable_tremor_filter().

Camera Images

It is possible to retrieve image data from the cameras inside the PST Tracker. In order to do so, image transfer has to be enabled on the PST Tracker by calling pstech.pstsdk.tracker.Tracker.enable_image_transfer().

When image transfer has been enabled, images can be requested by calling pstech.pstsdk.tracker.Tracker.get_image(). Images are provided as a pstech.pstsdk.image.Image class containing the width and height of the images in pixels and a list containing arrays with pixels of the left and right camera image. Images are gray scale and provided as an array without memory alignment. When numpy is available, numpy is used and the image arrays will consist of values of type numpy.ubyte. When numpy is not available, the image arrays will consist of values of type ctypes.c_ubyte. More information about these type can be found on https://numpy.org/devdocs/user/basics.types.html and https://docs.python.org/3/library/ctypes.html#fundamental-data-types

In order to keep receiving images, a call to pstech.pstsdk.tracker.Tracker.get_image() has to be made at least every 4 seconds. For performance reasons, image transfer will be automatically disabled after no images have been requested for 4 seconds.

Note: Enabling image transfer when using a standard PST Iris or PST Base will reduce the PST Tracker's frame rate to 30 Hz for as long as images are being requested. When image transfer is disabled, either automatically or manually by calling pstech.pstsdk.tracker.Tracker.disable_image_transfer(), the frame rate of the PST Tracker will be reset to its original value.

Reference System

Tracking results are reported relative to a predefined right-handed Cartesian coordinate system, called the reference system. The default reference system is located at 1 meter from the PST Tracker. It is oriented such that the Z-axis points away from the PST tracker and the X-axis is parallel to the PST tracker. The reference system can be changed by the user and is stored as a transformation matrix in a file called otracker.ref located in the configuration directory. Setting the reference system can be done in several ways.

Use the pose of a tracking target on the 'Reference System' tab in the PST-Client.
Enter a relative or absolute reference system transformation on the 'Reference System' tab in the PST-Client.
Use the Tracker.set_reference() function to supply a relative or absolute reference system.
Copy an existing otracker.ref reference system file into the configuration directory.

The PST-Client can be used to set the reference system according to the methods described in section Tracking Target Setup.

Safe Tracker Termination

The PST Tracking systems are sensitive hardware. Therefore, it is important that the PST Tracker is correctly terminated every time an application connecting to the PST Tracker is closed. Failure to do so might result in unpredictable system behavior and could lead to computer crashes.

In order to safely terminate the connection to the PST Tracker, it is important that the pstech.pstsdk.tracker.shutdown() function is called before the application closes. The __exit__() of the pstech.pstsdk.tracker.Tracker class will call pstech.pstsdk.tracker.shutdown() automatically, but there are cases in which the destructor might not be called properly. This could happen in case of an application crash, or because the console running the application is closed.

The first cause can be mitigated in most cases by using a try-except block around the code. Be aware that a number of PST SDK functions can throw pstech.pstsdk.tracker.TrackerError type errors that might need to be caught.

The second case should be caught by implementing the console exit handler. On Windows, this is done by implementing the SetConsoleCtrlHandler() function from the win32api from pywin32. This can be installed using pip install pywin32 . The callback function registered as the console handler should call pstech.pstsdk.tracker.Tracker.shutdown().

Taking the above mentioned precautions should take care of most cases where disconnecting from the PST Tracker can result in unwanted behavior.