The PST SDK can be used to receive tracking results and images from a PST Tracker. Implementing the SDK is done by making use of the PstTracker struct, the offered other structs and the offered C API functions. This way it provides access to settings on the PST Tracker and enables its users to receive tracking data.

Setup Windows

In order to start working with the PST SDK, create a Visual Studio (2015 or newer) project and add the include directory to the include path. When the PST SDK has been installed through the PST Software Suite installer the include folder can be found in the Development folder. Include the header file pstsdk_c.h in your project.

The application is dynamically linked using the pstsdk_c.lib import library and the pstsdk_c.dll shared library which can be found in the Redist directory. When the PST SDK has been installed through the PST Software Suite installer the Redist folder can be found in the Development folder. In order to run the application, copy all required binary dependencies from the Redist directory to the location of the application. A list of files to use for specific use-cases can be found in the Redistribution section of the PST SDK overview.

Setup Linux

In order to start working with the PST SDK, create a Makefile for your project comparable to the ones found in the examples directory. When the PST SDK has been installed through the PST Software Suite installer the examples can be found in the Development folder. Supply the linker with an rpath in order to point your executable to the location of the shared libraries (-Wl,-rpath=/opt/ps-tech/pst/Development/Redist or -Wl,-rpath=/opt/ps-tech/pst/Redist). Link your executable to libpstsdk_c using -lpstsdk_c. Copy the appropriate camera configuration XML file from the Redist directory to the working directory of the executable in order to be able to connect to the PST. It might be necessary to change the path on line 5 of the XML file to the directory containing the libbaslercameraplugin.so file.

Error Handling

Exceptions that occur in the underlying C++ API are handled internally and converted to error codes. Most of the C API functions return error codes in the form of an EPstErrorStatus enum value. Alternatively, the message of the last exception that occurred at any point in time can be retrieved using pst_alloc_and_get_last_error_message().

Initialization

Before using the PST Tracker for object tracking, it must be initialized with calibration and tracking target information. This information can be provided through the PST SDK directly, or using several alternative methods.

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 with one of the init functions pst_tracker_init(), pst_tracker_init1(), pst_tracker_init2(), pst_tracker_init3() or pst_tracker_init4(), 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 to the standard output, which is usually the command line. It is also possible to call pst_tracker_get_uncalibrated_camera_urls() or pst_tracker_get_connected_camera_urls() to receive an array 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. After downloading the calibration files and making them available on the local system, they can be uploaded to the configuration directory and loaded into the system using pst_tracker_load_calibration_from_local_path(). 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 manually.

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. When a tracking target model definition is available in the JSON format described in Appendix A of the PST Manual, it can be added to the model database using pst_tracker_import_json_model(). This function takes a JSON-formatted string describing the target model. After calling this function, the model will be available for tracking.

There are also a number of alternative ways to get tracking target models into the model database.

Copy an existing tracking target model database (models.db) into the configuration directory.
Train a new tracking target model using the 'New device model' tab in the PST-Client.
Import an existing tracking target model (JSON or PSM formatted) using the 'Edit device model' tab in the PST-Client.

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 C API by calling pst_sdk_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 PstTracker struct. Make sure to destroy the PstTracker struct using pst_tracker_destroy() when it is no longer required to ensure proper shutdown of the PST Tracker. 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 to the tracker object using pst_tracker_add_tracker_data_callback() or pst_tracker_add_tracker_callbacks(). The data from the PST tracker is pushed to the on_tracker_data callback function as PstTrackerData structs. Registered callback functions will start receiving the pushed PstTrackerData structs after the PST tracker is started with pst_tracker_start(). These structs 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 from the Redist directory to the binary directory of the application. When the PST SDK has been installed through the PST Software Suite installer the Redist folder can be found in the Development folder.

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 pst_tracker_set_position_filter() and pst_tracker_set_orientation_filter() respectively. Filtering using the DESP filter is enabled by default while the tremor filter is disabled by default. When data filtering is part of the end-user application it is recommended to disable PST SDK filtering using pst_tracker_disable_filtering() to prevent double filtering and over smoothing the data.

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 pst_tracker_enable_filtering() and pst_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 pst_tracker_enable_image_transfer().

When image transfer has been enabled, images can be requested by calling pst_tracker_get_pst_image(). Images are provided as a PstImage struct containing the width and height of the images in pixels and an array containing pointers to the first pixel of the left and right camera image. Images are gray scale and provided as a unsigned char array without memory alignment.

In order to keep receiving images, a call to pst_tracker_get_pst_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 pst_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 pst_tracker_set_reference() function to supply a relative or absolute reference system.
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.
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 either the pst_sdk_shutdown() or pst_tracker_destroy() function is called before the application closes. Sometimes, applications might not be properly closed because the console running the application is closed.

That should be caught by implementing the console exit handler. On Windows, this is done by implementing the SetConsoleCtrlHandler() function from the Windows API. The callback function registered as the console handler should call pst_sdk_shutdown().

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