This library defines the C API for the PST. Applications implementing this API get direct access to the PST to receive tracking data and set tracker parameters. Using this library, it is also possible to initialize a shared memory communication pipeline to connect to the PST Client application and initialize a REST server for HTTP-based communication. More...

Data Structures
struct	PstImage
	Images retrieved from the tracker. More...

struct	PstTarget
	Tracking target information. More...

struct	PstTargetStatus
	Tracking target status. More...

struct	PstPoint
	Estimated 3D marker location. More...

struct	PstTargetPose
	Estimated tracking target pose. More...

struct	PstTargetMarker
	3D marker positions of a single marker of a tracking Target. More...

struct	PstTargetMarkers
	Collection struct for PstTargetMarker. More...

struct	PstTrackerData
	Tracking information retrieved from tracker. More...

struct	PstTracker
	Main PST SDK struct for tracker communication. More...

struct	PstCameraURLs
	Struct to request urls for calibration information. More...

Enumerations
enum	EPstErrorStatus { PST_ERROR_STATUS_OK = 0, PST_ERROR_STATUS_TRACKER_ERROR = 1, PST_ERROR_STATUS_NOT_INITIALIZED_ERROR = 2, PST_ERROR_STATUS_NOT_SUPPORTED_ERROR = 3, PST_ERROR_STATUS_OUT_OF_RANGE_ERROR = 4, PST_ERROR_STATUS_NOT_FOUND_ERROR = 5, PST_ERROR_STATUS_HTTP_ERROR = 6, PST_ERROR_STATUS_FAILED_TO_ALLOCATE_MEMORY_ERROR = 7, PST_ERROR_STATUS_NULLPTR_ERROR = 8, PST_ERROR_STATUS_IMAGE_RETRIEVAL_FAILED_ERROR = 9, PST_ERROR_STATUS_INVALID_DATA_ERROR = 10, PST_ERROR_STATUS_ALREADY_EXISTS_ERROR = 11, PST_ERROR_STATUS_JSON_PARSING_ERROR = 12 }
	Tracker error messages enum class. More...

enum	EPstStatusMessage { PST_STATUSMESSAGE_OK = 0, PST_STATUSMESSAGE_NOT_INITIALIZED = 1, PST_STATUSMESSAGE_DISCONNECTED = 2, PST_STATUSMESSAGE_ERR_GENERAL = 3, PST_STATUSMESSAGE_ERR_TIMEOUT = 4, PST_STATUSMESSAGE_ERR_NOCAMS_FOUND = 5, PST_STATUSMESSAGE_ERR_NOTENOUGHTCAMS_FOUND = 6, PST_STATUSMESSAGE_ERR_INITERROR = 7, PST_STATUSMESSAGE_ERR_CANNOT_START_CAMS = 8, PST_STATUSMESSAGE_ERR_CANNOT_SETUP_CAMS = 9, PST_STATUSMESSAGE_ERR_NULL_TRACKER_HANDLE = 10, PST_STATUSMESSAGE_ERR_UNKNOWN_STATUS = 11 }
	Tracker status messages enum class. More...

enum	EPstTrackerMode { PST_MODE_LOWPOWER = 0, PST_MODE_SETUP = 1, PST_MODE_TRACKING = 2, PST_MODE_TRAINING = 3, PST_MODE_DISCONNECT = 4, PST_MODE_RECONNECT = 5, PST_MODE_UNKNOWN = 6 }
	Tracker mode enum class. More...

Functions
EPstErrorStatus	pst_alloc_and_get_last_error_message (char **cstring)
	This function returns the last error message that was recorded by the system. More...

EPstErrorStatus	pst_tracker_init (PstTracker *ctracker)
	This function initializes the tracker object. More...

EPstErrorStatus	pst_tracker_init1 (PstTracker *ctracker, const char path[])
	This function initializes the tracker object. More...

EPstErrorStatus	pst_tracker_init2 (PstTracker *ctracker, const char path[], const char config_file[])
	This function initializes the tracker object. More...

EPstErrorStatus	pst_tracker_init3 (PstTracker *ctracker, const char path[], const char config_file[], const char db_file[])
	This function initializes the tracker object. More...

EPstErrorStatus	pst_tracker_init4 (PstTracker *ctracker, const char path[], const char config_file[], const char db_file[], const char grabber_name[])
	This function initializes the tracker object. More...

void	pst_tracker_destroy (PstTracker *ctracker)

EPstErrorStatus	pst_tracker_load_calibration_from_local_path (const PstTracker *ctracker, const char path[])
	Load calibration information from a given path. More...

EPstErrorStatus	pst_tracker_get_connected_camera_urls (const PstTracker ctracker, bool silent, PstCameraURLs urls)
	Get URLs of the calibration information for the connected PST Tracker. More...

EPstErrorStatus	pst_tracker_get_uncalibrated_camera_urls (const PstTracker ctracker, bool silent, PstCameraURLs urls)
	Check if cameras of the connected PST Tracker are calibrated. More...

EPstErrorStatus	pst_tracker_alloc_and_get_version_info (const PstTracker ctracker, char *version_string)
	Get version information of the SDK. More...

EPstErrorStatus	pst_tracker_alloc_and_get_config_path (const PstTracker ctracker, char *config_path)
	Get the path to the current configuration directory. More...

EPstErrorStatus	pst_tracker_get_single_measurement (const PstTracker ctracker, PstTrackerData cdata)
	Retrieve the latest PstTrackerData available from the connected PstTracker. More...

EPstErrorStatus	pst_tracker_add_tracker_data_callback (PstTracker ctracker, void(on_tracker_data)(const PstTrackerData *, EPstErrorStatus))
	Add a callback function for tracker data. More...

EPstErrorStatus	pst_tracker_add_tracker_mode_callback (PstTracker ctracker, void(on_tracker_mode)(EPstTrackerMode))
	Add a callback function for mode changes. More...

EPstErrorStatus	pst_tracker_add_tracker_callbacks (PstTracker ctracker, void(on_tracker_data)(const PstTrackerData , EPstErrorStatus), void(on_tracker_mode)(EPstTrackerMode))
	Add callback functions for tracker data and mode changes. More...

EPstErrorStatus	pst_tracker_remove_tracker_data_callback (PstTracker ctracker, void(on_tracker_data)(const PstTrackerData *, EPstErrorStatus))
	Remove a callback function for tracker data. More...

EPstErrorStatus	pst_tracker_remove_tracker_mode_callback (PstTracker ctracker, void(on_tracker_mode)(EPstTrackerMode))
	Remove a callback function for mode changes. More...

EPstErrorStatus	pst_tracker_remove_tracker_callbacks (PstTracker ctracker, void(on_tracker_data)(const PstTrackerData , EPstErrorStatus), void(on_tracker_mode)(EPstTrackerMode))
	Remove callback functions for tracker data and mode changes. More...

EPstErrorStatus	pst_tracker_start (PstTracker *ctracker)
	Start tracking. More...

EPstErrorStatus	pst_tracker_pause (PstTracker *ctracker)
	Pause tracking. More...

EPstStatusMessage	pst_tracker_system_check (const PstTracker *ctracker)
	Check if the tracker is running correctly. More...

EPstErrorStatus	pst_tracker_set_framerate (PstTracker *ctracker, double fps)
	Set tracker frame rate. More...

EPstErrorStatus	pst_tracker_get_framerate (const PstTracker ctracker, double fps)
	Get current frame rate. More...

EPstErrorStatus	pst_tracker_alloc_and_get_supported_framerates (const PstTracker ctracker, float framerates, size_t number_of_framerates)
	Get an array of available frame rates. More...

EPstErrorStatus	pst_tracker_set_exposure (PstTracker *ctracker, double time)
	Set the exposure time. More...

EPstErrorStatus	pst_tracker_get_exposure (const PstTracker ctracker, double exposure)
	Get the current exposure time. More...

EPstErrorStatus	pst_tracker_get_exposure_range (const PstTracker ctracker, double min, double *max)
	Get the allowed exposure range. More...

EPstErrorStatus	pst_tracker_enable_filtering (PstTracker *ctracker)
	Enable filtering of the tracking results. More...

EPstErrorStatus	pst_tracker_disable_filtering (PstTracker *ctracker)
	Disable filtering of the tracking results. More...

EPstErrorStatus	pst_tracker_set_position_filter (PstTracker *ctracker, double value)
	Set the strength of the position filter. More...

EPstErrorStatus	pst_tracker_set_orientation_filter (PstTracker *ctracker, double value)
	Set the strength of the orientation filter. More...

EPstErrorStatus	pst_tracker_enable_tremor_filter (PstTracker *ctracker)
	Enable the tremor filter. More...

EPstErrorStatus	pst_tracker_disable_tremor_filter (PstTracker *ctracker)
	Disable the tremor filter. More...

EPstErrorStatus	pst_tracker_enable_image_transfer (PstTracker *ctracker)
	Enable image transfer from the PST Tracker. More...

EPstErrorStatus	pst_tracker_disable_image_transfer (PstTracker *ctracker)
	Disable image transfer from the PST Tracker. More...

EPstErrorStatus	pst_tracker_get_pst_image (const PstTracker ctracker, PstImage image)
	Retrieve images from the connected PST Tracker. More...

EPstErrorStatus	pst_tracker_alloc_and_get_target_list (const PstTracker ctracker, PstTargetStatus statuses, size_t number_of_statuses)
	Get TargetStatuses object containing all tracking targets and their status. More...

EPstErrorStatus	pst_tracker_get_target_info (const PstTracker ctracker, const char name, PstTarget *target)
	Get basic tracking target information. More...

EPstErrorStatus	pst_tracker_set_target_status (PstTracker ctracker, const char name, bool set_active)
	Set status of a single tracking Target. More...

EPstErrorStatus	pst_tracker_get_target_status (const PstTracker ctracker, const char name, bool *status)
	Get status of a single tracking Target. More...

EPstErrorStatus	pst_tracker_get_target_markers (const PstTracker ctracker, const char name, PstTargetMarkers *marker_list)
	Get 3D marker positions of stored tracking target. More...

EPstErrorStatus	pst_tracker_set_target_id (PstTracker ctracker, const char name, int id)
	Set the id of the tracking target. More...

EPstErrorStatus	pst_tracker_set_reference (PstTracker *ctracker, const float creference[16], bool relative)
	Set the reference system in which tracking results are reported. More...

EPstErrorStatus	pst_tracker_set_default_reference (PstTracker *ctracker)
	Reset the reference system to the default reference system. More...

EPstErrorStatus	pst_tracker_get_reference (const PstTracker *ctracker, float creference[16])
	Gets the transformation matrix for the current reference system. More...

EPstErrorStatus	pst_sdk_enable_shared_memory ()
	Enable shared memory communication layer. More...

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

EPstErrorStatus	pst_sdk_enable_rest_server (const char server_address, const char server_port, int event_stream_retry_timeout)
	Enable a REST Server using the HTTP protocol on a local area network. More...

void	pst_sdk_disable_rest_server ()
	Disable the REST server communication layer. More...

EPstErrorStatus	pst_tracker_remove_target_model (PstTracker ctracker, const char model_name)
	Remove a tracking target model from the target model database. More...

void	pst_camera_urls_init (PstCameraURLs *urls)

void	pst_camera_urls_destroy (PstCameraURLs *urls)

void	pst_trackerdata_init (PstTrackerData *cdata)

void	pst_trackerdata_destroy (PstTrackerData *cdata)

void	pst_image_init (PstImage *image)

void	pst_image_destroy (PstImage *image)

void	pst_target_markers_init (PstTargetMarkers *marker_list)

void	pst_target_markers_destroy (PstTargetMarkers *marker_list)

const char *	pst_sdk_get_version ()
	Retrieve the SDK version string. More...

void	pst_sdk_enable_logging ()
	Write plug-in status information to the standard C output stream stderr. More...

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

void	pst_free (void *data)
	Free data allocated by the PST SDK. More...

EPstErrorStatus	pst_tracker_import_json_model (const PstTracker ctracker, const char json_model)
	Import a tracking target model into the target model database. More...

EPstErrorStatus	pst_tracker_export_json_model (const PstTracker ctracker, const char model_name, char **model_string)
	Export a tracking target model as a JSON-formatted string. More...

Detailed Description

Some functions allocate memory to store objects. These functions will contain alloc or init in their names. As is conventional an alloc should always be paired with a free. If a corresponding free function is defined in this API, this function should be used to release memory, otherwise a normal free should be sufficient. Likewise every init should be paired with a destroy.

Enumeration Type Documentation

◆ EPstErrorStatus

enum EPstErrorStatus

This enum class lists all error states that can be reported by the tracker.

Enumerator
PST_ERROR_STATUS_OK	No error.
PST_ERROR_STATUS_TRACKER_ERROR	General tracker error.
PST_ERROR_STATUS_NOT_INITIALIZED_ERROR	A call was made to an uninitialized tracker.
PST_ERROR_STATUS_NOT_SUPPORTED_ERROR	The requested functionality is not supported by this tracker.
PST_ERROR_STATUS_OUT_OF_RANGE_ERROR	The supplied value is outside of the accepted range.
PST_ERROR_STATUS_NOT_FOUND_ERROR	The requested data could not be found.
PST_ERROR_STATUS_HTTP_ERROR	An HTTP error was thrown by the REST server.
PST_ERROR_STATUS_FAILED_TO_ALLOCATE_MEMORY_ERROR	Failed to allocate memory.
PST_ERROR_STATUS_NULLPTR_ERROR	The supplied tracker was a null pointer.
PST_ERROR_STATUS_IMAGE_RETRIEVAL_FAILED_ERROR	Image retrieval failed.
PST_ERROR_STATUS_INVALID_DATA_ERROR	Data provided did not match the requirements.
PST_ERROR_STATUS_ALREADY_EXISTS_ERROR	The provided object already exists.
PST_ERROR_STATUS_JSON_PARSING_ERROR	An error occurred while processing JSON information.

◆ EPstStatusMessage

enum EPstStatusMessage

This enum class lists all status messages that can be reported by the tracker.

See also: pst_tracker_system_check()

Enumerator
PST_STATUSMESSAGE_OK	The system is running OK.
PST_STATUSMESSAGE_NOT_INITIALIZED	Tracker failed to initialize correctly.
PST_STATUSMESSAGE_DISCONNECTED	The grabber has been disconnected.
PST_STATUSMESSAGE_ERR_GENERAL	Unspecified grabber error.
PST_STATUSMESSAGE_ERR_TIMEOUT	Grabber timeout error.
PST_STATUSMESSAGE_ERR_NOCAMS_FOUND	Grabber could not detect any cameras.
PST_STATUSMESSAGE_ERR_NOTENOUGHTCAMS_FOUND	Grabber could not detect sufficient cameras.
PST_STATUSMESSAGE_ERR_INITERROR	Grabber did not initialize correctly.
PST_STATUSMESSAGE_ERR_CANNOT_START_CAMS	Grabber could not start cameras.
PST_STATUSMESSAGE_ERR_CANNOT_SETUP_CAMS	Grabber failed setting up cameras.
PST_STATUSMESSAGE_ERR_NULL_TRACKER_HANDLE	Tracker not created or freed.
PST_STATUSMESSAGE_ERR_UNKNOWN_STATUS	Unknown status message.

◆ EPstTrackerMode

enum EPstTrackerMode

This enum class lists all the possible modes that the tracker can be in.

See also: pst_tracker_add_tracker_mode_callback(); pst_tracker_add_tracker_callbacks(); pst_tracker_remove_tracker_mode_callback(); pst_tracker_remove_tracker_callbacks()

Enumerator
PST_MODE_LOWPOWER	Tracker is in lowpower mode waiting for activity to resume
PST_MODE_SETUP	Tracker is in setup mode
PST_MODE_TRACKING	Tracker is in tracking mode
PST_MODE_TRAINING	Tracker is in training mode
PST_MODE_DISCONNECT	Tracker has been disconnected
PST_MODE_RECONNECT	Tracker has been reconnected
PST_MODE_UNKNOWN	Tracker is in an unknown state

Function Documentation

◆ pst_alloc_and_get_last_error_message()

EPstErrorStatus pst_alloc_and_get_last_error_message ( char ** cstring )

This function returns the last error message that was recorded by the system. It will try to allocate memory for and copy the error message in a pointer returned in cstring. It is important that cstring does not point to allocated memory, otherwise a memory leak is introduced. Since memory is allocated for *cstring, ensure that it is freed using pst_free() when it is no longer needed.

Parameters

[out] cstring - Pointer to a pointer to a memory location where the error message is allocated.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_FAILED_TO_ALLOCATE_MEMORY_ERROR.

See also: pst_free()

Examples: exposure.c, images.c, listener.c, minimal.c, reference.c, restserver.c, sharedmemory.c, and trackingtarget.c.

◆ pst_camera_urls_destroy()

void pst_camera_urls_destroy ( PstCameraURLs * urls )

Destroys PstCameraURLs.

Parameters

[in] urls Object to be destroyed.

Examples: listener.c.

◆ pst_camera_urls_init()

void pst_camera_urls_init ( PstCameraURLs * urls )

Initializes PstCameraURLs.

Parameters

[in] urls Object to be initialized.

Examples: listener.c.

◆ pst_free()

void pst_free ( void * data )

This function should be called on any data that was allocated by the PST SDK and is no longer needed by the user. Use this function instead of the general free() function to prevent memory issues.

Parameters

[in] data Pointer to the memory to be freed.

See also: pst_alloc_and_get_last_error_message(); pst_tracker_alloc_and_get_version_info(); pst_tracker_alloc_and_get_config_path(); pst_tracker_alloc_and_get_supported_framerates(); pst_tracker_alloc_and_get_target_list()

Examples: exposure.c, images.c, listener.c, minimal.c, reference.c, restserver.c, sharedmemory.c, and trackingtarget.c.

◆ pst_image_destroy()

void pst_image_destroy ( PstImage * image )

Destroy function for PstImage

Examples: images.c.

◆ pst_image_init()

void pst_image_init ( PstImage * image )

Initialization function for PstImage

Parameters

[out] image Empty image object to be initialized.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_image_destroy(); pst_tracker_get_pst_image()

Examples: images.c.

◆ pst_sdk_disable_rest_server()

void pst_sdk_disable_rest_server ( )

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 pst_sdk_disable_rest_server() does nothing.

See also: pst_sdk_enable_rest_server()

Examples: restserver.c.

◆ pst_sdk_disable_shared_memory()

void pst_sdk_disable_shared_memory ( )

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

See also: pst_sdk_enable_shared_memory()

Examples: sharedmemory.c.

◆ pst_sdk_enable_logging()

void pst_sdk_enable_logging ( )

Provides information about the status of the tracker plug-in. Information is written to the standard C output stream stderr. Useful when debugging.

Note: This should be called before creating any initializing a PstTracker with pst_tracker_init(). Calling this afterwards will have no effect.

◆ pst_sdk_enable_rest_server()

EPstErrorStatus pst_sdk_enable_rest_server	(	const char *	server_address,
		const char *	server_port,
		int	event_stream_retry_timeout
	)

Enable a REST Server that uses the HTTP protocol to enable access to the PST Tracker over a local area network. 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 pst_sdk_enable_rest_server() 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 documentation. If error result PST_ERROR_STATUS_HTTP_ERROR is returned, a possible cause could be an invalid IP address or port number.

Note: A PstTracker must have been initialized before enabling the REST server.

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]	event_stream_retry_timeout	Timeout in milliseconds before an eventstream attempt to reconnect to the server automatically.

See also: pst_sdk_disable_rest_server()

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NOT_INITIALIZED_ERROR, PST_ERROR_STATUS_HTTP_ERROR.

Examples: restserver.c.

◆ pst_sdk_enable_shared_memory()

EPstErrorStatus pst_sdk_enable_shared_memory ( )

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 on Windows 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.; A PstTracker must have been initialized before enabling shared memory.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NOT_INITIALIZED_ERROR.

See also: pst_sdk_disable_shared_memory(); pst_tracker_enable_filtering(); pst_tracker_enable_tremor_filter()

Examples: sharedmemory.c.

◆ pst_sdk_get_version()

const char* pst_sdk_get_version ( )

Retrieves the SDK version information as a c style string. The SDK version can differ from the internal tracker version which can be retrieved using pst_tracker_alloc_and_get_version_info().

See also: pst_tracker_alloc_and_get_version_info()

◆ pst_sdk_shutdown()

void pst_sdk_shutdown ( )

Fully shutdown the tracking system, disconnecting from the PST Tracker. When the shared memory interface or the REST server have been enabled these will be disabled as well. In order to restart the tracker, a new PstTracker has to be initialized using pst_tracker_init().

See also: pst_tracker_init(); pst_sdk_disable_shared_memory(); pst_sdk_disable_rest_server()

Examples: exposure.c, images.c, listener.c, minimal.c, reference.c, restserver.c, sharedmemory.c, and trackingtarget.c.

◆ pst_target_markers_destroy()

void pst_target_markers_destroy ( PstTargetMarkers * marker_list )

Destruction function for PstTargetMarkers

Parameters

[in] marker_list The marker_list object to be destroyed.

See also: pst_target_markers_init(); pst_tracker_get_target_markers()

Examples: trackingtarget.c.

◆ pst_target_markers_init()

void pst_target_markers_init ( PstTargetMarkers * marker_list )

Initialization function for PstTargetMarkers

Parameters

[in] marker_list Empty marker_list object to be initialized.

See also: pst_target_markers_destroy(); pst_tracker_get_target_markers()

Examples: trackingtarget.c.

◆ pst_tracker_add_tracker_callbacks()

EPstErrorStatus pst_tracker_add_tracker_callbacks	(	PstTracker *	ctracker,
		void()(const PstTrackerData , EPstErrorStatus)	on_tracker_data,
		void(*)(EPstTrackerMode)	on_tracker_mode
	)

Register two callback functions: one for receiving tracking information from the connected PST Tracker and one for reporting tracker mode changes. If only one callback function needs to be registered, NULL can be passed for the other callback. Alternatively, pst_tracker_add_tracker_data_callback() and pst_tracker_add_tracker_mode_callback() can be used to register a single callback function. The on_tracker_data callback function will be executed every time data from the PST Tracker arrives. The on_tracker_mode callback function will be executed every time there is a change of mode in the tracker. Multiple callback functions can be registered, and they will be executed in order of registration. Note that if pst_tracker_add_tracker_callbacks() is used to add callbacks, these callbacks can only be removed by calling pst_tracker_remove_tracker_callbacks() using the same pair of function pointers.

Parameters

[in]	ctracker	The tracker object for which the callback functions have to be added.
[in]	on_tracker_data	A function pointer to the callback that should be executed when data arrives.
[in]	on_tracker_mode	A function pointer to the callback that should be executed when a change of tracker mode happens.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: PstTrackerData; EPstTrackerMode; pst_tracker_add_tracker_data_callback(); pst_tracker_add_tracker_mode_callback(); pst_tracker_remove_tracker_callbacks()

Examples: listener.c.

◆ pst_tracker_add_tracker_data_callback()

EPstErrorStatus pst_tracker_add_tracker_data_callback	(	PstTracker *	ctracker,
		void()(const PstTrackerData , EPstErrorStatus)	on_tracker_data
	)

Register a callback function to receive tracking information from the connected PST Tracker. The callback function will be executed every time data from the PST Tracker arrives. Multiple callback functions can be registered, and they will be executed in order of registration. Note that if pst_tracker_add_tracker_data_callback() is used to add a callback, this callback can only be removed with pst_tracker_remove_tracker_data_callback()

Parameters

[in]	ctracker	The tracker object for which the on_tracker_data callback function has to be added.
[in]	on_tracker_data	A function pointer to the callback that should be executed when data arrives.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: PstTrackerData; pst_tracker_add_tracker_callbacks(); pst_tracker_remove_tracker_data_callback()

Examples: exposure.c, images.c, minimal.c, reference.c, and trackingtarget.c.

◆ pst_tracker_add_tracker_mode_callback()

EPstErrorStatus pst_tracker_add_tracker_mode_callback	(	PstTracker *	ctracker,
		void(*)(EPstTrackerMode)	on_tracker_mode
	)

Register a callback function to process changes to the tracker mode. The callback function will be executed every time there is a change of mode in the tracker. Multiple callback functions can be registered, and they will be executed in order of registration. Note that if pst_tracker_add_tracker_mode_callback() is used to add a callback, this callback can only be removed with pst_tracker_remove_tracker_mode_callback()

Parameters

[in]	ctracker	The tracker object for which the on_tracker_mode callback function has to be added.
[in]	on_tracker_mode	A function pointer to the callback that should be executed when a change of tracker mode happens.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: EPstTrackerMode; pst_tracker_add_tracker_callbacks(); pst_tracker_remove_tracker_mode_callback()

◆ pst_tracker_alloc_and_get_config_path()

EPstErrorStatus pst_tracker_alloc_and_get_config_path	(	const PstTracker *	ctracker,
		char **	config_path
	)

Retrieves the full path to the configuration directory currently being used by the PST Tracker. The default path is "%PROGRAMDATA%\PS-Tech\PST Iris" on Windows or ~/.pstiris on Linux. The configuration directory contains the target model database, server configuration, reference file and tracker calibration information. Memory will be allocated for *config_path. Ensure that it is freed using pst_free() when it is no longer needed.

Parameters

[in]	ctracker	The tracker object for which to request camera urls.
[out]	config_path	Contains a c style string with the version information.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_FAILED_TO_ALLOCATE_MEMORY_ERROR, PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_free()

◆ pst_tracker_alloc_and_get_supported_framerates()

EPstErrorStatus pst_tracker_alloc_and_get_supported_framerates	(	const PstTracker *	ctracker,
		float **	framerates,
		size_t *	number_of_framerates
	)

Get an array 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 pst_tracker_set_framerate() 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 pst_tracker_set_framerate. Ensure that *framerates is freed using pst_free() when it is no longer needed.

Parameters

[in]	ctracker	The tracker object.
[out]	framerates	Pointer to a pointer to float. Will contain an array after function succeeds.
[out]	number_of_framerates	The size of the array *framerates.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR, PST_ERROR_STATUS_FAILED_TO_ALLOCATE_MEMORY_ERROR.

See also: pst_tracker_set_framerate(); pst_tracker_get_framerate(); pst_free()

◆ pst_tracker_alloc_and_get_target_list()

EPstErrorStatus pst_tracker_alloc_and_get_target_list	(	const PstTracker *	ctracker,
		PstTargetStatus **	statuses,
		size_t *	number_of_statuses
	)

Retrieves the list of all tracking targets defined in the tracking target database and returns them as a TargetStatuses object. Make sure to free *statuses using pst_free() when the PstTargetStatus objects are no longer needed.

Parameters

[in]	ctracker	The tracker object.
[out]	statuses	Pointer to allocated array of PstTargetStatus objects.
[out]	number_of_statuses	Number of elements in statuses.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR, PST_ERROR_STATUS_FAILED_TO_ALLOCATE_MEMORY_ERROR.

See also: PstTargetStatus; pst_tracker_set_target_status(); pst_tracker_get_target_status(); pst_free()

Examples: trackingtarget.c.

◆ pst_tracker_alloc_and_get_version_info()

EPstErrorStatus pst_tracker_alloc_and_get_version_info	(	const PstTracker *	ctracker,
		char **	version_string
	)

Retrieves version information of the PST Server used by the SDK. This version can differ from the SDK version retrieved using pst_sdk_get_version(). Memory will be allocated for *version_string. Ensure that it is freed using pst_free() when it is no longer needed.

Parameters

[in]	ctracker	The tracker object for which to request camera urls.
[out]	version_string	Contains a c style string with the version information.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_FAILED_TO_ALLOCATE_MEMORY_ERROR, PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_sdk_get_version(); pst_free()

Examples: exposure.c, images.c, listener.c, reference.c, and trackingtarget.c.

◆ pst_tracker_destroy()

void pst_tracker_destroy ( PstTracker * ctracker )

Deallocates the state of ctracker.

Examples: exposure.c, images.c, listener.c, minimal.c, reference.c, restserver.c, sharedmemory.c, and trackingtarget.c.

◆ pst_tracker_disable_filtering()

EPstErrorStatus pst_tracker_disable_filtering ( PstTracker * ctracker )

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

Parameters

[in] ctracker The tracker object.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_enable_filtering(); pst_tracker_disable_tremor_filter()

◆ pst_tracker_disable_image_transfer()

EPstErrorStatus pst_tracker_disable_image_transfer ( PstTracker * ctracker )

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.

Parameters

[in] ctracker The tracker object.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_enable_image_transfer()

◆ pst_tracker_disable_tremor_filter()

EPstErrorStatus pst_tracker_disable_tremor_filter ( PstTracker * ctracker )

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

Parameters

[in] ctracker The tracker object.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_enable_tremor_filter(); pst_tracker_disable_filtering()

◆ pst_tracker_enable_filtering()

EPstErrorStatus pst_tracker_enable_filtering ( PstTracker * ctracker )

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.

Parameters

[in] ctracker The tracker object.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_disable_filtering(); pst_tracker_set_position_filter(); pst_tracker_set_orientation_filter(); pst_tracker_enable_tremor_filter(); pst_sdk_enable_shared_memory()

◆ pst_tracker_enable_image_transfer()

EPstErrorStatus pst_tracker_enable_image_transfer ( PstTracker * ctracker )

Enable transferring grayscale image data from the PST Tracker. After enabling image transfer, initialize an PstImage with pst_image_init() and use pst_tracker_get_pst_image() to receive captured images. When no calls are made to pst_tracker_get_pst_image() 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.

Parameters

[in] ctracker The tracker object.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: PstImage; pst_image_init(); pst_image_destroy(); pst_tracker_get_pst_image(); pst_tracker_disable_image_transfer()

Examples: images.c.

◆ pst_tracker_enable_tremor_filter()

EPstErrorStatus pst_tracker_enable_tremor_filter ( PstTracker * ctracker )

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.

Parameters

[in] ctracker The tracker object.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_disable_tremor_filter(); pst_tracker_enable_filtering()

◆ pst_tracker_export_json_model()

EPstErrorStatus pst_tracker_export_json_model	(	const PstTracker *	ctracker,
		const char *	model_name,
		char **	model_string
	)

Export a tracking target model from the target model database as a JSON-formatted string. The string will be formatted according to the specification found in Appendix A of the PST Manual. Memory will be allocated for *model_string. Ensure that it is freed using pst_free() when it is no longer needed.

Parameters

[in]	ctracker	The tracker object.
[in]	model_name	The name of the target model to be exported.
[out]	model_string	Contains a c style string with the exported JSON model.

Returns: PST_ERROR_STATUS_OK on success, PST_ERROR_STATUS_NULLPTR_ERROR if the tracker does not exist or PST_ERROR_STATUS_NOT_FOUND_ERROR.

◆ pst_tracker_get_connected_camera_urls()

EPstErrorStatus pst_tracker_get_connected_camera_urls	(	const PstTracker *	ctracker,
		bool	silent,
		PstCameraURLs *	urls
	)

Retrieves and prints the URLs to download the calibration information for the cameras in the connected PST Tracker. First initialize the urls with pst_camera_urls_init(). Destroy urls with pst_camera_urls_destroy() before freeing it if necessary.

Parameters

[in]	ctracker	The tracker object for which to request camera urls.
[in]	silent	Set to true in order to disable printing of calibration information.
[out]	urls	Object containing the urls for the connected cameras.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_FAILED_TO_ALLOCATE_MEMORY_ERROR, PST_ERROR_STATUS_NULLPTR_ERROR.

◆ pst_tracker_get_exposure()

EPstErrorStatus pst_tracker_get_exposure	(	const PstTracker *	ctracker,
		double *	exposure
	)

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

Parameters

[in]	ctracker	The tracker object.
[out]	exposure	The current exposure time in seconds.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_set_exposure()

Examples: exposure.c.

◆ pst_tracker_get_exposure_range()

EPstErrorStatus pst_tracker_get_exposure_range	(	const PstTracker *	ctracker,
		double *	min,
		double *	max
	)

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

[in]	ctracker	The tracker object.
[out]	min	The minimum exposure value that can be set.
[out]	max	The maximum exposure value that can be set.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_get_exposure(); pst_tracker_set_exposure(); pst_tracker_set_framerate()

Examples: exposure.c.

◆ pst_tracker_get_framerate()

EPstErrorStatus pst_tracker_get_framerate	(	const PstTracker *	ctracker,
		double *	fps
	)

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

Parameters

[in]	ctracker	The tracker object.
[out]	fps	Current frame rate in frames per second (fps).

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_set_framerate(); pst_tracker_alloc_and_get_supported_framerates()

Examples: exposure.c, images.c, listener.c, and reference.c.

◆ pst_tracker_get_pst_image()

EPstErrorStatus pst_tracker_get_pst_image	(	const PstTracker *	ctracker,
		PstImage *	image
	)

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

Note that PstImage.images is a pointer to an array of (likely) more than 1 grayscale images. These pointers could be invalidated by the next call of pst_tracker_get_pst_image(). If the images are still needed after this call, they should be deepcopied.

Make sure to initialize the PstImage with pst_image_init() before using this function. Afterwards the PstImage can be reused. This function will ensure that the data in the PstImage object is properly freed before new data is stored. In case the image retrieval fails PST_ERROR_STATUS_IMAGE_RETRIEVAL_FAILED_ERROR is returned, but PstImage is left untouched. Note that the pointers in the image.images array might still be invalidated.

Parameters

[in]	ctracker	The tracker object.
[out]	image	The image information retrieved from the PST Tracker.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR, PST_ERROR_STATUS_FAILED_TO_ALLOCATE_MEMORY_ERROR, PST_ERROR_STATUS_IMAGE_RETRIEVAL_FAILED_ERROR.

See also: PstImage; pst_image_init(); pst_image_destroy(); pst_tracker_enable_image_transfer()

Examples: images.c.

◆ pst_tracker_get_reference()

EPstErrorStatus pst_tracker_get_reference	(	const PstTracker *	ctracker,
		float	creference[16]
	)

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.

Parameters

[in]	ctracker	The tracker object.
[out]	creference	The transformation matrix for the current reference system.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_set_reference(); pst_tracker_set_default_reference()

Examples: reference.c.

◆ pst_tracker_get_single_measurement()

EPstErrorStatus pst_tracker_get_single_measurement	(	const PstTracker *	ctracker,
		PstTrackerData *	cdata
	)

Retrieve the latest PstTrackerData available from the PstTracker after the server started. If the PstTracker has not been started with pst_tracker_start(), the PstTrackerData will be empty. Make sure to initialize the PstTrackerData with pst_trackerdata_init() before using this function. The PstTrackerData can be reused, after its contents has been destroyed using pst_trackerdata_destroy(). When the PstTrackerData is not needed anymore, use pst_trackerdata_destroy() to free the content before removal.

Parameters

[in]	ctracker	The tracker object.
[in]	cdata	The latest PstTrackerData available retrieved from the PstTracker.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR, PST_ERROR_STATUS_FAILED_TO_ALLOCATE_MEMORY_ERROR.

See also: PstTracker; PstTrackerData; pst_tracker_start(); pst_trackerdata_init(); pst_trackerdata_destroy()

◆ pst_tracker_get_target_info()

EPstErrorStatus pst_tracker_get_target_info	(	const PstTracker *	ctracker,
		const char *	name,
		PstTarget *	target
	)

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

Parameters

[in]	ctracker	The tracker object.
[in]	name	The name of the tracking target.
[out]	target	Target object containing the basic target information.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR, PST_ERROR_STATUS_NOT_FOUND_ERROR.

See also: PstTarget

◆ pst_tracker_get_target_markers()

EPstErrorStatus pst_tracker_get_target_markers	(	const PstTracker *	ctracker,
		const char *	name,
		PstTargetMarkers *	marker_list
	)

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.

Make sure to initialize the PstTargetMarkers with pst_target_markers_init() before using this function. Afterwards the PstTargetMarkers can be reused in this function. This function will ensure that the data in the PstTargetMarkers object is properly freed before new data is stored. When the PstTargetMarkers object is no longer needed, please use pst_target_markers_destroy() to free the object.

Parameters

[in]	ctracker	The tracker object.
[in]	name	Name of the tracking target to get the marker positions of.
[out]	marker_list	Contains a list of 3D marker positions of the target.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR, PST_ERROR_STATUS_NOT_FOUND_ERROR, PST_ERROR_STATUS_FAILED_TO_ALLOCATE_MEMORY_ERROR.

See also: PstTargetMarkers; PstTarget; pst_target_markers_init(); pst_target_markers_destroy()

Examples: trackingtarget.c.

◆ pst_tracker_get_target_status()

EPstErrorStatus pst_tracker_get_target_status	(	const PstTracker *	ctracker,
		const char *	name,
		bool *	status
	)

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

Parameters

[in]	ctracker	The tracker object.
[in]	name	The name of the tracking target to get the status of.
[out]	status	Status of the tracking Target.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR, PST_ERROR_STATUS_NOT_FOUND_ERROR.

See also: PstTargetStatus; pst_tracker_set_target_status(); pst_tracker_alloc_and_get_target_list()

◆ pst_tracker_get_uncalibrated_camera_urls()

EPstErrorStatus pst_tracker_get_uncalibrated_camera_urls	(	const PstTracker *	ctracker,
		bool	silent,
		PstCameraURLs *	urls
	)

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. First initialize the urls with pst_camera_urls_init(). Destroy urls with pst_camera_urls_destroy() before freeing it if necessary.

Parameters

[in]	ctracker	The tracker object for which to request camera urls.
[in]	silent	Set to true in order to disable printing of missing calibration information. (default: false)
[out]	urls	Object containing the urls for the uncalibrated cameras.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_FAILED_TO_ALLOCATE_MEMORY_ERROR, PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_camera_urls_init(); pst_camera_urls_destroy()

Examples: listener.c.

◆ pst_tracker_import_json_model()

EPstErrorStatus pst_tracker_import_json_model	(	const PstTracker *	ctracker,
		const char *	json_model
	)

Import a JSON-formatted string representing a tracking target model into the target model database. The JSON string should be formatted according to the instructions found in Appendix A of the PST Manual. After successfully importing the model it can be tracked by the PST Tracker.

Parameters

[in]	ctracker	The tracker object.
[in]	json_model	A JSON-formatted string representing the tracking target model.

Returns: PST_ERROR_STATUS_OK on success, PST_ERROR_STATUS_NULLPTR_ERROR if the tracker does not exist or PST_ERROR_STATUS_NOT_FOUND_ERROR, PST_ERROR_STATUS_INVALID_DATA_ERROR, PST_ERROR_STATUS_ALREADY_EXISTS_ERROR, PST_ERROR_STATUS_JSON_PARSING_ERROR.

◆ pst_tracker_init()

EPstErrorStatus pst_tracker_init ( PstTracker * ctracker )

This function initializes the tracker object. Camera calibration will be checked. When calibration files for the connected tracker can not be found, a message with download links will be printed to the command line. Note that an initialized tracker object should be destroyed with pst_tracker_destroy() before the tracker object is freed.

Note: Ensure that a tracker object is initialized only once.

Parameters

[in] ctracker The tracker object to be initialized.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NOT_INITIALIZED_ERROR, PST_ERROR_STATUS_TRACKER_ERROR.

See also: pst_tracker_destroy()

Examples: exposure.c, images.c, listener.c, minimal.c, reference.c, restserver.c, sharedmemory.c, and trackingtarget.c.

◆ pst_tracker_init1()

EPstErrorStatus pst_tracker_init1	(	PstTracker *	ctracker,
		const char	path[]
	)

This function initializes the tracker object. Camera calibration will be checked. When calibration files for the connected tracker can not be found, a message with download links will be printed to the command line. Note that an initialized tracker object should be destroyed with pst_tracker_destroy() before the tracker object is freed.

Note: Ensure that a tracker object is initialized only once.

Parameters

[in]	ctracker	The tracker object to be initialized.
[in]	path	Path to the configuration directory to be used for storing camera calibrations, target database and configuration files. Use "" for default. (default: "%PROGRAMDATA%\PS-Tech\PST Iris" on Windows or ~/.pstiris on Linux)

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NOT_INITIALIZED_ERROR, PST_ERROR_STATUS_TRACKER_ERROR.

See also: pst_tracker_destroy()

◆ pst_tracker_init2()

EPstErrorStatus pst_tracker_init2	(	PstTracker *	ctracker,
		const char	path[],
		const char	config_file[]
	)

This function initializes the tracker object. Camera calibration will be checked. When calibration files for the connected tracker can not be found, a message with download links will be printed to the command line. Note that an initialized tracker object should be destroyed with pst_tracker_destroy() before the tracker object is freed.

Note: Ensure that a tracker object is initialized only once.

Parameters

[in]	ctracker	The tracker object to be initialized.
[in]	path	Path to the configuration directory to be used for storing camera calibrations, target database and configuration files. Use "" for default. (default: "%PROGRAMDATA%\PS-Tech\PST Iris" on Windows or ~/.pstiris on Linux)
[in]	config_file	Name of the server configuration file. Use "" for default. (default: "server.cfg")

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NOT_INITIALIZED_ERROR, PST_ERROR_STATUS_TRACKER_ERROR.

See also: pst_tracker_destroy()

◆ pst_tracker_init3()

EPstErrorStatus pst_tracker_init3	(	PstTracker *	ctracker,
		const char	path[],
		const char	config_file[],
		const char	db_file[]
	)

This function initializes the tracker object. Camera calibration will be checked. When calibration files for the connected tracker can not be found, a message with download links will be printed to the command line. Note that an initialized tracker object should be destroyed with pst_tracker_destroy() before the tracker object is freed.

Note: Ensure that a tracker object is initialized only once.

Parameters

[in]	ctracker	The tracker object to be initialized.
[in]	path	Path to the configuration directory to be used for storing camera calibrations, target database and configuration files. Use "" for default. (default: "%PROGRAMDATA%\PS-Tech\PST Iris" on Windows or ~/.pstiris on Linux)
[in]	config_file	Name of the server configuration file. Use "" for default. (default: "server.cfg")
[in]	db_file	Name of the tracking target database file. Use "" for default. (default: "models.db")

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NOT_INITIALIZED_ERROR, PST_ERROR_STATUS_TRACKER_ERROR.

See also: pst_tracker_destroy()

◆ pst_tracker_init4()

EPstErrorStatus pst_tracker_init4	(	PstTracker *	ctracker,
		const char	path[],
		const char	config_file[],
		const char	db_file[],
		const char	grabber_name[]
	)

This function initializes the tracker object. Camera calibration will be checked. When calibration files for the connected tracker can not be found, a message with download links will be printed to the command line. Note that an initialized tracker object should be destroyed with pst_tracker_destroy() before the tracker object is freed.

Note: Ensure that a tracker object is initialized only once.

Parameters

[in]	ctracker	The tracker object to be initialized.
[in]	path	Path to the configuration directory to be used for storing camera calibrations, target database and configuration files. Use "" for default. (default: "%PROGRAMDATA%\PS-Tech\PST Iris" on Windows or ~/.pstiris on Linux)
[in]	config_file	Name of the server configuration file. Use "" for default. (default: "server.cfg")
[in]	db_file	Name of the tracking target database file. Use "" for default. (default: "models.db")
[in]	grabber_name	Name of the grabber plugin to be used. Can contain absolute or relative path to xml config file. Set to "default" to use auto-detect. (default: "default")

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NOT_INITIALIZED_ERROR, PST_ERROR_STATUS_TRACKER_ERROR.

See also: pst_tracker_destroy()

Examples: exposure.c, images.c, listener.c, minimal.c, reference.c, restserver.c, sharedmemory.c, and trackingtarget.c.

◆ pst_tracker_load_calibration_from_local_path()

EPstErrorStatus pst_tracker_load_calibration_from_local_path	(	const PstTracker *	ctracker,
		const char	path[]
	)

Load the calibration information for each of the cameras in the connected PST Tracker from the specified local path. This function will overwrite any calibration information for the currently connected trackers available in the current configuration folder. Calibration information will only be loaded and placed in the configuration folder when calibration information is found and valid for all connected cameras.

Parameters

[in] path Path to the local directory where the calibration information for all connected cameras is stored.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_INVALID_DATA_ERROR, PST_ERROR_STATUS_NOT_FOUND_ERROR, PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_get_connected_camera_urls()

◆ pst_tracker_pause()

EPstErrorStatus pst_tracker_pause ( PstTracker * ctracker )

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

Parameters

[in] ctracker The tracker object that should be paused.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_start()

◆ pst_tracker_remove_target_model()

EPstErrorStatus pst_tracker_remove_target_model	(	PstTracker *	ctracker,
		const char *	model_name
	)

Remove a tracking target model from the target model database.

Parameters

[in]	ctracker	The tracker object.
[in]	model_name	The name of the tracking target model to be removed.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR, PST_ERROR_STATUS_NOT_FOUND_ERROR.

See also: pst_tracker_import_json_model(); pst_tracker_export_json_model()

◆ pst_tracker_remove_tracker_callbacks()

EPstErrorStatus pst_tracker_remove_tracker_callbacks	(	PstTracker *	ctracker,
		void()(const PstTrackerData , EPstErrorStatus)	on_tracker_data,
		void(*)(EPstTrackerMode)	on_tracker_mode
	)

Remove callback functions receiving tracking information and changes of mode from the connected PST Tracker. Note that only pairs of callback functions added with pst_tracker_add_tracker_callbacks() can be removed with this function using the same pairs of function pointers.

Parameters

[in]	ctracker	The tracker object for which the callback functions have to be removed.
[in]	on_tracker_data	A function pointer to the callback that should be removed.
[in]	on_tracker_mode	A function pointer to the mode change callback that should be removed.

Returns: PST_ERROR_STATUS_OK on success, PST_ERROR_STATUS_NULLPTR_ERROR if the tracker does not exist or PST_ERROR_STATUS_NOT_FOUND_ERROR if the pair of callback functions is not found.

See also: pst_tracker_add_tracker_callbacks()

Examples: listener.c.

◆ pst_tracker_remove_tracker_data_callback()

EPstErrorStatus pst_tracker_remove_tracker_data_callback	(	PstTracker *	ctracker,
		void()(const PstTrackerData , EPstErrorStatus)	on_tracker_data
	)

Remove a callback function receiving tracking information from the connected PST Tracker. Note that only callback functions added with pst_tracker_add_tracker_data_callback() can be removed with this function.

Parameters

[in]	ctracker	The tracker object for which the callback function has to be removed.
[in]	on_tracker_data	A function pointer to the callback that should be removed.

Returns: PST_ERROR_STATUS_OK on success, PST_ERROR_STATUS_NULLPTR_ERROR if the tracker does not exist or PST_ERROR_STATUS_NOT_FOUND_ERROR if the callback function is not found.

See also: pst_tracker_add_tracker_data_callback()

◆ pst_tracker_remove_tracker_mode_callback()

EPstErrorStatus pst_tracker_remove_tracker_mode_callback	(	PstTracker *	ctracker,
		void(*)(EPstTrackerMode)	on_tracker_mode
	)

Remove the supplied tracker mode change callback function from the given PST Tracker. Note that only callback functions added with pst_tracker_add_tracker_mode_callback() can be removed with this function.

Parameters

[in]	ctracker	The tracker object for which the callback function has to be removed.
[in]	on_tracker_mode	A function pointer to the callback that should be removed.

Returns: PST_ERROR_STATUS_OK on success, PST_ERROR_STATUS_NULLPTR_ERROR if the tracker does not exist or PST_ERROR_STATUS_NOT_FOUND_ERROR if the callback function is not found.

See also: pst_tracker_add_tracker_mode_callback()

◆ pst_tracker_set_default_reference()

EPstErrorStatus pst_tracker_set_default_reference ( PstTracker * ctracker )

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.

Parameters

[in] ctracker The tracker object.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_set_reference(); pst_tracker_get_reference()

Examples: reference.c.

◆ pst_tracker_set_exposure()

EPstErrorStatus pst_tracker_set_exposure	(	PstTracker *	ctracker,
		double	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]	ctracker	The tracker object.
[in]	time	Exposure time in seconds.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NOT_SUPPORTED_ERROR, PST_ERROR_STATUS_NULLPTR_ERROR, PST_ERROR_STATUS_OUT_OF_RANGE_ERROR.

See also: pst_tracker_get_exposure(); pst_tracker_get_exposure_range()

Examples: exposure.c.

◆ pst_tracker_set_framerate()

EPstErrorStatus pst_tracker_set_framerate	(	PstTracker *	ctracker,
		double	fps
	)

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

Parameters

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

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NOT_SUPPORTED_ERROR, PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_get_framerate(); pst_tracker_alloc_and_get_supported_framerates()

Examples: exposure.c, images.c, listener.c, and reference.c.

◆ pst_tracker_set_orientation_filter()

EPstErrorStatus pst_tracker_set_orientation_filter	(	PstTracker *	ctracker,
		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]	ctracker	The tracker object.
[in]	value	Filtering strength to be used in range [0, 0.99]

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_enable_filtering(); pst_tracker_set_position_filter()

◆ pst_tracker_set_position_filter()

EPstErrorStatus pst_tracker_set_position_filter	(	PstTracker *	ctracker,
		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]	ctracker	The tracker object.
[in]	value	Filtering strength to be used in range [0, 0.99]

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_enable_filtering(); pst_tracker_set_orientation_filter()

◆ pst_tracker_set_reference()

EPstErrorStatus pst_tracker_set_reference	(	PstTracker *	ctracker,
		const float	creference[16],
		bool	relative
	)

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 the rotation component of the supplied transformation matrix is orthonormal and if the supplied transformation matrix is homogeneous (i.e. the final row of the matrix is [0 0 0 1]). If either on of these conditions is not true, the function will return PST_ERROR_STATUS_TRACKER_ERROR. 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]	ctracker	The tracker object.
[in]	creference	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.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR, PST_ERROR_STATUS_TRACKER_ERROR.

See also: pst_tracker_get_reference(); pst_tracker_set_default_reference()

Examples: reference.c.

◆ pst_tracker_set_target_id()

EPstErrorStatus pst_tracker_set_target_id	(	PstTracker *	ctracker,
		const char *	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]	ctracker	The tracker object.
[in]	name	The name of the tracking target to change the id of.
[in]	id	The new id of the tracking target.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR, PST_ERROR_STATUS_NOT_FOUND_ERROR.

See also: PstTarget

◆ pst_tracker_set_target_status()

EPstErrorStatus pst_tracker_set_target_status	(	PstTracker *	ctracker,
		const char *	name,
		bool	set_active
	)

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

Parameters

[in]	ctracker	The tracker object.
[in]	name	The name of the tracking target to set the status of.
[in]	set_active	New status of the tracking target.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR, PST_ERROR_STATUS_NOT_FOUND_ERROR.

See also: PstTargetStatus; pst_tracker_get_target_status(); pst_tracker_alloc_and_get_target_list()

Examples: trackingtarget.c.

◆ pst_tracker_start()

EPstErrorStatus pst_tracker_start ( PstTracker * ctracker )

Start the tracking system and produce tracking results.

Parameters

[in] ctracker The tracker object that should be started.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_tracker_pause()

Examples: exposure.c, images.c, listener.c, minimal.c, reference.c, restserver.c, sharedmemory.c, and trackingtarget.c.

◆ pst_tracker_system_check()

EPstStatusMessage pst_tracker_system_check ( const PstTracker * ctracker )

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.

Parameters

[in] ctracker The tracker object.

Returns: Current system status code as StatusMessage enumeration member.

See also: EPstStatusMessage

Examples: exposure.c, images.c, listener.c, reference.c, and trackingtarget.c.

◆ pst_trackerdata_destroy()

void pst_trackerdata_destroy ( PstTrackerData * cdata )

Destroy function for PstTrackerData

◆ pst_trackerdata_init()

void pst_trackerdata_init ( PstTrackerData * cdata )

Initialization function for PstTrackerData

Parameters

[out] trackerdata Empty trackerdata object to be initialized.

Returns: PST_ERROR_STATUS_OK on success or PST_ERROR_STATUS_NULLPTR_ERROR.

See also: pst_trackerdata_destroy(); pst_tracker_get_single_measurement()

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ EPstErrorStatus

◆ EPstStatusMessage

◆ EPstTrackerMode

Function Documentation

◆ pst_alloc_and_get_last_error_message()

◆ pst_camera_urls_destroy()

◆ pst_camera_urls_init()

◆ pst_free()

◆ pst_image_destroy()

◆ pst_image_init()

◆ pst_sdk_disable_rest_server()

◆ pst_sdk_disable_shared_memory()

◆ pst_sdk_enable_logging()

◆ pst_sdk_enable_rest_server()

◆ pst_sdk_enable_shared_memory()

◆ pst_sdk_get_version()

◆ pst_sdk_shutdown()

◆ pst_target_markers_destroy()

◆ pst_target_markers_init()

◆ pst_tracker_add_tracker_callbacks()

◆ pst_tracker_add_tracker_data_callback()

◆ pst_tracker_add_tracker_mode_callback()

◆ pst_tracker_alloc_and_get_config_path()

◆ pst_tracker_alloc_and_get_supported_framerates()

◆ pst_tracker_alloc_and_get_target_list()

◆ pst_tracker_alloc_and_get_version_info()

◆ pst_tracker_destroy()

◆ pst_tracker_disable_filtering()

◆ pst_tracker_disable_image_transfer()

◆ pst_tracker_disable_tremor_filter()

◆ pst_tracker_enable_filtering()

◆ pst_tracker_enable_image_transfer()

◆ pst_tracker_enable_tremor_filter()

◆ pst_tracker_export_json_model()

◆ pst_tracker_get_connected_camera_urls()

◆ pst_tracker_get_exposure()

◆ pst_tracker_get_exposure_range()

◆ pst_tracker_get_framerate()

◆ pst_tracker_get_pst_image()

◆ pst_tracker_get_reference()

◆ pst_tracker_get_single_measurement()

◆ pst_tracker_get_target_info()

◆ pst_tracker_get_target_markers()

◆ pst_tracker_get_target_status()

◆ pst_tracker_get_uncalibrated_camera_urls()

◆ pst_tracker_import_json_model()

◆ pst_tracker_init()

◆ pst_tracker_init1()

◆ pst_tracker_init2()

◆ pst_tracker_init3()

◆ pst_tracker_init4()

◆ pst_tracker_load_calibration_from_local_path()

◆ pst_tracker_pause()

◆ pst_tracker_remove_target_model()

◆ pst_tracker_remove_tracker_callbacks()

◆ pst_tracker_remove_tracker_data_callback()

◆ pst_tracker_remove_tracker_mode_callback()

◆ pst_tracker_set_default_reference()

◆ pst_tracker_set_exposure()

◆ pst_tracker_set_framerate()

◆ pst_tracker_set_orientation_filter()

◆ pst_tracker_set_position_filter()

◆ pst_tracker_set_reference()

◆ pst_tracker_set_target_id()

◆ pst_tracker_set_target_status()

◆ pst_tracker_start()

◆ pst_tracker_system_check()

◆ pst_trackerdata_destroy()

◆ pst_trackerdata_init()