Skip to content

Commit 5cf66ff

Browse files
MyzharMyzhar
authored
Update README.md
1 parent bd9ef01 commit 5cf66ff

File tree

1 file changed

+117
-92
lines changed

1 file changed

+117
-92
lines changed

‎README.md

Lines changed: 117 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -2,32 +2,34 @@
22
Open Capture Camera API
33
</h1>
44

5-
<h4 align="center">A platform-agnostic camera and sensor capture API for the ZED stereo camera family</h4>
5+
<h4 align="center">A platform-agnostic camera and sensor capture API for the <a href="https://www.stereolabs.com/products/zed-2">ZED 2, ZED 2i, and ZED Mini</a> stereo cameras</h4>
6+
<h5 align="center">*** not compatible with GMSL2 devices: <a href="https://www.stereolabs.com/products/zed-x">ZED X, ZED X Mini, and ZED X One</a> ***</h5>
67

78
<p align="center">
89
<a href="#key-features">Key Features</a> •
9-
<a href="#build">Build</a> •
10+
<a href="#build-and-install">Build and install</a> •
1011
<a href="#run">Run</a> •
1112
<a href="#documentation">Documentation</a> •
1213
<a href="#running-the-examples">Examples</a> •
14+
<a href="#known-issues">Known issues</a> •
1315
<a href="#related">Related</a> •
1416
<a href="#license">License</a>
1517
</p>
1618
<br>
1719

18-
1920
## Key Features
21+
2022
* Open source C++ capture library compatible with C++11 standard
2123
* Video Capture
22-
- YUV 4:2:2 data format
24+
- raw YUV 4:2:2 data format
2325
- Camera controls
24-
- HIGH-RESOLUTION mode (requires USB3)
25-
- VGA mode with USB2
26-
* Sensor Data Capture [Not available for ZED]
26+
- HIGH-RESOLUTION mode with USB3
27+
- compatibility VGA mode with USB2
28+
* Sensor Data Capture
2729
- 6-DOF IMU (3-DOF accelerometer + 3-DOF gyroscope)
28-
- 3-DOF Magnetometer [Only ZED2 and ZED2i]
29-
- Barometer [Only ZED2 and ZED2i]
30-
- Sensors temperature [Only ZED2 and ZED2i]
30+
- 3-DOF Magnetometer (Only ZED 2 and ZED 2i)
31+
- Barometer (Only ZED 2 and ZED 2i)
32+
- Sensors temperature (Only ZED 2 and ZED 2i)
3133
* Sensors/video Synchronization
3234
* Portable
3335
- Tested on Linux
@@ -40,38 +42,23 @@
4042
- Camera control
4143
- Stereo rectification
4244
- IMU, magnetometer, and barometer data capture
43-
- Video and sensors synchronization
45+
- Video and sensor synchronization
4446
- Disparity/Depth/Point Cloud extraction using OpenCV Transparent API
4547
- Depth tuning using OpenCV control GUI
4648

4749
## Description
4850

4951
The ZED Open Capture is a multi-platform, open-source C++ library for low-level camera and sensor capture for the ZED stereo camera family. It doesn't require CUDA and therefore can be used on many desktop and embedded platforms.
5052

51-
The open-source library provides methods to access raw video frames, calibration data, camera controls, and raw data from the camera sensors (on ZED 2, ZED 2i, and ZED Mini). A synchronization mechanism is provided to get the correct sensor data associated with a video frame.
52-
53-
**Note:** While in the ZED SDK all output data is calibrated and compensated, here the extracted raw data is not corrected by the camera and sensor calibration parameters. You can retrieve camera and sensor calibration data using the [ZED SDK](https://www.stereolabs.com/docs/video/camera-calibration/) to correct your camera data [see `zed_open_capture_rectify_example` example].
54-
55-
## Known issues
56-
57-
### OpenGL version
58-
On some embedded devices, like Raspberry pi 4, the depth extraction example can crash with the following error:
59-
60-
`vtkShaderProgram.cxx:438 ERR| vtkShaderProgram (0x23a611c0): 0:1(10): error: GLSL 1.50 is not supported. Supported versions are: 1.10, 1.20, 1.00 ES, and 3.00 ES`
53+
The open-source library provides methods to access raw video frames, calibration data, camera controls, and raw data from the USB3 camera sensors (on ZED 2, ZED 2i, and ZED Mini). A synchronization mechanism is provided to get the correct sensor data associated with a video frame.
6154

62-
to correctly execute the example application it is necessary to change the default OpenGL version:
55+
**Note:** While in the ZED SDK all output data is calibrated and compensated, here the extracted raw data is not corrected by the camera and sensor calibration parameters. You can retrieve camera and sensor calibration data using the [ZED SDK](https://www.stereolabs.com/docs/video/camera-calibration/) to correct your camera data [see `zed_open_capture_rectify_example` example](#running-the-examples).
6356

64-
```
65-
export MESA_GL_VERSION_OVERRIDE=3.2
66-
```
67-
68-
you can permanently add this configuration by adding the above command as the last line of the `~/.bashrc` file.
69-
70-
## Build
57+
## Build and install
7158

7259
### Prerequisites
7360

74-
* Stereo camera: [ZED 2i](https://www.stereolabs.com/zed-2i/), [ZED 2](https://www.stereolabs.com/zed-2/), [ZED](https://www.stereolabs.com/zed/), [ZED Mini](https://www.stereolabs.com/zed-mini/)
61+
* USB3 Stereolabs Stereo camera: [ZED 2i](https://www.stereolabs.com/zed-2i/), [ZED 2](https://www.stereolabs.com/zed-2/), [ZED](https://www.stereolabs.com/zed/), [ZED Mini](https://www.stereolabs.com/zed-mini/)
7562
* Linux OS
7663
* GCC (v7.5+)
7764
* CMake (v3.1+)
@@ -81,91 +68,114 @@ you can permanently add this configuration by adding the above command as the la
8168

8269
* Install GCC compiler and build tools
8370

84-
`$ sudo apt install build-essential`
71+
`sudo apt install build-essential`
8572

8673
* Install CMake build system
8774

88-
`$ sudo apt install cmake`
75+
`sudo apt install cmake`
8976

9077
* Install HIDAPI and LIBUSB libraries:
9178

92-
`$ sudo apt install libusb-1.0-0-dev libhidapi-libusb0 libhidapi-dev`
79+
`sudo apt install libusb-1.0-0-dev libhidapi-libusb0 libhidapi-dev`
9380

9481
* Install OpenCV to build the examples (optional)
9582

96-
`$ sudo apt install libopencv-dev libopencv-viz-dev`
83+
`sudo apt install libopencv-dev libopencv-viz-dev`
9784

9885
### Clone the repository
9986

100-
$ git clone https://github.com/stereolabs/zed-open-capture.git
101-
$ cd zed-open-capture
87+
```bash
88+
git clone https://github.com/stereolabs/zed-open-capture.git
89+
cd zed-open-capture
90+
```
10291

10392
### Add udev rule
93+
10494
Stereo cameras such as ZED 2 and ZED Mini have built-in sensors (e.g. IMU) that are identified as USB HID devices.
10595
To be able to access the USB HID device, you must add a udev rule contained in the `udev` folder:
10696

107-
$ cd udev
108-
$ bash install_udev_rule.sh
109-
$ cd ..
97+
```bash
98+
cd udev
99+
bash install_udev_rule.sh
100+
cd ..
101+
```
110102

111103
### Build
112104

113105
#### Build library and examples
114106

115-
$ mkdir build
116-
$ cd build
117-
$ cmake ..
118-
$ make -j$(nproc)
107+
```bash
108+
mkdir build
109+
cd build
110+
cmake ..
111+
make -j$(nproc)
112+
```
119113

120114
#### Build only the library
121115

122-
$ mkdir build
123-
$ cd build
124-
$ cmake .. -DBUILD_EXAMPLES=OFF
125-
$ make -j$(nproc)
116+
```bash
117+
mkdir build
118+
cd build
119+
cmake .. -DBUILD_EXAMPLES=OFF
120+
make -j$(nproc)
121+
```
126122

127123
#### Build only the video capture library
128124

129-
$ mkdir build
130-
$ cd build
131-
$ cmake .. -DBUILD_SENSORS=OFF -DBUILD_EXAMPLES=OFF
132-
$ make -j$(nproc)
125+
```bash
126+
mkdir build
127+
cd build
128+
cmake .. -DBUILD_SENSORS=OFF -DBUILD_EXAMPLES=OFF
129+
make -j$(nproc)
130+
```
133131

134132
#### Build only the sensor capture library
135133

136-
$ mkdir build
137-
$ cd build
138-
$ cmake .. -DBUILD_VIDEO=OFF -DBUILD_EXAMPLES=OFF
139-
$ make -j$(nproc)
134+
```bash
135+
mkdir build
136+
cd build
137+
cmake .. -DBUILD_VIDEO=OFF -DBUILD_EXAMPLES=OFF
138+
make -j$(nproc)
139+
```
140140

141-
## Run
141+
### Install
142142

143143
To install the library, go to the `build` folder and launch the following commands:
144144

145-
$ sudo make install
146-
$ sudo ldconfig
145+
```bash
146+
sudo make install
147+
sudo ldconfig
148+
```
149+
150+
## Run
147151

148152
### Get video data
149153

150-
Include the `videocapture.hpp` header, declare a `VideoCapture` object and retrieve a video frame (in YUV 4:2:2 format) with `getLastFrame()`:
154+
Include the `videocapture.hpp` header, declare a `VideoCapture` object, and retrieve a video frame (in YUV 4:2:2 format) with `getLastFrame()`:
151155

152-
#include "videocapture.hpp"
153-
sl_oc::video::VideoCapture cap;
154-
cap.initializeVideo();
155-
const sl_oc::video::Frame frame = cap.getLastFrame();
156+
```C++
157+
#include "videocapture.hpp"
158+
159+
sl_oc::video::VideoCapture cap;
160+
cap.initializeVideo();
161+
const sl_oc::video::Frame frame = cap.getLastFrame();
162+
```
156163

157-
### Get sensors data
158-
159-
Include the `SensorCapture` header, declare a `SensorCapture` object, get a list of available devices, initialize the first one, and finally retrieve sensors data:
160-
161-
#include "sensorcapture.hpp"
162-
sl_oc::sensors::SensorCapture sens;
163-
std::vector<int> devs = sens.getDeviceList();
164-
sens.initializeSensors( devs[0] );
165-
const sl_oc::sensors::data::Imu imuData = sens.getLastIMUData(5000);
166-
const sl_oc::sensors::data::Magnetometer magData = sens.getLastMagnetometerData(100);
167-
const sl_oc::sensors::data::Environment envData = sens.getLastEnvironmentData(100);
168-
const sl_oc::sensors::data::Temperature tempData = sens.getLastCameraTemperatureData(100);
164+
### Get sensor data
165+
166+
Include the `SensorCapture` header, declare a `SensorCapture` object, get a list of available devices, initialize the first one, and finally retrieve sensor data:
167+
168+
```C++
169+
#include "sensorcapture.hpp"
170+
171+
sl_oc::sensors::SensorCapture sens;
172+
std::vector<int> devs = sens.getDeviceList();
173+
sens.initializeSensors( devs[0] );
174+
const sl_oc::sensors::data::Imu imuData = sens.getLastIMUData(5000);
175+
const sl_oc::sensors::data::Magnetometer magData = sens.getLastMagnetometerData(100);
176+
const sl_oc::sensors::data::Environment envData = sens.getLastEnvironmentData(100);
177+
const sl_oc::sensors::data::Temperature tempData = sens.getLastCameraTemperatureData(100);
178+
```
169179

170180
## Running the examples
171181

@@ -180,17 +190,17 @@ After installing the library and examples, you will have the following sample ap
180190
* [zed_open_capture_depth_example](https://github.com/stereolabs/zed-open-capture/blob/master/examples/zed_oc_depth_example.cpp): This application captures and displays video frames, calculates disparity map, then extracts the depth map and the point cloud displaying the result and the estimation of the performance.
181191
* [zed_open_capture_depth_tune_stereo](https://github.com/stereolabs/zed-open-capture/blob/master/examples/tools/zed_oc_tune_stereo_sgbm.cpp): This application captures the first available stereo frames and provides GUI Controls to tune the disparity map results and save them to be used in the `zed_open_capture_depth_example` example
182192

183-
To run the examples, open a terminal console and enter the following commands:
184-
185-
```
186-
$ zed_open_capture_video_example
187-
$ zed_open_capture_multicam_video_example
188-
$ zed_open_capture_control_example
189-
$ zed_open_capture_rectify_example
190-
$ zed_open_capture_sensors_example
191-
$ zed_open_capture_sync_example
192-
$ zed_open_capture_depth_example
193-
$ zed_open_capture_depth_tune_stereo
193+
To run the examples, open a terminal console and enter one of the following commands:
194+
195+
```bash
196+
zed_open_capture_video_example
197+
zed_open_capture_multicam_video_example
198+
zed_open_capture_control_example
199+
zed_open_capture_rectify_example
200+
zed_open_capture_sensors_example
201+
zed_open_capture_sync_example
202+
zed_open_capture_depth_example
203+
zed_open_capture_depth_tune_stereo
194204
```
195205

196206
**Note:** OpenCV is used in the examples for controls, display, and depth extraction.
@@ -202,19 +212,33 @@ The API is documented in the Include.h files. It is also generated as a Doxygen
202212

203213
You can also generate the documentation locally in HTML format (with Doxygen) using the commands below. Access the docs by opening `doc/html/index.html` in your web browser.
204214

205-
​
206-
$ sudo apt-get install -y doxygen # if not previously installed
207-
$ cd doc
208-
$ ./generate_doc.sh
209-
210-
215+
```bash
216+
sudo apt-get install -y doxygen # if not previously installed
217+
cd doc
218+
./generate_doc.sh
219+
```
211220

212221
## Coordinates system
213222

214223
The coordinate system is only used for sensor data. The given IMU and Magnetometer data are expressed in the RAW coordinate system as shown below
215224

216225
![](./images/imu_axis.jpg)
217226

227+
## Known issues
228+
229+
### OpenGL version
230+
On some embedded devices, like Raspberry Pi 4, the depth extraction example can crash with the following error:
231+
232+
`vtkShaderProgram.cxx:438 ERR| vtkShaderProgram (0x23a611c0): 0:1(10): error: GLSL 1.50 is not supported. Supported versions are: 1.10, 1.20, 1.00 ES, and 3.00 ES`
233+
234+
to correctly execute the example application it is necessary to change the default OpenGL version:
235+
236+
```
237+
export MESA_GL_VERSION_OVERRIDE=3.2
238+
```
239+
240+
you can permanently add this configuration by adding the above command as the last line of the `~/.bashrc` file.
241+
218242
## Related
219243

220244
- [Stereolabs](https://www.stereolabs.com)
@@ -226,5 +250,6 @@ The coordinate system is only used for sensor data. The given IMU and Magnetomet
226250
This library is licensed under the MIT License.
227251

228252
## Support
253+
229254
If you need assistance go to our Community site at https://community.stereolabs.com/
230255

0 commit comments

Comments
 (0)