PST SDK  6.0.0.0-272350a
StartTrackerDataStream

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 and a position fields.
id int Representation of a 3D point marker identifier.
position JSON object Representation of a 3D point coordinates x, y, and z as doubles.
TargetPoses array of TargetPose Array of detected tracking targets, represented as "TargetPose" JSON objects.
TargetPose JSON object Represent a target, with a 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.
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
      }
      }
    },
    {
      "DataPoint" : {
      "id" : 304,
      "position" : {
        "x" : 0.11064176,
        "y" : 0.24031277,
        "z" : -0.077169955
      }
      }
    }
    ],
    "TargetPoses" : [
    {
      "TargetPose" : {
      "Points" : [
        {
        "DataPoint" : {
          "id" : 0,
          "position" : {
          "x" : -0.13181098,
          "y" : 0.15336727,
          "z" : -0.021862864
          }
        }
        },
        {
        "DataPoint" : {
          "id" : 1,
          "position" : {
          "x" : -0.023771286,
          "y" : 0.13360241,
          "z" : -0.007646501
          }
        }
        },
        {
        "DataPoint" : {
          "id" : 2,
          "position" : {
          "x" : -0.0639198,
          "y" : 0.16175072,
          "z" : -0.015122235
          }
        }
        },
        {
        "DataPoint" : {
          "id" : 3,
          "position" : {
          "x" : -0.011663303,
          "y" : 0.19799936,
          "z" : -0.011572659
          }
        }
        }
      ],
      "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 } } } ], "TargetPoses" : [ { "TargetPose" : { "Points" : [ { "DataPoint" : { "id" : 0, "position" : { "x" : -0.13181098, "y" : 0.15336727, "z" : -0.021862864 } } }, { "DataPoint" : { "id" : 1, "position" : { "x" : -0.023771286, "y" : 0.13360241, "z" : -0.007646501 } } }, { "DataPoint" : { "id" : 2, "position" : { "x" : -0.0639198, "y" : 0.16175072, "z" : -0.015122235 } } }, { "DataPoint" : { "id" : 3, "position" : { "x" : -0.011663303, "y" : 0.19799936, "z" : -0.011572659 } } } ], "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