Merge pull request #117 from vpisarev/doc_updates

doc/conf.py

@@ -293,7 +293,7 @@ extlinks = {
             'svms':('http://opencv.itseez.com/modules/ml/doc/support_vector_machines.html#%s', None),
             'drawingfunc':('http://opencv.itseez.com/modules/core/doc/drawing_functions.html#%s', None),
             'xmlymlpers':('http://opencv.itseez.com/modules/core/doc/xml_yaml_persistence.html#%s', None),
-            'huivideo' : ('http://opencv.itseez.com/modules/highgui/doc/reading_and_writing_images_and_video.html#%s', None),
+            'hgvideo' : ('http://opencv.itseez.com/modules/highgui/doc/reading_and_writing_images_and_video.html#%s', None),
             'gpuinit' : ('http://opencv.itseez.com/modules/gpu/doc/initalization_and_information.html#%s', None),
             'gpudatastructure' : ('http://opencv.itseez.com/modules/gpu/doc/data_structures.html#%s', None),
             'gpuopmatrices' : ('http://opencv.itseez.com/modules/gpu/doc/operations_on_matrices.html#%s', None),

doc/tutorials/highgui/video-input-psnr-ssim/video-input-psnr-ssim.rst

@@ -27,9 +27,9 @@ As a test case where to show off these using OpenCV I've created a small program
 How to read a video stream (online-camera or offline-file)?
 ===========================================================
 
-Essentially, all the functionalities required for video manipulation is integrated in the :huivideo:`VideoCapture <videocapture>` C++ class. This on itself builds on the FFmpeg open source library. This is a basic dependency of OpenCV so you shouldn't need to worry about this. A video is composed of a succession of images, we refer to these in the literature as frames. In case of a video file there is a *frame rate* specifying just how long is between two frames. While for the video cameras usually there is a limit of just how many frames they can digitalize per second, this property is less important as at any time the camera sees the current snapshot of the world. 
+Essentially, all the functionalities required for video manipulation is integrated in the :hgvideo:`VideoCapture <videocapture>` C++ class. This on itself builds on the FFmpeg open source library. This is a basic dependency of OpenCV so you shouldn't need to worry about this. A video is composed of a succession of images, we refer to these in the literature as frames. In case of a video file there is a *frame rate* specifying just how long is between two frames. While for the video cameras usually there is a limit of just how many frames they can digitalize per second, this property is less important as at any time the camera sees the current snapshot of the world.
 
-The first task you need to do is to assign to a :huivideo:`VideoCapture <videocapture>` class its source. You can do this either via the :huivideo:`constructor <videocapture-videocapture>` or its :huivideo:`open <videocapture-open>` function. If this argument is an integer then you will bind the class to a camera, a device. The number passed here is the ID of the device, assigned by the operating system. If you have a single camera attached to your system its ID will probably be zero and further ones increasing from there. If the parameter passed to these is a string it will refer to a video file, and the string points to the location and name of the file. For example, to the upper source code a valid command line is: 
+The first task you need to do is to assign to a :hgvideo:`VideoCapture <videocapture>` class its source. You can do this either via the :hgvideo:`constructor <videocapture-videocapture>` or its :hgvideo:`open <videocapture-open>` function. If this argument is an integer then you will bind the class to a camera, a device. The number passed here is the ID of the device, assigned by the operating system. If you have a single camera attached to your system its ID will probably be zero and further ones increasing from there. If the parameter passed to these is a string it will refer to a video file, and the string points to the location and name of the file. For example, to the upper source code a valid command line is:
 
 .. code-block:: bash
 
@@ -46,7 +46,7 @@ We do a similarity check. This requires a reference and a test case video file.
    VideoCapture captUndTst;
    captUndTst.open(sourceCompareWith);
 
-To check if the binding of the class to a video source was successful or not use the :huivideo:`isOpened <video-isopened>` function:
+To check if the binding of the class to a video source was successful or not use the :hgvideo:`isOpened <video-isopened>` function:
 
 .. code-block:: cpp
 
@@ -56,7 +56,7 @@ To check if the binding of the class to a video source was successful or not use
      return -1;
      }
 
-Closing the video is automatic when the objects destructor is called. However, if you want to close it before this you need to call its :huivideo:`release <videocapture-release>` function. The frames of the video are just simple images. Therefore, we just need to extract them from the :huivideo:`VideoCapture <videocapture>` object and put them inside a *Mat* one. The video streams are sequential. You may get the frames one after another by the :huivideo:`read <videocapture-read>` or the overloaded >> operator: 
+Closing the video is automatic when the objects destructor is called. However, if you want to close it before this you need to call its :hgvideo:`release <videocapture-release>` function. The frames of the video are just simple images. Therefore, we just need to extract them from the :hgvideo:`VideoCapture <videocapture>` object and put them inside a *Mat* one. The video streams are sequential. You may get the frames one after another by the :hgvideo:`read <videocapture-read>` or the overloaded >> operator:
 
 .. code-block:: cpp
 
@@ -73,9 +73,9 @@ The upper read operations will leave empty the *Mat* objects if no frame could b
     // exit the program
    }
 
-A read method is made of a frame grab and a decoding applied on that. You may call explicitly these two by using the :huivideo:`grab <videocapture-grab>` and then the :huivideo:`retrieve <videocapture-retrieve>` functions. 
+A read method is made of a frame grab and a decoding applied on that. You may call explicitly these two by using the :hgvideo:`grab <videocapture-grab>` and then the :hgvideo:`retrieve <videocapture-retrieve>` functions.
 
-Videos have many-many information attached to them besides the content of the frames. These are usually numbers, however in some case it may be short character sequences (4 bytes or less). Due to this to acquire these information there is a general function named :huivideo:`get <videocapture-get>` that returns double values containing these properties. Use bitwise operations to decode the characters from a double type and conversions where valid values are only integers. Its single argument is the ID of the queried property. For example, here we get the size of the frames in the reference and test case video file; plus the number of frames inside the reference. 
+Videos have many-many information attached to them besides the content of the frames. These are usually numbers, however in some case it may be short character sequences (4 bytes or less). Due to this to acquire these information there is a general function named :hgvideo:`get <videocapture-get>` that returns double values containing these properties. Use bitwise operations to decode the characters from a double type and conversions where valid values are only integers. Its single argument is the ID of the queried property. For example, here we get the size of the frames in the reference and test case video file; plus the number of frames inside the reference.
 
 .. code-block:: cpp
 
@@ -85,7 +85,7 @@ Videos have many-many information attached to them besides the content of the fr
    cout << "Reference frame resolution: Width=" << refS.width << "  Height=" << refS.height
         << " of nr#: " << captRefrnc.get(CV_CAP_PROP_FRAME_COUNT) << endl;
 
-When you are working with videos you may often want to control these values yourself. To do this there is a :huivideo:`set <videocapture-set>` function. Its first argument remains the name of the property you want to change and there is a second of double type containing the value to be set. It will return true if it succeeds and false otherwise. Good examples for this is seeking in a video file to a given time or frame: 
+When you are working with videos you may often want to control these values yourself. To do this there is a :hgvideo:`set <videocapture-set>` function. Its first argument remains the name of the property you want to change and there is a second of double type containing the value to be set. It will return true if it succeeds and false otherwise. Good examples for this is seeking in a video file to a given time or frame:
 
 .. code-block:: cpp
 
@@ -93,7 +93,7 @@ When you are working with videos you may often want to control these values your
    captRefrnc.set(CV_CAP_PROP_POS_FRAMES, 10); // go to the 10th frame of the video
    // now a read operation would read the frame at the set position
 
-For properties you can read and change look into the documentation of the :huivideo:`get <videocapture-get>` and :huivideo:`set <videocapture-set>` functions. 
+For properties you can read and change look into the documentation of the :hgvideo:`get <videocapture-get>` and :hgvideo:`set <videocapture-set>` functions.
 
 
 Image similarity - PSNR and SSIM

doc/tutorials/highgui/video-write/video-write.rst

@@ -1,90 +1,137 @@
 .. _videoWriteHighGui:
+
 Creating a video with OpenCV
 ****************************
+
 Goal
 ====
-Whenever you work with video feeds you may eventually want to save your image processing result in a form of a new video file. For simple video outputs you can use the OpenCV built-in :huivideo:`VideoWriter <videowriter-videowriter>` class, designed for this.
+
+Whenever you work with video feeds you may eventually want to save your image processing result in a form of a new video file. For simple video outputs you can use the OpenCV built-in :hgvideo:`VideoWriter <videowriter-videowriter>` class, designed for this.
+
 .. container:: enumeratevisibleitemswithsquare
+
    + How to create a video file with OpenCV
    + What type of video files you can create with OpenCV
    + How to extract a given color channel from a video
+
 As a simple demonstration I'll just extract one of the RGB color channels of an input video file into a new video. You can control the flow of the application from its console line arguments:
+
 .. container:: enumeratevisibleitemswithsquare
+
    + The first argument points to the video file to work on
    + The second argument may be one of the characters: R G B. This will specify which of the channels to extract.
    + The last argument is the character Y (Yes) or N (No). If this is no, the codec used for the input video file will be the same as for the output. Otherwise, a window will pop up and allow you to select yourself the codec to use.
+
 For example, a valid command line would look like:
+
 .. code-block:: bash
+
    video-write.exe video/Megamind.avi R Y
+
 The source code
 ===============
 You may also find the source code and these video file in the :file:`samples/cpp/tutorial_code/highgui/video-write/` folder of the OpenCV source library or :download:`download it from here <../../../../samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp>`.
+
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp
    :language: cpp
    :linenos:
    :tab-width: 4
    :lines: 1-8, 21-22, 24-97
+
 The structure of a video
 ========================
 For start, you should have an idea of just how a video file looks. Every video file in itself is a container. The type of the container is expressed in the files extension (for example *avi*, *mov* or *mkv*). This contains multiple elements like: video feeds, audio feeds or other tracks (like for example subtitles). How these feeds are stored is determined by the codec used for each one of them. In case of the audio tracks commonly used codecs are *mp3* or *aac*. For the video files the list is somehow longer and includes names such as *XVID*, *DIVX*, *H264* or *LAGS* (*Lagarith Lossless Codec*). The full list of codecs you may use on a system depends on just what one you have installed.
+
 .. image:: images/videoFileStructure.png
    :alt: The Structure of the video
    :align: center
+
 As you can see things can get really complicated with videos. However, OpenCV is mainly a computer vision library, not a video stream, codec and write one. Therefore, the developers tried to keep this part as simple as possible. Due to this OpenCV for video containers supports only the *avi* extension, its first version. A direct limitation of this is that you cannot save a video file larger than 2 GB. Furthermore you can only create and expand a single video track inside the container. No audio or other track editing support here. Nevertheless, any video codec present on your system might work. If you encounter some of these limitations you will need to look into more specialized video writing libraries such as *FFMpeg* or codecs as *HuffYUV*, *CorePNG* and *LCL*. As an alternative, create the video track with OpenCV and expand it with sound tracks or convert it to other formats by using video manipulation programs such as *VirtualDub* or *AviSynth*.
 The *VideoWriter* class
 =======================
 The content written here builds on the assumption you already read the :ref:`videoInputPSNRMSSIM` tutorial and you know how to read video files.
-To create a video file you just need to create an instance of the :huivideo:`VideoWriter <videowriter-videowriter>` class. You can specify its properties either via parameters in the constructor or later on via the :huivideo:`open <videowriter-open>` function. Either way, the parameters are the same:
+To create a video file you just need to create an instance of the :hgvideo:`VideoWriter <videowriter-videowriter>` class. You can specify its properties either via parameters in the constructor or later on via the :hgvideo:`open <videowriter-open>` function. Either way, the parameters are the same:
 1. The name of the output that contains the container type in its extension. At the moment only *avi* is supported. We construct this from the input file, add to this the name of the channel to use, and finish it off with the container extension.
+
    .. code-block:: cpp
+
       const string source      = argv[1];            // the source file name
       string::size_type pAt = source.find_last_of('.');   // Find extension point
       const string NAME = source.substr(0, pAt) + argv[2][0] + ".avi";   // Form the new name with container
+
 #. The codec to use for the video track. Now all the video codecs have a unique short name of maximum four characters. Hence, the *XVID*, *DIVX* or *H264* names. This is called a four character code. You may also ask this from an input video by using its *get* function. Because the *get* function is a general function it always returns double values. A double value is stored on 64 bits. Four characters are four bytes, meaning 32 bits. These four characters are coded in the lower 32 bits of the *double*. A simple way to throw away the upper 32 bits would be to just convert this value to *int*:
+
    .. code-block:: cpp
+
       VideoCapture inputVideo(source);                                   // Open input
       int ex = static_cast<int>(inputVideo.get(CV_CAP_PROP_FOURCC));     // Get Codec Type- Int form
+
    OpenCV internally works with this integer type and expect this as its second parameter. Now to convert from the integer form to string we may use two methods: a bitwise operator and a union method. The first one extracting from an int the characters looks like (an "and" operation, some shifting and adding a 0 at the end to close the string):
+
    .. code-block:: cpp
+
       char EXT[] = {ex & 0XFF , (ex & 0XFF00) >> 8,(ex & 0XFF0000) >> 16,(ex & 0XFF000000) >> 24, 0};
+
    You can do the same thing with the *union* as:
+
    .. code-block:: cpp
+
       union { int v; char c[5];} uEx ;
       uEx.v = ex;                              // From Int to char via union
       uEx.c[4]='\0';
+
    The advantage of this is that the conversion is done automatically after assigning, while for the bitwise operator you need to do the operations whenever you change the codec type. In case you know the codecs four character code beforehand, you can use the *CV_FOURCC* macro to build the integer:
+
    .. code-block::cpp
+
       CV_FOURCC('P','I','M,'1') // this is an MPEG1 codec from the characters to integer
+
    If you pass for this argument minus one than a window will pop up at runtime that contains all the codec installed on your system and ask you to select the one to use:
+
    .. image:: images/videoCompressSelect.png
       :alt: Select the codec type to use
       :align: center
+
 #. The frame per second for the output video. Again, here I keep the input videos frame per second by using the *get* function.
 #. The size of the frames for the output video. Here too I keep the input videos frame size per second by using the *get* function.
 #. The final argument is an optional one. By default is true and says that the output will be a colorful one (so for write you will send three channel images). To create a gray scale video pass a false parameter here.
+
 Here it is, how I use it in the sample:
-.. code-block:: cpp
+
+    .. code-block:: cpp
+
        VideoWriter outputVideo;
        Size S = Size((int) inputVideo.get(CV_CAP_PROP_FRAME_WIDTH),    //Acquire input size
                      (int) inputVideo.get(CV_CAP_PROP_FRAME_HEIGHT));
        outputVideo.open(NAME , ex, inputVideo.get(CV_CAP_PROP_FPS),S, true);
-Afterwards, you use the :huivideo:`isOpened() <videowriter-isopened>` function to find out if the open operation succeeded or not. The video file automatically closes when the *VideoWriter* object is destroyed. After you open the object with success you can send the frames of the video in a sequential order by using the :huivideo:`write<videowriter-write>` function of the class. Alternatively, you can use its overloaded operator << :
+
+Afterwards, you use the :hgvideo:`isOpened() <videowriter-isopened>` function to find out if the open operation succeeded or not. The video file automatically closes when the *VideoWriter* object is destroyed. After you open the object with success you can send the frames of the video in a sequential order by using the :hgvideo:`write<videowriter-write>` function of the class. Alternatively, you can use its overloaded operator << :
+
 .. code-block:: cpp
+
     outputVideo.write(res);  //or
     outputVideo << res;
+
 Extracting a color channel from an RGB image means to set to zero the RGB values of the other channels. You can either do this with image scanning operations or by using the split and merge operations. You first split the channels up into different images, set the other channels to zero images of the same size and type and finally merge them back:
+
 .. code-block:: cpp
+
    split(src, spl);                 // process - extract only the correct channel
    for( int i =0; i < 3; ++i)
       if (i != channel)
          spl[i] = Mat::zeros(S, spl[0].type());
    merge(spl, res);
+
 Put all this together and you'll get the upper source code, whose runtime result will show something around the idea:
+
 .. image:: images/resultOutputWideoWrite.png
    :alt: A sample output
    :align: center
+
 You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=jpBwHxsl1_0>`_.
+
 .. raw:: html
+
   <div align="center">
   <iframe title="Creating a video with OpenCV" width="560" height="349" src="http://www.youtube.com/embed/jpBwHxsl1_0?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
   </div>

doc/tutorials/introduction/how_to_write_a_tutorial/how_to_write_a_tutorial.rst

@@ -1,36 +1,56 @@
 .. _howToWriteTutorial:
+
 How to write a tutorial for OpenCV?
 ***********************************
+
 Okay, so assume you have just finished a project of yours implementing something based on OpenCV and you want to present/share it with the community. Luckily, OpenCV is an *open source project*. This means that in theory anyone has access to the full source code and may extend it. While making a robust and practical library (like OpenCV) is great, the success of a library also depends on how user friendly it is. To improve on this aspect, the OpenCV team has already been listening to user feedback from its :opencv_group:`Yahoo user group <>` and by making samples you can find in the source directories sample folder. The addition of the tutorials (in both online and PDF format) is an extension of these efforts.
+
 Goal
 ====
 .. _reST: http://docutils.sourceforge.net/rst.html
+
 .. |reST| replace:: reStructuredText
+
 .. |Sphinx| replace:: Sphinx
+
 .. _Sphinx: http://sphinx.pocoo.org/
+
 The tutorials are just as an important part of the library as  the implementation of those crafty data structures and algorithms you can find in OpenCV. Therefore, the source codes for the tutorials are part of the library. And yes, I meant source codes. The reason for this formulation is that the tutorials are written by using the |Sphinx|_ documentation generation system. This is based on the popular python documentation system called |reST|_ (reST). ReStructuredText is a really neat language that by using a few simple conventions (indentation, directives) and emulating old school e-mail writing techniques (text only) tries to offer a simple way to create and edit documents. Sphinx extends this with some new features and creates the resulting document in both HTML (for web) and PDF (for offline usage) format.
+
 Usually, an OpenCV tutorial has the following parts:
-1. A source code demonstration of an OpenCV feature:
+
+  1. A source code demonstration of an OpenCV feature:
+
     a. One or more CPP, Python, Java or other type of files depending for what OpenCV offers support and for what language you make the tutorial.
     #. Occasionaly, input resource files required for running your tutorials application.
-#. A table of content entry (so people may easily find the tutorial):
+
+  2. A table of content entry (so people may easily find the tutorial):
+
     a. Adding your stuff to the tutorials table of content (**reST** file).
     #. Add an image file near the TOC entry.
-#. The content of the tutorial itself:
+
+  3. The content of the tutorial itself:
+
     a. The **reST** text of the tutorial
     #. Images following the idea that "*A picture is worth a thousand words*".
     #. For more complex demonstrations you may create a video.
+
 As you can see you will need at least some basic knowledge of the *reST* system in order to complete the task at hand with success. However, don't worry *reST* (and *Sphinx*) was made with simplicity in mind. It is easy to grasp its basics. I found that the `OpenAlea documentations introduction on this subject <http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/tutorial/rest_syntax.html>`_ (or the `Thomas Cokelaer one <http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`_ ) should enough for this. If for some directive or feature you need a more in-depth description look it up in the official |reST|_ help files or at the |Sphinx|_ documentation.
 In our world achieving some tasks is possible in multiple ways. However, some of the roads to take may have obvious or hidden advantages over others. Then again, in some other cases it may come down to just simple user preference. Here, I'll present how I decided to write the tutorials, based on my personal experience. If for some of them you know a better solution and you can back it up feel free to use that. I've nothing against it, as long as it gets the job done in an elegant fashion.
 Now the best would be if you could make the integration yourself. For this you need first to have the source code. I recommend following the guides for your operating system on acquiring OpenCV sources. For Linux users look :ref:`here <Linux-Installation>` and for :ref:`Windows here <Windows_Installation>`. You must also install python and sphinx with its dependencies in order to be able to build the documentation.
 Once you have downloaded the repository to your hard drive you can take a look in the OpenCV directory to make sure you have both the samples and doc folder present. Anyone may download the trunk source files from  :file:`git://code.opencv.org/opencv.git` . Nevertheless, not everyone has upload (commit/submit) rights. This is to protect the integrity of the library. If you plan doing more than one tutorial, and would like to have an account with commit user rights you should first register an account at http://code.opencv.org/ and then contact dr. Gary Bradski at -delete-bradski@-delete-willowgarage.com. Otherwise, you can just send the resulting files to us via the :opencv_group:`Yahoo user group <>` or to me at -delete-bernat@-delete-primeranks.net and I'll add it. If you have questions, suggestions or constructive critics I will gladly listen to them. If you send it to the OpenCV group please tag its subject with a **[Tutorial]** entry.
+
 Format the Source Code
 ======================
-Before I start this let it be clear: the main goal is to have a working sample code. However, for your tutorial to be of a top notch quality you should follow a few guide lines I am going to present here.
-In case you have an application by using the older interface (with *IplImage*, *CVMat*, *cvLoadImage* and such) consider migrating it to the new C++ interface. The tutorials are intended to be an up to date help for our users. And as of OpenCV 2 the OpenCV emphasis on using the less error prone and clearer C++ interface. Therefore, if possible please convert your code to the C++ interface. For this it may help to read the :ref:`InteroperabilityWithOpenCV1` tutorial. However, once you have an OpenCV 2 working code, then you should make your source code snippet as easy to read as possible. Here're a couple of advices for this:
+
+Before I start this let it be clear: the main goal is to have a working sample code. However, for your tutorial to be of a top notch quality you should follow a few guide lines I am going to present here. In case you have an application by using the older interface (with *IplImage*, *CVMat*, *cvLoadImage* and such) consider migrating it to the new C++ interface. The tutorials are intended to be an up to date help for our users. And as of OpenCV 2 the OpenCV emphasis on using the less error prone and clearer C++ interface. Therefore, if possible please convert your code to the C++ interface. For this it may help to read the :ref:`InteroperabilityWithOpenCV1` tutorial. However, once you have an OpenCV 2 working code, then you should make your source code snippet as easy to read as possible. Here're a couple of advices for this:
+
 .. container:: enumeratevisibleitemswithsquare
+
    + Add a standard output with the description of what your program does. Keep it short and yet, descriptive. This output is at the start of the program. In my example files this usually takes the form of a *help* function containing the output. This way both the source file viewer and application runner can see what all is about in your sample. Here's an instance of this:
+
      .. code-block:: cpp
+
         void help()
         {
         cout
@@ -48,29 +68,46 @@ In case you have an application by using the older interface (with *IplImage*, *
         help();
         // here comes the actual source code
         }
+
      Additionally, finalize the description with a short usage guide. This way the user will know how to call your programs, what leads us to the next point.
+
    + Prefer command line argument controlling instead of hard coded one. If your program has some variables that may be changed use command line arguments for this. The tutorials, can be a simple try-out ground for the user. If you offer command line controlling for the input image (for example), then you offer the possibility for the user to try it out with his/her own images, without the need to mess in the source code. In the upper example you can see that the input image, channel and codec selection may all be changed from the command line. Just compile the program and run it with your own input arguments.
+
    + Be as verbose as possible. There is no shame in filling the source code with comments. This way the more advanced user may figure out what's happening right from the sample code. This advice goes for the output console too. Specify to the user what's happening. Never leave the user hanging there and thinking on: "Is this program now crashing or just doing some computationally intensive task?." So, if you do a training task that may take some time, make sure you print out a message about this before starting and after finishing it.
+
    + Throw out unnecessary stuff from your source code. This is a warning to not take the previous point too seriously. Balance is the key. If it's something that can be done in a fewer lines or simpler than that's the way you should do it. Nevertheless, if for some reason you have such sections notify the user why you have chosen to do so. Keep the amount of information as low as possible, while still getting the job done in an elegant way.
+
    + Put your sample file into the :file:`opencv/samples/cpp/tutorial_code/sectionName` folder. If you write a tutorial for other languages than cpp, then change that part of the path. Before completing this you need to decide that to what section (module) does your tutorial goes. Think about on what module relies most heavily your code and that is the one to use. If the answer to this question is more than one modules then the *general* section is the one to use. For finding the *opencv* directory open up your file system and navigate where you downloaded our repository.
+
    + If the input resources are hard to acquire for the end user consider adding a few of them to the :file:`opencv/samples/cpp/tutorial_code/images`. Make sure that who reads your code can try it out!
+
 Add the TOC entry
 =================
+
 For this you will need to know some |reST|_. There is no going around this. |reST|_ files have **rst** extensions. However, these are simple text files. Use any text editor you like. Finding a text editor that offers syntax highlighting for |reST|_ was quite a challenge at the time of writing this tutorial. In my experience, `Intype <http://intype.info/>`_ is a solid option on Windows, although there is still place for improvement.
+
 Adding your source code to a table of content is important for multiple reasons. First and foremost this will allow for the user base to find your tutorial from our websites tutorial table of content. Secondly, if you omit this *Sphinx* will throw a warning that your tutorial file isn't part of any TOC tree entry. And there is nothing more than the developer team hates than an ever increasing warning/error list for their builds. *Sphinx* also uses this to build up the previous-back-up buttons on the website. Finally, omitting this step will lead to that your tutorial will **not** be added to the PDF version of the tutorials.
+
 Navigate to the :file:`opencv/doc/tutorials/section/table_of_content_section` folder (where the section is the module to which you're adding the tutorial). Open the *table_of_content_section* file. Now this may have two forms. If no prior tutorials are present in this section that there is a template message about this and has the following form:
+
 .. code-block:: rst
+
   .. _Table-Of-Content-Section:
+
    Section title
    -----------------------------------------------------------
    Description about the section.
    .. include:: ../../definitions/noContent.rst
    .. raw:: latex
       \pagebreak
+
 The first line is a reference to the section title in the reST system. The section title will be a link and you may refer to it via the ``:ref:`` directive. The *include* directive imports the template text from the definitions directories *noContent.rst* file. *Sphinx* does not creates the PDF from scratch. It does this by first creating a latex file. Then creates the PDF from the latex file. With the *raw* directive you can directly add to this output commands. Its unique argument is for what kind of output to add the content of the directive. For the PDFs it may happen that multiple sections will overlap on a single page. To avoid this at the end of the TOC we add a *pagebreak* latex command, that hints to the LATEX system that the next line should be on a new page.
 If you have one of this, try to transform it to the following form:
+
 .. include:: ../../definitions/tocDefinitions.rst
+
 .. code-block:: rst
+
    .. _Table-Of-Content-Section:
    Section title
    -----------------------------------------------------------
@@ -88,16 +125,25 @@ If you have one of this, try to transform it to the following form:
                       :height: 90pt
                       :width:  90pt
    .. raw:: latex
+
       \pagebreak
+
    .. toctree::
+
       :hidden:
       ../mat - the basic image container/mat - the basic image container
+
 If this is already present just add a new section of the content between the include and the raw directives (excluding those lines). Here you'll see a new include directive. This should be present only once in a TOC tree and the reST file contains the definitions of all the authors contributing to the OpenCV tutorials. We are a multicultural community and some of our name may contain some funky characters. However, reST **only supports** ANSI characters. Luckily we can specify Unicode characters with the *unicode* directive. Doing this for all of your tutorials is a troublesome procedure. Therefore, the tocDefinitions file contains the definition of your author name. Add it here once and afterwards just use the replace construction. For example here's the definition for my name:
+
 .. code-block:: rst
+
    .. |Author_BernatG| unicode:: Bern U+00E1 t U+0020 G U+00E1 bor
+
 The ``|Author_BernatG|`` is the text definitions alias. I can use later this to add the definition, like I've done in the TOCs *Author* part. After the ``::`` and a space you start the definition. If you want to add an UNICODE character (non-ASCI) leave an empty space and specify it in the format U+(UNICODE code). To find the UNICODE code of a character I recommend using the `FileFormat <http://www.fileformat.info>`_ websites service. Spaces are trimmed from the definition, therefore we add a space by its UNICODE character (U+0020).
 Until the *raw* directive what you can see is a TOC tree entry. Here's how a TOC entry will look like:
-+
+
+.. code-block:: rst
+
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
   =============== ======================================================
@@ -109,32 +155,45 @@ Until the *raw* directive what you can see is a TOC tree entry. Here's how a TOC
   .. |MatBasicIma| image:: images/matTheBasicImageStructure.jpg
                    :height: 90pt
                    :width:  90pt
+
 As you can see we have an image to the left and a description box to the right. To create two boxes we use a table with two columns and a single row. In the left column is the image and in the right one the description. However, the image directive is way too long to fit in a column. Therefore, we need to use the substitution definition system. We add this definition after the TOC tree. All images for the TOC tree are to be put in the images folder near its |reST|_ file. We use the point measurement system because we are also creating PDFs. PDFs are printable documents, where there is no such thing that pixels (px), just points (pt). And while generally space is no problem for web pages (we have monitors with **huge** resolutions) the size of the paper (A4 or letter) is constant and will be for a long time in the future. Therefore, size constrains come in play more like for the PDF, than the generated HTML code.
 Now your images should be as small as possible, while still offering the intended information for the user. Remember that the tutorial will become part of the OpenCV source code. If you add large images (that manifest in form of large image size) it will just increase the size of the repository pointlessly. If someone wants to download it later, its download time will be that much longer. Not to mention the larger PDF size for the tutorials and the longer load time for the web pages. In terms of pixels a TOC image should not be larger than 120 X 120 pixels. Resize your images if they are larger!
-.. note::
-   If you add a larger image and specify a smaller image size, *Sphinx* will not resize that. At build time will add the full size image and the resize will be done by your browser after the image is loaded. A 120 X 120 image is somewhere below 10KB. If you add a 110KB image, you have just pointlessly added a 100KB extra data to transfer over the internet for every user!
+
+.. note:: If you add a larger image and specify a smaller image size, *Sphinx* will not resize that. At build time will add the full size image and the resize will be done by your browser after the image is loaded. A 120 X 120 image is somewhere below 10KB. If you add a 110KB image, you have just pointlessly added a 100KB extra data to transfer over the internet for every user!
+
 Generally speaking you shouldn't need to specify your images size (excluding the TOC entries). If no such is found *Sphinx* will use the size of the image itself (so no resize occurs). Then again if for some reason you decide to specify a size that should be the **width** of the image rather than its height. The reason for this again goes back to the PDFs. On a PDF page the height is larger than the width. In the PDF the images will not be resized. If you specify a size that does not fit in the page, then what does not fits in **will be cut off**. When creating your images for your tutorial you should try to keep the image widths below 500 pixels, and calculate with around 400 point page width when specifying image widths.
-The image format depends on the content of the image. If you have some complex scene (many random like colors) then use *jpg*. Otherwise, prefer using *png*. They are even some tools out there that optimize the size of *PNG* images, such as `PNGGauntlet <http://pnggauntlet.com/>`_. Use them to make your images as small as possible in size.
-Now on the right side column of the table we add the information about the tutorial:
+
+The image format depends on the content of the image. If you have some complex scene (many random like colors) then use *jpg*. Otherwise, prefer using *png*. They are even some tools out there that optimize the size of *PNG* images, such as `PNGGauntlet <http://pnggauntlet.com/>`_. Use them to make your images as small as possible in size. Now on the right side column of the table we add the information about the tutorial:
+
 .. container:: enumeratevisibleitemswithsquare
+
    + In the first line it is the title of the tutorial. However, there is no need to specify it explicitly. We use the reference system. We'll start up our tutorial with a reference specification, just like in case of this TOC entry with its  `` .. _Table-Of-Content-Section:`` . If after this you have a title (pointed out by the following line of -), then Sphinx will replace the ``:ref:`Table-Of-Content-Section``` directive with the tile of the section in reference form (creates a link in web page). Here's how the definition looks in my case:
+
      .. code-block:: rst
+
         .. _matTheBasicImageContainer:
            Mat - The Basic Image Container
            *******************************
+
      Note, that according to the |reST|_ rules the * should be as long as your title.
    + Compatibility. What version of OpenCV is required to run your sample code.
    + Author. Use the substitution markup of |reST|_.
    + A short sentence describing the essence of your tutorial.
+
 Now before each TOC entry you need to add the three lines of:
+
 .. code-block:: cpp
+
    +
      .. tabularcolumns:: m{100pt} m{300pt}
      .. cssclass:: toctableopencv
+
 The plus sign (+) is to enumerate tutorials by using bullet points. So for every TOC entry we have a corresponding bullet point represented by the +. Sphinx is highly indenting sensitive. Indentation is used to express from which point until to which point does a construction last. Un-indentation means end of that construction. So to keep all the bullet points to the same group the following TOC entries (until the next +) should be indented by two spaces.
 Here, I should also mention that **always** prefer using spaces instead of tabs. Working with only spaces makes possible that if we both use monotype fonts we will see the same thing. Tab size is text editor dependent and as should be avoided. *Sphinx* translates all tabs into 8 spaces before interpreting it.
 It turns out that the automatic formatting of both the HTML and PDF(LATEX) system messes up our tables. Therefore, we need to help them out a little. For the PDF generation we add the ``.. tabularcolumns:: m{100pt} m{300pt}`` directive. This means that the first column should be 100 points wide and middle aligned. For the HTML look we simply name the following table of a *toctableopencv* class type. Then, we can modify the look of the table by modifying the CSS of our web page. The CSS definitions go into the :file:`opencv/doc/_themes/blue/static/default.css_t` file.
+
 .. code-block:: css
+
    .toctableopencv
    {
     width: 100% ;
@@ -150,91 +209,136 @@ It turns out that the automatic formatting of both the HTML and PDF(LATEX) syste
    {
     width: 100% !important;
    }
+
 However, you should not need to modify this. Just add these three lines (plus keep the two space indentation) for all TOC entries you add. At the end of the TOC file you'll find:
+
 .. code-block:: rst
+
    .. raw:: latex
       \pagebreak
    .. toctree::
       :hidden:
       ../mat - the basic image container/mat - the basic image container
+
 The page break entry comes for separating sections and should be only one in a TOC tree |reST|_ file. Finally, at the end of the TOC tree we need to add our tutorial to the *Sphinx* TOC tree system. *Sphinx* will generate from this the previous-next-up information for the HTML file and add items to the PDF according to the order here. By default this TOC tree directive generates a simple table of contents. However, we already created a fancy looking one so we no longer need this basic one. Therefore, we add the *hidden* option to do not show it.
 The path is of a relative type. We step back in the file system and then go into the :file:`mat - the basic image container` directory for the :file:`mat - the basic image container.rst` file. Putting out the *rst* extension for the file is optional.
+
 Write the tutorial
 ==================
+
 Create a folder with the name of your tutorial. Preferably, use small letters only. Then create a text file in this folder with *rst* extension and the same name. If you have images for the tutorial create an :file:`images` folder and add your images there. When creating your images follow the guidelines described in the previous part!
 Now here's our recommendation for the structure of the tutorial (although, remember that this is not carved in the stone; if you have a better idea, use it!):
+
 .. container:: enumeratevisibleitemswithsquare
+
    + Create the reference point and the title.
+
      .. code-block:: rst
+
         .. _matTheBasicImageContainer:
         Mat - The Basic Image Container
         *******************************
+
      You start the tutorial by specifying a reference point by the ``.. _matTheBasicImageContainer:`` and then its title. The name of the reference point should be a unique one over the whole documentation. Therefore, do not use general names like *tutorial1*. Use the * character to underline the title for its full width. The subtitles of the tutorial should be underlined with = charachter.
    + Goals. You start your tutorial by specifying what you will present. You can also enumerate the sub jobs to be done. For this you can use a bullet point construction. There is a single configuration file for both the reference manual and the tutorial documentation. In the reference manuals at the argument enumeration we do not want any kind of bullet point style enumeration. Therefore, by default all the bullet points at this level are set to do not show the dot before the entries in the HTML. You can override this by putting the bullet point in a container. I've defined a square type bullet point view under the name *enumeratevisibleitemswithsquare*. The CSS style definition for this is again in the  :file:`opencv\doc\_themes\blue\static\default.css_t` file. Here's a quick example of using it:
+
      .. code-block:: rst
+
         .. container:: enumeratevisibleitemswithsquare
            + Create the reference point and the title.
            + Second entry
            + Third entry
+
      Note that you need the keep the indentation of the container directive. Directive indentations are always three (3) spaces. Here you may even give usage tips for your sample code.
    + Source code. Present your samples code to the user. It's a good idea to offer a quick download link for the HTML page by using the *download* directive and pointing out where the user may find your source code in the file system by using the *file* directive:
+
      .. code-block:: rst
+
         Text :file:`samples/cpp/tutorial_code/highgui/video-write/` folder of the OpenCV source library
         or :download:`text to appear in the webpage
         <../../../../samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp>`.
+
      For the download link the path is a relative one, hence the multiple back stepping operations (..). Then you can add the source code either by using the *code block* directive or the *literal include* one. In case of the code block you will need to actually add all the source code text into your |reST|_ text and also apply the required indentation:
+
      .. code-block:: rst
+
         .. code-block:: cpp
            int i = 0;
            l = ++j;
+
      The only argument of the directive is the language used (here CPP). Then you add the source code into its content (meaning one empty line after the directive) by keeping the indentation of the directive (3 spaces). With the *literal include* directive you do not need to add the source code of the sample. You just specify the sample and *Sphinx* will load it for you, during build time. Here's an example usage:
+
      .. code-block:: rst
+
         .. literalinclude:: ../../../../samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp
            :language: cpp
            :linenos:
            :tab-width: 4
            :lines: 1-8, 21-22, 24-
+
      After the directive you specify a relative path to the file from what to import. It has four options: the language to use, if you add the ``:linenos:`` the line numbers will be shown, you can specify the tab size with the ``:tab-width:`` and you do not need to load the whole file, you can show just the important lines. Use the *lines* option to do not show redundant information (such as the *help* function). Here basically you specify ranges, if the second range line number is missing than that means that until the end of the file. The ranges specified here do no need to be in an ascending order, you may even reorganize the structure of how you want to show your sample inside the tutorial.
    + The tutorial. Well here goes the explanation for why and what have you used. Try to be short, clear, concise and yet a thorough one. There's no magic formula. Look into a few already made tutorials and start out from there. Try to mix sample OpenCV code with your explanations. If with words is hard to describe something do not hesitate to add in a reasonable size image, to overcome this issue.
      When you present OpenCV functionality it's a good idea to give a link to the used OpenCV data structure or function. Because the OpenCV tutorials and reference manual are in separate PDF files it is not possible to make this link work for the PDF format. Therefore, we use here only web page links to the **opencv.itseez.com** website. The OpenCV functions and data structures may be used for multiple tasks. Nevertheless, we want to avoid that every users creates its own reference to a commonly used function. So for this we use the global link collection of *Sphinx*. This is defined in the file:`opencv/doc/conf.py` configuration file. Open it and go all the way down to the last entry:
+
      .. code-block:: py
+
        # ---- External links for tutorials -----------------
        extlinks = {
-           'huivideo' : ('http://opencv.itseez.com/modules/highgui/doc/reading_and_writing_images_and_video.html#%s', None)
+           'hgvideo' : ('http://opencv.itseez.com/modules/highgui/doc/reading_and_writing_images_and_video.html#%s', None)
            }
-     In short here we defined a new **huivideo** directive that refers to an external webpage link. Its usage is:
+
+     In short here we defined a new **hgvideo** directive that refers to an external webpage link. Its usage is:
+
      .. code-block:: rst
-       A sample function of the highgui modules image write and read page is the :huivideo:`imread() function <imread>`.
-     Which turns to: A sample function of the highgui modules image write and read page is the :huivideo:`imread() function <imread>`. The argument you give between the <> will be put in place of the ``%s`` in the upper definition, and as the link will anchor to the correct function. To find out the anchor of a given function just open up a web page, search for the function and click on it. In the address bar it should appear like: ``http://opencv.itseez.com/modules/highgui/doc/reading_and_writing_images_and_video.html#imread`` .  Look here for the name of the directives for each page of the OpenCV reference manual. If none present for one of them feel free to add one for it.
+
+       A sample function of the highgui modules image write and read page is the :hgvideo:`imread() function <imread>`.
+
+     Which turns to: A sample function of the highgui modules image write and read page is the :hgvideo:`imread() function <imread>`. The argument you give between the <> will be put in place of the ``%s`` in the upper definition, and as the link will anchor to the correct function. To find out the anchor of a given function just open up a web page, search for the function and click on it. In the address bar it should appear like: ``http://opencv.itseez.com/modules/highgui/doc/reading_and_writing_images_and_video.html#imread`` .  Look here for the name of the directives for each page of the OpenCV reference manual. If none present for one of them feel free to add one for it.
      For formulas you can add LATEX code that will translate in the web pages into images. You do this by using the *math* directive. A usage tip:
+
      .. code-block:: latex
+
         .. math::
            MSE = \frac{1}{c*i*j} \sum{(I_1-I_2)^2}
+
      That after build turns into:
+
      .. math::
+
         MSE = \frac{1}{c*i*j} \sum{(I_1-I_2)^2}
+
      You can even use it inline as ``:math:` MSE = \frac{1}{c*i*j} \sum{(I_1-I_2)^2}``` that turns into :math:`MSE = \frac{1}{c*i*j} \sum{(I_1-I_2)^2}`.
      If you use some crazy LATEX library extension you need to add those to the ones to use at build time. Look into the file:`opencv/doc/conf.py` configuration file for more information on this.
    + Results. Well, here depending on your program show one of more of the following:
      - Console outputs by using the code block directive.
      - Output images.
      - Runtime videos, visualization. For this use your favorite screens capture software. `Camtasia Studio <http://www.techsmith.com/camtasia/>`_ certainly is one of the better choices, however their prices are out of this world. `CamStudio <http://camstudio.org/>`_ is a free alternative, but less powerful. If you do a video you can upload it to YouTube and then use the raw directive with HTML option to embed it into the generated web page:
+
        .. code-block:: rst
+
           You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=jpBwHxsl1_0>`_.
+
           .. raw:: html
+
              <div align="center">
              <iframe title="Creating a video with OpenCV" width="560" height="349" src="http://www.youtube.com/embed/jpBwHxsl1_0?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
              </div>
+
        This results in the text and video: You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=jpBwHxsl1_0>`_.
+
        .. raw:: html
+
           <div align="center">
           <iframe title="Creating a video with OpenCV" width="560" height="349" src="http://www.youtube.com/embed/jpBwHxsl1_0?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
           </div>
+
      When these aren't self-explanatory make sure to throw in a few guiding lines about what and why we can see.
    + Build the documentation and check for errors or warnings. In the CMake make sure you check or pass the option for building documentation. Then simply build the **docs** project for the PDF file and the **docs_html** project for the web page. Read the output of the build and check for errors/warnings for what you have added. This is also the time to observe and correct any kind of *not so good looking* parts. Remember to keep clean our build logs.
    + Read again your tutorial and check for both programming and spelling errors. If found any, please correct them.
+
 Take home the pride and joy of a job well done!
 ===============================================
+
 Once you are done contact me or dr. Gary Bradski with the tutorial. We may submit the tutorial ourselves to the trunk branch of our repository or ask you to do so.
 Now, to see your work **live** you may need to wait some time. The PDFs are updated usually at the launch of a new OpenCV version. The web pages are a little more diverse. They are automatically rebuilt in each evening. However, the **opencv.itseez.com** website contains only the most recent **stable branch** of OpenCV. Currently this is 2.3. When we add something new (like a tutorial) that first goes to the **trunk branch** of our repository. A build of this you may find on the **opencv.itseez.com/trunk** website. Although, we try to make a build every night occasionally we might freeze any of the branches to fix upcoming issues. During this it may take a little longer to see your work *live*, however if you submited it, be sure that eventually it will show up.
 If you have any questions or advices relating to this tutorial you can contact me at -delete-bernat@-delete-primeranks.net. Of course, delete the -delete- parts of that e-mail address.

doc/tutorials/ml/non_linear_svms/non_linear_svms.rst

@@ -2,56 +2,85 @@
 
 Support Vector Machines for Non-Linearly Separable Data
 *******************************************************
+
 Goal
 ====
 In this tutorial you will learn how to:
+
 .. container:: enumeratevisibleitemswithsquare
+
   + Define the optimization problem for SVMs when it is not possible to separate linearly the training data.
+
   + How to configure the parameters in :svms:`CvSVMParams <cvsvmparams>` to adapt your SVM for this class of problems.
+
 Motivation
 ==========
+
 Why is it interesting to extend the SVM optimation problem in order to handle non-linearly separable training data? Most of the applications in which SVMs are used in computer vision require a more powerful tool than a simple linear classifier. This stems from the fact that in these tasks **the training data can be rarely separated using an hyperplane**.
 Consider one of these tasks, for example, face detection. The training data in this case is composed by a set of images that are faces and another set of images that are non-faces (*every other thing in the world except from faces*). This training data is too complex so as to find a representation of each sample (*feature vector*) that could make the whole set of faces linearly separable from the whole set of non-faces.
+
 Extension of the Optimization Problem
 =====================================
+
 Remember that using SVMs we obtain a separating hyperplane. Therefore, since the training data is now non-linearly separable, we must admit that the hyperplane found will misclassify some of the samples. This *misclassification* is a new variable in the optimization that must be taken into account. The new model has to include both the old requirement of finding the hyperplane that gives the biggest margin and the new one of generalizing the training data correctly by not allowing too many classification errors.
 We start here from the formulation of the optimization problem of finding the hyperplane which maximizes the **margin** (this is explained in the :ref:`previous tutorial <introductiontosvms>`):
+
 .. math::
+
   \min_{\beta, \beta_{0}} L(\beta) = \frac{1}{2}||\beta||^{2} \text{ subject to } y_{i}(\beta^{T} x_{i} + \beta_{0}) \geq 1 \text{ } \forall i
+
 There are multiple ways in which this model can be modified so it takes into account the misclassification errors. For example, one could think of minimizing the same quantity plus a constant times the number of misclassification errors in the training data, i.e.:
+
 .. math::
+
   \min ||\beta||^{2} + C \text{(\# misclassication errors)}
+
 However, this one is not a very good solution since, among some other reasons, we do not distinguish between samples that are misclassified with a small distance to their appropriate decision region or samples that are not. Therefore, a better solution will take into account the *distance of the misclassified samples to their correct decision regions*, i.e.:
+
 .. math::
+
   \min ||\beta||^{2} + C \text{(distance of misclassified samples to their correct regions)}
+
 For each sample of the training data a new parameter :math:`\xi_{i}` is defined. Each one of these parameters contains the distance from its corresponding training sample to their correct decision region. The following picture shows non-linearly separable training data from two classes, a separating hyperplane and the distances to their correct regions of the samples that are misclassified.
+
 .. image:: images/sample-errors-dist.png
    :alt: Samples misclassified and their distances to their correct regions
    :align: center
-.. note:: Only the distances of the samples that are misclassified are shown in the picture. The distances of the rest of the samples are zero since they lay already in their correct decision region.
-The red and blue lines that appear on the picture are the margins to each one of the decision regions. It is very **important** to realize that each of the :math:`\xi_{i}` goes from a misclassified training sample to the margin of its appropriate region.
-Finally, the new formulation for the optimization problem is:
+
+.. note:: Only the distances of the samples that are misclassified are shown in the picture. The distances of the rest of the samples are zero since they lay already in their correct decision region. The red and blue lines that appear on the picture are the margins to each one of the decision regions. It is very **important** to realize that each of the :math:`\xi_{i}` goes from a misclassified training sample to the margin of its appropriate region. Finally, the new formulation for the optimization problem is:
+
 .. math::
+
   \min_{\beta, \beta_{0}} L(\beta) = ||\beta||^{2} + C \sum_{i} {\xi_{i}} \text{ subject to } y_{i}(\beta^{T} x_{i} + \beta_{0}) \geq 1 - \xi_{i} \text{ and } \xi_{i} \geq 0 \text{ } \forall i
+
 How should the parameter C be chosen? It is obvious that the answer to this question depends on how the training data is distributed. Although there is no general answer, it is useful to take into account these rules:
+
 .. container:: enumeratevisibleitemswithsquare
+
    * Large values of C give solutions with *less misclassification errors* but a *smaller margin*. Consider that in this case it is expensive to make misclassification errors. Since the aim of the optimization is to minimize the argument, few misclassifications errors are allowed.
+
    * Small values of C give solutions with *bigger margin* and *more classification errors*. In this case the minimization does not consider that much the term of the sum so it focuses more on finding a hyperplane with big margin.
+
 Source Code
 ===========
+
 You may also find the source code and these video file in the :file:`samples/cpp/tutorial_code/gpu/non_linear_svms/non_linear_svms` folder of the OpenCV source library or :download:`download it from here <../../../../samples/cpp/tutorial_code/ml/non_linear_svms/non_linear_svms.cpp>`.
+
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/ml/non_linear_svms/non_linear_svms.cpp
    :language: cpp
    :linenos:
    :tab-width: 4
    :lines: 1-11, 22-23, 26-
+
 Explanation
 ===========
+
 1. **Set up the training data**
-  The training data of this exercise is formed by a set of labeled 2D-points that belong to one of two different classes. To make the exercise more appealing, the training data is generated randomly using a uniform probability density functions (PDFs).
-  We have divided the generation of the training data into two main parts.
-  In the first part we generate data for both classes that is linearly separable.
+
+  The training data of this exercise is formed by a set of labeled 2D-points that belong to one of two different classes. To make the exercise more appealing, the training data is generated randomly using a uniform probability density functions (PDFs). We have divided the generation of the training data into two main parts. In the first part we generate data for both classes that is linearly separable.
+
   .. code-block:: cpp
+
      // Generate random points for the class 1
      Mat trainClass = trainData.rowRange(0, nLinearSamples);
      // The x coordinate of the points is in [0, 0.4)
@@ -68,8 +97,11 @@ Explanation
      // The y coordinate of the points is in [0, 1)
      c = trainClass.colRange(1,2);
      rng.fill(c, RNG::UNIFORM, Scalar(1), Scalar(HEIGHT));
+
   In the second part we create data for both classes that is non-linearly separable, data that overlaps.
+
   .. code-block:: cpp
+
      // Generate random points for the classes 1 and 2
      trainClass = trainData.rowRange(  nLinearSamples, 2*NTRAINING_SAMPLES-nLinearSamples);
      // The x coordinate of the points is in [0.4, 0.6)
@@ -78,27 +110,43 @@ Explanation
      // The y coordinate of the points is in [0, 1)
      c = trainClass.colRange(1,2);
      rng.fill(c, RNG::UNIFORM, Scalar(1), Scalar(HEIGHT));
+
 2. **Set up SVM's parameters**
+
   .. seealso::
+
       In the previous tutorial :ref:`introductiontosvms` there is an explanation of the atributes of the class :svms:`CvSVMParams <cvsvmparams>` that we configure here before training the SVM.
+
   .. code-block:: cpp
+
      CvSVMParams params;
      params.svm_type    = SVM::C_SVC;
      params.C              = 0.1;
      params.kernel_type = SVM::LINEAR;
      params.term_crit   = TermCriteria(CV_TERMCRIT_ITER, (int)1e7, 1e-6);
+
   There are just two differences between the configuration we do here and the one that was done in the :ref:`previous tutorial <introductiontosvms>` that we use as reference.
+
   * *CvSVM::C_SVC*. We chose here a small value of this parameter in order not to punish too much the misclassification errors in the optimization. The idea of doing this stems from the will of obtaining a solution close to the one intuitively expected. However, we recommend to get a better insight of the problem by making adjustments to this parameter.
       .. note:: Here there are just very few points in the overlapping region between classes, giving a smaller value to **FRAC_LINEAR_SEP** the density of points can be incremented and the impact of the parameter **CvSVM::C_SVC** explored deeply.
+
   * *Termination Criteria of the algorithm*. The maximum number of iterations has to be increased considerably in order to solve correctly a problem with non-linearly separable training data. In particular, we have increased in five orders of magnitude this value.
+
 3. **Train the SVM**
+
   We call the method :svms:`CvSVM::train <cvsvm-train>` to build the SVM model. Watch out that the training process may take a quite long time. Have patiance when your run the program.
+
   .. code-block:: cpp
+
      CvSVM svm;
      svm.train(trainData, labels, Mat(), Mat(), params);
+
 4. **Show the Decision Regions**
+
   The method :svms:`CvSVM::predict <cvsvm-predict>` is used to classify an input sample using a trained SVM. In this example we have used this method in order to color the space depending on the prediction done by the SVM. In other words, an image is traversed interpreting its pixels as points of the Cartesian plane. Each of the points is colored depending on the class predicted by the SVM; in dark green if it is the class with label 1 and in dark blue if it is the class with label 2.
+
   .. code-block:: cpp
+
      Vec3b green(0,100,0), blue (100,0,0);
      for (int i = 0; i < I.rows; ++i)
           for (int j = 0; j < I.cols; ++j)
@@ -108,9 +156,13 @@ Explanation
                if      (response == 1)    I.at<Vec3b>(j, i)  = green;
                else if (response == 2)    I.at<Vec3b>(j, i)  = blue;
           }
+
 5. **Show the training data**
+
   The method :drawingFunc:`circle <circle>` is used to show the samples that compose the training data. The samples of the class labeled with 1 are shown in light green and in light blue the samples of the class labeled with 2.
+
   .. code-block:: cpp
+
      int thick = -1;
      int lineType = 8;
      float px, py;
@@ -128,9 +180,13 @@ Explanation
           py = trainData.at<float>(i,1);
           circle(I, Point( (int) px, (int) py ), 3, Scalar(255, 0, 0), thick, lineType);
      }
+
 6. **Support vectors**
+
   We use here a couple of methods to obtain information about the support vectors. The method :svms:`CvSVM::get_support_vector_count <cvsvm-get-support-vector>` outputs the total number of support vectors used in the problem and with the method :svms:`CvSVM::get_support_vector <cvsvm-get-support-vector>` we obtain each of the support vectors using an index. We have used this methods here to find the training examples that are support vectors and highlight them.
+
   .. code-block:: cpp
+
      thick = 2;
      lineType  = 8;
      int x     = svm.get_support_vector_count();
@@ -139,18 +195,25 @@ Explanation
           const float* v = svm.get_support_vector(i);
           circle(     I,  Point( (int) v[0], (int) v[1]), 6, Scalar(128, 128, 128), thick, lineType);
      }
+
 Results
 =======
+
 .. container:: enumeratevisibleitemswithsquare
+
    * The code opens an image and shows the training examples of both classes. The points of one class are represented with light green and light blue ones are used for the other class.
    * The SVM is trained and used to classify all the pixels of the image. This results in a division of the image in a blue region and a green region. The boundary between both regions is the separating hyperplane. Since the training data is non-linearly separable, it can be seen that some of the examples of both classes are misclassified; some green points lay on the blue region and some blue points lay on the green one.
    * Finally the support vectors are shown using gray rings around the training examples.
+
 .. image:: images/result.png
   :alt: Training data and decision regions given by the SVM
   :width: 300pt
   :align: center
+
 You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=vFv2yPcSo-Q>`_.
+
 .. raw:: html
+
   <div align="center">
   <iframe title="Support Vector Machines for Non-Linearly Separable Data" width="560" height="349" src="http://www.youtube.com/embed/vFv2yPcSo-Q?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
   </div>

modules/contrib/doc/contrib.rst

@@ -10,3 +10,4 @@ The module contains some recently added functionality that has not been stabiliz
     stereo
     FaceRecognizer Documentation <facerec/index>
     Retina Documentation <retina/index>
+    openfabmap

modules/contrib/doc/openfabmap.rst

@@ -1,4 +1,4 @@
-openFABMAP
+OpenFABMAP
 ========================================
 
 .. highlight:: cpp

modules/gpu/doc/feature_detection_and_description.rst

@@ -485,7 +485,7 @@ The class ``BruteForceMatcher_GPU_base`` has an interface similar to the class :
 
 
 gpu::BruteForceMatcher_GPU_base::match
--------------------------------------
+--------------------------------------
 Finds the best match for each descriptor from a query set with train descriptors.
 
 .. ocv:function:: void gpu::BruteForceMatcher_GPU_base::match(const GpuMat& query, const GpuMat& train, std::vector<DMatch>& matches, const GpuMat& mask = GpuMat())
@@ -501,7 +501,7 @@ Finds the best match for each descriptor from a query set with train descriptors
 
 
 gpu::BruteForceMatcher_GPU_base::makeGpuCollection
--------------------------------------------------
+--------------------------------------------------
 Performs a GPU collection of train descriptors and masks in a suitable format for the :ocv:func:`gpu::BruteForceMatcher_GPU_base::matchCollection` function.
 
 .. ocv:function:: void gpu::BruteForceMatcher_GPU_base::makeGpuCollection(GpuMat& trainCollection, GpuMat& maskCollection, const vector<GpuMat>& masks = std::vector<GpuMat>())
@@ -509,7 +509,7 @@ Performs a GPU collection of train descriptors and masks in a suitable format fo
 
 
 gpu::BruteForceMatcher_GPU_base::matchDownload
----------------------------------------------
+----------------------------------------------
 Downloads matrices obtained via :ocv:func:`gpu::BruteForceMatcher_GPU_base::matchSingle` or :ocv:func:`gpu::BruteForceMatcher_GPU_base::matchCollection` to vector with :ocv:class:`DMatch`.
 
 .. ocv:function:: static void gpu::BruteForceMatcher_GPU_base::matchDownload(const GpuMat& trainIdx, const GpuMat& distance, std::vector<DMatch>&matches)
@@ -529,7 +529,7 @@ Converts matrices obtained via :ocv:func:`gpu::BruteForceMatcher_GPU_base::match
 
 
 gpu::BruteForceMatcher_GPU_base::knnMatch
-----------------------------------------
+-----------------------------------------
 Finds the ``k`` best matches for each descriptor from a query set with train descriptors.
 
 .. ocv:function:: void gpu::BruteForceMatcher_GPU_base::knnMatch(const GpuMat& query, const GpuMat& train, std::vector< std::vector<DMatch> >&matches, int k, const GpuMat& mask = GpuMat(), bool compactResult = false)
@@ -561,7 +561,7 @@ The third variant of the method stores the results in GPU memory.
 
 
 gpu::BruteForceMatcher_GPU_base::knnMatchDownload
-------------------------------------------------
+-------------------------------------------------
 Downloads matrices obtained via :ocv:func:`gpu::BruteForceMatcher_GPU_base::knnMatchSingle` or :ocv:func:`gpu::BruteForceMatcher_GPU_base::knnMatch2Collection` to vector with :ocv:class:`DMatch`.
 
 .. ocv:function:: void gpu::BruteForceMatcher_GPU_base::knnMatchDownload(const GpuMat& trainIdx, const GpuMat& distance, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
@@ -585,7 +585,7 @@ If ``compactResult`` is ``true`` , the ``matches`` vector does not contain match
 
 
 gpu::BruteForceMatcher_GPU_base::radiusMatch
--------------------------------------------
+--------------------------------------------
 For each query descriptor, finds the best matches with a distance less than a given threshold.
 
 .. ocv:function:: void gpu::BruteForceMatcher_GPU_base::radiusMatch(const GpuMat& query, const GpuMat& train, std::vector< std::vector<DMatch> >&matches, float maxDistance, const GpuMat& mask = GpuMat(), bool compactResult = false)
@@ -619,7 +619,7 @@ The third variant of the method stores the results in GPU memory and does not st
 
 
 gpu::BruteForceMatcher_GPU_base::radiusMatchDownload
----------------------------------------------------
+----------------------------------------------------
 Downloads matrices obtained via :ocv:func:`gpu::BruteForceMatcher_GPU_base::radiusMatchSingle` or :ocv:func:`gpu::BruteForceMatcher_GPU_base::radiusMatchCollection` to vector with :ocv:class:`DMatch`.
 
 .. ocv:function:: void gpu::BruteForceMatcher_GPU_base::radiusMatchDownload(const GpuMat& trainIdx, const GpuMat& distance, const GpuMat& nMatches, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)

modules/gpu/doc/image_processing.rst

@@ -886,7 +886,7 @@ gpu::FastNonLocalMeansDenoising
 The class implements fast approximate Non Local Means Denoising algorithm.
 
 gpu::FastNonLocalMeansDenoising::simpleMethod()
--------------------------------------
+-----------------------------------------------
 Perform image denoising using Non-local Means Denoising algorithm http://www.ipol.im/pub/algo/bcm_non_local_means_denoising with several computational optimizations. Noise expected to be a gaussian white noise
 
 .. ocv:function:: void gpu::FastNonLocalMeansDenoising::simpleMethod(const GpuMat& src, GpuMat& dst, float h, int search_window = 21, int block_size = 7, Stream& s = Stream::Null())
@@ -910,7 +910,7 @@ This function expected to be applied to grayscale images. For colored images loo
     :ocv:func:`fastNlMeansDenoising`
 
 gpu::FastNonLocalMeansDenoising::labMethod()
--------------------------------------
+--------------------------------------------
 Modification of ``FastNonLocalMeansDenoising::simpleMethod`` for color images
 
 .. ocv:function:: void gpu::FastNonLocalMeansDenoising::labMethod(const GpuMat& src, GpuMat& dst, float h_luminance, float h_color, int search_window = 21, int block_size = 7, Stream& s = Stream::Null())

modules/highgui/doc/reading_and_writing_images_and_video.rst

@@ -75,11 +75,11 @@ Loads an image from a file.
 
     :param flags: Flags specifying the color type of a loaded image:
     
-        * 1 - 
-        * CV_LOAD_IMAGE_ANYDEPTH - 
-        CV_LOAD_IMAGE_COLOR
-        CV_LOAD_IMAGE_GRAYSCALE
+        * CV_LOAD_IMAGE_ANYDEPTH - If set, return 16-bit/32-bit image when the input has the corresponding depth, otherwise convert it to 8-bit.
         
+        * CV_LOAD_IMAGE_COLOR - If set, always convert image to the color one
+
+        * CV_LOAD_IMAGE_GRAYSCALE - If set, always convert image to the grayscale one
 
         * **>0**  Return a 3-channel color image.
             .. note:: In the current implementation the alpha channel, if any, is stripped from the output image. Use negative value if you need the alpha channel.

modules/ml/doc/statistical_models.rst

@@ -156,7 +156,7 @@ CvStatModel::predict
 --------------------
 Predicts the response for a sample.
 
-.. ocv:function:: float CvStatModel::predict( const Mat& sample[, <prediction_params>] ) const
+.. ocv:function:: float CvStatModel::predict( const Mat& sample, <prediction_params> ) const
 
 The method is used to predict the response for a new sample. In case of a classification, the method returns the class label. In case of a regression, the method returns the output function value. The input sample must have as many components as the ``train_data`` passed to ``train`` contains. If the ``var_idx`` parameter is passed to ``train``, it is remembered and then is used to extract only the necessary components from the input sample in the method ``predict``.
 

modules/ocl/doc/data_structures.rst

@@ -0,0 +1,189 @@
+Data Structures
+=============================
+
+.. ocv:class:: oclMat
+
+OpenCV C++ 1-D or 2-D dense array class ::
+
+        class CV_EXPORTS oclMat
+        {
+        public:
+            //! default constructor
+            oclMat();
+            //! constructs oclMatrix of the specified size and type (_type is CV_8UC1, CV_64FC3, CV_32SC(12) etc.)
+            oclMat(int rows, int cols, int type);
+            oclMat(Size size, int type);
+            //! constucts oclMatrix and fills it with the specified value _s.
+            oclMat(int rows, int cols, int type, const Scalar &s);
+            oclMat(Size size, int type, const Scalar &s);
+            //! copy constructor
+            oclMat(const oclMat &m);
+
+            //! constructor for oclMatrix headers pointing to user-allocated data
+            oclMat(int rows, int cols, int type, void *data, size_t step = Mat::AUTO_STEP);
+            oclMat(Size size, int type, void *data, size_t step = Mat::AUTO_STEP);
+
+            //! creates a matrix header for a part of the bigger matrix
+            oclMat(const oclMat &m, const Range &rowRange, const Range &colRange);
+            oclMat(const oclMat &m, const Rect &roi);
+
+            //! builds oclMat from Mat. Perfom blocking upload to device.
+            explicit oclMat (const Mat &m);
+
+            //! destructor - calls release()
+            ~oclMat();
+
+            //! assignment operators
+            oclMat &operator = (const oclMat &m);
+            //! assignment operator. Perfom blocking upload to device.
+            oclMat &operator = (const Mat &m);
+
+
+            //! pefroms blocking upload data to oclMat.
+            void upload(const cv::Mat &m);
+
+
+            //! downloads data from device to host memory. Blocking calls.
+            operator Mat() const;
+            void download(cv::Mat &m) const;
+
+
+            //! returns a new oclMatrix header for the specified row
+            oclMat row(int y) const;
+            //! returns a new oclMatrix header for the specified column
+            oclMat col(int x) const;
+            //! ... for the specified row span
+            oclMat rowRange(int startrow, int endrow) const;
+            oclMat rowRange(const Range &r) const;
+            //! ... for the specified column span
+            oclMat colRange(int startcol, int endcol) const;
+            oclMat colRange(const Range &r) const;
+
+            //! returns deep copy of the oclMatrix, i.e. the data is copied
+            oclMat clone() const;
+            //! copies the oclMatrix content to "m".
+            // It calls m.create(this->size(), this->type()).
+            // It supports any data type
+            void copyTo( oclMat &m ) const;
+            //! copies those oclMatrix elements to "m" that are marked with non-zero mask elements.
+            //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4
+            void copyTo( oclMat &m, const oclMat &mask ) const;
+            //! converts oclMatrix to another datatype with optional scalng. See cvConvertScale.
+            //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4
+            void convertTo( oclMat &m, int rtype, double alpha = 1, double beta = 0 ) const;
+
+            void assignTo( oclMat &m, int type = -1 ) const;
+
+            //! sets every oclMatrix element to s
+            //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4
+            oclMat &operator = (const Scalar &s);
+            //! sets some of the oclMatrix elements to s, according to the mask
+            //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4
+            oclMat &setTo(const Scalar &s, const oclMat &mask = oclMat());
+            //! creates alternative oclMatrix header for the same data, with different
+            // number of channels and/or different number of rows. see cvReshape.
+            oclMat reshape(int cn, int rows = 0) const;
+
+            //! allocates new oclMatrix data unless the oclMatrix already has specified size and type.
+            // previous data is unreferenced if needed.
+            void create(int rows, int cols, int type);
+            void create(Size size, int type);
+            //! decreases reference counter;
+            // deallocate the data when reference counter reaches 0.
+            void release();
+
+            //! swaps with other smart pointer
+            void swap(oclMat &mat);
+
+            //! locates oclMatrix header within a parent oclMatrix. See below
+            void locateROI( Size &wholeSize, Point &ofs ) const;
+            //! moves/resizes the current oclMatrix ROI inside the parent oclMatrix.
+            oclMat &adjustROI( int dtop, int dbottom, int dleft, int dright );
+            //! extracts a rectangular sub-oclMatrix
+            // (this is a generalized form of row, rowRange etc.)
+            oclMat operator()( Range rowRange, Range colRange ) const;
+            oclMat operator()( const Rect &roi ) const;
+
+            //! returns true if the oclMatrix data is continuous
+            // (i.e. when there are no gaps between successive rows).
+            // similar to CV_IS_oclMat_CONT(cvoclMat->type)
+            bool isContinuous() const;
+            //! returns element size in bytes,
+            // similar to CV_ELEM_SIZE(cvMat->type)
+            size_t elemSize() const;
+            //! returns the size of element channel in bytes.
+            size_t elemSize1() const;
+            //! returns element type, similar to CV_MAT_TYPE(cvMat->type)
+            int type() const;
+            //! returns element type, i.e. 8UC3 returns 8UC4 because in ocl
+            //! 3 channels element actually use 4 channel space
+            int ocltype() const;
+            //! returns element type, similar to CV_MAT_DEPTH(cvMat->type)
+            int depth() const;
+            //! returns element type, similar to CV_MAT_CN(cvMat->type)
+            int channels() const;
+            //! returns element type, return 4 for 3 channels element,
+            //!becuase 3 channels element actually use 4 channel space
+            int oclchannels() const;
+            //! returns step/elemSize1()
+            size_t step1() const;
+            //! returns oclMatrix size:
+            // width == number of columns, height == number of rows
+            Size size() const;
+            //! returns true if oclMatrix data is NULL
+            bool empty() const;
+
+            //! returns pointer to y-th row
+            uchar *ptr(int y = 0);
+            const uchar *ptr(int y = 0) const;
+
+            //! template version of the above method
+            template<typename _Tp> _Tp *ptr(int y = 0);
+            template<typename _Tp> const _Tp *ptr(int y = 0) const;
+
+            //! matrix transposition
+            oclMat t() const;
+
+            /*! includes several bit-fields:
+              - the magic signature
+              - continuity flag
+              - depth
+              - number of channels
+              */
+            int flags;
+            //! the number of rows and columns
+            int rows, cols;
+            //! a distance between successive rows in bytes; includes the gap if any
+            size_t step;
+            //! pointer to the data(OCL memory object)
+            uchar *data;
+
+            //! pointer to the reference counter;
+            // when oclMatrix points to user-allocated data, the pointer is NULL
+            int *refcount;
+
+            //! helper fields used in locateROI and adjustROI
+            //datastart and dataend are not used in current version
+            uchar *datastart;
+            uchar *dataend;
+
+            //! OpenCL context associated with the oclMat object.
+            Context *clCxt;
+            //add offset for handle ROI, calculated in byte
+            int offset;
+            //add wholerows and wholecols for the whole matrix, datastart and dataend are no longer used
+            int wholerows;
+            int wholecols;
+        };
+
+Basically speaking, the oclMat is the mirror of Mat with the extension of ocl feature, the members have the same meaning and useage of Mat except following:
+
+datastart and dataend are replaced with wholerows and wholecols
+
+add clCxt for oclMat
+
+Only basic flags are supported in oclMat(i.e. depth number of channels)
+
+All the 3-channel matrix(i.e. RGB image) are represented by 4-channel matrix in oclMat. It means 3-channel image have 4-channel space with the last channel unused. We provide a transparent interface to handle the difference between OpenCV Mat and oclMat.
+
+For example: If a oclMat has 3 channels, channels() returns 3 and oclchannels() returns 4

modules/ocl/doc/feature_detection_and_description.rst

@@ -0,0 +1,502 @@
+Feature Detection And Description
+=================================
+
+.. highlight:: cpp
+
+ocl::Canny
+-------------------
+Finds edges in an image using the [Canny86]_ algorithm.
+
+.. ocv:function:: void ocl::Canny(const oclMat& image, oclMat& edges, double low_thresh, double high_thresh, int apperture_size = 3, bool L2gradient = false)
+
+.. ocv:function:: void ocl::Canny(const oclMat& image, CannyBuf& buf, oclMat& edges, double low_thresh, double high_thresh, int apperture_size = 3, bool L2gradient = false)
+
+.. ocv:function:: void ocl::Canny(const oclMat& dx, const oclMat& dy, oclMat& edges, double low_thresh, double high_thresh, bool L2gradient = false)
+
+.. ocv:function:: void ocl::Canny(const oclMat& dx, const oclMat& dy, CannyBuf& buf, oclMat& edges, double low_thresh, double high_thresh, bool L2gradient = false)
+
+    :param image: Single-channel 8-bit input image.
+
+    :param dx: First derivative of image in the vertical direction. Support only ``CV_32S`` type.
+
+    :param dy: First derivative of image in the horizontal direction. Support only ``CV_32S`` type.
+
+    :param edges: Output edge map. It has the same size and type as  ``image`` .
+
+    :param low_thresh: First threshold for the hysteresis procedure.
+
+    :param high_thresh: Second threshold for the hysteresis procedure.
+
+    :param apperture_size: Aperture size for the  :ocv:func:`Sobel`  operator.
+
+    :param L2gradient: Flag indicating whether a more accurate  :math:`L_2`  norm  :math:`=\sqrt{(dI/dx)^2 + (dI/dy)^2}`  should be used to compute the image gradient magnitude ( ``L2gradient=true`` ), or a faster default  :math:`L_1`  norm  :math:`=|dI/dx|+|dI/dy|`  is enough ( ``L2gradient=false`` ).
+
+    :param buf: Optional buffer to avoid extra memory allocations (for many calls with the same sizes).
+
+.. seealso:: :ocv:func:`Canny`
+
+
+ocl::BruteForceMatcher_OCL
+--------------------------
+.. ocv:class:: ocl::BruteForceMatcher_OCL_base
+
+Brute-force descriptor matcher. For each descriptor in the first set, this matcher finds the closest descriptor in the second set by trying each one. This descriptor matcher supports masking permissible matches between descriptor sets. ::
+
+    class BruteForceMatcher_OCL_base
+    {
+    public:
+            enum DistType {L1Dist = 0, L2Dist, HammingDist};
+
+        // Add descriptors to train descriptor collection.
+        void add(const std::vector<oclMat>& descCollection);
+
+        // Get train descriptors collection.
+        const std::vector<oclMat>& getTrainDescriptors() const;
+
+        // Clear train descriptors collection.
+        void clear();
+
+        // Return true if there are no train descriptors in collection.
+        bool empty() const;
+
+        // Return true if the matcher supports mask in match methods.
+        bool isMaskSupported() const;
+
+        void matchSingle(const oclMat& query, const oclMat& train,
+            oclMat& trainIdx, oclMat& distance,
+            const oclMat& mask = oclMat());
+
+        static void matchDownload(const oclMat& trainIdx,
+            const oclMat& distance, std::vector<DMatch>& matches);
+        static void matchConvert(const Mat& trainIdx,
+            const Mat& distance, std::vector<DMatch>& matches);
+
+        void match(const oclMat& query, const oclMat& train,
+            std::vector<DMatch>& matches, const oclMat& mask = oclMat());
+
+        void makeGpuCollection(oclMat& trainCollection, oclMat& maskCollection,
+            const vector<oclMat>& masks = std::vector<oclMat>());
+
+        void matchCollection(const oclMat& query, const oclMat& trainCollection,
+            oclMat& trainIdx, oclMat& imgIdx, oclMat& distance,
+            const oclMat& maskCollection);
+
+        static void matchDownload(const oclMat& trainIdx, oclMat& imgIdx,
+            const oclMat& distance, std::vector<DMatch>& matches);
+        static void matchConvert(const Mat& trainIdx, const Mat& imgIdx,
+            const Mat& distance, std::vector<DMatch>& matches);
+
+        void match(const oclMat& query, std::vector<DMatch>& matches,
+            const std::vector<oclMat>& masks = std::vector<oclMat>());
+
+        void knnMatchSingle(const oclMat& query, const oclMat& train,
+            oclMat& trainIdx, oclMat& distance, oclMat& allDist, int k,
+            const oclMat& mask = oclMat());
+
+        static void knnMatchDownload(const oclMat& trainIdx, const oclMat& distance,
+            std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
+        static void knnMatchConvert(const Mat& trainIdx, const Mat& distance,
+            std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
+
+        void knnMatch(const oclMat& query, const oclMat& train,
+            std::vector< std::vector<DMatch> >& matches, int k,
+            const oclMat& mask = oclMat(), bool compactResult = false);
+
+        void knnMatch2Collection(const oclMat& query, const oclMat& trainCollection,
+            oclMat& trainIdx, oclMat& imgIdx, oclMat& distance,
+            const oclMat& maskCollection = oclMat());
+
+        static void knnMatch2Download(const oclMat& trainIdx, const oclMat& imgIdx, const oclMat& distance,
+            std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
+        static void knnMatch2Convert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance,
+            std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
+
+        void knnMatch(const oclMat& query, std::vector< std::vector<DMatch> >& matches, int k,
+            const std::vector<oclMat>& masks = std::vector<oclMat>(),
+            bool compactResult = false);
+
+        void radiusMatchSingle(const oclMat& query, const oclMat& train,
+            oclMat& trainIdx, oclMat& distance, oclMat& nMatches, float maxDistance,
+            const oclMat& mask = oclMat());
+
+        static void radiusMatchDownload(const oclMat& trainIdx, const oclMat& distance, const oclMat& nMatches,
+            std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
+        static void radiusMatchConvert(const Mat& trainIdx, const Mat& distance, const Mat& nMatches,
+            std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
+
+        void radiusMatch(const oclMat& query, const oclMat& train,
+            std::vector< std::vector<DMatch> >& matches, float maxDistance,
+            const oclMat& mask = oclMat(), bool compactResult = false);
+
+        void radiusMatchCollection(const oclMat& query, oclMat& trainIdx, oclMat& imgIdx, oclMat& distance, oclMat& nMatches, float maxDistance,
+            const std::vector<oclMat>& masks = std::vector<oclMat>());
+
+        static void radiusMatchDownload(const oclMat& trainIdx, const oclMat& imgIdx, const oclMat& distance, const oclMat& nMatches,
+            std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
+        static void radiusMatchConvert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance, const Mat& nMatches,
+            std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
+
+        void radiusMatch(const oclMat& query, std::vector< std::vector<DMatch> >& matches, float maxDistance,
+            const std::vector<oclMat>& masks = std::vector<oclMat>(), bool compactResult = false);
+
+                DistType distType;
+
+    private:
+        std::vector<oclMat> trainDescCollection;
+    };
+
+
+The class ``BruteForceMatcher_OCL_base`` has an interface similar to the class :ocv:class:`DescriptorMatcher`. It has two groups of ``match`` methods: for matching descriptors of one image with another image or with an image set. Also, all functions have an alternative to save results either to the GPU memory or to the CPU memory. ``BruteForceMatcher_OCL_base`` supports only the ``L1<float>``, ``L2<float>``, and ``Hamming`` distance types.
+
+.. seealso:: :ocv:class:`DescriptorMatcher`, :ocv:class:`BruteForceMatcher`
+
+
+
+ocl::BruteForceMatcher_OCL_base::match
+--------------------------------------
+Finds the best match for each descriptor from a query set with train descriptors.
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::match(const oclMat& query, const oclMat& train, std::vector<DMatch>& matches, const oclMat& mask = oclMat())
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::matchSingle(const oclMat& query, const oclMat& train, oclMat& trainIdx, oclMat& distance, const oclMat& mask = oclMat())
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::match(const oclMat& query, std::vector<DMatch>& matches, const std::vector<oclMat>& masks = std::vector<oclMat>())
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::matchCollection(const oclMat& query, const oclMat& trainCollection, oclMat& trainIdx, oclMat& imgIdx, oclMat& distance, const oclMat& masks)
+
+.. seealso:: :ocv:func:`DescriptorMatcher::match`
+
+
+
+ocl::BruteForceMatcher_OCL_base::makeGpuCollection
+--------------------------------------------------
+Performs a GPU collection of train descriptors and masks in a suitable format for the :ocv:func:`ocl::BruteForceMatcher_OCL_base::matchCollection` function.
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::makeGpuCollection(oclMat& trainCollection, oclMat& maskCollection, const vector<oclMat>& masks = std::vector<oclMat>())
+
+
+
+ocl::BruteForceMatcher_OCL_base::matchDownload
+----------------------------------------------
+Downloads matrices obtained via :ocv:func:`ocl::BruteForceMatcher_OCL_base::matchSingle` or :ocv:func:`ocl::BruteForceMatcher_OCL_base::matchCollection` to vector with :ocv:class:`DMatch`.
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::matchDownload(const oclMat& trainIdx, const oclMat& distance, std::vector<DMatch>&matches)
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::matchDownload(const oclMat& trainIdx, oclMat& imgIdx, const oclMat& distance, std::vector<DMatch>&matches)
+
+
+
+ocl::BruteForceMatcher_OCL_base::matchConvert
+---------------------------------------------
+Converts matrices obtained via :ocv:func:`ocl::BruteForceMatcher_OCL_base::matchSingle` or :ocv:func:`ocl::BruteForceMatcher_OCL_base::matchCollection` to vector with :ocv:class:`DMatch`.
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::matchConvert(const Mat& trainIdx, const Mat& distance, std::vector<DMatch>&matches)
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::matchConvert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance, std::vector<DMatch>&matches)
+
+
+
+ocl::BruteForceMatcher_OCL_base::knnMatch
+-----------------------------------------
+Finds the ``k`` best matches for each descriptor from a query set with train descriptors.
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::knnMatch(const oclMat& query, const oclMat& train, std::vector< std::vector<DMatch> >&matches, int k, const oclMat& mask = oclMat(), bool compactResult = false)
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::knnMatchSingle(const oclMat& query, const oclMat& train, oclMat& trainIdx, oclMat& distance, oclMat& allDist, int k, const oclMat& mask = oclMat())
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::knnMatch(const oclMat& query, std::vector< std::vector<DMatch> >&matches, int k, const std::vector<oclMat>&masks = std::vector<oclMat>(), bool compactResult = false )
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::knnMatch2Collection(const oclMat& query, const oclMat& trainCollection, oclMat& trainIdx, oclMat& imgIdx, oclMat& distance, const oclMat& maskCollection = oclMat())
+
+    :param query: Query set of descriptors.
+
+    :param train: Training set of descriptors. It is not be added to train descriptors collection stored in the class object.
+
+    :param k: Number of the best matches per each query descriptor (or less if it is not possible).
+
+    :param mask: Mask specifying permissible matches between the input query and train matrices of descriptors.
+
+    :param compactResult: If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
+
+
+The function returns detected ``k`` (or less if not possible) matches in the increasing order by distance.
+
+The third variant of the method stores the results in GPU memory.
+
+.. seealso:: :ocv:func:`DescriptorMatcher::knnMatch`
+
+
+
+ocl::BruteForceMatcher_OCL_base::knnMatchDownload
+-------------------------------------------------
+Downloads matrices obtained via :ocv:func:`ocl::BruteForceMatcher_OCL_base::knnMatchSingle` or :ocv:func:`ocl::BruteForceMatcher_OCL_base::knnMatch2Collection` to vector with :ocv:class:`DMatch`.
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::knnMatchDownload(const oclMat& trainIdx, const oclMat& distance, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::knnMatch2Download(const oclMat& trainIdx, const oclMat& imgIdx, const oclMat& distance, std::vector< std::vector<DMatch> >& matches, bool compactResult = false)
+
+If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
+
+
+
+ocl::BruteForceMatcher_OCL_base::knnMatchConvert
+------------------------------------------------
+Converts matrices obtained via :ocv:func:`ocl::BruteForceMatcher_OCL_base::knnMatchSingle` or :ocv:func:`ocl::BruteForceMatcher_OCL_base::knnMatch2Collection` to CPU vector with :ocv:class:`DMatch`.
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::knnMatchConvert(const Mat& trainIdx, const Mat& distance, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::knnMatch2Convert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance, std::vector< std::vector<DMatch> >& matches, bool compactResult = false)
+
+If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
+
+
+
+ocl::BruteForceMatcher_OCL_base::radiusMatch
+--------------------------------------------
+For each query descriptor, finds the best matches with a distance less than a given threshold.
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::radiusMatch(const oclMat& query, const oclMat& train, std::vector< std::vector<DMatch> >&matches, float maxDistance, const oclMat& mask = oclMat(), bool compactResult = false)
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::radiusMatchSingle(const oclMat& query, const oclMat& train, oclMat& trainIdx, oclMat& distance, oclMat& nMatches, float maxDistance, const oclMat& mask = oclMat())
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::radiusMatch(const oclMat& query, std::vector< std::vector<DMatch> >&matches, float maxDistance, const std::vector<oclMat>& masks = std::vector<oclMat>(), bool compactResult = false)
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::radiusMatchCollection(const oclMat& query, oclMat& trainIdx, oclMat& imgIdx, oclMat& distance, oclMat& nMatches, float maxDistance, const std::vector<oclMat>& masks = std::vector<oclMat>())
+
+    :param query: Query set of descriptors.
+
+    :param train: Training set of descriptors. It is not added to train descriptors collection stored in the class object.
+
+    :param maxDistance: Distance threshold.
+
+    :param mask: Mask specifying permissible matches between the input query and train matrices of descriptors.
+
+    :param compactResult: If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
+
+
+The function returns detected matches in the increasing order by distance.
+
+The methods work only on devices with the compute capability  :math:`>=` 1.1.
+
+The third variant of the method stores the results in GPU memory and does not store the points by the distance.
+
+.. seealso:: :ocv:func:`DescriptorMatcher::radiusMatch`
+
+
+
+ocl::BruteForceMatcher_OCL_base::radiusMatchDownload
+----------------------------------------------------
+Downloads matrices obtained via :ocv:func:`ocl::BruteForceMatcher_OCL_base::radiusMatchSingle` or :ocv:func:`ocl::BruteForceMatcher_OCL_base::radiusMatchCollection` to vector with :ocv:class:`DMatch`.
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::radiusMatchDownload(const oclMat& trainIdx, const oclMat& distance, const oclMat& nMatches, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::radiusMatchDownload(const oclMat& trainIdx, const oclMat& imgIdx, const oclMat& distance, const oclMat& nMatches, std::vector< std::vector<DMatch> >& matches, bool compactResult = false)
+
+If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
+
+
+
+
+ocl::BruteForceMatcher_OCL_base::radiusMatchConvert
+---------------------------------------------------
+Converts matrices obtained via :ocv:func:`ocl::BruteForceMatcher_OCL_base::radiusMatchSingle` or :ocv:func:`ocl::BruteForceMatcher_OCL_base::radiusMatchCollection` to vector with :ocv:class:`DMatch`.
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::radiusMatchConvert(const Mat& trainIdx, const Mat& distance, const Mat& nMatches, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
+
+.. ocv:function:: void ocl::BruteForceMatcher_OCL_base::radiusMatchConvert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance, const Mat& nMatches, std::vector< std::vector<DMatch> >& matches, bool compactResult = false)
+
+If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
+
+ocl::HOGDescriptor
+------------------
+
+.. ocv:class:: ocl::HOGDescriptor
+
+The class implements Histogram of Oriented Gradients ([Dalal2005]_) object detector. ::
+
+    struct CV_EXPORTS HOGDescriptor
+    {
+        enum { DEFAULT_WIN_SIGMA = -1 };
+        enum { DEFAULT_NLEVELS = 64 };
+        enum { DESCR_FORMAT_ROW_BY_ROW, DESCR_FORMAT_COL_BY_COL };
+
+        HOGDescriptor(Size win_size=Size(64, 128), Size block_size=Size(16, 16),
+                      Size block_stride=Size(8, 8), Size cell_size=Size(8, 8),
+                      int nbins=9, double win_sigma=DEFAULT_WIN_SIGMA,
+                      double threshold_L2hys=0.2, bool gamma_correction=true,
+                      int nlevels=DEFAULT_NLEVELS);
+
+        size_t getDescriptorSize() const;
+        size_t getBlockHistogramSize() const;
+
+        void setSVMDetector(const vector<float>& detector);
+
+        static vector<float> getDefaultPeopleDetector();
+        static vector<float> getPeopleDetector48x96();
+        static vector<float> getPeopleDetector64x128();
+
+        void detect(const oclMat& img, vector<Point>& found_locations,
+                    double hit_threshold=0, Size win_stride=Size(),
+                    Size padding=Size());
+
+        void detectMultiScale(const oclMat& img, vector<Rect>& found_locations,
+                              double hit_threshold=0, Size win_stride=Size(),
+                              Size padding=Size(), double scale0=1.05,
+                              int group_threshold=2);
+
+        void getDescriptors(const oclMat& img, Size win_stride,
+                            oclMat& descriptors,
+                            int descr_format=DESCR_FORMAT_COL_BY_COL);
+
+        Size win_size;
+        Size block_size;
+        Size block_stride;
+        Size cell_size;
+        int nbins;
+        double win_sigma;
+        double threshold_L2hys;
+        bool gamma_correction;
+        int nlevels;
+
+    private:
+        // Hidden
+    }
+
+
+Interfaces of all methods are kept similar to the ``CPU HOG`` descriptor and detector analogues as much as possible.
+
+
+
+ocl::HOGDescriptor::HOGDescriptor
+-------------------------------------
+Creates the ``HOG`` descriptor and detector.
+
+.. ocv:function:: ocl::HOGDescriptor::HOGDescriptor(Size win_size=Size(64, 128), Size block_size=Size(16, 16), Size block_stride=Size(8, 8), Size cell_size=Size(8, 8), int nbins=9, double win_sigma=DEFAULT_WIN_SIGMA, double threshold_L2hys=0.2, bool gamma_correction=true, int nlevels=DEFAULT_NLEVELS)
+
+   :param win_size: Detection window size. Align to block size and block stride.
+
+   :param block_size: Block size in pixels. Align to cell size. Only (16,16) is supported for now.
+
+   :param block_stride: Block stride. It must be a multiple of cell size.
+
+   :param cell_size: Cell size. Only (8, 8) is supported for now.
+
+   :param nbins: Number of bins. Only 9 bins per cell are supported for now.
+
+   :param win_sigma: Gaussian smoothing window parameter.
+
+   :param threshold_L2hys: L2-Hys normalization method shrinkage.
+
+   :param gamma_correction: Flag to specify whether the gamma correction preprocessing is required or not.
+
+   :param nlevels: Maximum number of detection window increases.
+
+
+
+ocl::HOGDescriptor::getDescriptorSize
+-----------------------------------------
+Returns the number of coefficients required for the classification.
+
+.. ocv:function:: size_t ocl::HOGDescriptor::getDescriptorSize() const
+
+
+
+ocl::HOGDescriptor::getBlockHistogramSize
+---------------------------------------------
+Returns the block histogram size.
+
+.. ocv:function:: size_t ocl::HOGDescriptor::getBlockHistogramSize() const
+
+
+
+ocl::HOGDescriptor::setSVMDetector
+--------------------------------------
+Sets coefficients for the linear SVM classifier.
+
+.. ocv:function:: void ocl::HOGDescriptor::setSVMDetector(const vector<float>& detector)
+
+
+
+ocl::HOGDescriptor::getDefaultPeopleDetector
+------------------------------------------------
+Returns coefficients of the classifier trained for people detection (for default window size).
+
+.. ocv:function:: static vector<float> ocl::HOGDescriptor::getDefaultPeopleDetector()
+
+
+
+ocl::HOGDescriptor::getPeopleDetector48x96
+----------------------------------------------
+Returns coefficients of the classifier trained for people detection (for 48x96 windows).
+
+.. ocv:function:: static vector<float> ocl::HOGDescriptor::getPeopleDetector48x96()
+
+
+
+ocl::HOGDescriptor::getPeopleDetector64x128
+-----------------------------------------------
+Returns coefficients of the classifier trained for people detection (for 64x128 windows).
+
+.. ocv:function:: static vector<float> ocl::HOGDescriptor::getPeopleDetector64x128()
+
+
+
+ocl::HOGDescriptor::detect
+------------------------------
+Performs object detection without a multi-scale window.
+
+.. ocv:function:: void ocl::HOGDescriptor::detect(const oclMat& img, vector<Point>& found_locations, double hit_threshold=0, Size win_stride=Size(), Size padding=Size())
+
+   :param img: Source image.  ``CV_8UC1``  and  ``CV_8UC4`` types are supported for now.
+
+   :param found_locations: Left-top corner points of detected objects boundaries.
+
+   :param hit_threshold: Threshold for the distance between features and SVM classifying plane. Usually it is 0 and should be specfied in the detector coefficients (as the last free coefficient). But if the free coefficient is omitted (which is allowed), you can specify it manually here.
+
+   :param win_stride: Window stride. It must be a multiple of block stride.
+
+   :param padding: Mock parameter to keep the CPU interface compatibility. It must be (0,0).
+
+
+
+ocl::HOGDescriptor::detectMultiScale
+----------------------------------------
+Performs object detection with a multi-scale window.
+
+.. ocv:function:: void ocl::HOGDescriptor::detectMultiScale(const oclMat& img, vector<Rect>& found_locations, double hit_threshold=0, Size win_stride=Size(), Size padding=Size(), double scale0=1.05, int group_threshold=2)
+
+   :param img: Source image. See  :ocv:func:`ocl::HOGDescriptor::detect`  for type limitations.
+
+   :param found_locations: Detected objects boundaries.
+
+   :param hit_threshold: Threshold for the distance between features and SVM classifying plane. See  :ocv:func:`ocl::HOGDescriptor::detect`  for details.
+
+   :param win_stride: Window stride. It must be a multiple of block stride.
+
+   :param padding: Mock parameter to keep the CPU interface compatibility. It must be (0,0).
+
+   :param scale0: Coefficient of the detection window increase.
+
+   :param group_threshold: Coefficient to regulate the similarity threshold. When detected, some objects can be covered by many rectangles. 0 means not to perform grouping. See  :ocv:func:`groupRectangles` .
+
+
+
+ocl::HOGDescriptor::getDescriptors
+--------------------------------------
+Returns block descriptors computed for the whole image.
+
+.. ocv:function:: void ocl::HOGDescriptor::getDescriptors(const oclMat& img, Size win_stride, oclMat& descriptors, int descr_format=DESCR_FORMAT_COL_BY_COL)
+
+   :param img: Source image. See  :ocv:func:`ocl::HOGDescriptor::detect`  for type limitations.
+
+   :param win_stride: Window stride. It must be a multiple of block stride.
+
+   :param descriptors: 2D array of descriptors.
+
+   :param descr_format: Descriptor storage format:
+
+        * **DESCR_FORMAT_ROW_BY_ROW** - Row-major order.
+
+        * **DESCR_FORMAT_COL_BY_COL** - Column-major order.
+
+The function is mainly used to learn the classifier.

modules/ocl/doc/image_filtering.rst

@@ -0,0 +1,283 @@
+Image Filtering
+=============================
+
+.. highlight:: cpp
+
+ocl::Sobel
+------------------
+Returns void
+
+.. ocv:function:: void Sobel(const oclMat &src, oclMat &dst, int ddepth, int dx, int dy, int ksize = 3, double scale = 1, double delta = 0.0, int bordertype = BORDER_DEFAULT)
+
+    :param src: The source image
+
+    :param dst: The destination image; It will have the same size as src
+
+    :param ddepth: The destination image depth
+
+    :param dx: Order of the derivative x
+
+    :param dy: Order of the derivative y
+
+    :param ksize: Size of the extended Sobel kernel
+
+    :param scale: The optional scale factor for the computed derivative values(by default, no scaling is applied)
+
+    :param delta: The optional delta value, added to the results prior to storing them in dst
+
+    :param bordertype: Pixel extrapolation method.
+
+The function computes the first x- or y- spatial image derivative using Sobel operator. Surpport 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4 data type.
+
+ocl::Scharr
+------------------
+Returns void
+
+.. ocv:function:: void Scharr(const oclMat &src, oclMat &dst, int ddepth, int dx, int dy, double scale = 1, double delta = 0.0, int bordertype = BORDER_DEFAULT)
+
+    :param src: The source image
+
+    :param dst: The destination image; It will have the same size as src
+
+    :param ddepth: The destination image depth
+
+    :param dx: Order of the derivative x
+
+    :param dy: Order of the derivative y
+
+    :param scale: The optional scale factor for the computed derivative values(by default, no scaling is applied)
+
+    :param delta: The optional delta value, added to the results prior to storing them in dst
+
+    :param bordertype: Pixel extrapolation method.
+
+The function computes the first x- or y- spatial image derivative using Scharr operator. Surpport 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4 data type.
+
+ocl::GaussianBlur
+------------------
+Returns void
+
+.. ocv:function:: void GaussianBlur(const oclMat &src, oclMat &dst, Size ksize, double sigma1, double sigma2 = 0, int bordertype = BORDER_DEFAULT)
+
+    :param src: The source image
+
+    :param dst: The destination image; It will have the same size and the same type as src
+
+    :param ksize: The Gaussian kernel size; ksize.width and ksize.height can differ, but they both must be positive and odd. Or, they can be zero's, then they are computed from sigma
+
+    :param sigma1sigma2: The Gaussian kernel standard deviations in X and Y direction. If sigmaY is zero, it is set to be equal to sigmaX. If they are both zeros, they are computed from ksize.width and ksize.height. To fully control the result regardless of possible future modification of all this semantics, it is recommended to specify all of ksize, sigmaX and sigmaY
+
+    :param bordertype: Pixel extrapolation method.
+
+The function convolves the source image with the specified Gaussian kernel. In-place filtering is supported.  Surpport 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4 data type.
+
+ocl::boxFilter
+------------------
+Returns void
+
+.. ocv:function:: void boxFilter(const oclMat &src, oclMat &dst, int ddepth, Size ksize, Point anchor = Point(-1, -1), int borderType = BORDER_DEFAULT)
+
+    :param src: The source image
+
+    :param dst: The destination image; It will have the same size and the same type as src
+
+    :param ddepth: The desired depth of the destination image
+
+    :param ksize: The smoothing kernel size. It must be positive and odd
+
+    :param anchor: The anchor point. The default value Point(-1,-1) means that the anchor is at the kernel center.
+
+    :param bordertype: Pixel extrapolation method.
+
+Smoothes image using box filter.Supports data type: CV_8UC1, CV_8UC4, CV_32FC1 and CV_32FC4.
+
+ocl::Laplacian
+------------------
+Returns void
+
+.. ocv:function:: void Laplacian(const oclMat &src, oclMat &dst, int ddepth, int ksize = 1, double scale = 1)
+
+    :param src: The source image
+
+    :param dst: The destination image; It will have the same size and the same type as src
+
+    :param ddepth: The desired depth of the destination image
+
+    :param ksize: The aperture size used to compute the second-derivative filters. It must be positive and odd
+
+    :param scale: The optional scale factor for the computed Laplacian values (by default, no scaling is applied
+
+The function calculates the Laplacian of the source image by adding up the second x and y derivatives calculated using the Sobel operator.
+
+ocl::convolve
+------------------
+Returns void
+
+.. ocv:function:: void convolve(const oclMat &image, const oclMat &temp1, oclMat &result)
+
+    :param image: The source image
+
+    :param temp1: Convolution kernel, a single-channel floating point matrix.
+
+    :param result: The destination image
+
+Convolves an image with the kernel. Supports only CV_32FC1 data types and do not support ROI.
+
+ocl::bilateralFilter
+--------------------
+Returns void
+
+.. ocv:function:: void bilateralFilter(const oclMat &src, oclMat &dst, int d, double sigmaColor, double sigmaSpave, int borderType=BORDER_DEFAULT)
+
+    :param src: The source image
+
+    :param dst: The destination image; will have the same size and the same type as src
+
+    :param d: The diameter of each pixel neighborhood, that is used during filtering. If it is non-positive, it's computed from sigmaSpace
+
+    :param sigmaColor: Filter sigma in the color space. Larger value of the parameter means that farther colors within the pixel neighborhood (see sigmaSpace) will be mixed together, resulting in larger areas of semi-equal color
+
+    :param sigmaSpave: Filter sigma in the coordinate space. Larger value of the parameter means that farther pixels will influence each other (as long as their colors are close enough; see sigmaColor). Then d>0, it specifies the neighborhood size regardless of sigmaSpace, otherwise d is proportional to sigmaSpace.
+
+    :param borderType: Pixel extrapolation method.
+
+Applies bilateral filter to the image. Supports 8UC1 8UC4 data types.
+
+ocl::copyMakeBorder
+--------------------
+Returns void
+
+.. ocv:function:: void copyMakeBorder(const oclMat &src, oclMat &dst, int top, int bottom, int left, int right, int boardtype, const Scalar &value = Scalar())
+
+    :param src: The source image
+
+    :param dst: The destination image; will have the same type as src and the size size(src.cols+left+right, src.rows+top+bottom)
+
+    :param topbottomleftright: Specify how much pixels in each direction from the source image rectangle one needs to extrapolate, e.g. top=1, bottom=1, left=1, right=1mean that 1 pixel-wide border needs to be built
+
+    :param bordertype: Pixel extrapolation method.
+
+    :param value: The border value if borderType==BORDER CONSTANT
+
+Forms a border around the image. Supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4 data types.
+
+ocl::dilate
+------------------
+Returns void
+
+.. ocv:function:: void dilate( const oclMat &src, oclMat &dst, const Mat &kernel, Point anchor = Point(-1, -1), int iterations = 1, int borderType = BORDER_CONSTANT, const Scalar &borderValue = morphologyDefaultBorderValue())
+
+    :param src: The source image
+
+    :param dst: The destination image; It will have the same size and the same type as src
+
+    :param kernel: The structuring element used for dilation. If element=Mat(), a 3times 3 rectangular structuring element is used
+
+    :param anchor: Position of the anchor within the element. The default value (-1, -1) means that the anchor is at the element center, only default value is supported
+
+    :param iterations: The number of times dilation is applied
+
+    :param bordertype: Pixel extrapolation method.
+
+    :param value: The border value if borderType==BORDER CONSTANT
+
+The function dilates the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the maximum is taken. Supports 8UC1 8UC4 data types.
+
+ocl::erode
+------------------
+Returns void
+
+.. ocv:function:: void erode( const oclMat &src, oclMat &dst, const Mat &kernel, Point anchor = Point(-1, -1), int iterations = 1, int borderType = BORDER_CONSTANT, const Scalar &borderValue = morphologyDefaultBorderValue())
+
+    :param src: The source image
+
+    :param dst: The destination image; It will have the same size and the same type as src
+
+    :param kernel: The structuring element used for dilation. If element=Mat(), a 3times 3 rectangular structuring element is used
+
+    :param anchor: Position of the anchor within the element. The default value (-1, -1) means that the anchor is at the element center, only default value is supported
+
+    :param iterations: The number of times dilation is applied
+
+    :param bordertype: Pixel extrapolation method.
+
+    :param value: The border value if borderType==BORDER CONSTANT
+
+The function erodes the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the minimum is taken. Supports 8UC1 8UC4 data types.
+
+ocl::morphologyEx
+------------------
+Returns void
+
+.. ocv:function:: void morphologyEx( const oclMat &src, oclMat &dst, int op, const Mat &kernel, Point anchor = Point(-1, -1), int iterations = 1, int borderType = BORDER_CONSTANT, const Scalar &borderValue = morphologyDefaultBorderValue())
+
+    :param src: The source image
+
+    :param dst: The destination image; It will have the same size and the same type as src
+
+    :param op: Type of morphological operation, one of the following: ERODE DILTATE OPEN CLOSE GRADIENT TOPHAT BLACKHAT
+
+    :param kernel: The structuring element used for dilation. If element=Mat(), a 3times 3 rectangular structuring element is used
+
+    :param anchor: Position of the anchor within the element. The default value (-1, -1) means that the anchor is at the element center, only default value is supported
+
+    :param iterations: The number of times dilation is applied
+
+    :param bordertype: Pixel extrapolation method.
+
+    :param value: The border value if borderType==BORDER CONSTANT
+
+A wrapper for erode and dilate. Supports 8UC1 8UC4 data types.
+
+ocl::pyrDown
+-------------------
+Smoothes an image and downsamples it.
+
+.. ocv:function:: void ocl::pyrDown(const oclMat& src, oclMat& dst)
+
+    :param src: Source image.
+
+    :param dst: Destination image. Will have ``Size((src.cols+1)/2, (src.rows+1)/2)`` size and the same type as ``src`` .
+
+.. seealso:: :ocv:func:`pyrDown`
+
+
+
+ocl::pyrUp
+-------------------
+Upsamples an image and then smoothes it.
+
+.. ocv:function:: void ocl::pyrUp(const oclMat& src, oclMat& dst)
+
+    :param src: Source image.
+
+    :param dst: Destination image. Will have ``Size(src.cols*2, src.rows*2)`` size and the same type as ``src`` .
+
+.. seealso:: :ocv:func:`pyrUp`
+
+ocl::columnSum
+------------------
+Computes a vertical (column) sum.
+
+.. ocv:function:: void ocl::columnSum(const oclMat& src, oclMat& sum)
+
+    :param src: Source image. Only  ``CV_32FC1`` images are supported for now.
+
+    :param sum: Destination image of the  ``CV_32FC1`` type.
+
+
+ocl::blendLinear
+-------------------
+Performs linear blending of two images.
+
+.. ocv:function:: void ocl::blendLinear(const oclMat& img1, const oclMat& img2, const oclMat& weights1, const oclMat& weights2, oclMat& result)
+
+    :param img1: First image. Supports only ``CV_8U`` and ``CV_32F`` depth.
+
+    :param img2: Second image. Must have the same size and the same type as ``img1`` .
+
+    :param weights1: Weights for first image. Must have tha same size as ``img1`` . Supports only ``CV_32F`` type.
+
+    :param weights2: Weights for second image. Must have tha same size as ``img2`` . Supports only ``CV_32F`` type.
+
+    :param result: Destination image.

modules/ocl/doc/image_processing.rst

@@ -0,0 +1,331 @@
+Image Processing
+=============================
+
+.. highlight:: cpp
+
+ocl::cornerHarris
+------------------
+Returns void
+
+.. ocv:function:: void cornerHarris(const oclMat &src, oclMat &dst, int blockSize, int ksize, double k, int bordertype = cv::BORDER_DEFAULT)
+
+    :param src: Source image. Only CV_8UC1 and CV_32FC1 images are supported now.
+
+    :param dst: Destination image containing cornerness values. It has the same size as src and CV_32FC1 type.
+
+    :param blockSize: Neighborhood size
+
+    :param ksize: Aperture parameter for the Sobel operator
+
+    :param k: Harris detector free parameter
+
+    :param bordertype: Pixel extrapolation method. Only BORDER_REFLECT101, BORDER_REFLECT, BORDER_CONSTANT and BORDER_REPLICATE are supported now.
+
+Calculate Harris corner.
+
+ocl::cornerMinEigenVal
+------------------------
+Returns void
+
+.. ocv:function:: void cornerMinEigenVal(const oclMat &src, oclMat &dst, int blockSize, int ksize, int bordertype = cv::BORDER_DEFAULT)
+
+    :param src: Source image. Only CV_8UC1 and CV_32FC1 images are supported now.
+
+    :param dst: Destination image containing cornerness values. It has the same size as src and CV_32FC1 type.
+
+    :param blockSize: Neighborhood size
+
+    :param ksize: Aperture parameter for the Sobel operator
+
+    :param bordertype: Pixel extrapolation method. Only BORDER_REFLECT101, BORDER_REFLECT, BORDER_CONSTANT and BORDER_REPLICATE are supported now.
+
+Calculate MinEigenVal.
+
+ocl::calcHist
+------------------
+Returns void
+
+.. ocv:function:: void calcHist(const oclMat &mat_src, oclMat &mat_hist)
+
+    :param src: Source arrays. They all should have the same depth, CV 8U, and the same size. Each of them can have an arbitrary number of channels.
+
+    :param dst: The output histogram, a dense or sparse dims-dimensional
+
+Calculates histogram of one or more arrays. Supports only 8UC1 data type.
+
+ocl::remap
+------------------
+Returns void
+
+.. ocv:function:: void remap(const oclMat &src, oclMat &dst, oclMat &map1, oclMat &map2, int interpolation, int bordertype, const Scalar &value = Scalar())
+
+    :param src: Source image. Only CV_8UC1 and CV_32FC1 images are supported now.
+
+    :param dst: Destination image containing cornerness values. It has the same size as src and CV_32FC1 type.
+
+    :param map1: The first map of either (x,y) points or just x values having the type CV_16SC2 , CV_32FC1 , or CV_32FC2 . See covertMaps() for details on converting a floating point representation to fixed-point for speed.
+
+    :param map2: The second map of y values having the type CV_32FC1 , or none (empty map if map1 is (x,y) points), respectively.
+
+    :param interpolation: The interpolation method
+
+    :param bordertype: Pixel extrapolation method. Only BORDER_CONSTANT are supported now.
+
+    :param value: The border value if borderType==BORDER CONSTANT
+
+The function remap transforms the source image using the specified map: dst (x ,y) = src (map1(x , y) , map2(x , y)) where values of pixels with non-integer coordinates are computed using one of available interpolation methods. map1 and map2 can be encoded as separate floating-point maps in map1 and map2 respectively, or interleaved floating-point maps of (x,y) in map1. Supports CV_8UC1, CV_8UC3, CV_8UC4, CV_32FC1 , CV_32FC3 and CV_32FC4 data types.
+
+ocl::resize
+------------------
+Returns void
+
+.. ocv:function:: void resize(const oclMat &src, oclMat &dst, Size dsize, double fx = 0, double fy = 0, int interpolation = INTER_LINEAR)
+
+    :param src: Source image.
+
+    :param dst: Destination image.
+
+    :param dsize: he destination image size. If it is zero, then it is computed as: dsize = Size(round(fx*src.cols), round(fy*src.rows)). Either dsize or both fx or fy must be non-zero.
+
+    :param fx: The scale factor along the horizontal axis. When 0, it is computed as (double)dsize.width/src.cols
+
+    :param fy: The scale factor along the vertical axis. When 0, it is computed as (double)dsize.height/src.rows
+
+    :param interpolation: The interpolation method: INTER NEAREST or INTER LINEAR
+
+Resizes an image. Supports CV_8UC1, CV_8UC3, CV_8UC4, CV_32FC1 , CV_32FC3 and CV_32FC4 data types.
+
+ocl::warpAffine
+------------------
+Returns void
+
+.. ocv:function:: void warpAffine(const oclMat &src, oclMat &dst, const Mat &M, Size dsize, int flags = INTER_LINEAR)
+
+    :param src: Source image.
+
+    :param dst: Destination image.
+
+    :param M: 2times 3 transformation matrix
+
+    :param dsize: Size of the destination image
+
+    :param flags: A combination of interpolation methods, see cv::resize, and the optional flag WARP INVERSE MAP that means that M is the inverse transformation (dst to $src)
+
+The function warpAffine transforms the source image using the specified matrix. Supports INTER_NEAREST, INTER_LINEAR, INTER_CUBIC types.
+
+ocl::warpPerspective
+---------------------
+Returns void
+
+.. ocv:function:: void warpPerspective(const oclMat &src, oclMat &dst, const Mat &M, Size dsize, int flags = INTER_LINEAR)
+
+    :param src: Source image.
+
+    :param dst: Destination image.
+
+    :param M: 2times 3 transformation matrix
+
+    :param dsize: Size of the destination image
+
+    :param flags: A combination of interpolation methods, see cv::resize, and the optional flag WARP INVERSE MAP that means that M is the inverse transformation (dst to $src)
+
+Applies a perspective transformation to an image. Supports INTER_NEAREST, INTER_LINEAR, INTER_CUBIC types.
+
+ocl::cvtColor
+------------------
+Returns void
+
+.. ocv:function:: void cvtColor(const oclMat &src, oclMat &dst, int code , int dcn = 0)
+
+    :param src: Source image.
+
+    :param dst: Destination image.
+
+    :param code:The color space conversion code
+
+    :param dcn: The number of channels in the destination image; if the parameter is 0, the number of the channels will be derived automatically from src and the code
+
+Converts image from one color space to another.For now, only RGB2GRAY is supportted. Supports.CV_8UC1,CV_8UC4,CV_32SC1,CV_32SC4,CV_32FC1,CV_32FC4
+
+ocl::threshold
+------------------
+Returns Threshold value
+
+.. ocv:function:: double threshold(const oclMat &src, oclMat &dst, double thresh, double maxVal, int type = THRESH_TRUNC)
+
+    :param src: The source array
+
+    :param dst: Destination array; will have the same size and the same type as src
+
+    :param thresh: Threshold value
+
+    :param maxVal: Maximum value to use with THRESH BINARY and THRESH BINARY INV thresholding types
+
+    :param type: Thresholding type
+
+The function applies fixed-level thresholding to a single-channel array. The function is typically used to get a bi-level (binary) image out of a grayscale image or for removing a noise, i.e. filtering out pixels with too small or too large values. There are several types of thresholding that the function supports that are determined by thresholdType. Supports only CV_32FC1 and CV_8UC1 data type.
+
+ocl::buildWarpPlaneMaps
+-----------------------
+Builds plane warping maps.
+
+.. ocv:function:: void ocl::buildWarpPlaneMaps(Size src_size, Rect dst_roi, const Mat& R, double f, double s, double dist, oclMat& map_x, oclMat& map_y)
+
+
+
+ocl::buildWarpCylindricalMaps
+-----------------------------
+Builds cylindrical warping maps.
+
+.. ocv:function:: void ocl::buildWarpCylindricalMaps(Size src_size, Rect dst_roi, const Mat& R, double f, double s, oclMat& map_x, oclMat& map_y)
+
+
+
+
+ocl::buildWarpSphericalMaps
+---------------------------
+Builds spherical warping maps.
+
+.. ocv:function:: void ocl::buildWarpSphericalMaps(Size src_size, Rect dst_roi, const Mat& R, double f, double s, oclMat& map_x, oclMat& map_y)
+
+
+ocl::buildWarpPerspectiveMaps
+-----------------------------
+Builds transformation maps for perspective transformation.
+
+.. ocv:function:: void buildWarpAffineMaps(const Mat& M, bool inverse, Size dsize, oclMat& xmap, oclMat& ymap)
+
+    :param M: *3x3*  transformation matrix.
+
+    :param inverse: Flag  specifying that  ``M`` is an inverse transformation ( ``dst=>src`` ).
+
+    :param dsize: Size of the destination image.
+
+    :param xmap: X values with  ``CV_32FC1`` type.
+
+    :param ymap: Y values with  ``CV_32FC1`` type.
+
+.. seealso:: :ocv:func:`ocl::warpPerspective` , :ocv:func:`ocl::remap`
+
+
+ocl::buildWarpAffineMaps
+------------------------
+Builds transformation maps for affine transformation.
+
+.. ocv:function:: void buildWarpAffineMaps(const Mat& M, bool inverse, Size dsize, oclMat& xmap, oclMat& ymap)
+
+    :param M: *2x3*  transformation matrix.
+
+    :param inverse: Flag  specifying that  ``M`` is an inverse transformation ( ``dst=>src`` ).
+
+    :param dsize: Size of the destination image.
+
+    :param xmap: X values with  ``CV_32FC1`` type.
+
+    :param ymap: Y values with  ``CV_32FC1`` type.
+
+.. seealso:: :ocv:func:`ocl::warpAffine` , :ocv:func:`ocl::remap`
+
+ocl::PyrLKOpticalFlow
+---------------------
+.. ocv:class:: ocl::PyrLKOpticalFlow
+
+Class used for calculating an optical flow. ::
+
+    class PyrLKOpticalFlow
+    {
+    public:
+        PyrLKOpticalFlow();
+
+        void sparse(const oclMat& prevImg, const oclMat& nextImg, const oclMat& prevPts, oclMat& nextPts,
+            oclMat& status, oclMat* err = 0);
+
+        void dense(const oclMat& prevImg, const oclMat& nextImg, oclMat& u, oclMat& v, oclMat* err = 0);
+
+        Size winSize;
+        int maxLevel;
+        int iters;
+        double derivLambda;
+        bool useInitialFlow;
+        float minEigThreshold;
+        bool getMinEigenVals;
+
+        void releaseMemory();
+    };
+
+The class can calculate an optical flow for a sparse feature set or dense optical flow using the iterative Lucas-Kanade method with pyramids.
+
+.. seealso:: :ocv:func:`calcOpticalFlowPyrLK`
+
+
+
+ocl::PyrLKOpticalFlow::sparse
+-----------------------------
+Calculate an optical flow for a sparse feature set.
+
+.. ocv:function:: void ocl::PyrLKOpticalFlow::sparse(const oclMat& prevImg, const oclMat& nextImg, const oclMat& prevPts, oclMat& nextPts, oclMat& status, oclMat* err = 0)
+
+    :param prevImg: First 8-bit input image (supports both grayscale and color images).
+
+    :param nextImg: Second input image of the same size and the same type as  ``prevImg`` .
+
+    :param prevPts: Vector of 2D points for which the flow needs to be found. It must be one row matrix with CV_32FC2 type.
+
+    :param nextPts: Output vector of 2D points (with single-precision floating-point coordinates) containing the calculated new positions of input features in the second image. When ``useInitialFlow`` is true, the vector must have the same size as in the input.
+
+    :param status: Output status vector (CV_8UC1 type). Each element of the vector is set to 1 if the flow for the corresponding features has been found. Otherwise, it is set to 0.
+
+    :param err: Output vector (CV_32FC1 type) that contains the difference between patches around the original and moved points or min eigen value if ``getMinEigenVals`` is checked. It can be NULL, if not needed.
+
+.. seealso:: :ocv:func:`calcOpticalFlowPyrLK`
+
+
+
+ocl::PyrLKOpticalFlow::dense
+-----------------------------
+Calculate dense optical flow.
+
+.. ocv:function:: void ocl::PyrLKOpticalFlow::dense(const oclMat& prevImg, const oclMat& nextImg, oclMat& u, oclMat& v, oclMat* err = 0)
+
+    :param prevImg: First 8-bit grayscale input image.
+
+    :param nextImg: Second input image of the same size and the same type as  ``prevImg`` .
+
+    :param u: Horizontal component of the optical flow of the same size as input images, 32-bit floating-point, single-channel
+
+    :param v: Vertical component of the optical flow of the same size as input images, 32-bit floating-point, single-channel
+
+    :param err: Output vector (CV_32FC1 type) that contains the difference between patches around the original and moved points or min eigen value if ``getMinEigenVals`` is checked. It can be NULL, if not needed.
+
+
+
+ocl::PyrLKOpticalFlow::releaseMemory
+------------------------------------
+Releases inner buffers memory.
+
+.. ocv:function:: void ocl::PyrLKOpticalFlow::releaseMemory()
+
+
+ocl::interpolateFrames
+----------------------
+Interpolate frames (images) using provided optical flow (displacement field).
+
+.. ocv:function:: void ocl::interpolateFrames(const oclMat& frame0, const oclMat& frame1, const oclMat& fu, const oclMat& fv, const oclMat& bu, const oclMat& bv, float pos, oclMat& newFrame, oclMat& buf)
+
+    :param frame0: First frame (32-bit floating point images, single channel).
+
+    :param frame1: Second frame. Must have the same type and size as ``frame0`` .
+
+    :param fu: Forward horizontal displacement.
+
+    :param fv: Forward vertical displacement.
+
+    :param bu: Backward horizontal displacement.
+
+    :param bv: Backward vertical displacement.
+
+    :param pos: New frame position.
+
+    :param newFrame: Output image.
+
+    :param buf: Temporary buffer, will have width x 6*height size, CV_32FC1 type and contain 6 oclMat: occlusion masks for first frame, occlusion masks for second, interpolated forward horizontal flow, interpolated forward vertical flow, interpolated backward horizontal flow, interpolated backward vertical flow.

modules/ocl/doc/introduction.rst

@@ -6,14 +6,39 @@ OpenCL Module Introduction
 General Information
 -------------------
 
-The OpenCV OCL module is a set of classes and functions to utilize OpenCL compatible device. It should support any device compatible with OpenCL 1.1. The module includes utility functions, low-level vision primitives, and a few high-level algorithms ready to be used in the end-user applications.
+The OpenCV OCL module is a set of classes and functions to utilize OpenCL compatible device. In theroy, it supports any OpenCL 1.1 compatible device, but we only test it on AMD's, Intel's and NVIDIA's GPU at this stage. The compatibility, correctness and performance on CPU is not guaranteed. The OpenCV OCL module includes utility functions, low-level vision primitives, and high-level algorithms. The utility functions and low-level primitives provide a powerful infrastructure for developing fast vision algorithms taking advangtage of OCL whereas the high-level functionality includes some state-of-the-art algorithms(such as surf detector, face detector) ready to be used by the application developers.
 
-The OpenCV OCL module is designed as a host-level API plus device-level kernels. The device-level kernels are converted to text string and are compiled at runtime, so it need OpenCL runtime support. To correctly run the OpenCV OCL module, make sure you have OpenCL runtime provided by your device vendor, which is device driver normally.
+The OpenCV OCL module is designed as a host-level API plus device-level kernels. The device-level kernels are collected as strings at OpenCV compile time and are compiled at runtime, so it need OpenCL runtime support. To correctly build the OpenCV OCL module, make sure you have OpenCL SDK provided your device vendor. To correctly run the OpenCV OCL module, make sure you have OpenCL runtime provided by your device vendor, which is device driver normally.
 
-The OpenCV OCL module is designed for ease of use and does not require any knowledge of OpenCL. Though, such a knowledge will certainly be useful to handle non-trivial cases or achieve the highest performance. It is helpful to understand the cost of various operations, what the module does, what the preferred data formats are, and so on. Since there is data transfer between OpenCL host and OpenCL device, for better performance it's recommended to copy data once to the OpenCL host memory (i.e. copy ``cv::Mat`` to ``cv::ocl::OclMat``), then call several ``cv::ocl`` functions and then copy the result back to CPU memory, rather than do forward and backward transfer for each OCL function.
+The OpenCV OCL module is designed for ease of use and does not require any knowledge of OpenCL. Though, such a knowledge will certainly be useful to handle non-trivial cases or achieve the highest performance. It is helpful to understand the cost of various operations, what the OCL does, what the preferred data formats are, and so on. Since there is data transfer between OpenCL host and OpenCL device, for better performance it's recommended to copy data once to the OpenCL host memory (i.e. copy ``cv::Mat`` to ``cv::ocl::OclMat``), then call several ``cv::ocl`` functions and then copy the result back to CPU memory, rather than do forward and backward transfer for each OCL function.
 
-To enable OCL support, configure OpenCV using CMake with the option ``WITH\_OPENCL=ON``. If the option is passed and if OpenCL SDK is installed (e.g. on MacOSX it's always the case), the full-featured OpenCV OCL module will be built. Otherwise, the module will not be built.
+To enable OCL support, configure OpenCV using CMake with WIHT\_OPENCL=ON. When the flag is set and if OpenCL SDK is installed, the full-featured OpenCV OCL module is built. Otherwise, the module may be not built. If you have AMD'S FFT and BLAS library, you can select it with WITH\_OPENCLAMDFFT=ON, WIHT\_OPENCLAMDBLAS=ON.
 
-Right now, the user should define the ``cv::ocl::Info`` class in the application and call ``cv::ocl::getDevice`` before any ``cv::ocl::<func>``. This operation initialize OpenCL runtime and set the first found device as computing device. If there is more than one device and you want to use non-default device, you should call ``cv::ocl::setDevice``.
+Right now, the user should define the cv::ocl::Info class in the application and call cv::ocl::getDevice before any cv::ocl::func. This operation initialize OpenCL runtime and set the first found device as computing device. If there are more than one device and you want to use undefault device, you can call cv::ocl::setDevice then.
 
-In the current version, all the threads share the same context and device so the multi-devices are not supported. This is to be fixed in future releases.
+In the current version, all the thread share the same context and device so the multi-devices are not supported. We will add this feature soon. If a function support 4-channel operator, it should support 3-channel operator as well, because All the 3-channel matrix(i.e. RGB image) are represented by 4-channel matrix in oclMat. It means 3-channel image have 4-channel space with the last channel unused. We provide a transparent interface to handle the difference between OpenCV Mat and oclMat.
+
+Developer Notes
+-------------------
+
+This section descripe the design details of ocl module for who are interested in the detail of this module or want to contribute this module. User who isn't interested the details, can safely ignore it.
+
+1. OpenCL version should be larger than 1.1 with FULL PROFILE.
+
+2. There's only one OpenCL context and commandqueue and generated as a singleton. So now it only support one device with single commandqueue.
+
+3. All the functions use 256 as its workgroup size if possible, so the max work group size of the device must larger than 256.
+
+4. If the device support double, we will use double in kernel if OpenCV cpu version use double, otherwise, we use float instead.
+
+5. The oclMat use buffer object, not image object.
+
+6. All the 3-channel matrix(i.e. RGB image) are represented by 4-channel matrix in oclMat. It means 3-channel image have 4-channel space with the last channel unused. We provide a transparent interface to handle the difference between OpenCV Mat and oclMat.
+
+7. All the matrix in oclMat is aligned in column(now the alignment factor is 32 byte). It means, if a matrix is n columns m rows with the element size x byte, we will assign ALIGNMENT(x*n) bytes for each column with the last ALIGNMENT(x*n) - x*n bytes unused, so there's small holes after each column if its size is not the multiply of ALIGN.
+
+8. Data transfer between Mat and oclMat. If the CPU matrix is aligned in column, we will use faster API to transfer between Mat and oclMat, otherwise, we will use clEnqueueRead/WriteBufferRect to transfer data to guarantee the alignment. 3-channel matrix is an exception, it's directly transferred to a temp buffer and then padded to 4-channel matrix(also aligned) when uploading and do the reverse operation when downloading.
+
+9. Data transfer between Mat and oclMat. ROI is a feature of OpenCV, which allow users process a sub rectangle of a matrix. When a CPU matrix which has ROI will be transfered to GPU, the whole matrix will be transfered and set ROI as CPU's. In a word, we always transfer the whole matrix despite whether it has ROI or not.
+
+10. All the kernel file should locate in ocl/src/kernels/ with the extension ".cl". ALL the kernel files are transformed to pure characters at compilation time in kernels.cpp, and the file name without extension is the name of the characters.

modules/ocl/doc/matrix_reductions.rst

@@ -0,0 +1,70 @@
+Matrix Reductions
+=============================
+
+.. highlight:: cpp
+
+ocl::countNonZero
+------------------
+Returns the number of non-zero elements in src
+
+.. ocv:function:: int countNonZero(const oclMat &src)
+
+    :param src: Single-channel array
+
+Counts non-zero array elements.
+
+ocl::minMax
+------------------
+Returns void
+
+.. ocv:function:: void minMax(const oclMat &src, double *minVal, double *maxVal = 0, const oclMat &mask = oclMat())
+
+    :param src: Single-channel array
+
+    :param minVal: Pointer to returned minimum value, should not be NULL
+
+    :param maxVal: Pointer to returned maximum value, should not be NULL
+
+    :param mask: The optional mask used to select a sub-array
+
+Finds global minimum and maximum in a whole array or sub-array. Supports all data types.
+
+ocl::minMaxLoc
+------------------
+Returns void
+
+.. ocv:function:: void minMaxLoc(const oclMat &src, double *minVal, double *maxVal = 0, Point *minLoc = 0, Point *maxLoc = 0,const oclMat &mask = oclMat())
+
+    :param src: Single-channel array
+
+    :param minVal: Pointer to returned minimum value, should not be NULL
+
+    :param maxVal: Pointer to returned maximum value, should not be NULL
+
+    :param minLoc: Pointer to returned minimum location (in 2D case), should not be NULL
+
+    :param maxLoc: Pointer to returned maximum location (in 2D case) should not be NULL
+
+    :param mask: The optional mask used to select a sub-array
+
+The functions minMaxLoc find minimum and maximum element values and their positions. The extremums are searched across the whole array, or, if mask is not an empty array, in the specified array region. The functions do not work with multi-channel arrays.
+
+ocl::Sum
+------------------
+Returns the sum of matrix elements for each channel
+
+.. ocv:function:: Scalar sum(const oclMat &m)
+
+    :param m: The Source image of all depth
+
+Counts the sum of matrix elements for each channel.
+
+ocl::sqrSum
+------------------
+Returns the squared sum of matrix elements for each channel
+
+.. ocv:function:: Scalar sqrSum(const oclMat &m)
+
+    :param m: The Source image of all depth
+
+Counts the squared sum of matrix elements for each channel.

modules/ocl/doc/object_detection.rst

@@ -0,0 +1,188 @@
+Object Detection
+=============================
+
+.. highlight:: cpp
+
+ocl::oclCascadeClassifier
+-------------------------
+
+Cascade classifier class used for object detection. Supports HAAR cascade classifier  in the form of cross link ::
+
+    class CV_EXPORTS OclCascadeClassifier : public  cv::CascadeClassifier
+    {
+    public:
+          OclCascadeClassifier() {};
+          ~OclCascadeClassifier() {};
+           CvSeq *oclHaarDetectObjects(oclMat &gimg, CvMemStorage *storage,
+                                      double scaleFactor,int minNeighbors,
+                                      int flags, CvSize minSize = cvSize(0, 0),
+                                      CvSize maxSize = cvSize(0, 0));
+    };
+
+ocl::oclCascadeClassifier::oclHaarDetectObjects
+------------------------------------------------------
+Returns the detected objects by a list of rectangles
+
+.. ocv:function:: CvSeq *OclCascadeClassifier::oclHaarDetectObjects(oclMat &gimg, CvMemStorage *storage, double scaleFactor,int minNeighbors, int flags, CvSize minSize = cvSize(0, 0), CvSize maxSize = cvSize(0, 0))
+
+    :param image:  Matrix of type CV_8U containing an image where objects should be detected.
+
+    :param imageobjectsBuff: Buffer to store detected objects (rectangles). If it is empty, it is allocated with the defaultsize. If not empty, the function searches not more than N  objects, where N = sizeof(objectsBufers data)/sizeof(cv::Rect).
+
+    :param scaleFactor: Parameter specifying how much the image size is reduced at each image scale.
+
+    :param minNeighbors: Parameter specifying how many neighbors each candidate rectangle should have to retain it.
+
+    :param minSize: Minimum possible object size. Objects smaller than that are ignored.
+
+Detects objects of different sizes in the input image,only tested for face detection now. The function returns the number of detected objects.
+
+ocl::MatchTemplateBuf
+---------------------
+.. ocv:class:: ocl::MatchTemplateBuf
+
+Class providing memory buffers for :ocv:func:`ocl::matchTemplate` function, plus it allows to adjust some specific parameters. ::
+
+    struct CV_EXPORTS MatchTemplateBuf
+    {
+        Size user_block_size;
+        oclMat imagef, templf;
+        std::vector<oclMat> images;
+        std::vector<oclMat> image_sums;
+        std::vector<oclMat> image_sqsums;
+    };
+
+You can use field `user_block_size` to set specific block size for :ocv:func:`ocl::matchTemplate` function. If you leave its default value `Size(0,0)` then automatic estimation of block size will be used (which is optimized for speed). By varying `user_block_size` you can reduce memory requirements at the cost of speed.
+
+ocl::matchTemplate
+----------------------
+Computes a proximity map for a raster template and an image where the template is searched for.
+
+.. ocv:function:: void ocl::matchTemplate(const oclMat& image, const oclMat& templ, oclMat& result, int method)
+
+.. ocv:function:: void ocl::matchTemplate(const oclMat& image, const oclMat& templ, oclMat& result, int method, MatchTemplateBuf &buf)
+
+    :param image: Source image.  ``CV_32F`` and  ``CV_8U`` depth images (1..4 channels) are supported for now.
+
+    :param templ: Template image with the size and type the same as  ``image`` .
+
+    :param result: Map containing comparison results ( ``CV_32FC1`` ). If  ``image`` is  *W x H*  and ``templ`` is  *w x h*, then  ``result`` must be *W-w+1 x H-h+1*.
+
+    :param method: Specifies the way to compare the template with the image.
+
+    :param buf: Optional buffer to avoid extra memory allocations and to adjust some specific parameters. See :ocv:class:`ocl::MatchTemplateBuf`.
+
+    The following methods are supported for the ``CV_8U`` depth images for now:
+
+    * ``CV_TM_SQDIFF``
+    * ``CV_TM_SQDIFF_NORMED``
+    * ``CV_TM_CCORR``
+    * ``CV_TM_CCORR_NORMED``
+    * ``CV_TM_CCOEFF``
+    * ``CV_TM_CCOEFF_NORMED``
+
+    The following methods are supported for the ``CV_32F`` images for now:
+
+    * ``CV_TM_SQDIFF``
+    * ``CV_TM_CCORR``
+
+.. seealso:: :ocv:func:`matchTemplate`
+
+
+ocl::SURF_OCL
+-------------
+.. ocv:class:: ocl::SURF_OCL
+
+Class used for extracting Speeded Up Robust Features (SURF) from an image. ::
+
+    class SURF_OCL
+    {
+    public:
+        enum KeypointLayout
+        {
+            X_ROW = 0,
+            Y_ROW,
+            LAPLACIAN_ROW,
+            OCTAVE_ROW,
+            SIZE_ROW,
+            ANGLE_ROW,
+            HESSIAN_ROW,
+            ROWS_COUNT
+        };
+
+        //! the default constructor
+        SURF_OCL();
+        //! the full constructor taking all the necessary parameters
+        explicit SURF_OCL(double _hessianThreshold, int _nOctaves=4,
+             int _nOctaveLayers=2, bool _extended=false, float _keypointsRatio=0.01f, bool _upright = false);
+
+        //! returns the descriptor size in float's (64 or 128)
+        int descriptorSize() const;
+
+        //! upload host keypoints to device memory
+        void uploadKeypoints(const vector<KeyPoint>& keypoints,
+            oclMat& keypointsocl);
+        //! download keypoints from device to host memory
+        void downloadKeypoints(const oclMat& keypointsocl,
+            vector<KeyPoint>& keypoints);
+
+        //! download descriptors from device to host memory
+        void downloadDescriptors(const oclMat& descriptorsocl,
+            vector<float>& descriptors);
+
+        void operator()(const oclMat& img, const oclMat& mask,
+            oclMat& keypoints);
+
+        void operator()(const oclMat& img, const oclMat& mask,
+            oclMat& keypoints, oclMat& descriptors,
+            bool useProvidedKeypoints = false);
+
+        void operator()(const oclMat& img, const oclMat& mask,
+            std::vector<KeyPoint>& keypoints);
+
+        void operator()(const oclMat& img, const oclMat& mask,
+            std::vector<KeyPoint>& keypoints, oclMat& descriptors,
+            bool useProvidedKeypoints = false);
+
+        void operator()(const oclMat& img, const oclMat& mask,
+            std::vector<KeyPoint>& keypoints,
+            std::vector<float>& descriptors,
+            bool useProvidedKeypoints = false);
+
+        void releaseMemory();
+
+        // SURF parameters
+        double hessianThreshold;
+        int nOctaves;
+        int nOctaveLayers;
+        bool extended;
+        bool upright;
+
+        //! max keypoints = min(keypointsRatio * img.size().area(), 65535)
+        float keypointsRatio;
+
+        oclMat sum, mask1, maskSum, intBuffer;
+
+        oclMat det, trace;
+
+        oclMat maxPosBuffer;
+    };
+
+
+The class ``SURF_OCL`` implements Speeded Up Robust Features descriptor. There is a fast multi-scale Hessian keypoint detector that can be used to find the keypoints (which is the default option). But the descriptors can also be computed for the user-specified keypoints. Only 8-bit grayscale images are supported.
+
+The class ``SURF_OCL`` can store results in the GPU and CPU memory. It provides functions to convert results between CPU and GPU version ( ``uploadKeypoints``, ``downloadKeypoints``, ``downloadDescriptors`` ). The format of CPU results is the same as ``SURF`` results. GPU results are stored in ``oclMat``. The ``keypoints`` matrix is :math:`\texttt{nFeatures} \times 7` matrix with the ``CV_32FC1`` type.
+
+* ``keypoints.ptr<float>(X_ROW)[i]`` contains x coordinate of the i-th feature.
+* ``keypoints.ptr<float>(Y_ROW)[i]`` contains y coordinate of the i-th feature.
+* ``keypoints.ptr<float>(LAPLACIAN_ROW)[i]``  contains the laplacian sign of the i-th feature.
+* ``keypoints.ptr<float>(OCTAVE_ROW)[i]`` contains the octave of the i-th feature.
+* ``keypoints.ptr<float>(SIZE_ROW)[i]`` contains the size of the i-th feature.
+* ``keypoints.ptr<float>(ANGLE_ROW)[i]`` contain orientation of the i-th feature.
+* ``keypoints.ptr<float>(HESSIAN_ROW)[i]`` contains the response of the i-th feature.
+
+The ``descriptors`` matrix is :math:`\texttt{nFeatures} \times \texttt{descriptorSize}` matrix with the ``CV_32FC1`` type.
+
+The class ``SURF_OCL`` uses some buffers and provides access to it. All buffers can be safely released between function calls.
+
+.. seealso:: :ocv:class:`SURF`

modules/ocl/doc/ocl.rst

@@ -6,15 +6,13 @@ ocl. OpenCL-accelerated Computer Vision
     :maxdepth: 1
 
     introduction
-    structures_and_functions
-..    initalization_and_information
-..    data_structures
-..    operations_on_matrices
-..    per_element_operations
-..    image_processing
-..    matrix_reductions
-..    object_detection
-..    feature_detection_and_description
-..    image_filtering
+    structures_and_utility_functions
+    data_structures
+    operations_on_matrices
+    matrix_reductions
+    image_filtering
+    image_processing
+    object_detection
+    feature_detection_and_description
 ..    camera_calibration_and_3d_reconstruction
 ..    video

modules/ocl/doc/operations_on_matrices.rst

@@ -0,0 +1,474 @@
+Operations on Matrics
+=============================
+
+.. highlight:: cpp
+
+ocl::convertTo
+------------------
+Returns void
+
+.. ocv:function:: void convertTo( oclMat &m, int rtype, double alpha = 1, double beta = 0 ) const
+
+    :param m: The destination matrix. If it does not have a proper size or type before the operation, it will be reallocated
+
+    :param rtype: The desired destination matrix type, or rather, the depth(since the number of channels will be the same with the source one). If rtype is negative, the destination matrix will have the same type as the source.
+
+    :param alpha: must be default now
+
+    :param beta: must be default now
+
+The method converts source pixel values to the target datatype. saturate cast is applied in the end to avoid possible overflows. Supports CV_8UC1, CV_8UC4, CV_32SC1, CV_32SC4, CV_32FC1, CV_32FC4.
+
+ocl::copyTo
+------------------
+Returns void
+
+.. ocv:function:: void copyTo( oclMat &m, const oclMat &mask ) const
+
+    :param m: The destination matrix. If it does not have a proper size or type before the operation, it will be reallocated
+
+    :param mask(optional): The operation mask. Its non-zero elements indicate, which matrix elements need to be copied
+
+Copies the matrix to another one. Supports CV_8UC1, CV_8UC4, CV_32SC1, CV_32SC4, CV_32FC1, CV_32FC4
+
+ocl::setTo
+------------------
+Returns oclMat
+
+.. ocv:function:: oclMat &setTo(const Scalar &s, const oclMat &mask = oclMat())
+
+    :param s: Assigned scalar, which is converted to the actual array type
+
+    :param mask: The operation mask of the same size as ``*this``
+
+Sets all or some of the array elements to the specified value. This is the advanced variant of Mat::operator=(const Scalar s) operator. Supports CV_8UC1, CV_8UC4, CV_32SC1, CV_32SC4, CV_32FC1, CV_32FC4.
+
+ocl::absdiff
+------------------
+Returns void
+
+.. ocv:function:: void absdiff(const oclMat &a, const oclMat &b, oclMat &c)
+
+.. ocv:function:: void absdiff(const oclMat &a, const Scalar& sc, oclMat &c)
+
+    :param a: The first input array
+
+    :param b: The second input array, must be the same size and same type as a
+
+    :param sc: Scalar, the second input parameter
+
+    :param c: The destination array, it will have the same size and same type as a
+
+Computes per-element absolute difference between two arrays or between array and a scalar. Supports all data types except CV_8S.
+
+ocl::add
+------------------
+Returns void
+
+.. ocv:function:: void add(const oclMat &src1, const oclMat &src2, oclMat &dst, const oclMat& mask=oclMat())
+
+.. ocv:function:: void add(const oclMat &src1, const Scalar &sc, oclMat &dst, const oclMat& mask=oclMat())
+
+    :param src1: The first input array
+
+    :param src2: The second input array, must be the same size and same type as src1
+
+    :param sc: Scalar, the second input parameter
+
+    :param dst: The destination array, it will have the same size and same type as src1
+
+    :param mask: he optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed
+
+Computes per-element additon between two arrays or between array and a scalar. Supports all data types except CV_8S.
+
+ocl::subtract
+------------------
+Returns void
+
+.. ocv:function:: void subtract(const oclMat &src1, const oclMat &src2, oclMat &dst, const oclMat& mask=oclMat())
+
+.. ocv:function:: void subtract(const oclMat &src1, const Scalar &sc, oclMat &dst, const oclMat& mask=oclMat())
+
+    :param src1: The first input array
+
+    :param src2: The second input array, must be the same size and same type as src1
+
+    :param sc: Scalar, the second input parameter
+
+    :param dst: The destination array, it will have the same size and same type as src1
+
+    :param mask: he optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed
+
+Computes per-element subtract between two arrays or between array and a scalar. Supports all data types except CV_8S.
+
+ocl::multiply
+------------------
+Returns void
+
+.. ocv:function:: void multiply(const oclMat &src1, const oclMat &src2, oclMat &dst, double scale = 1)
+
+    :param src1: The first input array
+
+    :param src2: The second input array, must be the same size and same type as src1
+
+    :param dst: The destination array, it will have the same size and same type as src1
+
+    :param scale: must be 1 now
+
+Computes per-element multiply between two arrays or between array and a scalar. Supports all data types except CV_8S.
+
+ocl::divide
+------------------
+Returns void
+
+.. ocv:function:: void divide(const oclMat &src1, const oclMat &src2, oclMat &dst, double scale = 1)
+
+    :param src1: The first input array
+
+    :param src2: The second input array, must be the same size and same type as src1
+
+    :param dst: The destination array, it will have the same size and same type as src1
+
+    :param scale: must be 1 now
+
+Computes per-element divide between two arrays or between array and a scalar. Supports all data types except CV_8S.
+
+ocl::bitwise_and
+------------------
+Returns void
+
+.. ocv:function:: void bitwise_and(const oclMat &src1, const oclMat &src2, oclMat &dst, const oclMat& mask=oclMat())
+
+.. ocv:function:: void bitwise_and(const oclMat &src1, const Scalar &sc, oclMat &dst, const oclMat& mask=oclMat())
+
+    :param src1: The first input array
+
+    :param src2: The second input array, must be the same size and same type as src1
+
+    :param sc: Scalar, the second input parameter
+
+    :param dst: The destination array, it will have the same size and same type as src1
+
+    :param mask: The optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed
+
+Computes per-element bitwise_and between two arrays or between array and a scalar. Supports all data types except CV_8S.
+
+ocl::bitwise_or
+------------------
+Returns void
+
+.. ocv:function:: void bitwise_or(const oclMat &src1, const oclMat &src2, oclMat &dst, const oclMat& mask=oclMat())
+
+.. ocv:function:: void bitwise_or(const oclMat &src1, const Scalar &sc, oclMat &dst, const oclMat& mask=oclMat())
+
+    :param src1: The first input array
+
+    :param src2: The second input array, must be the same size and same type as src1
+
+    :param sc: Scalar, the second input parameter
+
+    :param dst: The destination array, it will have the same size and same type as src1
+
+    :param mask: The optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed
+
+Computes per-element bitwise_or between two arrays or between array and a scalar. Supports all data types except CV_8S.
+
+ocl::bitwise_xor
+------------------
+Returns void
+
+.. ocv:function:: void bitwise_xor(const oclMat &src1, const oclMat &src2, oclMat &dst, const oclMat& mask=oclMat())
+
+.. ocv:function:: void bitwise_xor(const oclMat &src1, const Scalar &sc, oclMat &dst, const oclMat& mask=oclMat())
+
+    :param src1: The first input array
+
+    :param src2: The second input array, must be the same size and same type as src1
+
+    :param sc: Scalar, the second input parameter
+
+    :param dst: The destination array, it will have the same size and same type as src1
+
+    :param mask: The optional operation mask, 8-bit single channel array; specifies elements of the destination array to be changed
+
+Computes per-element bitwise_xor between two arrays or between array and a scalar. Supports all data types except CV_8S.
+
+ocl::bitwise_not
+------------------
+Returns void
+
+.. ocv:function:: void bitwise_not(const oclMat &src, oclMat &dst)
+
+    :param src: The input array
+
+    :param dst: The destination array, it will have the same size and same type as src1
+
+The functions bitwise not compute per-element bit-wise inversion of the source array:. Supports all data types except CV_8S.
+
+ocl::cartToPolar
+------------------
+Returns void
+
+.. ocv:function:: void cartToPolar(const oclMat &x, const oclMat &y, oclMat &magnitude, oclMat &angle, bool angleInDegrees = false)
+
+    :param x: The array of x-coordinates; must be single-precision or double-precision floating-point array
+
+    :param y: The array of y-coordinates; it must have the same size and same type as x
+
+    :param magnitude: The destination array of magnitudes of the same size and same type as x
+
+    :param angle: The destination array of angles of the same size and same type as x. The angles are measured in radians (0 to 2pi ) or in degrees (0 to 360 degrees).
+
+    :param angleInDegrees: The flag indicating whether the angles are measured in radians, which is default mode, or in degrees
+
+Calculates the magnitude and angle of 2d vectors. Supports only CV_32F and CV_64F data types.
+
+ocl::polarToCart
+------------------
+Returns void
+
+.. ocv:function:: void polarToCart(const oclMat &magnitude, const oclMat &angle, oclMat &x, oclMat &y, bool angleInDegrees = false)
+
+    :param magnitude: The source floating-point array of magnitudes of 2D vectors. It can be an empty matrix (=Mat()) - in this case the function assumes that all the magnitudes are =1. If it's not empty, it must have the same size and same type as angle
+
+    :param angle: The source floating-point array of angles of the 2D vectors
+
+    :param x: The destination array of x-coordinates of 2D vectors; will have the same size and the same type as angle
+
+    :param y: The destination array of y-coordinates of 2D vectors; will have the same size and the same type as angle
+
+    :param angleInDegrees: The flag indicating whether the angles are measured in radians, which is default mode, or in degrees
+
+The function polarToCart computes the cartesian coordinates of each 2D vector represented by the corresponding elements of magnitude and angle. Supports only CV_32F and CV_64F data types.
+
+ocl::compare
+------------------
+Returns void
+
+.. ocv:function:: void compare(const oclMat &a, const oclMat &b, oclMat &c, int cmpop)
+
+    :param a: The first source array
+
+    :param b: The second source array; must have the same size and same type as a
+
+    :param c: The destination array; will have the same size as a
+
+    :param cmpop: The flag specifying the relation between the elements to be checked
+
+Performs per-element comparison of two arrays or an array and scalar value. Supports all the 1 channel data types except CV_8S.
+
+ocl::exp
+------------------
+Returns void
+
+.. ocv:function:: void exp(const oclMat &a, oclMat &b)
+
+    :param a: The first source array
+
+    :param b: The dst array; must have the same size and same type as a
+
+The function exp calculates the exponent of every element of the input array. Supports only CV_32FC1 data type.
+
+ocl::log
+------------------
+Returns void
+
+.. ocv:function:: void log(const oclMat &a, oclMat &b)
+
+    :param a: The first source array
+
+    :param b: The dst array; must have the same size and same type as a
+
+The function log calculates the log of every element of the input array. Supports only CV_32FC1 data type.
+
+ocl::LUT
+------------------
+Returns void
+
+.. ocv:function:: void LUT(const oclMat &src, const oclMat &lut, oclMat &dst)
+
+    :param src: Source array of 8-bit elements
+
+    :param lut: Look-up table of 256 elements. In the case of multi-channel source array, the table should either have a single channel (in this case the same table is used for all channels) or the same number of channels as in the source array
+
+    :param dst: Destination array; will have the same size and the same number of channels as src, and the same depth as lut
+
+Performs a look-up table transform of an array. Supports only CV_8UC1 and CV_8UC4 data type.
+
+ocl::magnitude
+------------------
+Returns void
+
+.. ocv:function:: void magnitude(const oclMat &x, const oclMat &y, oclMat &magnitude)
+
+    :param x: The floating-point array of x-coordinates of the vectors
+
+    :param y: he floating-point array of y-coordinates of the vectors; must have the same size as x
+
+    :param magnitude: The destination array; will have the same size and same type as x
+
+The function magnitude calculates magnitude of 2D vectors formed from the corresponding elements of x and y arrays. Supports only CV_32F and CV_64F data type.
+
+ocl::flip
+------------------
+Returns void
+
+.. ocv:function:: void flip(const oclMat &src, oclMat &dst, int flipCode)
+
+    :param src: Source image.
+
+    :param dst: Destination image
+
+    :param flipCode: Specifies how to flip the array: 0 means flipping around the x-axis, positive (e.g., 1) means flipping around y-axis, and negative (e.g., -1) means flipping around both axes.
+
+The function flip flips the array in one of three different ways (row and column indices are 0-based). Supports all data types.
+
+ocl::meanStdDev
+------------------
+Returns void
+
+.. ocv:function:: void meanStdDev(const oclMat &mtx, Scalar &mean, Scalar &stddev)
+
+    :param mtx: Source image.
+
+    :param mean: The output parameter: computed mean value
+
+    :param stddev: The output parameter: computed standard deviation
+
+The functions meanStdDev compute the mean and the standard deviation M of array elements, independently for each channel, and return it via the output parameters. Supports all data types except CV_32F,CV_64F
+
+ocl::merge
+------------------
+Returns void
+
+.. ocv:function:: void merge(const vector<oclMat> &src, oclMat &dst)
+
+    :param src: The source array or vector of the single-channel matrices to be merged. All the matrices in src must have the same size and the same type
+
+    :param dst: The destination array; will have the same size and the same depth as src, the number of channels will match the number of source matrices
+
+Composes a multi-channel array from several single-channel arrays. Supports all data types.
+
+ocl::split
+------------------
+Returns void
+
+.. ocv:function:: void split(const oclMat &src, vector<oclMat> &dst)
+
+    :param src: The source multi-channel array
+
+    :param dst: The destination array or vector of arrays; The number of arrays must match src.channels(). The arrays themselves will be reallocated if needed
+
+The functions split split multi-channel array into separate single-channel arrays. Supports all data types.
+
+ocl::norm
+------------------
+Returns the calculated norm
+
+.. ocv:function:: double norm(const oclMat &src1, int normType = NORM_L2)
+
+.. ocv:function:: double norm(const oclMat &src1, const oclMat &src2, int normType = NORM_L2)
+
+    :param src1: The first source array
+
+    :param src2: The second source array of the same size and the same type as src1
+
+    :param normType: Type of the norm
+
+Calculates absolute array norm, absolute difference norm, or relative difference norm. Supports only CV_8UC1 data type.
+
+ocl::phase
+------------------
+Returns void
+
+.. ocv:function:: void phase(const oclMat &x, const oclMat &y, oclMat &angle, bool angleInDegrees = false)
+
+    :param x: The source floating-point array of x-coordinates of 2D vectors
+
+    :param y: The source array of y-coordinates of 2D vectors; must have the same size and the same type as x
+
+    :param angle: The destination array of vector angles; it will have the same size and same type as x
+
+    :param angleInDegrees: When it is true, the function will compute angle in degrees, otherwise they will be measured in radians
+
+The function phase computes the rotation angle of each 2D vector that is formed from the corresponding elements of x and y. Supports only CV_32FC1 and CV_64FC1 data type.
+
+ocl::pow
+------------------
+Returns void
+
+.. ocv:function:: void pow(const oclMat &x, double p, oclMat &y)
+
+    :param x: The source array
+
+    :param power: The exponent of power;The source floating-point array of angles of the 2D vectors
+
+    :param y: The destination array, should be the same type as the source
+
+The function pow raises every element of the input array to p. Supports only CV_32FC1 and CV_64FC1 data type.
+
+ocl::transpose
+------------------
+Returns void
+
+.. ocv:function:: void transpose(const oclMat &src, oclMat &dst)
+
+    :param src: The source array
+
+    :param dst: The destination array of the same type as src
+
+Transposes a matrix. Supports 8UC1, 8UC4, 8SC4, 16UC2, 16SC2, 32SC1 and 32FC1 data types.
+
+
+ocl::dft
+------------
+Performs a forward or inverse discrete Fourier transform (1D or 2D) of the floating point matrix.
+
+.. ocv:function:: void ocl::dft(const oclMat& src, oclMat& dst, Size dft_size, int flags=0)
+
+    :param src: Source matrix (real or complex).
+
+    :param dst: Destination matrix (real or complex).
+
+    :param dft_size: Size of original input, which is used for transformation from complex to real.
+
+    :param flags: Optional flags:
+
+        * **DFT_ROWS** transforms each individual row of the source matrix.
+
+        * **DFT_COMPLEX_OUTPUT** performs a forward transformation of 1D or 2D real array. The result, though being a complex array, has complex-conjugate symmetry (*CCS*, see the function description below for details). Such an array can be packed into a real array of the same size as input, which is the fastest option and which is what the function does by default. However, you may wish to get a full complex array (for simpler spectrum analysis, and so on). Pass the flag to enable the function to produce a full-size complex output array.
+
+        * **DFT_INVERSE** inverts DFT. Use for complex-complex cases (real-complex and complex-real cases are always forward and inverse, respectively).
+
+        * **DFT_REAL_OUTPUT** specifies the output as real. The source matrix is the result of real-complex transform, so the destination matrix must be real.
+
+Use to handle real matrices ( ``CV32FC1`` ) and complex matrices in the interleaved format ( ``CV32FC2`` ).
+
+The dft_size must be powers of 2, 3 and 5. Real to complex dft output is not the same with cpu version. real to complex and complex to real does not support DFT_ROWS
+
+.. seealso:: :ocv:func:`dft`
+
+ocl::gemm
+------------------
+Performs generalized matrix multiplication.
+
+.. ocv:function:: void gemm(const oclMat& src1, const oclMat& src2, double alpha, const oclMat& src3, double beta, oclMat& dst, int flags = 0)
+
+    :param src1: First multiplied input matrix that should be ``CV_32FC1`` type.
+
+    :param src2: Second multiplied input matrix of the same type as  ``src1`` .
+
+    :param alpha: Weight of the matrix product.
+
+    :param src3: Third optional delta matrix added to the matrix product. It should have the same type as  ``src1``  and  ``src2`` .
+
+    :param beta: Weight of  ``src3`` .
+
+    :param dst: Destination matrix. It has the proper size and the same type as input matrices.
+
+    :param flags: Operation flags:
+
+            * **GEMM_1_T** transpose  ``src1``
+            * **GEMM_2_T** transpose  ``src2``
+
+.. seealso:: :ocv:func:`gemm`

modules/ocl/doc/structures_and_functions.rst

@@ -1,23 +0,0 @@
-Data Structures and Functions
-=============================
-
-.. highlight:: cpp
-
-ocl::Info
----------
-.. ocv:class:: ocl::Info
-
-this class should be maintained by the user and be passed to getDevice
-
-ocl::getDevice
-------------------
-Returns the list of devices
-
-.. ocv:function:: int ocl::getDevice( std::vector<Info> & oclinfo, int devicetype=CVCL_DEVICE_TYPE_GPU )
-
-    :param oclinfo: Output vector of ``ocl::Info`` structures
-
-    :param devicetype: One of ``CVCL_DEVICE_TYPE_GPU``, ``CVCL_DEVICE_TYPE_CPU`` or ``CVCL_DEVICE_TYPE_DEFAULT``.
-
-the function must be called before any other ``cv::ocl`` functions; it initializes ocl runtime.
-

modules/ocl/doc/structures_and_utility_functions.rst

@@ -0,0 +1,58 @@
+Data Structures and Utility Functions
+========================================
+
+.. highlight:: cpp
+
+ocl::Info
+---------
+.. ocv:class:: ocl::Info
+
+this class should be maintained by the user and be passed to getDevice
+
+ocl::getDevice
+------------------
+Returns the list of devices
+
+.. ocv:function:: int ocl::getDevice( std::vector<Info> & oclinfo, int devicetype=CVCL_DEVICE_TYPE_GPU )
+
+    :param oclinfo: Output vector of ``ocl::Info`` structures
+
+    :param devicetype: One of ``CVCL_DEVICE_TYPE_GPU``, ``CVCL_DEVICE_TYPE_CPU`` or ``CVCL_DEVICE_TYPE_DEFAULT``.
+
+the function must be called before any other ``cv::ocl`` functions; it initializes ocl runtime.
+
+ocl::setDevice
+------------------
+Returns void
+
+.. ocv:function:: void ocl::setDevice( Info &oclinfo, int devnum = 0 )
+
+    :param oclinfo: Output vector of ``ocl::Info`` structures
+
+    :param devnum: the selected OpenCL device under this platform.
+
+ocl::setBinpath
+------------------
+Returns void
+
+.. ocv:function:: void setBinpath(const char *path)
+
+    :param path: the path of OpenCL kernel binaries
+
+If you call this function and set a valid path, the OCL module will save the compiled kernel to the address in the first time and reload the binary since that. It can save compilation time at the runtime.
+
+ocl::getoclContext
+------------------
+Returns the pointer to the opencl context
+
+.. ocv:function:: void *getoclContext()
+
+Thefunction are used to get opencl context so that opencv can interactive with other opencl program.
+
+ocl::getoclCommandQueue
+--------------------------
+Returns the pointer to the opencl command queue
+
+.. ocv:function:: void *getoclCommandQueue()
+
+Thefunction are used to get opencl command queue so that opencv can interactive with other opencl program.