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.
The Python bindings can be used in two different ways:
The Python bindings come with a setup.py that can be used to install the Python bindings using PyPi by running: pip install . command from within the python directory. When the PST SDK has been installed through the PST Software Suite installer the python folder can be found in the Development folder. 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.
To use the Python API directly from source, copy the entire src\python\pstech directory to the location of your python file. When the PST SDK has been installed through the PST Software Suite installer the python can be found in the Development folder. 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 Redist directory and should all be copied to pstech\pstsdk\lib. When the PST SDK has been installed through the PST Software Suite installer the Redist folder can be found in the Development folder. 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.
When creating a pstech.pstsdk.tracker.Tracker object, an absolute path to the configuration file of your PST Tracker has to be supplied as fourth argument. This configuration file can be found in Redist and is one the following:
basler_ace as argument.basler_dart as argument.For more information about the files needed by the PST Tracker, please see the Redistribution section of the PST SDK Overview.
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.
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() or pstech.pstsdk.tracker.Tracker.get_connected_camera_info() 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. 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 pstech.pstsdk.tracker.Tracker.load_calibration_from_localpath(). 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.
The PST SDK provides a convenient way to verify whether local calibration files are up to date. By calling pstech.pstsdk.tracker.Tracker.get_connected_camera_info(), users can access verification data for each connected camera, including the local SHA1 values and the URLs to retrieve the corresponding server SHA1 values. Users can then compare the local SHA1 with the server SHA1 obtained from provided URLs to confirm that the local calibration files are synchronized with the latest version on the PS-tech server.
This verification mechanism helps ensure that calibration files are valid and up to date, preventing issues caused by outdated, missing, or unreadable calibration data. If mismatches are detected between local and server files, users can download the latest calibration files directly from the provided download URLs.
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 pstech.pstsdk.tracker.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.
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.
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.
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. To ensure proper shutdown of the PST Tracker when shutting down the application it is recommended to use the with statement to create the tracker object. More on this topic will be discussed in the section Safe Tracker Termination.
Tracking data can be received by implementing the pstech.pstsdk.tracker.Listener class and registering it as a listener to the instantiated pstech.pstsdk.tracker.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.
Redist folder to the pstech\pstsdk\lib directory. When the PST SDK has been installed through the PST Software Suite installer the Redist folder can be found in the Development folder.On selected PST Trackers it is possible to specify a Detection Region. Using pstech.pstsdk.tracker.Tracker.supports_detection_region_pruning() it can be determined if the currently connected PST Tracker supports Detection Regions.
The Detection Region can be set to OPTIMAL or FULL using pstech.pstsdk.tracker.Tracker.set_marker_detection_region(). Setting the Detection Region to OPTIMAL limits tracking target detection and tracking to a well-characterized working space with higher accuracy. When the Detection Region is set to FULL, tracking is performed in the full PST Tracker field of view, including areas that have not been fully characterized. On supported PST Trackers, the Detection Region will be set to OPTIMAL by default on startup unless changed.
Each detected pstech.pstsdk.point.Point has an associated pstech.pstsdk.point.ETrackingRegion which specifies in which Detection Region the marker was found. For each detected tracking target, the pstech.pstsdk.target.TargetPose.matched_points list specifies for each of the markers matched to the tracking target in which Detection Region it was detected. When the Detection Region is set to OPTIMAL, markers outside the OPTIMAL Detection Region will not be used to compute the pose of a tracking target.
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. When data filtering is part of the end-user application it is recommended to disable PST SDK filtering using pstech.pstsdk.tracker.Tracker.disable_filtering() to prevent double filtering and over smoothing the data.
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.
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.
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.
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 Python, the recommended way to safely terminate a Tracker is to use it inside a with block. The Tracker's exit() method will automatically call its internal cleanup function, removing registered listeners and releasing internal resources. This ensures deterministic cleanup of resources and registered listeners.
Registered listeners can also be removed explicitly using pstech.pstsdk.tracker.Tracker.remove_tracker_listener() if desired. However, if they are not removed manually, they are cleaned up when exiting the with block.
For cases where exceptions are raised inside the with block, cleanup still occurs automatically. Be aware that a number of PST SDK functions can raise pstech.pstsdk.tracker.TrackerError exceptions that may need to be caught using try/except blocks.
For abnormal termination scenarios, such as the console being closed or the application receiving Ctrl-C, a console exit handler can be implemented using the Windows API function SetConsoleCtrlHandler() from pywin32. The exit handler should signal the main program to stop and call pstech.pstsdk.tracker.Tracker.shutdown() to release native resources. Note that shutdown() only cleans up native resources and does not remove registered listeners; it is not a substitute for using the with block to ensure proper cleanup.
Taking the above mentioned precautions should take care of most cases where disconnecting from the PST Tracker can result in unwanted behavior.
1.15.0