| 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