← Back to branch summary

~paparazzi-uav/paparazzi/v5.0-manual

« back to all changes in this revision

Viewing changes to sw/ext/opencv_bebop/opencv/doc/tutorials/highgui/kinect_openni.markdown

  • Committer: Paparazzi buildbot
  • Date: 2016-05-18 15:00:29 UTC
  • Revision ID: felix.ruess+docbot@gmail.com-20160518150029-e8lgzi5kvb4p7un9
Manual import commit 4b8bbb730080dac23cf816b98908dacfabe2a8ec from v5.0 branch.

Show diffs side-by-side

added added

removed removed

Lines of Context:
sw/ext/opencv_bebop/opencv/doc/tutorials/highgui/kinect_openni.markdown
 
1
Using Kinect and other OpenNI compatible depth sensors {#tutorial_kinect_openni}
 
2
======================================================
 
3
 
 
4
Depth sensors compatible with OpenNI (Kinect, XtionPRO, ...) are supported through VideoCapture
 
5
class. Depth map, BGR image and some other formats of output can be retrieved by using familiar
 
6
interface of VideoCapture.
 
7
 
 
8
In order to use depth sensor with OpenCV you should do the following preliminary steps:
 
9
 
 
10
-#  Install OpenNI library (from here <http://www.openni.org/downloadfiles>) and PrimeSensor Module
 
11
    for OpenNI (from here <https://github.com/avin2/SensorKinect>). The installation should be done
 
12
    to default folders listed in the instructions of these products, e.g.:
 
13
    @code{.text}
 
14
    OpenNI:
 
15
        Linux & MacOSX:
 
16
            Libs into: /usr/lib
 
17
            Includes into: /usr/include/ni
 
18
        Windows:
 
19
            Libs into: c:/Program Files/OpenNI/Lib
 
20
            Includes into: c:/Program Files/OpenNI/Include
 
21
    PrimeSensor Module:
 
22
        Linux & MacOSX:
 
23
            Bins into: /usr/bin
 
24
        Windows:
 
25
            Bins into: c:/Program Files/Prime Sense/Sensor/Bin
 
26
    @endcode
 
27
    If one or both products were installed to the other folders, the user should change
 
28
    corresponding CMake variables OPENNI_LIB_DIR, OPENNI_INCLUDE_DIR or/and
 
29
    OPENNI_PRIME_SENSOR_MODULE_BIN_DIR.
 
30
 
 
31
-#  Configure OpenCV with OpenNI support by setting WITH_OPENNI flag in CMake. If OpenNI is found
 
32
    in install folders OpenCV will be built with OpenNI library (see a status OpenNI in CMake log)
 
33
    whereas PrimeSensor Modules can not be found (see a status OpenNI PrimeSensor Modules in CMake
 
34
    log). Without PrimeSensor module OpenCV will be successfully compiled with OpenNI library, but
 
35
    VideoCapture object will not grab data from Kinect sensor.
 
36
 
 
37
-#  Build OpenCV.
 
38
 
 
39
VideoCapture can retrieve the following data:
 
40
 
 
41
-#  data given from depth generator:
 
42
    -   CAP_OPENNI_DEPTH_MAP - depth values in mm (CV_16UC1)
 
43
    -   CAP_OPENNI_POINT_CLOUD_MAP - XYZ in meters (CV_32FC3)
 
44
    -   CAP_OPENNI_DISPARITY_MAP - disparity in pixels (CV_8UC1)
 
45
    -   CAP_OPENNI_DISPARITY_MAP_32F - disparity in pixels (CV_32FC1)
 
46
    -   CAP_OPENNI_VALID_DEPTH_MASK - mask of valid pixels (not ocluded, not shaded etc.)
 
47
        (CV_8UC1)
 
48
 
 
49
-#  data given from BGR image generator:
 
50
    -   CAP_OPENNI_BGR_IMAGE - color image (CV_8UC3)
 
51
    -   CAP_OPENNI_GRAY_IMAGE - gray image (CV_8UC1)
 
52
 
 
53
In order to get depth map from depth sensor use VideoCapture::operator \>\>, e. g. :
 
54
@code{.cpp}
 
55
    VideoCapture capture( CAP_OPENNI );
 
56
    for(;;)
 
57
    {
 
58
        Mat depthMap;
 
59
        capture >> depthMap;
 
60
 
 
61
        if( waitKey( 30 ) >= 0 )
 
62
            break;
 
63
    }
 
64
@endcode
 
65
For getting several data maps use VideoCapture::grab and VideoCapture::retrieve, e.g. :
 
66
@code{.cpp}
 
67
    VideoCapture capture(0); // or CAP_OPENNI
 
68
    for(;;)
 
69
    {
 
70
        Mat depthMap;
 
71
        Mat bgrImage;
 
72
 
 
73
        capture.grab();
 
74
 
 
75
        capture.retrieve( depthMap, CAP_OPENNI_DEPTH_MAP );
 
76
        capture.retrieve( bgrImage, CAP_OPENNI_BGR_IMAGE );
 
77
 
 
78
        if( waitKey( 30 ) >= 0 )
 
79
            break;
 
80
    }
 
81
@endcode
 
82
For setting and getting some property of sensor\` data generators use VideoCapture::set and
 
83
VideoCapture::get methods respectively, e.g. :
 
84
@code{.cpp}
 
85
    VideoCapture capture( CAP_OPENNI );
 
86
    capture.set( CAP_OPENNI_IMAGE_GENERATOR_OUTPUT_MODE, CAP_OPENNI_VGA_30HZ );
 
87
    cout << "FPS    " << capture.get( CAP_OPENNI_IMAGE_GENERATOR+CAP_PROP_FPS ) << endl;
 
88
@endcode
 
89
Since two types of sensor's data generators are supported (image generator and depth generator),
 
90
there are two flags that should be used to set/get property of the needed generator:
 
91
 
 
92
-   CAP_OPENNI_IMAGE_GENERATOR -- A flag for access to the image generator properties.
 
93
-   CAP_OPENNI_DEPTH_GENERATOR -- A flag for access to the depth generator properties. This flag
 
94
    value is assumed by default if neither of the two possible values of the property is not set.
 
95
 
 
96
Some depth sensors (for example XtionPRO) do not have image generator. In order to check it you can
 
97
get CAP_OPENNI_IMAGE_GENERATOR_PRESENT property.
 
98
@code{.cpp}
 
99
bool isImageGeneratorPresent = capture.get( CAP_PROP_OPENNI_IMAGE_GENERATOR_PRESENT ) != 0; // or == 1
 
100
@endcode
 
101
Flags specifing the needed generator type must be used in combination with particular generator
 
102
property. The following properties of cameras available through OpenNI interfaces are supported:
 
103
 
 
104
-   For image generator:
 
105
 
 
106
    -   CAP_PROP_OPENNI_OUTPUT_MODE -- Three output modes are supported: CAP_OPENNI_VGA_30HZ
 
107
        used by default (image generator returns images in VGA resolution with 30 FPS),
 
108
        CAP_OPENNI_SXGA_15HZ (image generator returns images in SXGA resolution with 15 FPS) and
 
109
        CAP_OPENNI_SXGA_30HZ (image generator returns images in SXGA resolution with 30 FPS, the
 
110
        mode is supported by XtionPRO Live); depth generator's maps are always in VGA resolution.
 
111
 
 
112
-   For depth generator:
 
113
 
 
114
    -   CAP_PROP_OPENNI_REGISTRATION -- Flag that registers the remapping depth map to image map
 
115
        by changing depth generator's view point (if the flag is "on") or sets this view point to
 
116
        its normal one (if the flag is "off"). The registration process’s resulting images are
 
117
        pixel-aligned,which means that every pixel in the image is aligned to a pixel in the depth
 
118
        image.
 
119
 
 
120
        Next properties are available for getting only:
 
121
 
 
122
    -   CAP_PROP_OPENNI_FRAME_MAX_DEPTH -- A maximum supported depth of Kinect in mm.
 
123
    -   CAP_PROP_OPENNI_BASELINE -- Baseline value in mm.
 
124
    -   CAP_PROP_OPENNI_FOCAL_LENGTH -- A focal length in pixels.
 
125
    -   CAP_PROP_FRAME_WIDTH -- Frame width in pixels.
 
126
    -   CAP_PROP_FRAME_HEIGHT -- Frame height in pixels.
 
127
    -   CAP_PROP_FPS -- Frame rate in FPS.
 
128
 
 
129
-   Some typical flags combinations "generator type + property" are defined as single flags:
 
130
 
 
131
    -   CAP_OPENNI_IMAGE_GENERATOR_OUTPUT_MODE = CAP_OPENNI_IMAGE_GENERATOR + CAP_PROP_OPENNI_OUTPUT_MODE
 
132
    -   CAP_OPENNI_DEPTH_GENERATOR_BASELINE = CAP_OPENNI_DEPTH_GENERATOR + CAP_PROP_OPENNI_BASELINE
 
133
    -   CAP_OPENNI_DEPTH_GENERATOR_FOCAL_LENGTH = CAP_OPENNI_DEPTH_GENERATOR + CAP_PROP_OPENNI_FOCAL_LENGTH
 
134
    -   CAP_OPENNI_DEPTH_GENERATOR_REGISTRATION = CAP_OPENNI_DEPTH_GENERATOR + CAP_PROP_OPENNI_REGISTRATION
 
135
 
 
136
For more information please refer to the example of usage
 
137
[openni_capture.cpp](https://github.com/Itseez/opencv/tree/master/samples/cpp/openni_capture.cpp) in
 
138
opencv/samples/cpp folder.