| PST SDK 6.0.0.0-272350a

Data Structures | Enumerations | Functions
PST SDK C API

## 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

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.

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()