| PST SDK 6.0.0.0-272350a

Using PST SDK

# Overview

The REST API can be used to receive tracking results and images from a PST Tracker. The REST API can be accessed through a web browser or using a network communication tool like Curl. In order to retrieve tracking information from the PST Tracker using the REST API, the stand-alone PST REST Server application or another application implementing the REST Server using any of the other APIs should be running.

By default the PST REST server root address is set to http://localhost:7278/PSTapi/. The address and the port can be specified using command line arguments (e.g. `pst-rest.exe --address 127.0.0.1 --port 7278`). The PST REST API uses HTTP GET and POST commands to communicate to the PST Tracker. Data is communicated in the form of JSON formatted strings and HTTP status codes.

Examples

     curl -X GET http://localhost:7278/PSTapi/GetFramerate

     curl --header "Content-Type: application/json" --request POST --data "{\"Framerate\":30}"  http://localhost:7278/PSTapi/SetFramerate

The full REST API documentation can be found on the REST API page.

# Initialization

Most important runtime settings for the PST Tracker (e.g. setting frame rate and exposure, enabling/disabling tracking targets) can be controlled directly from the REST API. However, some steps that are required in order to start working with a new PST Tracker can currently not be performed using the API. The main steps are retrieving calibration information and defining tracking targets.

## Calibration

Each time a PST Tracker is connected to a new computer, tracker calibration information needs to be provided. When the PST REST Server is initialized it checks whether or not calibration information can be found in the specified configuration directory. If no calibration information can be found, a message specifying the download locations of the required files will be printed on the command line. It is also possible to call the GetUncalibratedCameraUrls endpoint to receive a vector of download URLs. A single PST Tracker requires two calibration files. The download URL of these files takes the following form: http://www.ps-tech.com/pstsw/calibrations/iris_####.cam, where #### is the identification number of each camera. When the PST Tracker that is going to be used is known on forehand, tracker calibration files can be provided by copying the right files from any medium into the configuration directory.

## Tracking Target Setup

A new installation of the PST software will not contain any tracking targets. In order to start tracking, tracking targets need to be added to the model database. This can be done in three different ways.

1. Train a new tracking target model using the 'New device model' tab in the PST-Client.
2. Import an existing tracking target model using the 'Edit device model' tab in the PST-Client.
3. Copy an existing tracking target model database into the configuration directory.

When tracking target models are added using the PST-Client, a shared memory pipeline needs to be available to connect the PST-Client to the PST Tracker. Such a pipeline can be created by running the stand-alone PST-Server application or by implementing any of the `Target` object of any of the other APIs.

Note
  The PST Interface Service will not be available when the PST SDK has been installed.
  The PST-Server and the PST REST Server can not be active at the same time, since only one application can connect to the PST Tracker at any given time.

The PST-Server and the PST REST Server will both store the model database at C:\ProgramData\PS-Tech\PST Iris\models.db on Windows systems and ~/.pstiris/models.db on Linux systems. When the REST server is implemented through the PST SDK, it is possible to specify another configuration directory. In that case, the model database file can be copied to the configuration directory used by the application.

## Reference System

Tracking results are reported relative to a predefined right-handed Cartesian coordinate system, called the reference system. The default reference system is located at 1 meter from the PST Tracker. It is oriented such that the Z-axis points away from the PST tracker and the X-axis is parallel to the PST tracker. The reference system can be changed by the user and is stored as a transformation matrix in a file called otracker.ref located in the configuration directory. Setting the reference system can be done in several ways.

1. Use the pose of a tracking target on the 'Reference System' tab in the PST-Client.
2. Enter a relative or absolute reference system transformation on the 'Reference System' tab in the PST-Client.
3. Use the SetReference endpoint to supply a relative or absolute reference system.
4. Copy an existing `otracker.ref` reference system file into the configuration directory.

The PST-Client can be used to set the reference system according to the methods described in section Tracking Target Setup.

# Usage

When a PST REST server is running (either the stand-alone PST REST server or a custom application implementing the SDK), it is possible to retrieve information through HTTP GET and POST requests passing JSON objects. First, if this is not yet the case, the server needs to be started. As such, the first call must be to the Start endpoint:

      POST /PSTapi/Start HTTP/1.1
      Host: address:port

## Receiving tracker data

The REST API can be used to receive tracking data from the PST Tracker. For this, the tracker needs to be started, the required tracking targets must be enabled and visible, and a data stream must be opened to which the PST Tracker can push the data. Starting the tracker can be done by calling the Start endpoint. Next, posting a target status for a required tracking target to the SetTargetStatus endpoint, makes sure that the required tracking target is enabled. Finally, receiving tracking data for the required tracking targets is done by calling the StartTrackerDataStream endpoint. This opens up a Server-Send Events (SSE) communication channel and as long as this channel is open, tracking data will be received. For a call sequence example, see the REST_Tracking_Example example.

## Retrieving status information

With HTTP GET requests, it is possible to retrieve general information about the tracker such as the frame rate or specific information about a target, passing the name of the target as a query.

Retrieving general information

General information is retrieved by making a standard GET call to a PST REST server endpoint URI. For example, the endpoint GetFramerate is defined as follows:

      GET /PSTapi/GetFramerate HTTP/1.1
      Host: address:port

and can be called like this:

      http://localhost:7278/PSTapi/GetFramerate

Retrieving target specific information

Extra information necessary for the PST REST server to complete a GET request can be supplied as parameters to the PST REST server endpoint URI.

For example, the endpoint GetTargetStatus is defined as follows:

      GET /PSTapi/GetTargetStatus HTTP/1.1
      Query string parameter: target name
      Host: address:port

and can be called like this:

      http://localhost:7278/PSTapi/GetTargetStatus?MyTargetName

## Changing the state

With HTTP POST requests, parameters can be set and the state of the tracker can changed. This can be general settings such as frame rate and exposure, but also specific target settings, such as whether a target is active. These calls all require a JSON object to be passed with information on the setting to be changed. In some cases, no additional information is needed and an empty JSON object is passed.

Changing general settings

General settings, such as frame rate or exposure, can be changed by making a POST call with a JSON object. For example, the endpoint SetFramerate is defined as follows:

      POST /PSTapi/SetFramerate HTTP/1.1
      Host: address:port

and expects a JSON object in the body of the request, informing the PST REST server what the new frame rate will be. This can be called as follows using Curl:

      curl --header "Content-Type: application/json" --request POST --data "{\"Framerate\":30}" http://localhost:7278/PSTapi/SetFramerate

Changing target information

It is also possible to use the PST REST server to update specifig information about targets, such as whether a target is active. For example, the endpoint SetTargetStatus is defined as follows:

      POST /PSTapi/SetTargetStatus HTTP/1.1
      Host: address:port

and expects a JSON object in the body of the request, informing the PST REST server which target should get what status. An example call using Curl, is as follows:

      curl --header "Content-Type: application/json" --request POST --data "{\"TargetStatus\":{\"name\":\"MyTargetName\",\"status\":true}}" http://localhost:7278/PSTapi/SetTargetStatus

For more extensive call sequences, see the Examples page. For more information about the REST endpoints, see the REST API page.