Retrieves real time tracking results by subscribing to an event stream.
The PST Rest server implements a Server-Send Events (SSEs) communication channel. When a new connection is established, tracking result are served with a text/event-stream Content-Type, that follows the SSE format. Each new tracking result is contained in a new "data:" line.
- Note
- The server does not allow to have more than 15 tracking result streams open at the same time (this number might differ depending on system configuration). It is possible to close all currently opened data streams using PSTapi/CloseDataStream or PSTapi/CloseStreams. If a client closes the connection or does not read the data fast enough, the server will automatically end the connection.
-
More detailed information on Server Sent Events and the event-stream protocol can be found at https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format
- Endpoint
GET /PSTapi/StartTrackerDataStream HTTP/1.1
Host: address:port
- Get Request example
http://localhost:7278/PSTapi/StartTrackerDataStream
- Response
Open a Server-Send Events (SSEs) stream, with a text/event-stream Content-Type. Each new tracking result is represented as "TrackerData" JSON object, encapsulated in a new "data:" line as a JSON formated string, following the SSE format. When parsing the "TrackerData" JSON object, it is possible to extract a timestamp, a sequence number, an array of unidentified 3D points and an array of TargetsPoses containing the detected targets information.
- Data Object
| Key | Value Type | Description |
| data | JSON string | The data field for the message, containing the TrackerData JSON object. |
| TrackerData | JSON object | Container for all tracking results of one frame. |
| Points | array of DataPoint | Array of detected 3D markers not matched to a tracking target, as "DataPoint" JSON objects. |
| DataPoint | JSON object | Representation of a 3D point with an id, a position field and a detection region field. |
| id | int | Representation of a 3D point marker identifier. |
| position | JSON object | Representation of a 3D point coordinates x, y, and z as doubles. |
| DetectionRegion | string | Tracking region of the detected marker. Possible values: "Optimal", "Full". |
| TargetPoses | array of TargetPose | Array of detected tracking targets, represented as "TargetPose" JSON objects. |
| TargetPose | JSON object | Represent a target, with a TargetMatchingError, TransformationMatrix, it's id, name, UUID and detected 3D markers matched. |
| Points | array of DataPoint | Array of detected 3D markers matched to this tracking target, as "DataPoint" JSON objects. |
| TargetMatchingError | matching error | RMSE in meters between the observed marker points and the fitted target model. |
| TransformationMatrix | array of double | Tracking target pose as a row-major 4x4 transformation matrix. |
| seqnumber | int | Incremental data recording id. |
| timestamp | double | Timestamp of the moment the cameras captured the data. The timestamp uses the system clock provided in seconds since system boot (Windows) or Epoch (Linux). |
- Example
data: {
"TrackerData" : {
"Points" : [
{
"DataPoint" : {
"id" : 303,
"position" : {
"x" : 0.12679271,
"y" : 0.18989243,
"z" : -0.04876107
},
"DetectionRegion": "optimal"
}
},
{
"DataPoint" : {
"id" : 304,
"position" : {
"x" : 0.11064176,
"y" : 0.24031277,
"z" : -0.077169955
},
"DetectionRegion": "optimal"
}
}
],
"TargetPoses" : [
{
"TargetPose" : {
"Points" : [
{
"DataPoint" : {
"id" : 0,
"position" : {
"x" : -0.13181098,
"y" : 0.15336727,
"z" : -0.021862864
},
"DetectionRegion": "optimal"
}
},
{
"DataPoint" : {
"id" : 1,
"position" : {
"x" : -0.023771286,
"y" : 0.13360241,
"z" : -0.007646501
},
"DetectionRegion": "optimal"
}
},
{
"DataPoint" : {
"id" : 2,
"position" : {
"x" : -0.0639198,
"y" : 0.16175072,
"z" : -0.015122235
},
"DetectionRegion": "optimal"
}
},
{
"DataPoint" : {
"id" : 3,
"position" : {
"x" : -0.011663303,
"y" : 0.19799936,
"z" : -0.011572659
},
"DetectionRegion": "optimal"
}
}
],
"TargetMatchingError": 0.000861010747,
"TransformationMatrix" : [0.98451585, 0.14966916, -0.09125596, -0.057694428, -0.17010944, 0.94141203, -0.29121497, 0.16192964, 0.04232356, 0.30222926, 0.95229524, -0.012890403, 0, 0, 0, 1],
"id" : 1,
"name" : "Reference",
"uuid" : "0bb57673-7e1a-4f03-9bcd-f4f7c21f62be"
}
}
],
"seqnumber" : 0,
"timestamp" : 448693.88845280005
}
}
data: {
"TrackerData" : {
"Points" : [
{
"DataPoint" : {
"id" : 304,
"position" : {
"x" : 0.11064176,
"y" : 0.24031277,
"z" : -0.077169955
},
"DetectionRegion": "optimal"
}
}
],
"TargetPoses" : [
{
"TargetPose" : {
"Points" : [
{
"DataPoint" : {
"id" : 0,
"position" : {
"x" : -0.13181098,
"y" : 0.15336727,
"z" : -0.021862864
},
"DetectionRegion": "optimal"
}
},
{
"DataPoint" : {
"id" : 1,
"position" : {
"x" : -0.023771286,
"y" : 0.13360241,
"z" : -0.007646501
},
"DetectionRegion": "optimal"
}
},
{
"DataPoint" : {
"id" : 2,
"position" : {
"x" : -0.0639198,
"y" : 0.16175072,
"z" : -0.015122235
},
"DetectionRegion": "optimal"
}
},
{
"DataPoint" : {
"id" : 3,
"position" : {
"x" : -0.011663303,
"y" : 0.19799936,
"z" : -0.011572659
},
"DetectionRegion": "optimal"
}
}
],
"TargetMatchingError": 0.000861010747,
"TransformationMatrix" : [0.98451585, 0.14966916, -0.09125596, -0.057694428, -0.17010944, 0.94141203, -0.29121497, 0.16192964, 0.04232356, 0.30222926, 0.95229524, -0.012890403, 0, 0, 0, 1],
"id" : 1,
"name" : "Reference",
"uuid" : "0bb57673-7e1a-4f03-9bcd-f4f7c21f62be"
}
}
],
"seqnumber" : 1,
"timestamp" : 448693.9214528
}
}
...
- Verification table
| Status Code | Content Example | Meaning |
| 200 | JSON event stream "data:" | Stream of "data" objects containing the tracking result. |
| 429 | {"message":"TOO_MANY_DATA_STREAMS_ALREADY_OPENED"} | There are 15 data streams open already. cf. CloseDataStream |
| 500 | {"message":"TrackerException: <...>"} | An other type of internal error |
1.15.0 