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	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	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": 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"}	There are 15 data streams open already. cf. CloseDataStream
500	{"message":"TrackerException: <...>"}	An other type of internal error