4 Retrieving Stream Data

Stream Types

The Astra SDK comes “stock” with a variety of stream types. Low-level stream types are generated by the sensor and passed along through the SDK to an application. Higher-level stream types are efficiently computed from low-level stream types by SDK plugins. In general, higher-level streams should be preferred to the low-level ones when they can be used.

Low Level

Stream Type Description
ColorStream RGB pixel data from the sensor. The data array included in each ColorFrame contains values ranging from 0-255 for each color component of each pixel.
DepthStream Depth data from the sensor. The data array included in each DepthFrame contains values in millimeters for each pixel within the sensor’s field of view.

Higher-Level

Stream Type Description
PointStream World coordinates (XYZ) computed from the depth data. The data array included in each PointFrame is an array of astra:Vector3f elements to more easily access the x, y and z values for each pixel.
HandStream Hand points computed from the depth data. On each HandFrame, the number of points detected at any given time can be retrieved through the HandFrame::handpoint_count function, and a astra::HandFrame::HandPointList can be retrieved through the HandFrame::handpoints function.

Getting the Data

Two methods are provided by the Astra SDK to get stream data. Depending on your particular use case and the complexity of your application, one method may be better suited than the other.

Polling

The polling method for getting frame data is the most direct method for getting stream data, and is also the method used in the Hello World tutorial. To use this method, you only need to call the get_latest_frame function on the StreamReader, then use the templated get<T> function on the returned frame to retrieve specific frame types. “T” in this case must be a valid frame type. The get_latest_frame function is blocking, so application execution will suspend until a new frame is returned. A timeout can be passed as a parameter to the get_latest_frame function if you want to limit the amount of time that the SDK will wait for a new frame to arrive.

astra::initialize();

astra::StreamSet streamSet;
astra::StreamReader reader = streamSet.create_reader();

reader.stream<astra::DepthStream>().start();

astra::Frame frame = reader.get_latest_frame();
const auto depthFrame = frame.get<astra::DepthFrame>();

astra::terminate();
  • Retrieving a depth frame using the polling method

Listening

The listening method for getting frame data requires a small amount of additional setup, but allows the developer to delegate the handling of a frame to one or more separate classes. The Astra SDK provides an abstract class called FrameListener which implements a single function called FrameListener::on_frame_ready. FrameListener::on_frame_ready is called as soon as the frame is ready for processing and passed a reference to that frame.

class DepthFrameListener : public astra::FrameListener
{
   virtual void on_frame_ready(astra::StreamReader& reader,
                               astra::Frame& frame) override
   {
      const astra::DepthFrame depthFrame = frame.get<astra::DepthFrame>();

      if (depthFrame.is_valid())
      {
         // do all the things
      }
   }
};
  • An example of a listener class derived from frame_listener

After defining a listener class, in order to use it you must instantiate the listener in your application and add it to the StreamReader using the StreamReader::add_listener function.

astra::initialize();

astra::StreamSet streamSet;
astra::StreamReader reader = streamSet.create_reader();

reader.stream<astra::DepthStream>().start();

DepthFrameListener listener;
reader.add_listener(listener);

while(true)
{
   astra_update();
}
  • Example usage of a listener. In practice, the loop over astra_update should only execute until the application is closed or another application-specific event takes place.

Once the listener is added, we need to pump the SDK’s event loop using the astra_update function. Doing this allows the SDK to check if a frame is available, and if so will, in this case, call the DepthFrameListener::on_frame_ready function and pass along a reference to the latest frame.

For a more practical example of a listener, continue on to our Simple Depth Reader Tutorial.