PST SDK  5.0.1.0-acae3ae
REST API

Overview

The PST REST API enables access to the PST Tracker using the HTTP protocol. This API is primarily convenient when for some reason it is not possible to make use of the native C++ API. The PST REST API can act as a gateway for applications written in a different language than the native API or using a 64 bit architecture. Although the REST API might add a small amount of latency to the communication with the PST Tracker, it offers a similar level of control over the PST Tracker as the C++ API. 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 the C++ API 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). If the PST REST server address is different from "localhost" or "127.0.0.1", or if it is listening on port 80, the application requires admin rights.

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

Using the REST API

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 

PST Tracker 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 PSTapi/GetUncalibratedCameraUrls 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 the C++ SDK Tracking Target Setup.

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

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:

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

Retrieving status information from the PST REST server

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 PSTapi/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 PSTapi/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
 

Setting parameters and changing the state

With HTTP POST requests, parameters can be set and the way information is processed by the PST Tracker can be changed. These calls 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.

For example, the endpoint PSTapi/SetFramerate is defined as follows:

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

and can be called as follows using Curl:

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

Examples: Call Sequences

Getting tracking results

To start receiving tracking results it is important to make sure the server is started (required only once at the start or after PSTapi/Pause has been called in the meantime). Explicitly setting the right exposure and activating the required target helps limit the chance of missed detections.

A typical call sequence in Curl

  curl --header "Content-Type: application/json" --request POST --data "{}" http://localhost:7278/PSTapi/Start
  curl -X GET http://localhost:7278/PSTapi/GetTargetList
  curl --header "Content-Type: application/json" --request POST --data "{\"TargetStatus\":{\"name\":\"target_main\",\"status\":true}}" http://localhost:7278/PSTapi/SetTargetStatus
  curl --header "Content-Type: application/json" --request POST --data "{\"Framerate\":30}" http://localhost:7278/PSTapi/SetFramerate
  curl -X GET http://localhost:7278/PSTapi/GetExposureRange
  curl --header "Content-Type: application/json" --request POST --data "{\"Exposure\":0.0001189}" http://localhost:7278/PSTapi/SetExposure
  curl -X GET http://localhost:7278/PSTapi/StartTrackerDataStream
  
Note
On line 3, change the name of the target "target_main" to a target name present in the target list.
If no objects are detected, try increasing the exposure setting on line 6.
When too many streams are opened at the same time, PSTapi/StartTrackerDataStream returns a 429 too_many_requests status code. More information on how to handle this error can be found in the PSTapi/CloseDataStream documentation.
The output of the previous example in a Windows command prompt
Type message
COMMAND curl --header "Content-Type: application/json" --request POST --data "{}" http://localhost:7278/PSTapi/Start
RESPONSE {"message":"Server Started"}
COMMAND curl -X GET http://localhost:7278/PSTapi/GetTargetList
RESPONSE {"TargetList":["target_main","target_test","Reference"]}
COMMAND curl --header "Content-Type: application/json" --request POST --data "{\"TargetStatus\":{\"name\":\"target_main\",\"status\":true}}" http://localhost:7278/PSTapi/SetTargetStatus
RESPONSE {"message":"Model Status correctly set"}
COMMAND curl --header "Content-Type: application/json" --request POST --data "{\"Framerate\":30}" http://localhost:7278/PSTapi/SetFramerate
RESPONSE {"message":"Frame rate set successfully"}
COMMAND curl -X GET http://localhost:7278/PSTapi/GetExposureRange
RESPONSE {"ExposureRange":{"max":0.0024999999441206455,"min":9.9999997473787516e-05}}
COMMAND curl --header "Content-Type: application/json" --request POST --data "{\"Exposure\":0.0001189}" http://localhost:7278/PSTapi/SetExposure
RESPONSE {"message":"Exposure time set successfully"}
COMMAND curl -X GET http://localhost:7278/PSTapi/StartTrackerDataStream
RESPONSE
data: {
  "TrackerData": {
    "Points": [
      {
        "DataPoint": {
          "id": 4979,
          "position": {
            "x": 0.036606535315513611,
            "y": -0.057408709079027176,
            "z": -0.4420783519744873
          }
        }
      },
      {
        "DataPoint": {
          "id": 5034,
          "position": {
            "x": 0.082240507006645203,
            "y": -0.039975382387638092,
            "z": -0.43901127576828003
          }
        }
      }
    ],
    "TargetPoses": [
      {
        "TargetPose": {
          "TransformationMatrix": [ 0.1579325795173645, 0.21561136841773987, 0.9636228084564209, -0.062948554754257202, -0.96623826026916504, -0.16743898391723633, 0.19582584500312805, -0.28300657868385315, 0.20357045531272888, -0.96201658248901367, 0.18188798427581787, -0.44499132037162781, 0, 0, 0, 1 ],
          "id": 6,
          "name": "Reference",
          "uuid": "88035e90-c205-49c0-b99d-da90843eb465"
        }
      }
    ],
    "seqnumber": 27,
    "timestamp": 1628315.5216415992
  }
}
...


Getting camera images

As with the previous example, to receive image data it is important to make sure the server is started (required only once at the start or after PSTapi/Pause has been called in the meantime). In order to get the image stream, image transfer should be enabled on the PST Tracker first by using PSTapi/EnableImageTransfer. Enabling image transfer will ensure new images are pushed to the image stream buffer.

A typical call sequence in Curl

  curl --header "Content-Type: application/json" --request POST --data "{}" http://localhost:7278/PSTapi/Start 
  curl --header "Content-Type: application/json" --request POST --data "{\"Framerate\":30}"  http://localhost:7278/PSTapi/SetFramerate 
  curl -X GET http://localhost:7278/PSTapi/GetExposureRange 
  curl --header "Content-Type: application/json" --request POST --data "{\"Exposure\":0.0001189}"  http://localhost:7278/PSTapi/SetExposure
  curl --header "Content-Type: application/json" --request POST --data "{}" http://localhost:7278/PSTapi/EnableImageTransfer
  curl -X GET http://localhost:7278/PSTapi/StartRawImageDataStream
  
Note
The last two lines should be executed within 4 seconds form each other. Otherwise, EnableImageTransfer will time out and no images will be sent by the PST Tracker.
When too many streams are opened at the same time, PSTapi/StartRawImageDataStream returns a 429 too_many_requests status code. More information on how to handle this error can be found in the PSTapi/CloseImageStream documentation.
The output of the previous example in a Windows command prompt
Type message
COMMAND curl --header "Content-Type: application/json" --request POST --data "{}" http://localhost:7278/PSTapi/Start
RESPONSE {"message":"Server Started"}
COMMAND curl --header "Content-Type: application/json" --request POST --data "{\"Framerate\":30}" http://localhost:7278/PSTapi/SetFramerate
RESPONSE {"message":"Frame rate set successfully"}
COMMAND curl -X GET http://localhost:7278/PSTapi/GetExposureRange
RESPONSE {"ExposureRange":{"max":0.0024999999441206455,"min":9.9999997473787516e-05}}
COMMAND curl --header "Content-Type: application/json" --request POST --data "{\"Exposure\":0.0001189}" http://localhost:7278/PSTapi/SetExposure
RESPONSE {"message":"Exposure time set successfully"}
COMMAND curl --header "Content-Type: application/json" --request POST --data "{}" http://localhost:7278/PSTapi/EnableImageTransfer
RESPONSE {"message":"Image transfer enabled"}
COMMAND curl -X GET http://localhost:7278/PSTapi/StartRawImageDataStream
RESPONSE data: /9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAgGBgcGBQgH...<rest of a base64 char array of the jpeg image 1, frame 0>
data: /9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAgGBgcGBQgH...<rest of a base64 char array of the jpeg image 2, frame 0>

data: /9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAgGBgcGBQgH...<rest of a base64 char array of the jpeg image 1, frame 1>
data: /9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAgGBgcGBQgH...<rest of a base64 char array of the jpeg image 2, frame 1>