modified documentation about using OpenNI wrapper #1657

diff --git a/doc/user_guide/ug_highgui.rst b/doc/user_guide/ug_highgui.rst
index a49dd3d..7afcaa9 100644 (file)
--- a/doc/user_guide/ug_highgui.rst
+++ b/doc/user_guide/ug_highgui.rst
@@ -4,15 +4,15 @@ HighGUI
 
 .. highlight:: cpp
 
-Using Kinect sensor
+Using depth sensors
 ===================
 
-Kinect sensor is supported through ``VideoCapture`` class. Depth map, RGB image and some other formats of Kinect output can be retrieved by using familiar interface of ``VideoCapture``.
+Depth sensors compatible with OpenNI (Kinect, XtionPRO, ...) are supported through ``VideoCapture`` class. Depth map, RGB image and some other formats of output can be retrieved by using familiar interface of ``VideoCapture``.
 
-In order to use Kinect with OpenCV you should do the following preliminary steps:
+In order to use depth sensor with OpenCV you should do the following preliminary steps:
 
 #.
-    Install OpenNI library (from here \url{http://www.openni.org/downloadfiles}) and PrimeSensor Module for OpenNI (from here https://github.com/avin2/SensorKinect}). The installation should be done to default folders listed in the instructions of these products, e.g.:
+    Install OpenNI library (from here http://www.openni.org/downloadfiles) and PrimeSensor Module for OpenNI (from here https://github.com/avin2/SensorKinect). The installation should be done to default folders listed in the instructions of these products, e.g.:
 
     .. code-block:: text
     
@@ -32,12 +32,12 @@ In order to use Kinect with OpenCV you should do the following preliminary steps
     If one or both products were installed to the other folders, the user should change corresponding CMake variables ``OPENNI_LIB_DIR``, ``OPENNI_INCLUDE_DIR`` or/and ``OPENNI_PRIME_SENSOR_MODULE_BIN_DIR``.
     
 #.
-    Configure OpenCV with OpenNI support by setting \texttt{WITH\_OPENNI} flag in CMake. If OpenNI is found in install folders OpenCV will be built with OpenNI library (see a status ``OpenNI`` in CMake log) whereas PrimeSensor Modules can not be found (see a status ``OpenNI PrimeSensor Modules`` in CMake log). Without PrimeSensor module OpenCV will be successfully compiled with OpenNI library, but ``VideoCapture`` object will not grab data from Kinect sensor.
+    Configure OpenCV with OpenNI support by setting ``WITH_OPENNI`` flag in CMake. If OpenNI is found in install folders OpenCV will be built with OpenNI library (see a status ``OpenNI`` in CMake log) whereas PrimeSensor Modules can not be found (see a status ``OpenNI PrimeSensor Modules`` in CMake log). Without PrimeSensor module OpenCV will be successfully compiled with OpenNI library, but ``VideoCapture`` object will not grab data from Kinect sensor.
 
 #.
     Build OpenCV.
 
-VideoCapture can retrieve the following Kinect data:
+VideoCapture can retrieve the following data:
 
 #.
     data given from depth generator:
@@ -51,7 +51,7 @@ VideoCapture can retrieve the following Kinect data:
       * ``OPENNI_BGR_IMAGE``          - color image (CV_8UC3)
       * ``OPENNI_GRAY_IMAGE``         - gray image (CV_8UC1)
 
-In order to get depth map from Kinect use ``VideoCapture::operator >>``, e. g. ::
+In order to get depth map from depth sensor use ``VideoCapture::operator >>``, e. g. ::
 
     VideoCapture capture( CV_CAP_OPENNI );
     for(;;)
@@ -63,7 +63,7 @@ In order to get depth map from Kinect use ``VideoCapture::operator >>``, e. g. :
             break;
     }
 
-For getting several Kinect maps use ``VideoCapture::grab`` and ``VideoCapture::retrieve``, e.g. ::
+For getting several data maps use ``VideoCapture::grab`` and ``VideoCapture::retrieve``, e.g. ::
 
     VideoCapture capture(0); // or CV_CAP_OPENNI
     for(;;)
@@ -80,30 +80,36 @@ For getting several Kinect maps use ``VideoCapture::grab`` and ``VideoCapture::r
             break;
     }
 
-For setting and getting some property of Kinect data generators use ``VideoCapture::set`` and ``VideoCapture::get`` methods respectively, e.g. ::
+For setting and getting some property of sensor` data generators use ``VideoCapture::set`` and ``VideoCapture::get`` methods respectively, e.g. ::
 
     VideoCapture capture( CV_CAP_OPENNI );    
     capture.set( CV_CAP_OPENNI_IMAGE_GENERATOR_OUTPUT_MODE, CV_CAP_OPENNI_VGA_30HZ );
     cout << "FPS    " << capture.get( CV_CAP_OPENNI_IMAGE_GENERATOR+CV_CAP_PROP_FPS ) << endl;
 
-Since two types of Kinect's data generators are supported (image generator and depth generator), there are two flags that should be used to set/get property of the needed generator:
+Since two types of sensor's data generators are supported (image generator and depth generator), there are two flags that should be used to set/get property of the needed generator:
 
 * CV_CAP_OPENNI_IMAGE_GENERATOR -- A flag for access to the image generator properties.
 
 * CV_CAP_OPENNI_DEPTH_GENERATOR -- A flag for access to the depth generator properties. This flag value is assumed by default if neither of the two possible values of the property is not set.
 
+Some depth sensors (for example XtionPRO) do not have image generator. In order to check it you can get ``CV_CAP_OPENNI_PROP_IMAGE_GENERATOR_PRESENT`` property. If returned value greater than zero sensor has image generator.
+::
+
+    bool isImageGeneratorPresent = capture.get( CV_CAP_OPENNI_PROP_IMAGE_GENERATOR_PRESENT ) > 0;
+
+
 Flags specifing the needed generator type must be used in combination with particular generator property. The following properties of cameras available through OpenNI interfaces are supported:
 
 * 
   For image generator:
   
-  - ``CV_CAP_PROP_OPENNI_OUTPUT_MODE`` -- Two output modes are supported: ``CV_CAP_OPENNI_VGA_30HZ`` used by default (image generator returns images in VGA resolution with 30 FPS) or ``CV_CAP_OPENNI_SXGA_15HZ`` (image generator returns images in SXGA resolution with 15 FPS); depth generator's maps are always in VGA resolution.
+  - ``CV_CAP_PROP_OPENNI_OUTPUT_MODE`` -- Three output modes are supported: ``CV_CAP_OPENNI_VGA_30HZ`` used by default (image generator returns images in VGA resolution with 30 FPS), ``CV_CAP_OPENNI_SXGA_15HZ`` (image generator returns images in SXGA resolution with 15 FPS) and ``CV_CAP_OPENNI_SXGA_30HZ`` (image generator returns images in SXGA resolution with 30 FPS, the mode is supported by XtionPRO Live); depth generator's maps are always in VGA resolution.
   
 
 * 
   For depth generator:
 
-  - ``CV_CAP_PROP_OPENNI_REGISTRATION`` -- Flag that synchronizes the remapping depth map to image map  by changing depth generator's view point (if the flag is ``"on"``) or sets this view point to its normal one (if the flag is ``"off"``).
+  - ``CV_CAP_PROP_OPENNI_REGISTRATION`` -- Flag that registers the remapping depth map to image map  by changing depth generator's view point (if the flag is ``"on"``) or sets this view point to its normal one (if the flag is ``"off"``). The registration process’s resulting images are pixel-aligned,which means that every pixel in the image is aligned to a pixel in the depth image.
   
     Next properties are available for getting only:
   
@@ -122,4 +128,6 @@ Flags specifing the needed generator type must be used in combination with parti
     - ``CV_CAP_OPENNI_DEPTH_GENERATOR_FOCAL_LENGTH = CV_CAP_OPENNI_DEPTH_GENERATOR + CV_CAP_PROP_OPENNI_FOCAL_LENGTH``
     - ``CV_CAP_OPENNI_DEPTH_GENERATOR_REGISTRATION_ON = CV_CAP_OPENNI_DEPTH_GENERATOR + CV_CAP_PROP_OPENNI_REGISTRATION_ON``
     
-For more information please refer to a Kinect example of usage ``kinect_maps.cpp`` in ``opencv/samples/cpp`` folder.
+For more information please refer to the example of usage openni_capture.cpp_ in ``opencv/samples/cpp`` folder.
+
+.. _openni_capture.cpp: http://code.opencv.org/svn/opencv/trunk/opencv/samples/cpp/openni_capture.cpp