Main PST SDK class implementing tracker communication. More...

#include <pst-sdk.h>

Public Member Functions
	Tracker (const std::string &path="", const std::string &config_file="server.cfg", const std::string &db_file="models.db", const std::string &grabber_name="default")
	Tracker constructor. More...

	~Tracker ()

std::vector< std::string >	GetUncalibratedCameraUrls (bool silent=false)
	Check if cameras of the connected PST Tracker are calibrated. More...

std::string	GetVersionInfo () const
	Get version information of the SDK. More...

std::string	GetConfigPath () const
	Get the path to the current configuration directory. More...

void	AddTrackerListener (Listener *listener)
	Add a listener for tracker data. More...

void	RemoveTrackerListener (Listener *listener)
	Remove a listener for tracker data. More...

void	Start ()
	Start tracking. More...

void	Pause ()
	Pause tracking. More...

void	Shutdown ()
	Shutdown the tracking system, stopping tracking. More...

StatusMessage	Systemcheck () const
	Check if the tracker is running correctly. More...

void	SetFramerate (double fps)
	Set tracker frame rate. More...

double	GetFramerate () const
	Get current frame rate. More...

std::vector< float >	GetSupportedFramerates () const
	Get vector of available frame rates. More...

void	SetExposure (float time)
	Set the exposure time. More...

float	GetExposure () const
	Get the current exposure time. More...

void	GetExposureRange (double &min, double &max) const
	Get the allowed exposure range. More...

void	EnableFiltering ()
	Enable filtering of the tracking results. More...

void	DisableFiltering ()
	Disable filtering of the tracking results. More...

void	SetPositionFilter (double value)
	Set the strength of the position filter. More...

void	SetOrientationFilter (double value)
	Set the strength of the orientation filter. More...

void	EnableTremorFilter ()
	Enable the tremor filter. More...

void	DisableTremorFilter ()
	Disable the tremor filter. More...

void	EnableImageTransfer ()
	Enable image transfer from the PST Tracker. More...

void	DisableImageTransfer ()
	Disable image transfer from the PST Tracker. More...

bool	GetImage (Image &image) const
	Retrieve images from the connected PST Tracker. More...

TargetStatuses	GetTargetList () const
	Get TargetStatuses object containing all tracking targets and their status. More...

Target	GetTargetInfo (const std::string &name) const
	Get basic tracking target information. More...

void	SetTargetStatus (const std::string &name, bool active)
	Set status of a single tracking Target. More...

bool	GetTargetStatus (const std::string &name) const
	Get status of a single tracking Target. More...

MarkerList	GetTargetMarkers (const std::string &name) const
	Get 3D marker positions of stored tracking Target. More...

void	SetTargetId (const std::string &name, int id)
	Set the id of the tracking target. More...

void	SetReference (const std::array< float, 16 > &reference, bool relative=false)
	Set the reference system in which tracking results are reported. More...

void	SetDefaultReference ()
	Reset the reference system to the default reference system. More...

std::array< float, 16 >	GetReference () const
	Gets the transformation matrix for the current reference system. More...

void	EnableSharedMemory ()
	Enable shared memory communication layer. More...

void	DisableSharedMemory ()
	Disable shared memory communication layer. More...

void	EnableRestServer (const std::string &server_address, const std::string &server_port, const int &eventStream_retry_timeout_ms=3000, const size_t &socket_size=65536)
	Enable a Rest Server using the HTTP protocol on a local area network. More...

void	DisableRestServer ()
	Disable the Rest server communication layer. More...

Detailed Description

This class implements the main PST SDK functionality. Examples on how to use this class and how to get data from the PST Tracker can be found in the Examples section.

Constructor & Destructor Documentation

◆ Tracker()

PSTech::pstsdk::Tracker::Tracker	(	const std::string &	path = `""`,
		const std::string &	config_file = `"server.cfg"`,
		const std::string &	db_file = `"models.db"`,
		const std::string &	grabber_name = `"default"`
	)

Construct Tracker object and initialize connected PST tracker. Camera calibration information is checked during initialization. When calibration files for the connected tracker can not be found, a message with download links will be printed to the command line.

Parameters

[in]	path	Path to the configuration directory to be used for storing camera calibrations, target database and configuration files. (default: "%PROGRAMDATA%\PS-Tech\PST Iris")
[in]	config_file	Name of the server configuration file. (default: "server.cfg")
[in]	db_file	Name of the tracking target database file. (default: "models.db")
[in]	grabber_name	Name of the grabber plugin to be used. Set to "default" to use auto-detect. (default: "default")

See also: Tracker::GetUncalibratedCameraUrls()

Exceptions

PSTech::TrackerException	Unable to initialize Tracker
PSTech::NotInitializedException	Tracker was not initialized correctly

◆ ~Tracker()

PSTech::pstsdk::Tracker::~Tracker ( )

Member Function Documentation

◆ AddTrackerListener()

void PSTech::pstsdk::Tracker::AddTrackerListener ( Listener * listener )

Register a listener to receive tracking information from the connected PST Tracker. The use of this method requires an implementation of the Listener class to be made.

Parameters

[in] listener A pointer to an implementation of the Listener class to function as a callback.

See also: Listener; TrackerData; Tracker::RemoveTrackerListener()

◆ DisableFiltering()

void PSTech::pstsdk::Tracker::DisableFiltering ( )

Switch off filtering of the tracking results using the double exponential-based prediction filter (DESP).

See also: Tracker::EnableFiltering(); Tracker::DisableTremorFilter()

◆ DisableImageTransfer()

void PSTech::pstsdk::Tracker::DisableImageTransfer ( )

Disable transferring grayscale image data from the PST Tracker. When using a standard PST Iris or PST Base tracker, the frame rate of the tracker will be restored to the frame rate that was set before enabling image transfer.

See also: Tracker::EnableImageTransfer()

◆ DisableRestServer()

void PSTech::pstsdk::Tracker::DisableRestServer ( )

Disable the Rest server communication layer. If a Rest server is running, the connections will be closed and the rest server will be destroyed. If no Rest server is running a call to Tracker::DisableRestServer() does nothing.

See also: Tracker::EnableRestServer()

◆ DisableSharedMemory()

void PSTech::pstsdk::Tracker::DisableSharedMemory ( )

Disable the shared memory-based communication layer. The PST-Client application will no longer be able to connect to the PST Tracker.

See also: Tracker::EnableSharedMemory()

◆ DisableTremorFilter()

void PSTech::pstsdk::Tracker::DisableTremorFilter ( )

Disables the tremor filter. The tremor filter will no longer be used to filter the estimated target pose.

See also: Tracker::EnableTremorFilter(); Tracker::DisableFiltering()

◆ EnableFiltering()

void PSTech::pstsdk::Tracker::EnableFiltering ( )

Switch on filtering of the tracker results using a double exponential-based prediction filter (DESP). This will result in smoother tracking with less noise. It can have a small impact on tracker accuracy.

Note: When the shared memory communication pipeline is used to connect the PST-Client application to the SDK, filtering will be disabled upon starting the PST-Client application. To prevent multiple filter passes, filtering should not be re-enabled until the PST-Client application is closed.

See also: Tracker::DisableFiltering(); Tracker::SetPositionFilter(); Tracker::SetOrientationFilter(); Tracker::EnableTremorFilter(); Tracker::EnableSharedMemory()

◆ EnableImageTransfer()

void PSTech::pstsdk::Tracker::EnableImageTransfer ( )

Enable transferring grayscale image data from the PST Tracker. After enabling image transfer, call Tracker::GetImage() in order to receive the captured images. When no calls are made to Tracker::GetImage() for more than 4 seconds, image transfer will be automatically disabled. Note that for the standard PST Iris and standard PST Base trackers, enabling image transfer will result in a reduced framerate of 30 fps. The frame rate will be restored to the original setting after image transfer is disabled.

See also: Tracker::GetImage(); Tracker::DisableImageTransfer()

◆ EnableRestServer()

void PSTech::pstsdk::Tracker::EnableRestServer	(	const std::string &	server_address,
		const std::string &	server_port,
		const int &	eventStream_retry_timeout_ms = `3000`,
		const size_t &	socket_size = `65536`
	)

Enable a Rest Server that uses the HTTP protocol to enable access to the PST Tracker over a local area network. If the server address is different from "localhost" or "127.0.0.1", or if port "80" is used, the server requires elevated access (administrator rights) to start properly. Parameters from the tracker can be accessed using GET requests. Tracking results and image can be streamed using an Event-stream based communication pipeline. The state of the tracker and parameters can be set through POST calls. If a Rest server is aleady running, calling Tracker::EnableRestServer() will terminate the current server and restart it with the new parameters. More information on how to use the Rest server can be found in the REST API documentation.

Parameters

[in]	server_address	The IP address on which the Rest server should be accessible.
[in]	server_port	The port number on which the Rest server should be accessible.
[in]	eventStream_retry_timeout_ms	Timeout in milliseconds before an eventstream attempt to reconnect to the server automatically.
[in]	socket_size	Size of the socket to chunk the data streams (tracking results and images).

See also: Tracker::DisableRestServer()

Exceptions

PSTech::HttpException The Rest server failed to initialize properly. A possible cause could be an invalid IP address or port number or running on a address different from "localhost" without using elevated access.

◆ EnableSharedMemory()

void PSTech::pstsdk::Tracker::EnableSharedMemory ( )

Enable a shared memory-based communication layer. Enabling shared memory will allow the PST-Client application to connect to the SDK. This will allow receiving tracking data and setting parameters using the PST-Client application. Note that a PST-Client that is connected in this way will not be updated when settings are changed through the SDK. This could cause instabilities in the PST software. It is recommended to only use this function when setting up a PST Tracker (e.g. adding tracking targets or retrieving calibration data). When using a tracker in normal operation, it is recommended to choose to use either the PST-Client application or the SDK and not mix usage.

Note: When using shared memory the application needs to have elevated access (run as Administrator). When running without elevated access the PST-Client will not be able to connect.; When the shared memory communication pipeline is used to connect the PST-Client application to the SDK, filtering will be disabled upon starting the PST-Client application. To prevent multiple filter passes, filtering should not be re-enabled until the PST-Client application is closed.

See also: Tracker::DisableSharedMemory(); Tracker::EnableFiltering(); Tracker::EnableTremorFilter()

◆ EnableTremorFilter()

void PSTech::pstsdk::Tracker::EnableTremorFilter ( )

Enables the tremor filter. This filter greatly reduces the noise levels of the estimated target pose. However, using the filter introduces latency to the tracking results received and lowers tracking accuracy. This filter is mainly useful when using the PST Tracker in an interaction-type setting. When the PST Tracker is used for measurement purposes, enabling the tremor filter is not recommended.

Note: When the shared memory communication pipeline is used to connect the PST-Client application to the SDK, filtering will be disabled upon starting the PST-Client application. To prevent multiple filter passes, filtering should not be re-enabled until the PST-Client application is closed.

See also: Tracker::DisableTremorFilter(); Tracker::EnableFiltering()

◆ GetConfigPath()

std::string PSTech::pstsdk::Tracker::GetConfigPath ( ) const

Retrieves the full path to the configuration directory currently being used by the PST Tracker. The default path is "%PROGRAMDATA%\PS-Tech\PST Iris". The configuration directory contains the target model database, server configuration, reference file and tracker calibration information.

Returns: The full path to the configuration directory.

◆ GetExposure()

float PSTech::pstsdk::Tracker::GetExposure ( ) const

Get the current exposure time as set on the PST Tracker.

Returns: The current exposure time in seconds.

See also: Tracker::SetExposure()

◆ GetExposureRange()

void PSTech::pstsdk::Tracker::GetExposureRange	(	double &	min,
		double &	max
	)		const

Get the minimum and maximum exposure value that can be set with the current frame rate. The maximum exposure value differs for different frame rates and PST Trackers. In general, lower frame rates allow for higher exposures and higher frame rates have a lower maximum exposure value. After changing the frame rate it is advised to check the currently allowed range before changing exposure values.

Parameters

[out]	min	The minimum exposure value that can be set.
[out]	max	The maximum exposure value that can be set.

See also: Tracker::GetExposure(); Tracker::SetExposure(); Tracker::SetFramerate()

◆ GetFramerate()

double PSTech::pstsdk::Tracker::GetFramerate ( ) const

Get the current frame rate as set on the PST Tracker.

Returns: Current frame rate in frames per second (fps).

See also: Tracker::SetFramerate(); Tracker::GetSupportedFramerates()

◆ GetImage()

bool PSTech::pstsdk::Tracker::GetImage ( Image & image ) const

Retrieve images from the PST Tracker when image transfer has been enabled. When image transfer has not been enabled by calling Tracker::EnableImageTransfer() before calling this method, Image.image will be an empty vector. Note that image transfer will automatically be disabled when no call to this method is made for 4 seconds.

Parameters

[out] image The image information retrieved from the PST Tracker.

Returns: Success of the operation as a boolean.

See also: Image; Tracker::EnableImageTransfer()

◆ GetReference()

std::array<float, 16> PSTech::pstsdk::Tracker::GetReference ( ) const

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 transformation matrix defining the reference system is a row-major 4x4 homogeneous transformation matrix.

Returns: The transformation matrix for the current reference system.

See also: Tracker::SetReference(); Tracker::SetDefaultReference()

◆ GetSupportedFramerates()

std::vector<float> PSTech::pstsdk::Tracker::GetSupportedFramerates ( ) const

Get a vector containing all frame rates that are available for the currently connected PST Tracker. The range of available frame rates differs for different types of PST Trackers. When using Tracker::SetFramerate() to set a new frame rate, the frame rate of the PST Tracker will be set to the value provided by this function nearest to the value supplied to Tracker::SetFramerate().

Returns: A vector of available frame rates.

See also: Tracker::SetFramerate(); Tracker::GetFramerate()

◆ GetTargetInfo()

Target PSTech::pstsdk::Tracker::GetTargetInfo ( const std::string & name ) const

Retrieves the name, uuid and id for the requested tracking target.

Parameters

[in] name The name of the tracking target.

Returns: Target object containing the basic target information.

See also: Target

Exceptions

PSTech::NotFoundException Target name could not be found.

◆ GetTargetList()

TargetStatuses PSTech::pstsdk::Tracker::GetTargetList ( ) const

Retrieves the list of all tracking targets defined in the tracking target database and returns them as a TargetStatuses object.

Returns: TargetStatuses object containing the information and status of all available tracking Targets.

See also: TargetStatus; TargetStatuses; Tracker::SetTargetStatus(); Tracker::GetTargetStatus()

◆ GetTargetMarkers()

MarkerList PSTech::pstsdk::Tracker::GetTargetMarkers ( const std::string & name ) const

Gets a list of the 3D positions of the markers making up the specified tracking Target. The returned positions are relative to the tracking Target origin.

Parameters

[in] name Name of the tracking Target to get the marker positions of.

Returns: A list of 3D marker positions.

See also: MarkerList; Target

Exceptions

PSTech::NotFoundException Target name could not be found.

◆ GetTargetStatus()

bool PSTech::pstsdk::Tracker::GetTargetStatus ( const std::string & name ) const

Retrieves the status of a single tracking Target. Tracking targets can be either active (true) or inactive (false).

Parameters

[in] name The name of the tracking Target to get the status of.

Returns: Status of the tracking Target.

See also: TargetStatus; Tracker::SetTargetStatus(); Tracker::GetTargetList()

Exceptions

PSTech::NotFoundException Target name could not be found.

◆ GetUncalibratedCameraUrls()

std::vector<std::string> PSTech::pstsdk::Tracker::GetUncalibratedCameraUrls ( bool silent = false )

Check for calibration information of the cameras of the connected PST Tracker. When not all calibration information can be retrieved, download urls for the uncalibrated cameras will be returned. Furthermore, a message will be shown at the command line specifying which files are missing and where they can be downloaded.

Parameters

[in] silent Set to true in order to disable printing of missing calibration information. (default: false)

Returns: Vector of URLs specifying the download location of calibration information for uncalibrated cameras. The size of the vector is the number of uncalibrated cameras.

◆ GetVersionInfo()

std::string PSTech::pstsdk::Tracker::GetVersionInfo ( ) const

Retrieves version information of the PST Server used by the SDK.

Returns: The version number of the PST Server.

◆ Pause()

void PSTech::pstsdk::Tracker::Pause ( )

Pause the tracking system, stop producing tracking results and enter low-power mode. Tracking can be resumed with a subsequent call to Tracker::Start().

See also: Tracker::Start()

◆ RemoveTrackerListener()

void PSTech::pstsdk::Tracker::RemoveTrackerListener ( Listener * listener )

Remove a listener receiving tracking information from the connected PST Tracker.

Parameters

[in] listener A pointer to an implementation of the Listener class which has previously been added using Tracker::AddTrackerListener().

See also: Listener; Tracker::AddTrackerListener()

◆ SetDefaultReference()

void PSTech::pstsdk::Tracker::SetDefaultReference ( )

Resets the currently set reference system to the default reference system. The default system is defined by a 4x4 identity matrix. This places the origin of the reference system 1 meter away 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.

See also: Tracker::SetReference(); Tracker::GetReference()

◆ SetExposure()

void PSTech::pstsdk::Tracker::SetExposure ( float time )

Set the PST Tracker exposure time to the supplied time. This adjusts both the shutter speed of the PST Tracker and the time the IR illumination panel will be turned on.

Parameters

[in] time Exposure time in seconds.

See also: Tracker::GetExposure(); Tracker::GetExposureRange()

Exceptions

PSTech::OutOfRangeException	The value supplied is not within the allowed range.
PSTech::NotSupportedException	Exposure could not be set on the Tracker.

◆ SetFramerate()

void PSTech::pstsdk::Tracker::SetFramerate ( double fps )

Set the PST Tracker frame rate to the value available for the connected PST Tracker nearest to the supplied value.

Parameters

[in] fps The new frame rate to be set.

See also: Tracker::GetFramerate(); Tracker::GetSupportedFramerates()

Exceptions

PSTech::NotSupportedException Supplied frame rate could not be set on the Tracker.

◆ SetOrientationFilter()

void PSTech::pstsdk::Tracker::SetOrientationFilter ( double value )

Set the strength of the double exponential-based prediction filter (DESP) that filters the estimated orientation of the tracked tracking targets. The supplied filtering value should be between 0 (no filtering) and 0.99 (maximum filtering).

Parameters

[in] value Filtering strength to be used in range [0, 0.99]

See also: Tracker::EnableFiltering(); Tracker::SetPositionFilter()

◆ SetPositionFilter()

void PSTech::pstsdk::Tracker::SetPositionFilter ( double value )

Set the strength of the double exponential-based prediction filter (DESP) that filters the estimated positions of the tracked tracking targets. The supplied filtering value should be between 0 (no filtering) and 0.99 (maximum filtering).

Parameters

[in] value Filtering strength to be used in range [0, 0.99]

See also: Tracker::EnableFiltering(); Tracker::SetOrientationFilter()

◆ SetReference()

void PSTech::pstsdk::Tracker::SetReference	(	const std::array< float, 16 > &	reference,
		bool	relative = `false`
	)

Sets the reference system relative to which tracking results are reported. The reference system is defined by a homogeneous transformation matrix (a row-major 4x4 matrix) representing a right-handed Cartesian coordinate system. The function checks if a valid, orthogonal transformation matrix has been supplied. When an invalid matrix has been supplied, it will not be applied. To check if the function was successful, please use Tracker::GetReference() and compare the result. As an optional parameter, the reference system can be set relative to the current reference system. When this option is used, the current reference system is transformed using the supplied transformation matrix. Otherwise, the current reference system is replaced by the supplied reference system.

Parameters

[in]	reference	The transformation matrix for the new reference system.
[in]	relative	When set to true, the current transformation matrix is transformed using the supplied transformation matrix.

See also: Tracker::GetReference(); Tracker::SetDefaultReference()

◆ SetTargetId()

void PSTech::pstsdk::Tracker::SetTargetId	(	const std::string &	name,
		int	id
	)

This function changes the id of the tracking target. This id is mainly used when connecting to the PST Tracker through VRPN.

Parameters

[in]	name	The name of the tracking target to change the id of.
[in]	id	The new id of the tracking target.

See also: Target

Exceptions

PSTech::NotFoundException Target name could not be found.

◆ SetTargetStatus()

void PSTech::pstsdk::Tracker::SetTargetStatus	(	const std::string &	name,
		bool	active
	)

Sets the status of a single tracking Target to active (true) or inactive (false).

Parameters

[in]	name	The name of the tracking Target to set the status of.
[in]	active	New status of the tracking Target.

See also: TargetStatus; Tracker::GetTargetStatus(); Tracker::GetTargetList()

Exceptions

PSTech::NotFoundException Target name could not be found.

◆ Shutdown()

void PSTech::pstsdk::Tracker::Shutdown ( )

Fully shutdown the tracking system, disconnecting from the PST Tracker and rendering the Tracker object useless. When the shared memory interface has been enabled it will be disabled as well. In order to restart the tracker, a new instance of the Tracker class has to be created.

See also: Tracker::Tracker(); Tracker::DisableSharedMemory()

◆ Start()

void PSTech::pstsdk::Tracker::Start ( )

Start the tracking system and produce tracking results.

See also: Tracker::Pause()

◆ Systemcheck()

StatusMessage PSTech::pstsdk::Tracker::Systemcheck ( ) const

Perform a system check, checking if the PST Tracker has been initialized correctly and if the system is running properly. In order to get continuous feedback on the status of the PST Tracker it is recommended to implement regular polling of this function. This way, issues that will not cause the software to crash (e.g. a camera disconnect) can be handled.

Returns: Current system status code as StatusMessage enumeration member.

See also: StatusMessage

The documentation for this class was generated from the following file:

C:/CI/builds/c149454a/0/ps-tech/pst-installer/pstsdk/include/pst-sdk.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Tracker()

◆ ~Tracker()

Member Function Documentation

◆ AddTrackerListener()

◆ DisableFiltering()

◆ DisableImageTransfer()

◆ DisableRestServer()

◆ DisableSharedMemory()

◆ DisableTremorFilter()

◆ EnableFiltering()

◆ EnableImageTransfer()

◆ EnableRestServer()

◆ EnableSharedMemory()

◆ EnableTremorFilter()

◆ GetConfigPath()

◆ GetExposure()

◆ GetExposureRange()

◆ GetFramerate()

◆ GetImage()

◆ GetReference()

◆ GetSupportedFramerates()

◆ GetTargetInfo()

◆ GetTargetList()

◆ GetTargetMarkers()

◆ GetTargetStatus()

◆ GetUncalibratedCameraUrls()

◆ GetVersionInfo()

◆ Pause()

◆ RemoveTrackerListener()

◆ SetDefaultReference()

◆ SetExposure()

◆ SetFramerate()

◆ SetOrientationFilter()

◆ SetPositionFilter()

◆ SetReference()

◆ SetTargetId()

◆ SetTargetStatus()

◆ Shutdown()

◆ Start()

◆ Systemcheck()