 |
PST SDK
6.0.0.0-272350a
|
|
PST SDK
6.0.0.0-272350a
|
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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
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
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.
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
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.
1.8.17