Using the Sensors API

The Sensors API lets you access sensors available on ZED depth cameras and perform a wide variety of sensor-related tasks explained below.

Getting Sensors Data

The data from the different sensors are accessible with the SensorsData class. The class contains raw and calibrated values of each sensor.

To retrieve sensor values synchronized with the image frames, you will need to:

Open the camera and grab the current image.
Get sensor data corresponding to this image using TIME_REFERENCE::IMAGE.
Retrieve data from the different sensors.

1 // Create and open the camera
2 Camera zed;
3 zed.open();
4 SensorsData sensors_data;
5 
6 // Grab new frames and retrieve sensors data
7 while (zed.grab() == ERROR_CODE::SUCCESS) {
8     zed.getSensorsData(sensors_data, TIME_REFERENCE::IMAGE); // Get frame synchronized sensor data
9 
10     // Extract multi-sensor data
11     imu_data = sensors_data.imu;
12     barometer_data = sensors_data.barometer;
13     magnetometer_data = sensors_data.magnetometer;
14 
15     // Retrieve linear acceleration and angular velocity
16     float3 linear_acceleration = imu_data.linear_acceleration;
17     float3 angular_velocity = imu_data.angular_velocity;
18 
19     // Retrieve pressure and relative altitude
20     float pressure = barometer_data.pressure;
21     float relative_altitude = barometer_data.relative_altitude;
22 
23     // Retrieve magnetic field
24     float3 magnetic_field = magnetometer_data.magnetic_field_uncalibrated;
25 }

Time Reference

The function getSensorsData can be called with a TIME_REFERENCE. For example, you can use TIME_REFERENCE::CURRENT to get the sensor data corresponding to the timestamp of the function call, or TIME_REFERENCE::IMAGE to get the data synchronized with the current camera image.

For more information on sensor time reference, read the Sensors Time Synchronization section.

Retrieve New Sensor Data

To retrieve updated sensor data, getSensorsData must be called at a frequency superior to or equal to the sensor data rate. Since sensors have different frequencies and their data is stored in the same sensors_data structure, some sensor data might not be updated between two calls to getSensorsData.

To know if a given sensor data has been updated, we compare their timestamps which are used as unique identifiers. If they are the same, then the sensor data has not been updated.

1 Timestamp last_imu_ts = 0;
2 while (zed.grab() == ERROR_CODE::SUCCESS) {
3     zed.getSensorsData(sensors_data, TIME_REFERENCE::IMAGE);
4 
5     // Check if a new IMU sample is available
6     if (sensors_data.imu.timestamp > last_imu_ts) {
7         cout << "Linear Acceleration: " << sensors_data.imu.linear_acceleration << endl;
8         cout << "Angular Velocity: " << sensors_data.imu.angular_velocity << endl;
9         last_imu_ts = sensors_data.imu.timestamp;
10     }
11 }

Accessing Raw Sensor Data

The Sensors API lets you read raw data from the depth camera’s built-in motion and position sensors. To retrieve raw data, use the uncalibrated values present in sensors_data structure.

Identifying Sensors Capabilities

Sensors factory parameters can be accessed through the API. They cannot be changed as they are fixed in the microcontroller firmware of the cameras. You can access the following parameters:

Sensor Type
Sampling Rate
Range
Resolution
Noise Density
Random Walk (if applicable)
Sensor Units

1 // Display camera information (model, serial number, firmware version)
2 auto info = zed.getCameraInformation();
3 cout << "Camera Model: " << info.camera_model << endl;
4 cout << "Serial Number: " << info.serial_number << endl;
5 cout << "Camera Firmware: " << info.camera_configuration.firmware_version << endl;
6 cout << "Sensors Firmware: " << info.sensors_configuration.firmware_version << endl;
7 
8 // Display accelerometer sensor configuration
9 SensorParameters& sensor_parameters = info.sensors_configuration.accelerometer_parameters;
10 cout << "Sensor Type: " << sensor_parameters.type << endl;
11 cout << "Sampling Rate: " << sensor_parameters.sampling_rate << endl;
12 cout << "Range: "       << sensor_parameters.range << endl;
13 cout << "Resolution: "  << sensor_parameters.resolution << endl;
14 if (isfinite(sensor_parameters.noise_density)) cout << "Noise Density: " << sensor_parameters.noise_density << endl;
15 if (isfinite(sensor_parameters.random_walk)) cout << "Random Walk: " << sensor_parameters.random_walk << endl;

Code Example

For a code example, check out the Getting Sensor Data tutorial.