Retrieves real time tracking results by subscribing to an event stream.

The PST Rest server implements a Server-Send Events (SSEs) communication channel. When an 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 doesn't allow to have more than 2 tracking result streams open at the same time. It is possible to close all currently opened data streams using PSTapi/CloseDataStream or PSTapi/CloseStreams. If a client closes the connection or doesn't 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	JSON object	Vector 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
position	JSON object	Representation of a 3D point coordinates x, y, and z as doubles
TargetPoses	JSON object	Vector of detected tracking targets, represented as "TargetPose" Json objects
TargetPose	JSON object	Represent a target, with a TransformationMatrix, it's id, name and uuid.
TransformationMatrix	array of double	Tracking target pose as a row-major 4x4 transformation matrix
seqnumber	int	Incremental data recording id
timestamp	double	Time the data was recorded

Example

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

  data: {
    "TrackerData": {
      "Points": [
        {
          "DataPoint": {
            "id": 6482,
            "position": {
              "x": 0.036606535315513611,
              "y": -0.057408709079027176,
              "z": -0.4420783519744873
            }
          }
        }
      ],
      "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": 28,
      "timestamp": 1628442.1564851354
    }
  }

  ...

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"}	Their is already 2 data stream open. cf. CloseDataStream
500	{"message":"TrackerException: <...>"}	an other type of internal error