Normalize whitespace in documentation and text files
authorAndrey Kamaev <andrey.kamaev@itseez.com>
Wed, 17 Oct 2012 17:42:09 +0000 (21:42 +0400)
committerAndrey Kamaev <andrey.kamaev@itseez.com>
Wed, 17 Oct 2012 17:42:09 +0000 (21:42 +0400)
95 files changed:
3rdparty/ffmpeg/readme.txt
3rdparty/readme.txt
android/java.rst
android/service/ReadMe.txt
android/service/doc/BaseLoaderCallback.rst
android/service/doc/LoaderCallbackInterface.rst
doc/packaging.txt
doc/tutorials/calib3d/camera_calibration/camera_calibration.rst
doc/tutorials/calib3d/camera_calibration_square_chess/camera_calibration_square_chess.rst
doc/tutorials/calib3d/table_of_content_calib3d/table_of_content_calib3d.rst
doc/tutorials/core/adding_images/adding_images.rst
doc/tutorials/core/basic_geometric_drawing/basic_geometric_drawing.rst
doc/tutorials/core/basic_linear_transform/basic_linear_transform.rst
doc/tutorials/core/discrete_fourier_transform/discrete_fourier_transform.rst
doc/tutorials/core/file_input_output_with_xml_yml/file_input_output_with_xml_yml.rst
doc/tutorials/core/how_to_scan_images/how_to_scan_images.rst
doc/tutorials/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.rst
doc/tutorials/core/mat-mask-operations/mat-mask-operations.rst
doc/tutorials/core/mat_the_basic_image_container/mat_the_basic_image_container.rst
doc/tutorials/core/table_of_content_core/table_of_content_core.rst
doc/tutorials/definitions/noContent.rst
doc/tutorials/definitions/tocDefinitions.rst
doc/tutorials/features2d/detection_of_planar_objects/detection_of_planar_objects.rst
doc/tutorials/features2d/table_of_content_features2d/table_of_content_features2d.rst
doc/tutorials/features2d/trackingmotion/corner_subpixeles/corner_subpixeles.rst
doc/tutorials/features2d/trackingmotion/harris_detector/harris_detector.rst
doc/tutorials/gpu/gpu-basics-similarity/gpu-basics-similarity.rst
doc/tutorials/gpu/table_of_content_gpu/table_of_content_gpu.rst
doc/tutorials/highgui/table_of_content_highgui/table_of_content_highgui.rst
doc/tutorials/highgui/trackbar/trackbar.rst
doc/tutorials/highgui/video-input-psnr-ssim/video-input-psnr-ssim.rst
doc/tutorials/highgui/video-write/video-write.rst
doc/tutorials/imgproc/erosion_dilatation/erosion_dilatation.rst
doc/tutorials/imgproc/gausian_median_blur_bilateral_filter/gausian_median_blur_bilateral_filter.rst
doc/tutorials/imgproc/histograms/back_projection/back_projection.rst
doc/tutorials/imgproc/imgtrans/remap/remap.rst
doc/tutorials/imgproc/opening_closing_hats/opening_closing_hats.rst
doc/tutorials/imgproc/pyramids/pyramids.rst
doc/tutorials/imgproc/table_of_content_imgproc/table_of_content_imgproc.rst
doc/tutorials/imgproc/threshold/threshold.rst
doc/tutorials/introduction/how_to_write_a_tutorial/how_to_write_a_tutorial.rst
doc/tutorials/introduction/ios_install/ios_install.rst
doc/tutorials/introduction/linux_eclipse/linux_eclipse.rst
doc/tutorials/introduction/linux_gcc_cmake/linux_gcc_cmake.rst
doc/tutorials/introduction/linux_install/linux_install.rst
doc/tutorials/introduction/load_save_image/load_save_image.rst
doc/tutorials/introduction/windows_install/windows_install.rst
doc/tutorials/introduction/windows_visual_studio_Opencv/windows_visual_studio_Opencv.rst
doc/tutorials/ios/hello/hello.rst
doc/tutorials/ios/image_manipulation/image_manipulation.rst
doc/tutorials/ios/table_of_content_ios/table_of_content_ios.rst
doc/tutorials/ios/video_processing/video_processing.rst
doc/tutorials/ml/introduction_to_svm/introduction_to_svm.rst
doc/tutorials/ml/table_of_content_ml/table_of_content_ml.rst
doc/tutorials/objdetect/table_of_content_objdetect/table_of_content_objdetect.rst
doc/tutorials/video/table_of_content_video/table_of_content_video.rst
doc/user_guide/ug_features2d.rst
doc/user_guide/ug_mat.rst
doc/user_guide/ug_traincascade.rst
modules/calib3d/doc/camera_calibration_and_3d_reconstruction.rst
modules/contrib/doc/facerec/facerec_changelog.rst
modules/contrib/doc/facerec/facerec_tutorial.rst
modules/contrib/doc/facerec/tutorial/facerec_save_load.rst
modules/contrib/doc/facerec/tutorial/facerec_video_recognition.rst
modules/core/doc/clustering.rst
modules/core/doc/command_line_parser.rst
modules/core/doc/drawing_functions.rst
modules/core/doc/intro.rst
modules/core/doc/operations_on_arrays.rst
modules/features2d/doc/common_interfaces_of_descriptor_extractors.rst
modules/features2d/doc/object_categorization.rst
modules/flann/doc/flann_clustering.rst
modules/flann/doc/flann_fast_approximate_nearest_neighbor_search.rst
modules/gpu/doc/image_processing.rst
modules/gpu/doc/matrix_reductions.rst
modules/highgui/doc/reading_and_writing_images_and_video.rst
modules/highgui/src/files_Qt/Milky/README.txt
modules/imgproc/doc/histograms.rst
modules/ml/doc/gradient_boosted_trees.rst
modules/ml/doc/k_nearest_neighbors.rst
modules/ml/doc/mldata.rst
modules/objdetect/doc/cascade_classification.rst
modules/ocl/doc/structures_and_functions.rst
modules/photo/doc/denoising.rst
modules/photo/doc/photo.rst
modules/stitching/doc/camera.rst
modules/stitching/doc/high_level.rst
modules/stitching/doc/seam_estimation.rst
modules/stitching/doc/stitching.rst
modules/video/doc/motion_analysis_and_object_tracking.rst
modules/videostab/doc/fast_marching.rst
modules/videostab/doc/global_motion.rst
samples/MacOSX/FaceTracker/README.txt
samples/c/example_cmake/README.txt [changed mode: 0755->0644]
samples/cpp/matching_to_many_images/train/trainImages.txt [changed mode: 0755->0644]

index 1089ee2..1928a53 100644 (file)
@@ -16,7 +16,7 @@ How to update opencv_ffmpeg.dll and opencv_ffmpeg_64.dll when a new version of F
 2. Install 64-bit MinGW. http://mingw-w64.sourceforge.net/
    Let's assume, it's installed in C:\MSYS64
 3. Copy C:\MSYS32\msys to C:\MSYS64\msys. Edit C:\MSYS64\msys\etc\fstab, change C:\MSYS32 to C:\MSYS64.
-   
+
 4. Now you have working MSYS32 and MSYS64 environments.
    Launch, one by one, C:\MSYS32\msys\msys.bat and C:\MSYS64\msys\msys.bat to create your home directories.
 
index 6d2aeec..ca46fbd 100644 (file)
@@ -45,13 +45,13 @@ jasper-1.900.1    -   JasPer is a collection of software
                       and manipulation of images.  This software can handle image data in a
                       variety of formats.  One such format supported by JasPer is the JPEG-2000
                       format defined in ISO/IEC 15444-1.
-             
+
                       Copyright (c) 1999-2000 Image Power, Inc.
                       Copyright (c) 1999-2000 The University of British Columbia
                       Copyright (c) 2001-2003 Michael David Adams
 
                       The JasPer license can be found in src/libjasper.
-             
+
                       OpenCV on Windows uses pre-built libjasper library
                       (lib/libjasper*). To get the latest source code,
                       please, visit the project homepage:
index b5e3070..0b4a288 100644 (file)
@@ -3,4 +3,4 @@ Java API
 ********
 
 
-`Java API reference external link (JavaDoc) <http://docs.opencv.org/java/>`_ 
\ No newline at end of file
+`Java API reference external link (JavaDoc) <http://docs.opencv.org/java/>`_
\ No newline at end of file
index cd89762..2c4ebd5 100644 (file)
@@ -8,7 +8,7 @@ The package provides new OpenCV SDK that uses OpenCV Manager for library initial
 * Hardware specific optimizations for all supported platforms;
 * Trusted OpenCV library source. All packages with OpenCV are published on Google Play service;
 * Regular updates and bug fixes;
+
 Package consists from Library Project for Java development with Eclipse, C++ headers and libraries for native application development, javadoc samples and prebuilt binaries for ARM and X86 platforms.
 To try new SDK on serial device with Google Play just install sample package and follow application messages (Google Play service access will be needed).
 TO start example on device without Google Play you need to install OpenCV manager package and OpenCV binary pack for your platform from apk folder before.
index f756db4..9c4db16 100644 (file)
@@ -55,6 +55,6 @@ There is a very base code snippet implementing the async initialization with Bas
 Using in Service
 ----------------
 
-Default BaseLoaderCallback implementation treat application context as Activity and calls Activity.finish() method to exit in case of initialization failure. 
-To override this behavior you need to override finish() method of BaseLoaderCallback class and implement your own finalization method. 
+Default BaseLoaderCallback implementation treat application context as Activity and calls Activity.finish() method to exit in case of initialization failure.
+To override this behavior you need to override finish() method of BaseLoaderCallback class and implement your own finalization method.
 
index 0549b5a..08bc160 100644 (file)
@@ -13,7 +13,7 @@ void onManagerConnected()
 .. method:: void onManagerConnected(int status)
 
     Callback method that is called after OpenCV Library initialization.
+
     :param status: status of initialization (see Initialization Status Constants).
 
 void onPackageInstall()
index a4d3dc2..a27119b 100644 (file)
@@ -4,14 +4,14 @@ INSTRUCTIONS TO BUILD WIN32 PACKAGES WITH CMAKE+CPACK
 
 - Install NSIS.
 - Generate OpenCV solutions for MSVC using CMake as usual.
-- In cmake-gui: 
-       - Mark BUILD_PACKAGE
-       - Mark BUILD_EXAMPLES (If examples are desired to be shipped as binaries...)
-       - Unmark ENABLE_OPENMP, since this feature seems to have some issues yet...
-       - Mark INSTALL_*_EXAMPLES
+- In cmake-gui:
+    - Mark BUILD_PACKAGE
+    - Mark BUILD_EXAMPLES (If examples are desired to be shipped as binaries...)
+    - Unmark ENABLE_OPENMP, since this feature seems to have some issues yet...
+    - Mark INSTALL_*_EXAMPLES
 - Open the OpenCV solution and build ALL in Debug and Release.
-- Build PACKAGE, from the Release configuration. An NSIS installer package will be 
+- Build PACKAGE, from the Release configuration. An NSIS installer package will be
   created with both release and debug LIBs and DLLs.
 
-  
+
 Jose Luis Blanco, 2009/JUL/29
index 9196c87..3f8ecbd 100644 (file)
@@ -3,30 +3,30 @@
 Camera calibration With OpenCV
 ******************************
 
-Cameras have been around for a long-long time. However, with the introduction of the cheap *pinhole* cameras in the late 20th century, they became a common occurrence in our everyday life. Unfortunately, this cheapness comes with its price: significant distortion. Luckily, these are constants and with a calibration and some remapping we can correct this. Furthermore, with calibration you may also determinate the relation between the camera's natural units (pixels) and the real world units (for example millimeters). 
+Cameras have been around for a long-long time. However, with the introduction of the cheap *pinhole* cameras in the late 20th century, they became a common occurrence in our everyday life. Unfortunately, this cheapness comes with its price: significant distortion. Luckily, these are constants and with a calibration and some remapping we can correct this. Furthermore, with calibration you may also determinate the relation between the camera's natural units (pixels) and the real world units (for example millimeters).
 
 Theory
 ======
 
-For the distortion OpenCV takes into account the radial and tangential factors. For the radial one uses the following formula: 
+For the distortion OpenCV takes into account the radial and tangential factors. For the radial one uses the following formula:
 
-.. math:: 
+.. math::
 
    x_{corrected} = x( 1 + k_1 r^2 + k_2 r^4 + k^3 r^6) \\
    y_{corrected} = y( 1 + k_1 r^2 + k_2 r^4 + k^3 r^6)
 
-So for an old pixel point at :math:`(x,y)` coordinate in the input image, for a corrected output image its position will be :math:`(x_{corrected} y_{corrected})` . The presence of the radial distortion manifests in form of the "barrel" or "fish-eye" effect. 
+So for an old pixel point at :math:`(x,y)` coordinate in the input image, for a corrected output image its position will be :math:`(x_{corrected} y_{corrected})` . The presence of the radial distortion manifests in form of the "barrel" or "fish-eye" effect.
 
-Tangential distortion occurs because the image taking lenses are not perfectly parallel to the imaging plane. Correcting this is made via the formulas: 
+Tangential distortion occurs because the image taking lenses are not perfectly parallel to the imaging plane. Correcting this is made via the formulas:
 
-.. math:: 
+.. math::
 
    x_{corrected} = x + [ 2p_1xy + p_2(r^2+2x^2)] \\
    y_{corrected} = y + [ p_1(r^2+ 2y^2)+ 2p_2xy]
 
-So we have five distortion parameters, which in OpenCV are organized in a 5 column one row matrix: 
+So we have five distortion parameters, which in OpenCV are organized in a 5 column one row matrix:
 
-.. math:: 
+.. math::
 
   Distortion_{coefficients}=(k_1 \hspace{10pt} k_2 \hspace{10pt} p_1 \hspace{10pt} p_2 \hspace{10pt} k_3)
 
@@ -38,7 +38,7 @@ Now for the unit conversion, we use the following formula:
 
 Here the presence of the :math:`w` is cause we use a homography coordinate system (and :math:`w=Z`). The unknown parameters are :math:`f_x` and :math:`f_y` (camera focal lengths) and :math:`(c_x, c_y)` what are the optical centers expressed in pixels coordinates. If for both axes a common focal length is used with a given :math:`a` aspect ratio (usually 1), then :math:`f_y=f_x*a` and in the upper formula we will have a single :math:`f` focal length. The matrix containing these four parameters is referred to as the *camera matrix*. While the distortion coefficients are the same regardless of the camera resolutions used, these should be scaled along with the current resolution from the calibrated resolution.
 
-The process of determining these two matrices is the calibration. Calculating these parameters is done by some basic geometrical equations. The equations used depend on the calibrating objects used. Currently OpenCV supports three types of object for calibration: 
+The process of determining these two matrices is the calibration. Calculating these parameters is done by some basic geometrical equations. The equations used depend on the calibrating objects used. Currently OpenCV supports three types of object for calibration:
 
 .. container:: enumeratevisibleitemswithsquare
 
@@ -46,12 +46,12 @@ The process of determining these two matrices is the calibration. Calculating th
    + Symmetrical circle pattern
    + Asymmetrical circle pattern
 
-Basically, you need to take snapshots of these patterns with your camera and let OpenCV find them. Each found pattern equals in a new equation. To solve the equation you need at least a predetermined number of pattern snapshots to form a well-posed equation system. This number is higher for the chessboard pattern and less for the circle ones. For example, in theory the chessboard one requires at least two. However, in practice we have a good amount of noise present in our input images, so for good results you will probably want at least 10 good snapshots of the input pattern in different position. 
+Basically, you need to take snapshots of these patterns with your camera and let OpenCV find them. Each found pattern equals in a new equation. To solve the equation you need at least a predetermined number of pattern snapshots to form a well-posed equation system. This number is higher for the chessboard pattern and less for the circle ones. For example, in theory the chessboard one requires at least two. However, in practice we have a good amount of noise present in our input images, so for good results you will probably want at least 10 good snapshots of the input pattern in different position.
 
 Goal
 ====
 
-The sample application will: 
+The sample application will:
 
 .. container:: enumeratevisibleitemswithsquare
 
@@ -67,7 +67,7 @@ Source code
 
 You may also find the source code in the :file:`samples/cpp/tutorial_code/calib3d/camera_calibration/` folder of the OpenCV source library or :download:`download it from here <../../../../samples/cpp/tutorial_code/calib3d/camera_calibration/camera_calibration.cpp>`. The program has a single argument. The name of its configuration file. If none given it will try to open the one named "default.xml". :download:`Here's a sample configuration file <../../../../samples/cpp/tutorial_code/calib3d/camera_calibration/in_VID5.xml>` in XML format. In the configuration file you may choose to use as input a camera, a video file or an image list. If you opt for the later one, you need to create a configuration file where you enumerate the images to use. Here's :download:`an example of this <../../../../samples/cpp/tutorial_code/calib3d/camera_calibration/VID5.xml>`. The important part to remember is that the images needs to be specified using the absolute path or the relative one from your applications working directory. You may find all this in the beforehand mentioned directory.
 
-The application starts up with reading the settings from the configuration file. Although, this is an important part of it, it has nothing to do with the subject of this tutorial: *camera calibration*. Therefore, I've chosen to do not post here the code part for that. The technical background on how to do this you can find in the :ref:`fileInputOutputXMLYAML` tutorial. 
+The application starts up with reading the settings from the configuration file. Although, this is an important part of it, it has nothing to do with the subject of this tutorial: *camera calibration*. Therefore, I've chosen to do not post here the code part for that. The technical background on how to do this you can find in the :ref:`fileInputOutputXMLYAML` tutorial.
 
 Explanation
 ===========
@@ -76,15 +76,15 @@ Explanation
 
    .. code-block:: cpp
 
-      Settings s; 
+      Settings s;
       const string inputSettingsFile = argc > 1 ? argv[1] : "default.xml";
       FileStorage fs(inputSettingsFile, FileStorage::READ); // Read the settings
       if (!fs.isOpened())
       {
-            cout << "Could not open the configuration file: \"" << inputSettingsFile << "\"" << endl; 
+            cout << "Could not open the configuration file: \"" << inputSettingsFile << "\"" << endl;
             return -1;
       }
-      fs["Settings"] >> s; 
+      fs["Settings"] >> s;
       fs.release();                                         // close Settings file
 
       if (!s.goodInput)
@@ -95,7 +95,7 @@ Explanation
 
    For this I've used simple OpenCV class input operation. After reading the file I've an additional post-process function that checks for the validity of the input. Only if all of them are good will be the *goodInput* variable true.
 
-#. **Get next input, if it fails or we have enough of them calibrate**. After this we have a big loop where we do the following operations: get the next image from the image list, camera or video file. If this fails or we have enough images we run the calibration process. In case of image we step out of the loop and otherwise the remaining frames will be undistorted (if the option is set) via changing from *DETECTION* mode to *CALIBRATED* one. 
+#. **Get next input, if it fails or we have enough of them calibrate**. After this we have a big loop where we do the following operations: get the next image from the image list, camera or video file. If this fails or we have enough images we run the calibration process. In case of image we step out of the loop and otherwise the remaining frames will be undistorted (if the option is set) via changing from *DETECTION* mode to *CALIBRATED* one.
 
    .. code-block:: cpp
 
@@ -123,7 +123,7 @@ Explanation
         if( s.flipVertical )    flip( view, view, 0 );
         }
 
-   For some cameras we may need to flip the input image. Here we do this too. 
+   For some cameras we may need to flip the input image. Here we do this too.
 
 #. **Find the pattern in the current input**. The formation of the equations I mentioned above consists of finding the major patterns in the input: in case of the chessboard this is their corners of the squares and for the circles, well, the circles itself. The position of these will form the result and is collected into the *pointBuf* vector.
 
@@ -146,19 +146,19 @@ Explanation
         break;
       }
 
-   Depending on the type of the input pattern you use either the :calib3d:`findChessboardCorners <findchessboardcorners>` or the :calib3d:`findCirclesGrid <findcirclesgrid>` function. For both of them you pass on the current image, the size of the board and you'll get back the positions of the patterns. Furthermore, they return a boolean variable that states if in the input we could find or not the pattern (we only need to take into account images where this is true!). 
+   Depending on the type of the input pattern you use either the :calib3d:`findChessboardCorners <findchessboardcorners>` or the :calib3d:`findCirclesGrid <findcirclesgrid>` function. For both of them you pass on the current image, the size of the board and you'll get back the positions of the patterns. Furthermore, they return a boolean variable that states if in the input we could find or not the pattern (we only need to take into account images where this is true!).
 
-   Then again in case of cameras we only take camera images after an input delay time passed. This is in order to allow for the user to move the chessboard around and as getting different images. Same images mean same equations, and same equations at the calibration will form an ill-posed problem, so the calibration will fail. For square images the position of the corners are only approximate. We may improve this by calling the :feature2d:`cornerSubPix <cornersubpix>` function. This way will get a better calibration result. After this we add a valid inputs result to the *imagePoints* vector to collect all of the equations into a single container. Finally, for visualization feedback purposes we will draw the found points on the input image with the :calib3d:`findChessboardCorners <drawchessboardcorners>` function. 
+   Then again in case of cameras we only take camera images after an input delay time passed. This is in order to allow for the user to move the chessboard around and as getting different images. Same images mean same equations, and same equations at the calibration will form an ill-posed problem, so the calibration will fail. For square images the position of the corners are only approximate. We may improve this by calling the :feature2d:`cornerSubPix <cornersubpix>` function. This way will get a better calibration result. After this we add a valid inputs result to the *imagePoints* vector to collect all of the equations into a single container. Finally, for visualization feedback purposes we will draw the found points on the input image with the :calib3d:`findChessboardCorners <drawchessboardcorners>` function.
 
    .. code-block:: cpp
 
-      if ( found)                // If done with success, 
+      if ( found)                // If done with success,
         {
             // improve the found corners' coordinate accuracy for chessboard
-              if( s.calibrationPattern == Settings::CHESSBOARD) 
+              if( s.calibrationPattern == Settings::CHESSBOARD)
               {
                   Mat viewGray;
-                  cvtColor(view, viewGray, CV_BGR2GRAY); 
+                  cvtColor(view, viewGray, CV_BGR2GRAY);
                   cornerSubPix( viewGray, pointBuf, Size(11,11),
                     Size(-1,-1), TermCriteria( CV_TERMCRIT_EPS+CV_TERMCRIT_ITER, 30, 0.1 ));
               }
@@ -171,11 +171,11 @@ Explanation
                   blinkOutput = s.inputCapture.isOpened();
               }
 
-              // Draw the corners. 
+              // Draw the corners.
               drawChessboardCorners( view, s.boardSize, Mat(pointBuf), found );
         }
 
-#. **Show state and result for the user, plus command line control of the application**. The showing part consists of a text output on the live feed, and for video or camera input to show the "capturing" frame we simply bitwise negate the input image. 
+#. **Show state and result for the user, plus command line control of the application**. The showing part consists of a text output on the live feed, and for video or camera input to show the "capturing" frame we simply bitwise negate the input image.
 
    .. code-block:: cpp
 
@@ -183,7 +183,7 @@ Explanation
       string msg = (mode == CAPTURING) ? "100/100" :
                 mode == CALIBRATED ? "Calibrated" : "Press 'g' to start";
       int baseLine = 0;
-      Size textSize = getTextSize(msg, 1, 1, 1, &baseLine);        
+      Size textSize = getTextSize(msg, 1, 1, 1, &baseLine);
       Point textOrigin(view.cols - 2*textSize.width - 10, view.rows - 2*baseLine - 10);
 
       if( mode == CAPTURING )
@@ -199,7 +199,7 @@ Explanation
       if( blinkOutput )
          bitwise_not(view, view);
 
-   If we only ran the calibration and got the camera matrix plus the distortion coefficients we may just as correct the image with the :imgproc_geometric:`undistort <undistort>` function: 
+   If we only ran the calibration and got the camera matrix plus the distortion coefficients we may just as correct the image with the :imgproc_geometric:`undistort <undistort>` function:
 
    .. code-block:: cpp
 
@@ -229,7 +229,7 @@ Explanation
         imagePoints.clear();
       }
 
-#. **Show the distortion removal for the images too**. When you work with an image list it is not possible to remove the distortion inside the loop. Therefore, you must append this after the loop. Taking advantage of this now I'll expand the :imgproc_geometric:`undistort <undistort>` function, which is in fact first a call of the :imgproc_geometric:`initUndistortRectifyMap <initundistortrectifymap>` to find out the transformation matrices and then doing the transformation with the :imgproc_geometric:`remap <remap>` function. Because, after a successful calibration the map calculation needs to be done only once, by using this expanded form you may speed up your application: 
+#. **Show the distortion removal for the images too**. When you work with an image list it is not possible to remove the distortion inside the loop. Therefore, you must append this after the loop. Taking advantage of this now I'll expand the :imgproc_geometric:`undistort <undistort>` function, which is in fact first a call of the :imgproc_geometric:`initUndistortRectifyMap <initundistortrectifymap>` to find out the transformation matrices and then doing the transformation with the :imgproc_geometric:`remap <remap>` function. Because, after a successful calibration the map calculation needs to be done only once, by using this expanded form you may speed up your application:
 
    .. code-block:: cpp
 
@@ -256,9 +256,9 @@ Explanation
 The calibration and save
 ========================
 
-Because the calibration needs to be only once per camera it makes sense to save them after a successful calibration. This way later on you can just load these values into your program. Due to this we first make the calibration, and if it succeeds we save the result into an OpenCV style XML or YAML file, depending on the extension you give in the configuration file. 
+Because the calibration needs to be only once per camera it makes sense to save them after a successful calibration. This way later on you can just load these values into your program. Due to this we first make the calibration, and if it succeeds we save the result into an OpenCV style XML or YAML file, depending on the extension you give in the configuration file.
 
-Therefore in the first function we just split up these two processes. Because we want to save many of the calibration variables we'll create these variables here and pass on both of them to the calibration and saving function. Again, I'll not show the saving part as that has little in common with the calibration. Explore the source file in order to find out how and what: 
+Therefore in the first function we just split up these two processes. Because we want to save many of the calibration variables we'll create these variables here and pass on both of them to the calibration and saving function. Again, I'll not show the saving part as that has little in common with the calibration. Explore the source file in order to find out how and what:
 
 .. code-block:: cpp
 
@@ -269,10 +269,10 @@ Therefore in the first function we just split up these two processes. Because we
     vector<float> reprojErrs;
     double totalAvgErr = 0;
 
-    bool ok = runCalibration(s,imageSize, cameraMatrix, distCoeffs, imagePoints, rvecs, tvecs, 
+    bool ok = runCalibration(s,imageSize, cameraMatrix, distCoeffs, imagePoints, rvecs, tvecs,
                              reprojErrs, totalAvgErr);
     cout << (ok ? "Calibration succeeded" : "Calibration failed")
-        << ". avg re projection error = "  << totalAvgErr ; 
+        << ". avg re projection error = "  << totalAvgErr ;
 
     if( ok )   // save only if the calibration was done with success
         saveCameraParams( s, imageSize, cameraMatrix, distCoeffs, rvecs ,tvecs, reprojErrs,
@@ -280,15 +280,15 @@ Therefore in the first function we just split up these two processes. Because we
     return ok;
    }
 
-We do the calibration with the help of the :calib3d:`calibrateCamera <calibratecamera>` function. This has the following parameters: 
+We do the calibration with the help of the :calib3d:`calibrateCamera <calibratecamera>` function. This has the following parameters:
 
 .. container:: enumeratevisibleitemswithsquare
 
-   + The object points. This is a vector of *Point3f* vector that for each input image describes how should the pattern look. If we have a planar pattern (like a chessboard) then we can simply set all Z coordinates to zero. This is a collection of the points where these important points are present. Because, we use a single pattern for all the input images we can calculate this just once and multiply it for all the other input views. We calculate the corner points with the *calcBoardCornerPositions* function as: 
+   + The object points. This is a vector of *Point3f* vector that for each input image describes how should the pattern look. If we have a planar pattern (like a chessboard) then we can simply set all Z coordinates to zero. This is a collection of the points where these important points are present. Because, we use a single pattern for all the input images we can calculate this just once and multiply it for all the other input views. We calculate the corner points with the *calcBoardCornerPositions* function as:
 
      .. code-block:: cpp
 
-        void calcBoardCornerPositions(Size boardSize, float squareSize, vector<Point3f>& corners, 
+        void calcBoardCornerPositions(Size boardSize, float squareSize, vector<Point3f>& corners,
                           Settings::Pattern patternType /*= Settings::CHESSBOARD*/)
         {
         corners.clear();
@@ -310,19 +310,19 @@ We do the calibration with the help of the :calib3d:`calibrateCamera <calibratec
         }
         }
 
-     And then multiply it as: 
+     And then multiply it as:
 
-     .. code-block:: cpp 
+     .. code-block:: cpp
 
         vector<vector<Point3f> > objectPoints(1);
         calcBoardCornerPositions(s.boardSize, s.squareSize, objectPoints[0], s.calibrationPattern);
-        objectPoints.resize(imagePoints.size(),objectPoints[0]); 
+        objectPoints.resize(imagePoints.size(),objectPoints[0]);
 
-   + The image points. This is a vector of *Point2f* vector that for each input image contains where the important points (corners for chessboard, and center of circles for the circle patterns) were found. We already collected this from what the :calib3d:`findChessboardCorners <findchessboardcorners>` or the :calib3d:`findCirclesGrid <findcirclesgrid>` function returned. We just need to pass it on. 
+   + The image points. This is a vector of *Point2f* vector that for each input image contains where the important points (corners for chessboard, and center of circles for the circle patterns) were found. We already collected this from what the :calib3d:`findChessboardCorners <findchessboardcorners>` or the :calib3d:`findCirclesGrid <findcirclesgrid>` function returned. We just need to pass it on.
 
-   + The size of the image acquired from the camera, video file or the images. 
+   + The size of the image acquired from the camera, video file or the images.
 
-   + The camera matrix. If we used the fix aspect ratio option we need to set the :math:`f_x` to zero: 
+   + The camera matrix. If we used the fix aspect ratio option we need to set the :math:`f_x` to zero:
 
      .. code-block:: cpp
 
@@ -330,24 +330,24 @@ We do the calibration with the help of the :calib3d:`calibrateCamera <calibratec
         if( s.flag & CV_CALIB_FIX_ASPECT_RATIO )
              cameraMatrix.at<double>(0,0) = 1.0;
 
-   + The distortion coefficient matrix. Initialize with zero. 
+   + The distortion coefficient matrix. Initialize with zero.
 
      .. code-block:: cpp
 
         distCoeffs = Mat::zeros(8, 1, CV_64F);
 
-   + The function will calculate for all the views the rotation and translation vector that transform the object points (given in the model coordinate space) to the image points (given in the world coordinate space). The 7th and 8th parameters are an output vector of matrices containing in the ith position the rotation and translation vector for the ith object point to the ith image point. 
+   + The function will calculate for all the views the rotation and translation vector that transform the object points (given in the model coordinate space) to the image points (given in the world coordinate space). The 7th and 8th parameters are an output vector of matrices containing in the ith position the rotation and translation vector for the ith object point to the ith image point.
 
-   + The final argument is a flag. You need to specify here options like fix the aspect ratio for the focal length, assume zero tangential distortion or to fix the principal point. 
+   + The final argument is a flag. You need to specify here options like fix the aspect ratio for the focal length, assume zero tangential distortion or to fix the principal point.
 
    .. code-block:: cpp
 
      double rms = calibrateCamera(objectPoints, imagePoints, imageSize, cameraMatrix,
                                  distCoeffs, rvecs, tvecs, s.flag|CV_CALIB_FIX_K4|CV_CALIB_FIX_K5);
 
-   + The function returns the average re-projection error. This number gives a good estimation of just how exact is the found parameters. This should be as close to zero as possible. Given the intrinsic, distortion, rotation and translation matrices we may calculate the error for one view by using the :calib3d:`projectPoints <projectpoints>` to first transform the object point to image point. Then we calculate the absolute norm between what we got with our transformation and the corner/circle finding algorithm. To find the average error we calculate the arithmetical mean of the errors calculate for all the calibration images. 
+   + The function returns the average re-projection error. This number gives a good estimation of just how exact is the found parameters. This should be as close to zero as possible. Given the intrinsic, distortion, rotation and translation matrices we may calculate the error for one view by using the :calib3d:`projectPoints <projectpoints>` to first transform the object point to image point. Then we calculate the absolute norm between what we got with our transformation and the corner/circle finding algorithm. To find the average error we calculate the arithmetical mean of the errors calculate for all the calibration images.
 
-     .. code-block:: cpp 
+     .. code-block:: cpp
 
         double computeReprojectionErrors( const vector<vector<Point3f> >& objectPoints,
                                   const vector<vector<Point2f> >& imagePoints,
@@ -378,7 +378,7 @@ We do the calibration with the help of the :calib3d:`calibrateCamera <calibratec
 Results
 =======
 
-Let there be :download:`this input chessboard pattern <../../../pattern.png>` that has a size of 9 X 6. I've used an AXIS IP camera to create a couple of snapshots of the board and saved it into a VID5 directory. I've put this inside the :file:`images/CameraCalibraation` folder of my working directory and created the following :file:`VID5.XML` file that describes which images to use: 
+Let there be :download:`this input chessboard pattern <../../../pattern.png>` that has a size of 9 X 6. I've used an AXIS IP camera to create a couple of snapshots of the board and saved it into a VID5 directory. I've put this inside the :file:`images/CameraCalibraation` folder of my working directory and created the following :file:`VID5.XML` file that describes which images to use:
 
 .. code-block:: xml
 
@@ -396,25 +396,25 @@ Let there be :download:`this input chessboard pattern <../../../pattern.png>` th
    </images>
    </opencv_storage>
 
-Then specified the :file:`images/CameraCalibraation/VID5/VID5.XML` as input in the configuration file. Here's a chessboard pattern found during the runtime of the application: 
+Then specified the :file:`images/CameraCalibraation/VID5/VID5.XML` as input in the configuration file. Here's a chessboard pattern found during the runtime of the application:
 
-.. image:: images/fileListImage.jpg 
+.. image:: images/fileListImage.jpg
    :alt: A found chessboard
    :align: center
 
-After applying the distortion removal we get: 
+After applying the distortion removal we get:
 
-.. image:: images/fileListImageUnDist.jpg 
+.. image:: images/fileListImageUnDist.jpg
    :alt: Distortion removal for File List
    :align: center
 
-The same works for :download:`this asymmetrical circle pattern <../../../acircles_pattern.png>` by setting the input width to 4 and height to 11. This time I've used a live camera feed by specifying its ID ("1") for the input. Here's, how a detected pattern should look: 
+The same works for :download:`this asymmetrical circle pattern <../../../acircles_pattern.png>` by setting the input width to 4 and height to 11. This time I've used a live camera feed by specifying its ID ("1") for the input. Here's, how a detected pattern should look:
 
-.. image:: images/asymetricalPattern.jpg 
+.. image:: images/asymetricalPattern.jpg
    :alt: Asymmetrical circle detection
    :align: center
 
-In both cases in the specified output XML/YAML file you'll find the camera and distortion coefficients matrices: 
+In both cases in the specified output XML/YAML file you'll find the camera and distortion coefficients matrices:
 
 .. code-block:: cpp
 
@@ -433,9 +433,9 @@ In both cases in the specified output XML/YAML file you'll find the camera and d
     -4.1802327176423804e-001 5.0715244063187526e-001 0. 0.
     -5.7843597214487474e-001</data></Distortion_Coefficients>
 
-Add these values as constants to your program, call the :imgproc_geometric:`initUndistortRectifyMap <initundistortrectifymap>` and the :imgproc_geometric:`remap <remap>` function to remove distortion and enjoy distortion free inputs with cheap and low quality cameras. 
+Add these values as constants to your program, call the :imgproc_geometric:`initUndistortRectifyMap <initundistortrectifymap>` and the :imgproc_geometric:`remap <remap>` function to remove distortion and enjoy distortion free inputs with cheap and low quality cameras.
 
-You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=ViPN810E0SU>`_. 
+You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=ViPN810E0SU>`_.
 
 .. raw:: html
 
index ec7354b..4eff264 100644 (file)
@@ -7,16 +7,16 @@ Camera calibration with square chessboard
 
 The goal of this tutorial is to learn how to calibrate a camera given a set of chessboard images.
 
-*Test data*: use images in your data/chess folder. 
+*Test data*: use images in your data/chess folder.
 
 #.
-    Compile opencv with samples by setting ``BUILD_EXAMPLES`` to ``ON`` in cmake configuration. 
+    Compile opencv with samples by setting ``BUILD_EXAMPLES`` to ``ON`` in cmake configuration.
 
 #.
     Go to ``bin`` folder and use ``imagelist_creator`` to create an ``XML/YAML`` list of your images.
-    
+
 #.
-    Then, run ``calibration`` sample to get camera parameters. Use square size equal to 3cm. 
+    Then, run ``calibration`` sample to get camera parameters. Use square size equal to 3cm.
 
 Pose estimation
 ===============
@@ -57,6 +57,6 @@ Now, let us write a code that detects a chessboard in a new image and finds its
                              distCoeffs, rvec, tvec, false);
 
 #.
-    Calculate reprojection error like it is done in ``calibration`` sample (see ``opencv/samples/cpp/calibration.cpp``, function ``computeReprojectionErrors``). 
+    Calculate reprojection error like it is done in ``calibration`` sample (see ``opencv/samples/cpp/calibration.cpp``, function ``computeReprojectionErrors``).
 
-Question: how to calculate the distance from the camera origin to any of the corners? 
\ No newline at end of file
+Question: how to calculate the distance from the camera origin to any of the corners?
\ No newline at end of file
index 3d45664..91f80b7 100644 (file)
@@ -3,11 +3,11 @@
 *calib3d* module. Camera calibration and 3D reconstruction
 -----------------------------------------------------------
 
-Although we got most of our images in a 2D format they do come from a 3D world. Here you will learn how to find out from the 2D images information about the 3D world. 
+Although we got most of our images in a 2D format they do come from a 3D world. Here you will learn how to find out from the 2D images information about the 3D world.
 
-.. include:: ../../definitions/tocDefinitions.rst 
+.. include:: ../../definitions/tocDefinitions.rst
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
@@ -26,7 +26,7 @@ Although we got most of our images in a 2D format they do come from a 3D world.
      :height: 90pt
      :width:  90pt
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
index 2df40c2..40e2a0d 100644 (file)
@@ -18,7 +18,7 @@ Theory
 
 .. note::
 
-   The explanation below belongs to the book `Computer Vision: Algorithms and Applications <http://szeliski.org/Book/>`_  by Richard Szeliski 
+   The explanation below belongs to the book `Computer Vision: Algorithms and Applications <http://szeliski.org/Book/>`_  by Richard Szeliski
 
 From our previous tutorial, we know already a bit of *Pixel operators*. An interesting dyadic (two-input) operator is the *linear blend operator*:
 
@@ -43,7 +43,7 @@ As usual, after the not-so-lengthy explanation, let's go to the code:
 
    int main( int argc, char** argv )
    {
-    double alpha = 0.5; double beta; double input; 
+    double alpha = 0.5; double beta; double input;
 
     Mat src1, src2, dst;
 
@@ -69,7 +69,7 @@ As usual, after the not-so-lengthy explanation, let's go to the code:
 
     beta = ( 1.0 - alpha );
     addWeighted( src1, alpha, src2, beta, 0.0, dst);
-  
+
     imshow( "Linear Blend", dst );
 
     waitKey(0);
@@ -99,10 +99,10 @@ Explanation
 #. Now we need to generate the :math:`g(x)` image. For this, the function :add_weighted:`addWeighted <>` comes quite handy:
 
    .. code-block:: cpp
-   
+
       beta = ( 1.0 - alpha );
       addWeighted( src1, alpha, src2, beta, 0.0, dst);
+
    since :add_weighted:`addWeighted <>` produces:
 
    .. math::
@@ -110,12 +110,12 @@ Explanation
       dst = \alpha \cdot src1 + \beta \cdot src2 + \gamma
 
    In this case, :math:`\gamma` is the argument :math:`0.0` in the code above.
-#. Create windows, show the images and wait for the user to end the program. 
+
+#. Create windows, show the images and wait for the user to end the program.
 
 Result
 =======
 
 .. image:: images/Adding_Images_Tutorial_Result_0.jpg
    :alt: Blending Images Tutorial - Final Result
-   :align: center 
+   :align: center
index 3bd3237..be0016b 100644 (file)
@@ -99,11 +99,11 @@ Explanation
 
       /// 2.b. Creating rectangles
       rectangle( rook_image,
-                Point( 0, 7*w/8.0 ),
-                Point( w, w),
-                Scalar( 0, 255, 255 ),
-                -1,
-                8 );
+             Point( 0, 7*w/8.0 ),
+             Point( w, w),
+             Scalar( 0, 255, 255 ),
+             -1,
+             8 );
 
       /// 2.c. Create a few lines
       MyLine( rook_image, Point( 0, 15*w/16 ), Point( w, 15*w/16 ) );
@@ -118,16 +118,16 @@ Explanation
      .. code-block:: cpp
 
         void MyLine( Mat img, Point start, Point end )
-       {
-         int thickness = 2;
-         int lineType = 8;
-         line( img,
-               start,
-               end,
-               Scalar( 0, 0, 0 ),
-               thickness,
-               lineType );
-       }
+    {
+      int thickness = 2;
+      int lineType = 8;
+      line( img,
+        start,
+        end,
+        Scalar( 0, 0, 0 ),
+        thickness,
+        lineType );
+    }
 
      As we can see, *MyLine* just call the function :line:`line <>`, which does the following:
 
@@ -145,18 +145,18 @@ Explanation
 
         void MyEllipse( Mat img, double angle )
         {
-         int thickness = 2;
-         int lineType = 8;
-
-         ellipse( img,
-                  Point( w/2.0, w/2.0 ),
-                  Size( w/4.0, w/16.0 ),
-                  angle,
-                  0,
-                  360,
-                  Scalar( 255, 0, 0 ),
-                  thickness,
-                  lineType );
+      int thickness = 2;
+      int lineType = 8;
+
+      ellipse( img,
+           Point( w/2.0, w/2.0 ),
+           Size( w/4.0, w/16.0 ),
+           angle,
+           0,
+           360,
+           Scalar( 255, 0, 0 ),
+           thickness,
+           lineType );
         }
 
      From the code above, we can observe that the function :ellipse:`ellipse <>` draws an ellipse such that:
@@ -176,17 +176,17 @@ Explanation
      .. code-block:: cpp
 
         void MyFilledCircle( Mat img, Point center )
-       {
-        int thickness = -1;
-        int lineType = 8;
-
-        circle( img,
-                center,
-                w/32.0,
-                Scalar( 0, 0, 255 ),
-                thickness,
-                lineType );
-       }
+    {
+     int thickness = -1;
+     int lineType = 8;
+
+     circle( img,
+         center,
+         w/32.0,
+         Scalar( 0, 0, 255 ),
+         thickness,
+         lineType );
+    }
 
      Similar to the ellipse function, we can observe that *circle* receives as arguments:
 
@@ -203,41 +203,41 @@ Explanation
      .. code-block:: cpp
 
         void MyPolygon( Mat img )
-       {
-         int lineType = 8;
-
-         /** Create some points */
-         Point rook_points[1][20];
-         rook_points[0][0] = Point( w/4.0, 7*w/8.0 );
-         rook_points[0][1] = Point( 3*w/4.0, 7*w/8.0 );
-         rook_points[0][2] = Point( 3*w/4.0, 13*w/16.0 );
-         rook_points[0][3] = Point( 11*w/16.0, 13*w/16.0 );
-         rook_points[0][4] = Point( 19*w/32.0, 3*w/8.0 );
-         rook_points[0][5] = Point( 3*w/4.0, 3*w/8.0 );
-         rook_points[0][6] = Point( 3*w/4.0, w/8.0 );
-         rook_points[0][7] = Point( 26*w/40.0, w/8.0 );
-         rook_points[0][8] = Point( 26*w/40.0, w/4.0 );
-         rook_points[0][9] = Point( 22*w/40.0, w/4.0 );
-         rook_points[0][10] = Point( 22*w/40.0, w/8.0 );
-         rook_points[0][11] = Point( 18*w/40.0, w/8.0 );
-         rook_points[0][12] = Point( 18*w/40.0, w/4.0 );
-         rook_points[0][13] = Point( 14*w/40.0, w/4.0 );
-         rook_points[0][14] = Point( 14*w/40.0, w/8.0 );
-         rook_points[0][15] = Point( w/4.0, w/8.0 );
-         rook_points[0][16] = Point( w/4.0, 3*w/8.0 );
-         rook_points[0][17] = Point( 13*w/32.0, 3*w/8.0 );
-         rook_points[0][18] = Point( 5*w/16.0, 13*w/16.0 );
-         rook_points[0][19] = Point( w/4.0, 13*w/16.0) ;
-
-         const Point* ppt[1] = { rook_points[0] };
-         int npt[] = { 20 };
-
-         fillPoly( img,
-                   ppt,
-                   npt,
-                   1,
-                   Scalar( 255, 255, 255 ),
-                   lineType );
+    {
+      int lineType = 8;
+
+      /** Create some points */
+      Point rook_points[1][20];
+      rook_points[0][0] = Point( w/4.0, 7*w/8.0 );
+      rook_points[0][1] = Point( 3*w/4.0, 7*w/8.0 );
+      rook_points[0][2] = Point( 3*w/4.0, 13*w/16.0 );
+      rook_points[0][3] = Point( 11*w/16.0, 13*w/16.0 );
+      rook_points[0][4] = Point( 19*w/32.0, 3*w/8.0 );
+      rook_points[0][5] = Point( 3*w/4.0, 3*w/8.0 );
+      rook_points[0][6] = Point( 3*w/4.0, w/8.0 );
+      rook_points[0][7] = Point( 26*w/40.0, w/8.0 );
+      rook_points[0][8] = Point( 26*w/40.0, w/4.0 );
+      rook_points[0][9] = Point( 22*w/40.0, w/4.0 );
+      rook_points[0][10] = Point( 22*w/40.0, w/8.0 );
+      rook_points[0][11] = Point( 18*w/40.0, w/8.0 );
+      rook_points[0][12] = Point( 18*w/40.0, w/4.0 );
+      rook_points[0][13] = Point( 14*w/40.0, w/4.0 );
+      rook_points[0][14] = Point( 14*w/40.0, w/8.0 );
+      rook_points[0][15] = Point( w/4.0, w/8.0 );
+      rook_points[0][16] = Point( w/4.0, 3*w/8.0 );
+      rook_points[0][17] = Point( 13*w/32.0, 3*w/8.0 );
+      rook_points[0][18] = Point( 5*w/16.0, 13*w/16.0 );
+      rook_points[0][19] = Point( w/4.0, 13*w/16.0) ;
+
+      const Point* ppt[1] = { rook_points[0] };
+      int npt[] = { 20 };
+
+      fillPoly( img,
+                ppt,
+                npt,
+                    1,
+                Scalar( 255, 255, 255 ),
+                lineType );
          }
 
      To draw a filled polygon we use the function :fill_poly:`fillPoly <>`. We note that:
@@ -255,11 +255,11 @@ Explanation
      .. code-block:: cpp
 
         rectangle( rook_image,
-                  Point( 0, 7*w/8.0 ),
-                  Point( w, w),
-                  Scalar( 0, 255, 255 ),
-                  -1,
-                  8 );
+               Point( 0, 7*w/8.0 ),
+               Point( w, w),
+               Scalar( 0, 255, 255 ),
+               -1,
+               8 );
 
      Finally we have the :rectangle:`rectangle <>` function (we did not create a special function for this guy). We note that:
 
index 097e79e..613f4e1 100644 (file)
@@ -10,7 +10,7 @@ In this tutorial you will learn how to:
 
 .. container:: enumeratevisibleitemswithsquare
 
-   + Access pixel values 
+   + Access pixel values
 
    + Initialize a matrix with zeros
 
@@ -20,16 +20,16 @@ In this tutorial you will learn how to:
 
 Theory
 =======
+
 .. note::
-   The explanation below belongs to the book `Computer Vision: Algorithms and Applications <http://szeliski.org/Book/>`_  by Richard Szeliski 
+   The explanation below belongs to the book `Computer Vision: Algorithms and Applications <http://szeliski.org/Book/>`_  by Richard Szeliski
 
 Image Processing
 --------------------
 
 .. container:: enumeratevisibleitemswithsquare
 
-   * A general image processing operator is a function that takes one or more input images and produces an output image. 
+   * A general image processing operator is a function that takes one or more input images and produces an output image.
 
    * Image transforms can be seen as:
 
@@ -54,18 +54,18 @@ Brightness and contrast adjustments
    * Two commonly used point processes are *multiplication* and *addition* with a constant:
 
      .. math::
+
         g(x) = \alpha f(x) + \beta
-  
+
    * The parameters :math:`\alpha > 0` and :math:`\beta` are often called the *gain* and *bias* parameters; sometimes these parameters are said to control *contrast* and *brightness* respectively.
 
    * You can think of :math:`f(x)` as the source image pixels and :math:`g(x)` as the output image pixels. Then, more conveniently we can write the expression as:
 
      .. math::
-   
+
         g(i,j) = \alpha \cdot f(i,j) + \beta
-  
-     where :math:`i` and :math:`j` indicates that the pixel is located in the *i-th* row and *j-th* column. 
+
+     where :math:`i` and :math:`j` indicates that the pixel is located in the *i-th* row and *j-th* column.
 
 Code
 =====
@@ -91,7 +91,7 @@ Code
     Mat image = imread( argv[1] );
     Mat new_image = Mat::zeros( image.size(), image.type() );
 
-    /// Initialize values 
+    /// Initialize values
     std::cout<<" Basic Linear Transforms "<<std::endl;
     std::cout<<"-------------------------"<<std::endl;
     std::cout<<"* Enter the alpha value [1.0-3.0]: ";std::cin>>alpha;
@@ -102,7 +102,7 @@ Code
        { for( int x = 0; x < image.cols; x++ )
             { for( int c = 0; c < 3; c++ )
                  {
-         new_image.at<Vec3b>(y,x)[c] = 
+         new_image.at<Vec3b>(y,x)[c] =
             saturate_cast<uchar>( alpha*( image.at<Vec3b>(y,x)[c] ) + beta );
                 }
        }
@@ -133,41 +133,41 @@ Explanation
 
 
 #. We load an image using :imread:`imread <>` and save it in a Mat object:
-   
+
    .. code-block:: cpp
 
       Mat image = imread( argv[1] );
 
 #. Now, since we will make some transformations to this image, we need a new Mat object to store it. Also, we want this to have the following features:
-   
+
    .. container:: enumeratevisibleitemswithsquare
 
       * Initial pixel values equal to zero
       * Same size and type as the original image
+
    .. code-block:: cpp
 
-      Mat new_image = Mat::zeros( image.size(), image.type() ); 
-   We observe that :mat_zeros:`Mat::zeros <>` returns a Matlab-style zero initializer based on *image.size()* and *image.type()*  
+      Mat new_image = Mat::zeros( image.size(), image.type() );
+
+   We observe that :mat_zeros:`Mat::zeros <>` returns a Matlab-style zero initializer based on *image.size()* and *image.type()*
 
 #. Now, to perform the operation :math:`g(i,j) = \alpha \cdot f(i,j) + \beta` we will access to each pixel in image. Since we are operating with RGB images, we will have three values per pixel (R, G and B), so we will also access them separately. Here is the piece of code:
 
    .. code-block:: cpp
+
       for( int y = 0; y < image.rows; y++ )
          { for( int x = 0; x < image.cols; x++ )
               { for( int c = 0; c < 3; c++ )
-                   { new_image.at<Vec3b>(y,x)[c] = 
+                   { new_image.at<Vec3b>(y,x)[c] =
                                saturate_cast<uchar>( alpha*( image.at<Vec3b>(y,x)[c] ) + beta ); }
          }
          }
+
    Notice the following:
 
    .. container:: enumeratevisibleitemswithsquare
 
-      * To access each pixel in the images we are using this syntax: *image.at<Vec3b>(y,x)[c]* where *y* is the row, *x* is the column and *c* is R, G or B (0, 1 or 2). 
+      * To access each pixel in the images we are using this syntax: *image.at<Vec3b>(y,x)[c]* where *y* is the row, *x* is the column and *c* is R, G or B (0, 1 or 2).
 
       * Since the operation :math:`\alpha \cdot p(i,j) + \beta` can give values out of range or not integers (if :math:`\alpha` is float), we use :saturate_cast:`saturate_cast <>` to make sure the values are valid.
 
@@ -175,7 +175,7 @@ Explanation
 #. Finally, we create windows and show the images, the usual way.
 
    .. code-block:: cpp
-   
+
       namedWindow("Original Image", 1);
       namedWindow("New Image", 1);
 
@@ -185,9 +185,9 @@ Explanation
       waitKey(0);
 
 .. note::
-  
+
    Instead of using the **for** loops to access each pixel, we could have simply used this command:
-  
+
    .. code-block:: cpp
 
       image.convertTo(new_image, -1, alpha, beta);
@@ -211,4 +211,4 @@ Result
 
 .. image:: images/Basic_Linear_Transform_Tutorial_Result_0.jpg
    :alt: Basic Linear Transform - Final Result
-   :align: center 
+   :align: center
index b5f8e77..b7cf446 100644 (file)
@@ -4,22 +4,22 @@ Discrete Fourier Transform
 **************************
 
 Goal
-==== 
+====
 
-We'll seek answers for the following questions: 
+We'll seek answers for the following questions:
 
 .. container:: enumeratevisibleitemswithsquare
 
-   + What is a Fourier transform and why use it? 
-   + How to do it in OpenCV? 
+   + What is a Fourier transform and why use it?
+   + How to do it in OpenCV?
    + Usage of functions such as: :imgprocfilter:`copyMakeBorder() <copymakeborder>`, :operationsonarrays:`merge() <merge>`, :operationsonarrays:`dft() <dft>`, :operationsonarrays:`getOptimalDFTSize() <getoptimaldftsize>`, :operationsonarrays:`log() <log>` and :operationsonarrays:`normalize() <normalize>` .
 
 Source code
 ===========
 
-You can :download:`download this from here <../../../../samples/cpp/tutorial_code/core/discrete_fourier_transform/discrete_fourier_transform.cpp>` or find it in the :file:`samples/cpp/tutorial_code/core/discrete_fourier_transform/discrete_fourier_transform.cpp` of the OpenCV source code library. 
+You can :download:`download this from here <../../../../samples/cpp/tutorial_code/core/discrete_fourier_transform/discrete_fourier_transform.cpp>` or find it in the :file:`samples/cpp/tutorial_code/core/discrete_fourier_transform/discrete_fourier_transform.cpp` of the OpenCV source code library.
 
-Here's a sample usage of :operationsonarrays:`dft() <dft>` : 
+Here's a sample usage of :operationsonarrays:`dft() <dft>` :
 
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/discrete_fourier_transform/discrete_fourier_transform.cpp
    :language: cpp
@@ -30,11 +30,11 @@ Here's a sample usage of :operationsonarrays:`dft() <dft>` :
 Explanation
 ===========
 
-The Fourier Transform will decompose an image into its sinus and cosines components. In other words, it will transform an image from its spatial domain to its frequency domain. The idea is that any function may be approximated exactly with the sum of infinite sinus and cosines functions. The Fourier Transform is a way how to do this. Mathematically a two dimensional images Fourier transform is: 
+The Fourier Transform will decompose an image into its sinus and cosines components. In other words, it will transform an image from its spatial domain to its frequency domain. The idea is that any function may be approximated exactly with the sum of infinite sinus and cosines functions. The Fourier Transform is a way how to do this. Mathematically a two dimensional images Fourier transform is:
 
 .. math::
 
-   F(k,l) = \displaystyle\sum\limits_{i=0}^{N-1}\sum\limits_{j=0}^{N-1} f(i,j)e^{-i2\pi(\frac{ki}{N}+\frac{lj}{N})} 
+   F(k,l) = \displaystyle\sum\limits_{i=0}^{N-1}\sum\limits_{j=0}^{N-1} f(i,j)e^{-i2\pi(\frac{ki}{N}+\frac{lj}{N})}
 
    e^{ix} = \cos{x} + i\sin {x}
 
@@ -44,65 +44,65 @@ In this sample I'll show how to calculate and show the *magnitude* image of a Fo
 
 1. **Expand the image to an optimal size**. The performance of a DFT is dependent of the image size. It tends to be the fastest for image sizes that are multiple of the numbers two, three and five. Therefore, to achieve maximal performance it is generally a good idea to pad border values to the image to get a size with such traits. The :operationsonarrays:`getOptimalDFTSize() <getoptimaldftsize>` returns this optimal size and we can use the :imgprocfilter:`copyMakeBorder() <copymakeborder>` function to expand the borders of an image:
 
-   .. code-block:: cpp 
+   .. code-block:: cpp
 
       Mat padded;                            //expand input image to optimal size
       int m = getOptimalDFTSize( I.rows );
       int n = getOptimalDFTSize( I.cols ); // on the border add zero pixels
       copyMakeBorder(I, padded, 0, m - I.rows, 0, n - I.cols, BORDER_CONSTANT, Scalar::all(0));
 
-   The appended pixels are initialized with zero. 
+   The appended pixels are initialized with zero.
 
 2. **Make place for both the complex and the real values**. The result of a Fourier Transform is complex. This implies that for each image value the result is two image values (one per component). Moreover, the frequency domains range is much larger than its spatial counterpart. Therefore, we store these usually at least in a *float* format. Therefore we'll convert our input image to this type and expand it with another channel to hold the complex values:
 
-   .. code-block:: cpp 
+   .. code-block:: cpp
 
        Mat planes[] = {Mat_<float>(padded), Mat::zeros(padded.size(), CV_32F)};
        Mat complexI;
        merge(planes, 2, complexI);         // Add to the expanded another plane with zeros
 
-3. **Make the Discrete Fourier Transform**. It's possible an in-place calculation (same input as output): 
+3. **Make the Discrete Fourier Transform**. It's possible an in-place calculation (same input as output):
 
-   .. code-block:: cpp 
+   .. code-block:: cpp
 
       dft(complexI, complexI);            // this way the result may fit in the source matrix
 
-4. **Transform the real and complex values to magnitude**. A complex number has a real (*Re*) and a complex (imaginary - *Im*) part. The results of a DFT are complex numbers. The magnitude of a DFT is: 
+4. **Transform the real and complex values to magnitude**. A complex number has a real (*Re*) and a complex (imaginary - *Im*) part. The results of a DFT are complex numbers. The magnitude of a DFT is:
 
    .. math::
 
       M = \sqrt[2]{ {Re(DFT(I))}^2 + {Im(DFT(I))}^2}
 
-   Translated to OpenCV code: 
+   Translated to OpenCV code:
 
-   .. code-block:: cpp 
+   .. code-block:: cpp
 
       split(complexI, planes);                   // planes[0] = Re(DFT(I), planes[1] = Im(DFT(I))
-      magnitude(planes[0], planes[1], planes[0]);// planes[0] = magnitude  
+      magnitude(planes[0], planes[1], planes[0]);// planes[0] = magnitude
       Mat magI = planes[0];
 
-5. **Switch to a logarithmic scale**. It turns out that the dynamic range of the Fourier coefficients is too large to be displayed on the screen. We have some small and some high changing values that we can't observe like this. Therefore the high values will all turn out as white points, while the small ones as black. To use the gray scale values to for visualization we can transform our linear scale to a logarithmic one: 
+5. **Switch to a logarithmic scale**. It turns out that the dynamic range of the Fourier coefficients is too large to be displayed on the screen. We have some small and some high changing values that we can't observe like this. Therefore the high values will all turn out as white points, while the small ones as black. To use the gray scale values to for visualization we can transform our linear scale to a logarithmic one:
 
    .. math::
 
       M_1 = \log{(1 + M)}
 
-   Translated to OpenCV code: 
+   Translated to OpenCV code:
 
-   .. code-block:: cpp 
+   .. code-block:: cpp
 
       magI += Scalar::all(1);                    // switch to logarithmic scale
       log(magI, magI);
 
-6. **Crop and rearrange**. Remember, that at the first step, we expanded the image? Well, it's time to throw away the newly introduced values. For visualization purposes we may also rearrange the quadrants of the result, so that the origin (zero, zero) corresponds with the image center. 
+6. **Crop and rearrange**. Remember, that at the first step, we expanded the image? Well, it's time to throw away the newly introduced values. For visualization purposes we may also rearrange the quadrants of the result, so that the origin (zero, zero) corresponds with the image center.
 
-   .. code-block:: cpp 
+   .. code-block:: cpp
 
       magI = magI(Rect(0, 0, magI.cols & -2, magI.rows & -2));
       int cx = magI.cols/2;
       int cy = magI.rows/2;
 
-      Mat q0(magI, Rect(0, 0, cx, cy));   // Top-Left - Create a ROI per quadrant 
+      Mat q0(magI, Rect(0, 0, cx, cy));   // Top-Left - Create a ROI per quadrant
       Mat q1(magI, Rect(cx, 0, cx, cy));  // Top-Right
       Mat q2(magI, Rect(0, cy, cx, cy));  // Bottom-Left
       Mat q3(magI, Rect(cx, cy, cx, cy)); // Bottom-Right
@@ -116,25 +116,25 @@ In this sample I'll show how to calculate and show the *magnitude* image of a Fo
       q2.copyTo(q1);
       tmp.copyTo(q2);
 
-7.  **Normalize**. This is done again for visualization purposes. We now have the magnitudes, however this are still out of our image display range of zero to one. We normalize our values to this range using the :operationsonarrays:`normalize() <normalize>` function. 
+7.  **Normalize**. This is done again for visualization purposes. We now have the magnitudes, however this are still out of our image display range of zero to one. We normalize our values to this range using the :operationsonarrays:`normalize() <normalize>` function.
 
-   .. code-block:: cpp 
+   .. code-block:: cpp
 
-      normalize(magI, magI, 0, 1, CV_MINMAX); // Transform the matrix with float values into a 
+      normalize(magI, magI, 0, 1, CV_MINMAX); // Transform the matrix with float values into a
                                               // viewable image form (float between values 0 and 1).
 
 Result
 ======
 
-An application idea would be to determine the geometrical orientation present in the image. For example, let us find out if a text is horizontal or not? Looking at some text you'll notice that the text lines sort of form also horizontal lines and the letters form sort of vertical lines. These two main components of a text snippet may be also seen in case of the Fourier transform. Let us use :download:`this horizontal <../../../../samples/cpp/tutorial_code/images/imageTextN.png>` and :download:`this rotated<../../../../samples/cpp/tutorial_code/images/imageTextR.png>` image about a text. 
+An application idea would be to determine the geometrical orientation present in the image. For example, let us find out if a text is horizontal or not? Looking at some text you'll notice that the text lines sort of form also horizontal lines and the letters form sort of vertical lines. These two main components of a text snippet may be also seen in case of the Fourier transform. Let us use :download:`this horizontal <../../../../samples/cpp/tutorial_code/images/imageTextN.png>` and :download:`this rotated<../../../../samples/cpp/tutorial_code/images/imageTextR.png>` image about a text.
 
-In case of the horizontal text: 
+In case of the horizontal text:
 
 .. image:: images/result_normal.jpg
    :alt: In case of normal text
    :align: center
 
-In case of a rotated text: 
+In case of a rotated text:
 
 .. image:: images/result_rotated.jpg
    :alt: In case of rotated text
index 44eed2e..87166b7 100644 (file)
@@ -4,9 +4,9 @@ File Input and Output using XML and YAML files
 **********************************************
 
 Goal
-==== 
+====
 
-You'll find answers for the following questions: 
+You'll find answers for the following questions:
 
 .. container:: enumeratevisibleitemswithsquare
 
@@ -18,7 +18,7 @@ You'll find answers for the following questions:
 Source code
 ===========
 
-You can :download:`download this from here <../../../../samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp>` or find it in the :file:`samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp` of the OpenCV source code library. 
+You can :download:`download this from here <../../../../samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp>` or find it in the :file:`samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp` of the OpenCV source code library.
 
 Here's a sample code of how to achieve all the stuff enumerated at the goal list.
 
@@ -31,9 +31,9 @@ Here's a sample code of how to achieve all the stuff enumerated at the goal list
 Explanation
 ===========
 
-Here we talk only about XML and YAML file inputs. Your output (and its respective input) file may have only one of these extensions and the structure coming from this. They are two kinds of data structures you may serialize: *mappings* (like the STL map) and *element sequence* (like the STL vector>. The difference between these is that in a map every element has a unique name through what you may access it. For sequences you need to go through them to query a specific item. 
+Here we talk only about XML and YAML file inputs. Your output (and its respective input) file may have only one of these extensions and the structure coming from this. They are two kinds of data structures you may serialize: *mappings* (like the STL map) and *element sequence* (like the STL vector>. The difference between these is that in a map every element has a unique name through what you may access it. For sequences you need to go through them to query a specific item.
 
-1. **XML\\YAML File Open and Close.** Before you write any content to such file you need to open it and at the end to close it. The XML\YAML data structure in OpenCV is :xmlymlpers:`FileStorage <filestorage>`. To specify that this structure to which file binds on your hard drive you can use either its constructor or the *open()* function of this: 
+1. **XML\\YAML File Open and Close.** Before you write any content to such file you need to open it and at the end to close it. The XML\YAML data structure in OpenCV is :xmlymlpers:`FileStorage <filestorage>`. To specify that this structure to which file binds on your hard drive you can use either its constructor or the *open()* function of this:
 
    .. code-block:: cpp
 
@@ -42,29 +42,29 @@ Here we talk only about XML and YAML file inputs. Your output (and its respectiv
       \\...
       fs.open(filename, FileStorage::READ);
 
-   Either one of this you use the second argument is a constant specifying the type of operations you'll be able to on them: WRITE, READ or APPEND. The extension specified in the file name also determinates the output format that will be used. The output may be even compressed if you specify an extension such as *.xml.gz*. 
+   Either one of this you use the second argument is a constant specifying the type of operations you'll be able to on them: WRITE, READ or APPEND. The extension specified in the file name also determinates the output format that will be used. The output may be even compressed if you specify an extension such as *.xml.gz*.
+
+   The file automatically closes when the :xmlymlpers:`FileStorage <filestorage>` objects is destroyed. However, you may explicitly call for this by using the *release* function:
 
-   The file automatically closes when the :xmlymlpers:`FileStorage <filestorage>` objects is destroyed. However, you may explicitly call for this by using the *release* function: 
-   
    .. code-block:: cpp
 
       fs.release();                                       // explicit close
 
-#. **Input and Output of text and numbers.** The data structure uses the same << output operator that the STL library. For outputting any type of data structure we need first to specify its name. We do this by just simply printing out the name of this. For basic types you may follow this with the print of the value : 
+#. **Input and Output of text and numbers.** The data structure uses the same << output operator that the STL library. For outputting any type of data structure we need first to specify its name. We do this by just simply printing out the name of this. For basic types you may follow this with the print of the value :
 
    .. code-block:: cpp
 
       fs << "iterationNr" << 100;
 
-   Reading in is a simple addressing (via the [] operator) and casting operation or a read via the >> operator : 
+   Reading in is a simple addressing (via the [] operator) and casting operation or a read via the >> operator :
 
    .. code-block:: cpp
 
-      int itNr; 
+      int itNr;
       fs["iterationNr"] >> itNr;
       itNr = (int) fs["iterationNr"];
 
-#. **Input\\Output of OpenCV Data structures.** Well these behave exactly just as the basic C++ types: 
+#. **Input\\Output of OpenCV Data structures.** Well these behave exactly just as the basic C++ types:
 
    .. code-block:: cpp
 
@@ -77,7 +77,7 @@ Here we talk only about XML and YAML file inputs. Your output (and its respectiv
       fs["R"] >> R;                                      // Read cv::Mat
       fs["T"] >> T;
 
-#. **Input\\Output of vectors (arrays) and associative maps.** As I mentioned beforehand we can output maps and sequences (array, vector) too. Again we first print the name of the variable and then we have to specify if our output is either a sequence or map. 
+#. **Input\\Output of vectors (arrays) and associative maps.** As I mentioned beforehand we can output maps and sequences (array, vector) too. Again we first print the name of the variable and then we have to specify if our output is either a sequence or map.
 
    For sequence before the first element print the "[" character and after the last one the "]" character:
 
@@ -95,7 +95,7 @@ Here we talk only about XML and YAML file inputs. Your output (and its respectiv
         fs << "{" << "One" << 1;
         fs <<        "Two" << 2 << "}";
 
-   To read from these we use the :xmlymlpers:`FileNode <filenode>` and the :xmlymlpers:`FileNodeIterator <filenodeiterator>` data structures. The [] operator of the :xmlymlpers:`FileStorage <filestorage>` class returns a :xmlymlpers:`FileNode <filenode>` data type. If the node is sequential we can use the :xmlymlpers:`FileNodeIterator <filenodeiterator>` to iterate through the items: 
+   To read from these we use the :xmlymlpers:`FileNode <filenode>` and the :xmlymlpers:`FileNodeIterator <filenodeiterator>` data structures. The [] operator of the :xmlymlpers:`FileStorage <filestorage>` class returns a :xmlymlpers:`FileNode <filenode>` data type. If the node is sequential we can use the :xmlymlpers:`FileNodeIterator <filenodeiterator>` to iterate through the items:
 
    .. code-block:: cpp
 
@@ -115,8 +115,8 @@ Here we talk only about XML and YAML file inputs. Your output (and its respectiv
    .. code-block:: cpp
 
       n = fs["Mapping"];                                // Read mappings from a sequence
-      cout << "Two  " << (int)(n["Two"]) << "; "; 
-      cout << "One  " << (int)(n["One"]) << endl << endl; 
+      cout << "Two  " << (int)(n["Two"]) << "; ";
+      cout << "One  " << (int)(n["One"]) << endl << endl;
 
 #. **Read and write your own data structures.** Suppose you have a data structure such as:
 
@@ -148,7 +148,7 @@ Here we talk only about XML and YAML file inputs. Your output (and its respectiv
         id = (string)node["id"];
       }
 
-   Then you need to add the following functions definitions outside the class: 
+   Then you need to add the following functions definitions outside the class:
 
    .. code-block:: cpp
 
@@ -175,17 +175,17 @@ Here we talk only about XML and YAML file inputs. Your output (and its respectiv
       fs << "MyData" << m;                                // your own data structures
       fs["MyData"] >> m;                                 // Read your own structure_
 
-   Or to try out reading a non-existing read: 
+   Or to try out reading a non-existing read:
 
    .. code-block:: cpp
 
-      fs["NonExisting"] >> m;   // Do not add a fs << "NonExisting" << m command for this to work 
+      fs["NonExisting"] >> m;   // Do not add a fs << "NonExisting" << m command for this to work
       cout << endl << "NonExisting = " << endl << m << endl;
 
 Result
 ======
 
-Well mostly we just print out the defined numbers. On the screen of your console you could see: 
+Well mostly we just print out the defined numbers. On the screen of your console you could see:
 
 .. code-block:: bash
 
@@ -212,7 +212,7 @@ Well mostly we just print out the defined numbers. On the screen of your console
 
    Tip: Open up output.xml with a text editor to see the serialized data.
 
-Nevertheless, it's much more interesting what you may see in the output xml file: 
+Nevertheless, it's much more interesting what you may see in the output xml file:
 
 .. code-block:: xml
 
@@ -242,7 +242,7 @@ Nevertheless, it's much more interesting what you may see in the output xml file
      <id>mydata1234</id></MyData>
    </opencv_storage>
 
-Or the YAML file: 
+Or the YAML file:
 
 .. code-block:: yaml
 
index eba0cae..ef0f864 100644 (file)
@@ -4,9 +4,9 @@ How to scan images, lookup tables and time measurement with OpenCV
 *******************************************************************
 
 Goal
-==== 
+====
 
-We'll seek answers for the following questions: 
+We'll seek answers for the following questions:
 
 .. container:: enumeratevisibleitemswithsquare
 
@@ -18,11 +18,11 @@ We'll seek answers for the following questions:
 Our test case
 =============
 
-Let us consider a simple color reduction method. Using the unsigned char C and C++ type for matrix item storing a channel of pixel may have up to 256 different values. For a three channel image this can allow the formation of way too many colors (16 million to be exact). Working with so many color shades may give a heavy blow to our algorithm performance. However, sometimes it is enough to work with a lot less of them to get the same final result. 
+Let us consider a simple color reduction method. Using the unsigned char C and C++ type for matrix item storing a channel of pixel may have up to 256 different values. For a three channel image this can allow the formation of way too many colors (16 million to be exact). Working with so many color shades may give a heavy blow to our algorithm performance. However, sometimes it is enough to work with a lot less of them to get the same final result.
 
-In this cases it's common that we make a *color space reduction*. This means that we divide the color space current value with a new input value to end up with fewer colors. For instance every value between zero and nine takes the new value zero, every value between ten and nineteen the value ten and so on. 
+In this cases it's common that we make a *color space reduction*. This means that we divide the color space current value with a new input value to end up with fewer colors. For instance every value between zero and nine takes the new value zero, every value between ten and nineteen the value ten and so on.
 
-When you divide an *uchar* (unsigned char - aka values between zero and 255) value with an *int* value the result will be also *char*. These values may only be char values. Therefore, any fraction will be rounded down. Taking advantage of this fact the upper operation in the *uchar* domain may be expressed as: 
+When you divide an *uchar* (unsigned char - aka values between zero and 255) value with an *int* value the result will be also *char*. These values may only be char values. Therefore, any fraction will be rounded down. Taking advantage of this fact the upper operation in the *uchar* domain may be expressed as:
 
 .. math::
 
@@ -30,11 +30,11 @@ When you divide an *uchar* (unsigned char - aka values between zero and 255) val
 
 A simple color space reduction algorithm would consist of just passing through every pixel of an image matrix and applying this formula. It's worth noting that we do a divide and a multiplication operation. These operations are bloody expensive for a system. If possible it's worth avoiding them by using cheaper operations such as a few subtractions, addition or in best case a simple assignment. Furthermore, note that we only have a limited number of input values for the upper operation. In case of the *uchar* system this is 256 to be exact.
 
-Therefore, for larger images it would be wise to calculate all possible values beforehand and during the assignment just make the assignment, by using a lookup table. Lookup tables are simple arrays (having one or more dimensions) that for a given input value variation holds the final output value. Its strength lies that we do not need to make the calculation, we just need to read the result. 
+Therefore, for larger images it would be wise to calculate all possible values beforehand and during the assignment just make the assignment, by using a lookup table. Lookup tables are simple arrays (having one or more dimensions) that for a given input value variation holds the final output value. Its strength lies that we do not need to make the calculation, we just need to read the result.
 
-Our test case program (and the sample presented here) will do the following: read in a console line argument image (that may be either color or gray scale - console line argument too) and apply the reduction with the given console line argument integer value. In OpenCV, at the moment they are three major ways of going through an image pixel by pixel. To make things a little more interesting will make the scanning for each image using all of these methods, and print out how long it took. 
+Our test case program (and the sample presented here) will do the following: read in a console line argument image (that may be either color or gray scale - console line argument too) and apply the reduction with the given console line argument integer value. In OpenCV, at the moment they are three major ways of going through an image pixel by pixel. To make things a little more interesting will make the scanning for each image using all of these methods, and print out how long it took.
 
-You can download the full source code :download:`here <../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp>` or look it up in the samples directory of OpenCV at the cpp tutorial code for the core section. Its basic usage is: 
+You can download the full source code :download:`here <../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp>` or look it up in the samples directory of OpenCV at the cpp tutorial code for the core section. Its basic usage is:
 
 .. code-block:: bash
 
@@ -45,25 +45,25 @@ The final argument is optional. If given the image will be loaded in gray scale
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
    :language: cpp
    :tab-width: 4
-   :lines: 48-60 
+   :lines: 48-60
 
 Here we first use the C++ *stringstream* class to convert the third command line argument from text to an integer format. Then we use a simple look and the upper formula to calculate the lookup table. No OpenCV specific stuff here.
 
-Another issue is how do we measure time? Well OpenCV offers two simple functions to achieve this :UtilitySystemFunctions:`getTickCount() <gettickcount>` and :UtilitySystemFunctions:`getTickFrequency() <gettickfrequency>`. The first returns the number of ticks of your systems CPU from a certain event (like since you booted your system). The second returns how many times your CPU emits a tick during a second. So to measure in seconds the number of time elapsed between two operations is easy as: 
+Another issue is how do we measure time? Well OpenCV offers two simple functions to achieve this :UtilitySystemFunctions:`getTickCount() <gettickcount>` and :UtilitySystemFunctions:`getTickFrequency() <gettickfrequency>`. The first returns the number of ticks of your systems CPU from a certain event (like since you booted your system). The second returns how many times your CPU emits a tick during a second. So to measure in seconds the number of time elapsed between two operations is easy as:
 
 .. code-block:: cpp
 
    double t = (double)getTickCount();
    // do something ...
-   t = ((double)getTickCount() - t)/getTickFrequency(); 
+   t = ((double)getTickCount() - t)/getTickFrequency();
    cout << "Times passed in seconds: " << t << endl;
 
-.. _How_Image_Stored_Memory: 
+.. _How_Image_Stored_Memory:
 
 How the image matrix is stored in the memory?
 =============================================
 
-As you could already read in my :ref:`matTheBasicImageContainer` tutorial the size of the matrix depends of the color system used. More accurately, it depends from the number of channels used. In case of a gray scale image we have something like: 
+As you could already read in my :ref:`matTheBasicImageContainer` tutorial the size of the matrix depends of the color system used. More accurately, it depends from the number of channels used. In case of a gray scale image we have something like:
 
 .. math::
 
@@ -94,14 +94,14 @@ Note that the order of the channels is inverse: BGR instead of RGB. Because in m
 The efficient way
 =================
 
-When it comes to performance you cannot beat the classic C style operator[] (pointer) access. Therefore, the most efficient method we can recommend for making the assignment is: 
+When it comes to performance you cannot beat the classic C style operator[] (pointer) access. Therefore, the most efficient method we can recommend for making the assignment is:
 
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
    :language: cpp
    :tab-width: 4
    :lines: 125-152
 
-Here we basically just acquire a pointer to the start of each row and go through it until it ends. In the special case that the matrix is stored in a continues manner we only need to request the pointer a single time and go all the way to the end. We need to look out for color images: we have three channels so we need to pass through three times more items in each row. 
+Here we basically just acquire a pointer to the start of each row and go through it until it ends. In the special case that the matrix is stored in a continues manner we only need to request the pointer a single time and go all the way to the end. We need to look out for color images: we have three channels so we need to pass through three times more items in each row.
 
 There's another way of this. The *data* data member of a *Mat* object returns the pointer to the first row, first column. If this pointer is null you have no valid input in that object. Checking this is the simplest method to check if your image loading was a success. In case the storage is continues we can use this to go through the whole data pointer. In case of a gray scale image this would look like:
 
@@ -114,17 +114,17 @@ There's another way of this. The *data* data member of a *Mat* object returns th
 
 You would get the same result. However, this code is a lot harder to read later on. It gets even harder if you have some more advanced technique there. Moreover, in practice I've observed you'll get the same performance result (as most of the modern compilers will probably make this small optimization trick automatically for you).
 
-The iterator (safe) method 
+The iterator (safe) method
 ==========================
 
-In case of the efficient way making sure that you pass through the right amount of *uchar* fields and to skip the gaps that may occur between the rows was your responsibility. The iterator method is considered a safer way as it takes over these tasks from the user. All you need to do is ask the begin and the end of the image matrix and then just increase the begin iterator until you reach the end. To acquire the value *pointed* by the iterator use the * operator (add it before it). 
+In case of the efficient way making sure that you pass through the right amount of *uchar* fields and to skip the gaps that may occur between the rows was your responsibility. The iterator method is considered a safer way as it takes over these tasks from the user. All you need to do is ask the begin and the end of the image matrix and then just increase the begin iterator until you reach the end. To acquire the value *pointed* by the iterator use the * operator (add it before it).
 
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
    :language: cpp
    :tab-width: 4
    :lines: 154-182
 
-In case of color images we have three uchar items per column. This may be considered a short vector of uchar items, that has been baptized in OpenCV with the *Vec3b* name. To access the n-th sub column we use simple operator[] access. It's important to remember that OpenCV iterators go through the columns and automatically skip to the next row. Therefore in case of color images if you use a simple *uchar* iterator you'll be able to access only the blue channel values. 
+In case of color images we have three uchar items per column. This may be considered a short vector of uchar items, that has been baptized in OpenCV with the *Vec3b* name. To access the n-th sub column we use simple operator[] access. It's important to remember that OpenCV iterators go through the columns and automatically skip to the next row. Therefore in case of color images if you use a simple *uchar* iterator you'll be able to access only the blue channel values.
 
 On-the-fly address calculation with reference returning
 =======================================================
@@ -136,7 +136,7 @@ The final method isn't recommended for scanning. It was made to acquire or modif
    :tab-width: 4
    :lines: 184-216
 
-The functions takes your input type and coordinates and calculates on the fly the address of the queried item. Then returns a reference to that. This may be a constant when you *get* the value and non-constant when you *set* the value. As a safety step in **debug mode only*** there is performed a check that your input coordinates are valid and does exist. If this isn't the case you'll get a nice output message of this on the standard error output stream. Compared to the efficient way in release mode the only difference in using this is that for every element of the image you'll get a new row pointer for what we use the C operator[] to acquire the column element. 
+The functions takes your input type and coordinates and calculates on the fly the address of the queried item. Then returns a reference to that. This may be a constant when you *get* the value and non-constant when you *set* the value. As a safety step in **debug mode only*** there is performed a check that your input coordinates are valid and does exist. If this isn't the case you'll get a nice output message of this on the standard error output stream. Compared to the efficient way in release mode the only difference in using this is that for every element of the image you'll get a new row pointer for what we use the C operator[] to acquire the column element.
 
 If you need to multiple lookups using this method for an image it may be troublesome and time consuming to enter the type and the at keyword for each of the accesses. To solve this problem OpenCV has a :basicstructures:`Mat_ <id3>` data type. It's the same as Mat with the extra need that at definition you need to specify the data type through what to look at the data matrix, however in return you can use the operator() for fast access of items. To make things even better this is easily convertible from and to the usual :basicstructures:`Mat <id3>` data type. A sample usage of this you can see in case of the color images of the upper function. Nevertheless, it's important to note that the same operation (with the same runtime speed) could have been done with the :basicstructures:`at() <mat-at>` function. It's just a less to write for the lazy programmer trick.
 
index 938e504..9340a7c 100644 (file)
@@ -6,7 +6,7 @@ Interoperability with OpenCV 1
 Goal
 ====
 
-For the OpenCV developer team it's important to constantly improve the library. We are constantly thinking about methods that will ease your work process, while still maintain the libraries flexibility. The new C++ interface is a development of us that serves this goal. Nevertheless, backward compatibility remains important. We do not want to break your code written for earlier version of the OpenCV library. Therefore, we made sure that we add some functions that deal with this. In the following you'll learn: 
+For the OpenCV developer team it's important to constantly improve the library. We are constantly thinking about methods that will ease your work process, while still maintain the libraries flexibility. The new C++ interface is a development of us that serves this goal. Nevertheless, backward compatibility remains important. We do not want to break your code written for earlier version of the OpenCV library. Therefore, we made sure that we add some functions that deal with this. In the following you'll learn:
 
 .. container:: enumeratevisibleitemswithsquare
 
@@ -17,9 +17,9 @@ For the OpenCV developer team it's important to constantly improve the library.
 General
 =======
 
-When making the switch you first need to learn some about the new data structure for images: :ref:`matTheBasicImageContainer`, this replaces the old *CvMat* and *IplImage* ones. Switching to the new functions is easier. You just need to remember a couple of new things. 
+When making the switch you first need to learn some about the new data structure for images: :ref:`matTheBasicImageContainer`, this replaces the old *CvMat* and *IplImage* ones. Switching to the new functions is easier. You just need to remember a couple of new things.
 
-OpenCV 2 received reorganization. No longer are all the functions crammed into a single library. We have many modules, each of them containing data structures and functions relevant to certain tasks. This way you do not need to ship a large library if you use just a subset of OpenCV. This means that you should also include only those headers you will use. For example: 
+OpenCV 2 received reorganization. No longer are all the functions crammed into a single library. We have many modules, each of them containing data structures and functions relevant to certain tasks. This way you do not need to ship a large library if you use just a subset of OpenCV. This means that you should also include only those headers you will use. For example:
 
 .. code-block:: cpp
 
@@ -28,13 +28,13 @@ OpenCV 2 received reorganization. No longer are all the functions crammed into a
    #include <opencv2/highgui/highgui.hpp>
 
 
-All the OpenCV related stuff is put into the *cv* namespace to avoid name conflicts with other libraries data structures and functions. Therefore, either you need to prepend the *cv::* keyword before everything that comes from OpenCV or after the includes, you just add a directive to use this: 
+All the OpenCV related stuff is put into the *cv* namespace to avoid name conflicts with other libraries data structures and functions. Therefore, either you need to prepend the *cv::* keyword before everything that comes from OpenCV or after the includes, you just add a directive to use this:
 
 .. code-block:: cpp
 
    using namespace cv;  // The new C++ interface API is inside this namespace. Import it.
 
-Because the functions are already in a namespace there is no need for them to contain the *cv* prefix in their name. As such all the new C++ compatible functions don't have this and they follow the camel case naming rule. This means the first letter is small (unless it's a name, like Canny) and the subsequent words start with a capital letter (like *copyMakeBorder*). 
+Because the functions are already in a namespace there is no need for them to contain the *cv* prefix in their name. As such all the new C++ compatible functions don't have this and they follow the camel case naming rule. This means the first letter is small (unless it's a name, like Canny) and the subsequent words start with a capital letter (like *copyMakeBorder*).
 
 Now, remember that you need to link to your application all the modules you use, and in case you are on Windows using the *DLL* system you will need to add, again, to the path all the binaries. For more in-depth information if you're on Windows read :ref:`Windows_Visual_Studio_How_To` and for Linux an example usage is explained in :ref:`Linux_Eclipse_Usage`.
 
@@ -42,7 +42,7 @@ Now for converting the *Mat* object you can use either the *IplImage* or the *Cv
 
 .. code-block:: cpp
 
-   Mat I; 
+   Mat I;
    IplImage pI = I;
    CvMat    mI = I;
 
@@ -50,9 +50,9 @@ Now if you want pointers the conversion gets just a little more complicated. The
 
 .. code-block:: cpp
 
-   Mat I; 
-   IplImage* pI     = &I.operator IplImage(); 
-   CvMat* mI        =  &I.operator CvMat(); 
+   Mat I;
+   IplImage* pI     = &I.operator IplImage();
+   CvMat* mI        =  &I.operator CvMat();
 
 One of the biggest complaints of the C interface is that it leaves all the memory management to you. You need to figure out when it is safe to release your unused objects and make sure you do so before the program finishes or you could have troublesome memory leeks. To work around this issue in OpenCV there is introduced a sort of smart pointer. This will automatically release the object when it's no longer in use. To use this declare the pointers as a specialization of the *Ptr* :
 
@@ -60,11 +60,11 @@ One of the biggest complaints of the C interface is that it leaves all the memor
 
    Ptr<IplImage> piI = &I.operator IplImage();
 
-Converting from the C data structures to the *Mat* is done by passing these inside its constructor. For example: 
+Converting from the C data structures to the *Mat* is done by passing these inside its constructor. For example:
 
 .. code-block:: cpp
 
-   Mat K(piL), L; 
+   Mat K(piL), L;
    L = Mat(pI);
 
 A case study
@@ -79,7 +79,7 @@ Now that you have the basics done :download:`here's <../../../../samples/cpp/tut
    :tab-width: 4
    :lines: 1-9, 22-25, 27-44
 
-Here you can observe that with the new structure we have no pointer problems, although it is possible to use the old functions and in the end just transform the result to a *Mat* object. 
+Here you can observe that with the new structure we have no pointer problems, although it is possible to use the old functions and in the end just transform the result to a *Mat* object.
 
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp
    :language: cpp
@@ -87,7 +87,7 @@ Here you can observe that with the new structure we have no pointer problems, al
    :tab-width: 4
    :lines: 46-51
 
-Because, we want to mess around with the images luma component we first convert from the default RGB to the YUV color space and then split the result up into separate planes. Here the program splits: in the first example it processes each plane using one of the three major image scanning algorithms in OpenCV (C [] operator, iterator, individual element access). In a second variant we add to the image some Gaussian noise and then mix together the channels according to some formula. 
+Because, we want to mess around with the images luma component we first convert from the default RGB to the YUV color space and then split the result up into separate planes. Here the program splits: in the first example it processes each plane using one of the three major image scanning algorithms in OpenCV (C [] operator, iterator, individual element access). In a second variant we add to the image some Gaussian noise and then mix together the channels according to some formula.
 
 The scanning version looks like:
 
@@ -97,7 +97,7 @@ The scanning version looks like:
    :tab-width: 4
    :lines: 55-75
 
-Here you can observe that we may go through all the pixels of an image in three fashions: an iterator, a C pointer and an individual element access style. You can read a more in-depth description of these in the :ref:`howToScanImagesOpenCV` tutorial. Converting from the old function names is easy. Just remove the cv prefix and use the new *Mat* data structure. Here's an example of this by using the weighted addition function: 
+Here you can observe that we may go through all the pixels of an image in three fashions: an iterator, a C pointer and an individual element access style. You can read a more in-depth description of these in the :ref:`howToScanImagesOpenCV` tutorial. Converting from the old function names is easy. Just remove the cv prefix and use the new *Mat* data structure. Here's an example of this by using the weighted addition function:
 
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp
    :language: cpp
@@ -105,7 +105,7 @@ Here you can observe that we may go through all the pixels of an image in three
    :tab-width: 4
    :lines: 79-112
 
-As you may observe the *planes* variable is of type *Mat*. However, converting from *Mat* to *IplImage* is easy and made automatically with a simple assignment operator. 
+As you may observe the *planes* variable is of type *Mat*. However, converting from *Mat* to *IplImage* is easy and made automatically with a simple assignment operator.
 
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp
    :language: cpp
@@ -113,14 +113,14 @@ As you may observe the *planes* variable is of type *Mat*. However, converting f
    :tab-width: 4
    :lines: 115-127
 
-The new *imshow* highgui function accepts both the *Mat* and *IplImage* data structures. Compile and run the program and if the first image below is your input you may get either the first or second as output: 
+The new *imshow* highgui function accepts both the *Mat* and *IplImage* data structures. Compile and run the program and if the first image below is your input you may get either the first or second as output:
 
 .. image:: images/outputInteropOpenCV1.jpg
    :alt: The output of the sample
    :align: center
 
 
-You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=qckm-zvo31w>`_ and you can :download:`download the source code from here <../../../../samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp>` or find it in the :file:`samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp` of the OpenCV source code library. 
+You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=qckm-zvo31w>`_ and you can :download:`download the source code from here <../../../../samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp>` or find it in the :file:`samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp` of the OpenCV source code library.
 
 .. raw:: html
 
index f5bacbf..0549a9c 100644 (file)
@@ -8,11 +8,11 @@ Mask operations on matrices are quite simple. The idea is that we recalculate ea
 Our test case
 =============
 
-Let us consider the issue of an image contrast enhancement method. Basically we want to apply for every pixel of the image the following formula: 
+Let us consider the issue of an image contrast enhancement method. Basically we want to apply for every pixel of the image the following formula:
 
 .. math::
 
-   I(i,j) = 5*I(i,j) - [ I(i-1,j) + I(i+1,j) + I(i,j-1) + I(i,j+1)] 
+   I(i,j) = 5*I(i,j) - [ I(i-1,j) + I(i+1,j) + I(i,j-1) + I(i,j+1)]
 
    \iff I(i,j)*M, \text{where }
    M = \bordermatrix{ _i\backslash ^j  & -1 &  0 & +1 \cr
@@ -23,12 +23,12 @@ Let us consider the issue of an image contrast enhancement method. Basically we
 
 The first notation is by using a formula, while the second is a compacted version of the first by using a mask. You use the mask by putting the center of the mask matrix (in the upper case noted by the zero-zero index) on the pixel you want to calculate and sum up the pixel values multiplied with the overlapped matrix values. It's the same thing, however in case of large matrices the latter notation is a lot easier to look over.
 
-Now let us see how we can make this happen by using the basic pixel access method or by using the :filtering:`filter2D <filter2d>` function. 
+Now let us see how we can make this happen by using the basic pixel access method or by using the :filtering:`filter2D <filter2d>` function.
 
 The Basic Method
 ================
 
-Here's a function that will do this: 
+Here's a function that will do this:
 
 .. code-block:: cpp
 
@@ -49,7 +49,7 @@ Here's a function that will do this:
 
            for(int i= nChannels;i < nChannels*(myImage.cols-1); ++i)
            {
-               *output++ = saturate_cast<uchar>(5*current[i] 
+               *output++ = saturate_cast<uchar>(5*current[i]
                             -current[i-nChannels] - current[i+nChannels] - previous[i] - next[i]);
            }
        }
@@ -87,7 +87,7 @@ We'll use the plain C [] operator to access pixels. Because we need to access mu
 
        for(int i= nChannels;i < nChannels*(myImage.cols-1); ++i)
        {
-           *output++ = saturate_cast<uchar>(5*current[i] 
+           *output++ = saturate_cast<uchar>(5*current[i]
                         -current[i-nChannels] - current[i+nChannels] - previous[i] - next[i]);
        }
    }
@@ -96,7 +96,7 @@ On the borders of the image the upper notation results inexistent pixel location
 
 .. code-block:: cpp
 
-   Result.row(0).setTo(Scalar(0));             // The top row 
+   Result.row(0).setTo(Scalar(0));             // The top row
    Result.row(Result.rows-1).setTo(Scalar(0)); // The bottom row
    Result.col(0).setTo(Scalar(0));             // The left column
    Result.col(Result.cols-1).setTo(Scalar(0)); // The right column
@@ -108,19 +108,19 @@ Applying such filters are so common in image processing that in OpenCV there exi
 
 .. code-block:: cpp
 
-   Mat kern = (Mat_<char>(3,3) <<  0, -1,  0, 
+   Mat kern = (Mat_<char>(3,3) <<  0, -1,  0,
                                   -1,  5, -1,
                                    0, -1,  0);
 
-Then call the :filtering:`filter2D <filter2d>` function specifying the input, the output image and the kernell to use: 
+Then call the :filtering:`filter2D <filter2d>` function specifying the input, the output image and the kernell to use:
 
 .. code-block:: cpp
 
-   filter2D(I, K, I.depth(), kern ); 
+   filter2D(I, K, I.depth(), kern );
 
 The function even has a fifth optional argument to specify the center of the kernel, and a sixth one for determining what to do in the regions where the operation is undefined (borders). Using this function has the advantage that it's shorter, less verbose and because there are some optimization techniques implemented it is usually faster than the *hand-coded method*. For example in my test while the second one took only 13 milliseconds the first took around 31 milliseconds. Quite some difference.
 
-For example: 
+For example:
 
 .. image:: images/resultMatMaskFilter2D.png
    :alt: A sample output of the program
@@ -128,7 +128,7 @@ For example:
 
 You can download this source code from :download:`here <../../../../samples/cpp/tutorial_code/core/mat_mask_operations/mat_mask_operations.cpp>` or look in the OpenCV source code libraries sample directory at :file:`samples/cpp/tutorial_code/core/mat_mask_operations/mat_mask_operations.cpp`.
 
-Check out an instance of running the program on our `YouTube channel <http://www.youtube.com/watch?v=7PF1tAU9se4>`_ . 
+Check out an instance of running the program on our `YouTube channel <http://www.youtube.com/watch?v=7PF1tAU9se4>`_ .
 
 .. raw:: html
 
index 42fe58f..2797b22 100644 (file)
@@ -19,13 +19,13 @@ For example in the above image you can see that the mirror of the care is nothin
 
 OpenCV has been around ever since 2001. In those days the library was built around a *C* interface. In those days to store the image in the memory they used a C structure entitled *IplImage*. This is the one you'll see in most of the older tutorials and educational materials. The problem with this is that it brings to the table all the minuses of the C language. The biggest issue is the manual management. It builds on the assumption that the user is responsible for taking care of memory allocation and deallocation. While this is no issue in case of smaller programs once your code base start to grove larger and larger it will be more and more a struggle to handle all this rather than focusing on actually solving your development goal.
 
-Luckily C++ came around and introduced the concept of classes making possible to build another road for the user: automatic memory management (more or less). The good news is that C++ if fully compatible with C so no compatibility issues can arise from making the change. Therefore, OpenCV with its 2.0 version introduced a new C++ interface that by taking advantage of these offers a new way of doing things. A way, in which you do not need to fiddle with memory management; making your code concise (less to write, to achieve more). The only main downside of the C++ interface is that many embedded development systems at the moment support only C. Therefore, unless you are targeting this platform, there's no point on using the *old* methods (unless you're a masochist programmer and you're asking for trouble). 
+Luckily C++ came around and introduced the concept of classes making possible to build another road for the user: automatic memory management (more or less). The good news is that C++ if fully compatible with C so no compatibility issues can arise from making the change. Therefore, OpenCV with its 2.0 version introduced a new C++ interface that by taking advantage of these offers a new way of doing things. A way, in which you do not need to fiddle with memory management; making your code concise (less to write, to achieve more). The only main downside of the C++ interface is that many embedded development systems at the moment support only C. Therefore, unless you are targeting this platform, there's no point on using the *old* methods (unless you're a masochist programmer and you're asking for trouble).
 
 The first thing you need to know about *Mat* is that you no longer need to manually allocate its size and release it as soon as you do not need it. While doing this is still a possibility, most of the OpenCV functions will allocate its output data manually. As a nice bonus if you pass on an already existing *Mat* object, what already has allocated the required space for the matrix, this will be reused. In other words we use at all times only as much memory as much we must to perform the task.
 
 *Mat* is basically a class having two data parts: the matrix header (containing information such as the size of the matrix, the method used for storing, at which address is the matrix stored and so on) and a pointer to the matrix containing the pixel values (may take any dimensionality depending on the method chosen for storing) . The matrix header size is constant. However, the size of the matrix itself may vary from image to image and usually is larger by order of magnitudes. Therefore, when you're passing on images in your program and at some point you need to create a copy of the image the big price you will need to build is for the matrix itself rather than its header. OpenCV is an image processing library. It contains a large collection of image processing functions. To solve a computational challenge most of the time you will end up using multiple functions of the library. Due to this passing on images to functions is a common practice. We should not forget that we are talking about image processing algorithms, which tend to be quite computational heavy. The last thing we want to do is to further decrease the speed of your program by making unnecessary copies of potentially *large* images.
 
-To tackle this issue OpenCV uses a reference counting system. The idea is that each *Mat* object has its own header, however the matrix may be shared between two instance of them by having their matrix pointer point to the same address. Moreover, the copy operators **will only copy the headers**, and as also copy the pointer to the large matrix too, however not the matrix itself. 
+To tackle this issue OpenCV uses a reference counting system. The idea is that each *Mat* object has its own header, however the matrix may be shared between two instance of them by having their matrix pointer point to the same address. Moreover, the copy operators **will only copy the headers**, and as also copy the pointer to the large matrix too, however not the matrix itself.
 
 .. code-block:: cpp
    :linenos:
@@ -37,21 +37,21 @@ To tackle this issue OpenCV uses a reference counting system. The idea is that e
 
    C = A;                                    // Assignment operator
 
-All the above objects, in the end point to the same single data matrix. Their headers are different, however making any modification using either one of them will affect all the other ones too. In practice the different objects just provide different access method to the same underlying data. Nevertheless, their header parts are different. The real interesting part comes that you can create headers that refer only to a subsection of the full data. For example, to create a region of interest (*ROI*) in an image you just create a new header with the new boundaries: 
+All the above objects, in the end point to the same single data matrix. Their headers are different, however making any modification using either one of them will affect all the other ones too. In practice the different objects just provide different access method to the same underlying data. Nevertheless, their header parts are different. The real interesting part comes that you can create headers that refer only to a subsection of the full data. For example, to create a region of interest (*ROI*) in an image you just create a new header with the new boundaries:
 
 .. code-block:: cpp
    :linenos:
 
    Mat D (A, Rect(10, 10, 100, 100) ); // using a rectangle
-   Mat E = A(Range:all(), Range(1,3)); // using row and column boundaries 
+   Mat E = A(Range:all(), Range(1,3)); // using row and column boundaries
 
 Now you may ask if the matrix itself may belong to multiple *Mat* objects who will take responsibility for its cleaning when it's no longer needed. The short answer is: the last object that used it. For this a reference counting mechanism is used. Whenever somebody copies a header of a *Mat* object a counter is increased for the matrix. Whenever a header is cleaned this counter is decreased. When the counter reaches zero the matrix too is freed. Because, sometimes you will still want to copy the matrix itself too, there exists the :basicstructures:`clone() <mat-clone>` or the :basicstructures:`copyTo() <mat-copyto>` function.
 
 .. code-block:: cpp
    :linenos:
 
-   Mat F = A.clone(); 
-   Mat G; 
+   Mat F = A.clone();
+   Mat G;
    A.copyTo(G);
 
 Now modifying *F* or *G* will not affect the matrix pointed by the *Mat* header. What you need to remember from all this is that:
@@ -64,19 +64,19 @@ Now modifying *F* or *G* will not affect the matrix pointed by the *Mat* header.
    * Use the :basicstructures:`clone()<mat-clone>` or the :basicstructures:`copyTo() <mat-copyto>` function to copy the underlying matrix of an image.
 
 *Storing* methods
-================= 
+=================
 
-This is about how you store the pixel values. You can select the color space and the data type used. The color space refers to how we combine color components in order to code a given color. The simplest one is the gray scale. Here the colors at our disposal are black and white. The combination of these allows us to create many shades of gray. 
+This is about how you store the pixel values. You can select the color space and the data type used. The color space refers to how we combine color components in order to code a given color. The simplest one is the gray scale. Here the colors at our disposal are black and white. The combination of these allows us to create many shades of gray.
 
-For *colorful* ways we have a lot more of methods to choose from. However, every one of them breaks it down to three or four basic components and the combination of this will give all others. The most popular one of this is RGB, mainly because this is also how our eye builds up colors in our eyes. Its base colors are red, green and blue. To code the transparency of a color sometimes a fourth element: alpha (A) is added. 
+For *colorful* ways we have a lot more of methods to choose from. However, every one of them breaks it down to three or four basic components and the combination of this will give all others. The most popular one of this is RGB, mainly because this is also how our eye builds up colors in our eyes. Its base colors are red, green and blue. To code the transparency of a color sometimes a fourth element: alpha (A) is added.
 
 However, they are many color systems each with their own advantages:
 
 .. container:: enumeratevisibleitemswithsquare
 
    * RGB is the most common as our eyes use something similar, our display systems also compose colors using these.
-   * The HSV and HLS decompose colors into their hue, saturation and value/luminance components, which is a more natural way for us to describe colors. Using you may for example dismiss the last component, making your algorithm less sensible to light conditions of the input image. 
-   * YCrCb is used by the popular JPEG image format. 
+   * The HSV and HLS decompose colors into their hue, saturation and value/luminance components, which is a more natural way for us to describe colors. Using you may for example dismiss the last component, making your algorithm less sensible to light conditions of the input image.
+   * YCrCb is used by the popular JPEG image format.
    * CIE L*a*b* is a perceptually uniform color space, which comes handy if you need to measure the *distance* of a given color to another color.
 
 Now each of the building components has their own valid domains. This leads to the data type used. How we store a component defines just how fine control we have over its domain. The smallest data type possible is *char*, which means one byte or 8 bits. This may be unsigned (so can store values from 0 to 255) or signed (values from -127 to +127). Although in case of three components this already gives 16 million possible colors to represent (like in case of RGB) we may acquire an even finer control by using the float (4 byte = 32 bit) or double (8 byte = 64 bit) data types for each component. Nevertheless, remember that increasing the size of a component also increases the size of the whole picture in the memory.
@@ -84,13 +84,13 @@ Now each of the building components has their own valid domains. This leads to t
 Creating explicitly a *Mat* object
 ==================================
 
-In the :ref:`Load_Save_Image` tutorial you could already see how to write a matrix to an image file by using the :readWriteImageVideo:` imwrite() <imwrite>` function. However, for debugging purposes it's much more convenient to see the actual values. You can achieve this via the << operator of *Mat*. However, be aware that this only works for two dimensional matrices. 
+In the :ref:`Load_Save_Image` tutorial you could already see how to write a matrix to an image file by using the :readWriteImageVideo:` imwrite() <imwrite>` function. However, for debugging purposes it's much more convenient to see the actual values. You can achieve this via the << operator of *Mat*. However, be aware that this only works for two dimensional matrices.
 
 Although *Mat* is a great class as image container it is also a general matrix class. Therefore, it is possible to create and manipulate multidimensional matrices. You can create a Mat object in multiple ways:
 
 .. container:: enumeratevisibleitemswithsquare
 
-   + :basicstructures:`Mat() <mat-mat>` Constructor 
+   + :basicstructures:`Mat() <mat-mat>` Constructor
 
      .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
         :language: cpp
@@ -103,7 +103,7 @@ Although *Mat* is a great class as image container it is also a general matrix c
 
     For two dimensional and multichannel images we first define their size: row and column count wise.
 
-    Then we need to specify the data type to use for storing the elements and the number of channels per matrix point. To do this we have multiple definitions made according to the following convention: 
+    Then we need to specify the data type to use for storing the elements and the number of channels per matrix point. To do this we have multiple definitions made according to the following convention:
 
     .. code-block:: cpp
 
@@ -118,7 +118,7 @@ Although *Mat* is a great class as image container it is also a general matrix c
         :tab-width: 4
         :lines:  35-36
 
-     The upper example shows how to create a matrix with more than two dimensions. Specify its dimension, then pass a pointer containing the size for each dimension and the rest remains the same.      
+     The upper example shows how to create a matrix with more than two dimensions. Specify its dimension, then pass a pointer containing the size for each dimension and the rest remains the same.
 
 
    + Create a header for an already existing IplImage pointer:
@@ -174,7 +174,7 @@ Although *Mat* is a great class as image container it is also a general matrix c
         :alt: Demo image of the matrix output
         :align: center
 
-.. note:: 
+.. note::
 
    You can fill out a matrix with random values using the :operationsOnArrays:`randu() <randu>` function. You need to give the lower and upper value between what you want the random values:
 
@@ -187,11 +187,11 @@ Although *Mat* is a great class as image container it is also a general matrix c
 Print out formatting
 ====================
 
-In the above examples you could see the default formatting option. Nevertheless, OpenCV allows you to format your matrix output format to fit the rules of: 
+In the above examples you could see the default formatting option. Nevertheless, OpenCV allows you to format your matrix output format to fit the rules of:
 
 .. container:: enumeratevisibleitemswithsquare
 
-   + Default 
+   + Default
 
      .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
        :language: cpp
@@ -213,7 +213,7 @@ In the above examples you could see the default formatting option. Nevertheless,
         :alt: Default Output
         :align: center
 
-   + Comma separated values (CSV) 
+   + Comma separated values (CSV)
 
      .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
        :language: cpp
@@ -253,7 +253,7 @@ OpenCV offers support for print of other common OpenCV data structures too via t
 
 .. container:: enumeratevisibleitemswithsquare
 
-   + 2D Point 
+   + 2D Point
 
      .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
        :language: cpp
index ddd8ef2..b50d976 100644 (file)
@@ -44,7 +44,7 @@ Here you will learn the about the basic building blocks of the library. A must r
   .. |HowScanImag| image:: images/howToScanImages.jpg
                    :height: 90pt
                    :width:  90pt
-                   
+
 
 +
   .. tabularcolumns:: m{100pt} m{300pt}
@@ -193,7 +193,7 @@ Here you will learn the about the basic building blocks of the library. A must r
                   *Author:* |Author_BernatG|
 
                   Did you used OpenCV before its 2.0 version? Do you wanna know what happened with your library with 2.0? Don't you know how to convert your old OpenCV programs to the new C++ interface? Look here to shed light on all this questions.
-                  
+
   =============== ======================================================
 
   .. |InterOOpenCV1| image:: images/interopOpenCV1.png
@@ -208,7 +208,7 @@ Here you will learn the about the basic building blocks of the library. A must r
 
 .. toctree::
    :hidden:
-   
+
    ../mat_the_basic_image_container/mat_the_basic_image_container
    ../how_to_scan_images/how_to_scan_images
    ../mat-mask-operations/mat-mask-operations
index 35f9b2a..ded9e78 100644 (file)
@@ -1,3 +1,3 @@
 
 .. note::
-   Unfortunetly we have no tutorials into this section. Nevertheless, our tutorial writting team is working on it. If you have a tutorial suggestion or you have writen yourself a tutorial (or coded a sample code) that you would like to see here please contact us via our :opencv_group:`user group <>`. 
\ No newline at end of file
+   Unfortunetly we have no tutorials into this section. Nevertheless, our tutorial writting team is working on it. If you have a tutorial suggestion or you have writen yourself a tutorial (or coded a sample code) that you would like to see here please contact us via our :opencv_group:`user group <>`.
\ No newline at end of file
index 58bfca4..9c8e03b 100644 (file)
@@ -3,8 +3,8 @@
 .. |Author_AndreyK| unicode:: Andrey U+0020 Kamaev
 .. |Author_LeonidBLB| unicode:: Leonid U+0020 Beynenson
 .. |Author_VsevolodG| unicode:: Vsevolod U+0020 Glumov
-.. |Author_VictorE| unicode:: Victor U+0020 Eruhimov 
-.. |Author_ArtemM| unicode:: Artem U+0020 Myagkov 
-.. |Author_FernandoI| unicode:: Fernando U+0020 Iglesias U+0020 Garc U+00ED a 
+.. |Author_VictorE| unicode:: Victor U+0020 Eruhimov
+.. |Author_ArtemM| unicode:: Artem U+0020 Myagkov
+.. |Author_FernandoI| unicode:: Fernando U+0020 Iglesias U+0020 Garc U+00ED a
 .. |Author_EduardF| unicode:: Eduard U+0020 Feicho
 
index 48d93ce..009d537 100644 (file)
@@ -5,9 +5,9 @@ Detection of planar objects
 
 .. highlight:: cpp
 
-The goal of this tutorial is to learn how to use *features2d* and *calib3d* modules for detecting known planar objects in scenes. 
+The goal of this tutorial is to learn how to use *features2d* and *calib3d* modules for detecting known planar objects in scenes.
 
-*Test data*: use images in your data folder, for instance, ``box.png`` and ``box_in_scene.png``. 
+*Test data*: use images in your data folder, for instance, ``box.png`` and ``box_in_scene.png``.
 
 #.
     Create a new console project. Read two input images. ::
@@ -22,7 +22,7 @@ The goal of this tutorial is to learn how to use *features2d* and *calib3d* modu
         FastFeatureDetector detector(15);
         vector<KeyPoint> keypoints1;
         detector.detect(img1, keypoints1);
-        
+
         ... // do the same for the second image
 
 #.
@@ -32,7 +32,7 @@ The goal of this tutorial is to learn how to use *features2d* and *calib3d* modu
         SurfDescriptorExtractor extractor;
         Mat descriptors1;
         extractor.compute(img1, keypoints1, descriptors1);
-        
+
         ... // process keypoints from the second image as well
 
 #.
@@ -69,4 +69,4 @@ The goal of this tutorial is to learn how to use *features2d* and *calib3d* modu
         perspectiveTransform(Mat(points1), points1Projected, H);
 
 #.
-    Use ``drawMatches`` for drawing inliers. 
+    Use ``drawMatches`` for drawing inliers.
index be0f515..cc90082 100644 (file)
 
 Learn about how to use the feature points  detectors, descriptors and matching framework found inside OpenCV.
 
-.. include:: ../../definitions/tocDefinitions.rst 
+.. include:: ../../definitions/tocDefinitions.rst
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
   ===================== ==============================================
    |Harris|             **Title:** :ref:`harris_detector`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-                        
+
                         Why is it a good idea to track corners? We learn to use the Harris method to detect corners
-  
+
   ===================== ==============================================
-  
+
   .. |Harris| image:: images/trackingmotion/Harris_Detector_Cover.jpg
                    :height: 90pt
                    :width:  90pt
-  
 
-+ 
+
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
   ===================== ==============================================
    |ShiTomasi|          **Title:** :ref:`good_features_to_track`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-                        
+
                         Where we use an improved method to detect corners more accuratelyI
-  
+
   ===================== ==============================================
-  
+
   .. |ShiTomasi| image:: images/trackingmotion/Shi_Tomasi_Detector_Cover.jpg
                       :height: 90pt
                       :width:  90pt
 
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
   ===================== ==============================================
    |GenericCorner|      **Title:** :ref:`generic_corner_detector`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-                        
+
                         Here you will learn how to use OpenCV functions to make your personalized corner detector!
-  
+
   ===================== ==============================================
-  
+
   .. |GenericCorner| image:: images/trackingmotion/Generic_Corner_Detector_Cover.jpg
                           :height: 90pt
                           :width:  90pt
 
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
   ===================== ==============================================
    |Subpixel|           **Title:** :ref:`corner_subpixeles`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-                        
+
                         Is pixel resolution enough? Here we learn a simple method to improve our accuracy.
-  
+
   ===================== ==============================================
-  
+
   .. |Subpixel| image:: images/trackingmotion/Corner_Subpixeles_Cover.jpg
                      :height: 90pt
                      :width:  90pt
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
   ===================== ==============================================
    |FeatureDetect|      **Title:** :ref:`feature_detection`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-                        
+
                         In this tutorial, you will use *features2d* to detect interest points.
-  
+
   ===================== ==============================================
-  
+
   .. |FeatureDetect| image:: images/Feature_Detection_Tutorial_Cover.jpg
                      :height: 90pt
                      :width:  90pt
 
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
   ===================== ==============================================
    |FeatureDescript|    **Title:** :ref:`feature_description`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-                        
+
                         In this tutorial, you will use *features2d* to calculate feature vectors.
-  
+
   ===================== ==============================================
-  
+
   .. |FeatureDescript| image:: images/Feature_Description_Tutorial_Cover.jpg
                        :height: 90pt
                        :width:  90pt
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
   ===================== ==============================================
    |FeatureFlann|       **Title:** :ref:`feature_flann_matcher`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-                        
+
                         In this tutorial, you will use the FLANN library to make a fast matching.
-  
+
   ===================== ==============================================
-  
+
   .. |FeatureFlann| image:: images/Feature_Flann_Matcher_Tutorial_Cover.jpg
                     :height: 90pt
                     :width:  90pt
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
   ===================== ==============================================
    |FeatureHomo|        **Title:** :ref:`feature_homography`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-                        
+
                         In this tutorial, you will use *features2d* and *calib3d* to detect an object in a scene.
-  
+
   ===================== ==============================================
-  
+
   .. |FeatureHomo| image:: images/Feature_Homography_Tutorial_Cover.jpg
                    :height: 90pt
                    :width:  90pt
 
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
@@ -175,7 +175,7 @@ Learn about how to use the feature points  detectors, descriptors and matching f
 
                         *Author:* |Author_VictorE|
 
-                        You will use *features2d* and *calib3d* modules for detecting known planar objects in scenes. 
+                        You will use *features2d* and *calib3d* modules for detecting known planar objects in scenes.
 
   ===================== ==============================================
 
index 1b405e4..afb74f2 100644 (file)
@@ -87,14 +87,14 @@ This tutorial code's is shown lines below. You can also download it from `here <
 
      /// Apply corner detection
      goodFeaturesToTrack( src_gray,
-                         corners,
-                         maxCorners,
-                         qualityLevel,
-                         minDistance,
-                         Mat(),
-                         blockSize,
-                         useHarrisDetector,
-                         k );
+                  corners,
+                  maxCorners,
+                  qualityLevel,
+                  minDistance,
+                  Mat(),
+                  blockSize,
+                  useHarrisDetector,
+                  k );
 
 
      /// Draw corners detected
index cb96507..05025cc 100644 (file)
@@ -98,16 +98,16 @@ How does it work?
                         u & v
                        \end{bmatrix}
                        \left (
-                      \displaystyle \sum_{x,y}
+               \displaystyle \sum_{x,y}
                        w(x,y)
                        \begin{bmatrix}
                         I_x^{2} & I_{x}I_{y} \\
                         I_xI_{y} & I_{y}^{2}
-                      \end{bmatrix}
-                      \right )
-                      \begin{bmatrix}
+               \end{bmatrix}
+               \right )
+               \begin{bmatrix}
                         u \\
-                       v
+            v
                        \end{bmatrix}
 
    * Let's denote:
@@ -115,11 +115,11 @@ How does it work?
      .. math::
 
         M = \displaystyle \sum_{x,y}
-                             w(x,y)
-                             \begin{bmatrix}
-                               I_x^{2} & I_{x}I_{y} \\
-                               I_xI_{y} & I_{y}^{2}
-                              \end{bmatrix}
+                  w(x,y)
+                  \begin{bmatrix}
+                            I_x^{2} & I_{x}I_{y} \\
+                            I_xI_{y} & I_{y}^{2}
+                       \end{bmatrix}
 
    * So, our equation now is:
 
@@ -128,10 +128,10 @@ How does it work?
         E(u,v) \approx \begin{bmatrix}
                         u & v
                        \end{bmatrix}
-                      M
-                      \begin{bmatrix}
+               M
+               \begin{bmatrix}
                         u \\
-                       v
+            v
                        \end{bmatrix}
 
 
index 04ce2b2..cc59084 100644 (file)
@@ -1 +1 @@
-.. _gpuBasicsSimilarity:\r\rSimilarity check (PNSR and SSIM) on the GPU\r*******************************************\r\rGoal\r====\r\rIn the :ref:`videoInputPSNRMSSIM` tutorial I already presented the PSNR and SSIM methods for checking the similarity between the two images. And as you could see there performing these takes quite some time, especially in the case of the SSIM. However, if the performance numbers of an OpenCV implementation for the CPU do not satisfy you and you happen to have an NVidia CUDA GPU device in your system all is not lost. You may try to port or write your algorithm for the video card. \r\rThis tutorial will give a good grasp on how to approach coding by using the GPU module of OpenCV. As a prerequisite you should already know how to handle the core, highgui and imgproc modules. So, our goals are: \r\r.. container:: enumeratevisibleitemswithsquare\r\r   + What's different compared to the CPU?\r   + Create the GPU code for the PSNR and SSIM \r   + Optimize the code for maximal performance\r\rThe source code\r===============\r\rYou may also find the source code and these video file in the :file:`samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity` folder of the OpenCV source library or :download:`download it from here <../../../../samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp>`. The full source code is quite long (due to the controlling of the application via the command line arguments and performance measurement). Therefore, to avoid cluttering up these sections with those you'll find here only the functions itself. \r\rThe PSNR returns a float number, that if the two inputs are similar between 30 and 50 (higher is better). \r\r.. literalinclude:: ../../../../samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp\r   :language: cpp\r   :linenos:\r   :tab-width: 4\r   :lines: 165-210, 18-23, 210-235\r\rThe SSIM returns the MSSIM of the images. This is too a float number between zero and one (higher is better), however we have one for each channel. Therefore, we return a *Scalar* OpenCV data structure:\r\r.. literalinclude:: ../../../../samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp\r   :language: cpp\r   :linenos:\r   :tab-width: 4\r   :lines: 235-355, 26-42, 357-\r\rHow to do it? - The GPU\r=======================\r\rNow as you can see we have three types of functions for each operation. One for the CPU and two for the GPU. The reason I made two for the GPU is too illustrate that often simple porting your CPU to GPU will actually make it slower. If you want some performance gain you will need to remember a few rules, whose I'm going to detail later on.\r\rThe development of the GPU module was made so that it resembles as much as possible its CPU counterpart. This is to make porting easy. The first thing you need to do before writing any code is to link the GPU module to your project, and include the header file for the module. All the functions and data structures of the GPU are in a *gpu* sub namespace of the *cv* namespace. You may add this to the default one via the *use namespace* keyword, or mark it everywhere explicitly via the cv:: to avoid confusion. I'll do the later. \r\r.. code-block:: cpp\r\r   #include <opencv2/gpu/gpu.hpp>        // GPU structures and methods\r\rGPU stands for **g**\ raphics **p**\ rocessing **u**\ nit. It was originally build to render graphical scenes. These scenes somehow build on a lot of data. Nevertheless, these aren't all dependent one from another in a sequential way and as it is possible a parallel processing of them. Due to this a GPU will contain multiple smaller processing units. These aren't the state of the art processors and on a one on one test with a CPU it will fall behind. However, its strength lies in its numbers. In the last years there has been an increasing trend to harvest these massive parallel powers of the GPU in non-graphical scene rendering too. This gave birth to the general-purpose computation on graphics processing units (GPGPU). \r\rThe GPU has its own memory. When you read data from the hard drive with OpenCV into a *Mat* object that takes place in your systems memory. The CPU works somehow directly on this (via its cache), however the GPU cannot. He has too transferred the information he will use for calculations from the system memory to its own. This is done via an upload process and takes time. In the end the result will have to be downloaded back to your system memory for your CPU to see it and use it. Porting small functions to GPU is not recommended as the upload/download time will be larger than the amount you gain by a parallel execution. \r\r*Mat* objects are stored **only** in the system memory (or the CPU cache). For getting an OpenCV matrix to the GPU you'll need to use its GPU counterpart :gpudatastructure:`GpuMat <gpu-gpumat>`. It works similar to the *Mat* with a 2D only limitation and no reference returning for its functions (cannot mix GPU references with CPU ones). To upload a *Mat* object to the *GPU* you need to call the *upload* function after creating an instance of the class. To download you may use simple assignment to a *Mat* object or use the *download* function.\r\r.. code-block:: cpp \r\r   Mat I1;         // Main memory item - read image into with imread for example\r   gpu::GpuMat gI; // GPU matrix - for now empty\r   gI1.upload(I1); // Upload a data from the system memory to the GPU memory\r\r   I1 = gI1;       // Download, gI1.download(I1) will work too\r\rOnce you have your data up in the GPU memory you may call GPU enabled functions of OpenCV. Most of the functions keep the same name just as on the CPU, with the difference that they only accept *GpuMat* inputs. A full list of these you will find in the documentation: `online here <http://opencv.itseez.com/modules/gpu/doc/gpu.html>`_ or the OpenCV reference manual that comes with the source code.\r\rAnother thing to keep in mind is that not for all channel numbers you can make efficient algorithms on the GPU. Generally, I found that the input images for the GPU images need to be either one or four channel ones and one of the char or float type for the item sizes. No double support on the GPU, sorry. Passing other types of objects for some functions will result in an exception thrown, and an error message on the error output. The documentation details in most of the places the types accepted for the inputs. If you have three channel images as an input you can do two things: either adds a new channel (and use char elements) or split up the image and call the function for each image. The first one isn't really recommended as you waste memory. \r\rFor some functions, where the position of the elements (neighbor items) doesn't matter quick solution is to just reshape it into a single channel image. This is the case for the PSNR implementation where for the *absdiff* method the value of the neighbors is not important. However, for the *GaussianBlur* this isn't an option and such need to use the split method for the SSIM. With this knowledge you can already make a GPU viable code (like mine GPU one) and run it. You'll be surprised to see that it might turn out slower than your CPU implementation. \r\rOptimization\r============\r\rThe reason for this is that you're throwing out on the window the price for memory allocation and data transfer. And on the GPU this is damn high. Another possibility for optimization is to introduce asynchronous OpenCV GPU calls too with the help of the :gpudatastructure:`gpu::Stream <gpu-stream>`. \r\r1. Memory allocation on the GPU is considerable. Therefore, if it’s possible allocate new memory as few times as possible. If you create a function what you intend to call multiple times it is a good idea to allocate any local parameters for the function only once, during the first call. To do this you create a data structure containing all the local variables you will use. For instance in case of the PSNR these are: \r\r   .. code-block:: cpp \r\r      struct BufferPSNR                                     // Optimized GPU versions\r        {   // Data allocations are very expensive on GPU. Use a buffer to solve: allocate once reuse later.\r        gpu::GpuMat gI1, gI2, gs, t1,t2;\r\r        gpu::GpuMat buf;\r      };\r\r   Then create an instance of this in the main program: \r\r   .. code-block:: cpp\r\r      BufferPSNR bufferPSNR;\r\r   And finally pass this to the function each time you call it: \r\r   .. code-block:: cpp\r\r      double getPSNR_GPU_optimized(const Mat& I1, const Mat& I2, BufferPSNR& b)\r\r   Now you access these local parameters as: *b.gI1*, *b.buf* and so on. The GpuMat will only reallocate itself on a new call if the new matrix size is different from the previous one. \r\r#. Avoid unnecessary function data transfers. Any small data transfer will be significant one once you go to the GPU. Therefore, if possible make all calculations in-place (in other words do not create new memory objects - for reasons explained at the previous point). For example, although expressing arithmetical operations may be easier to express in one line formulas, it will be slower. In case of the SSIM at one point I need to calculate:\r\r   .. code-block:: cpp \r\r      b.t1 = 2 * b.mu1_mu2 + C1;  \r\r   Although the upper call will succeed observe that there is a hidden data transfer present. Before it makes the addition it needs to store somewhere the multiplication. Therefore, it will create a local matrix in the background, add to that the *C1* value and finally assign that to *t1*. To avoid this we use the gpu functions, instead of the arithmetic operators: \r\r   .. code-block:: cpp\r\r      gpu::multiply(b.mu1_mu2, 2, b.t1); //b.t1 = 2 * b.mu1_mu2 + C1; \r      gpu::add(b.t1, C1, b.t1);\r\r#. Use asynchronous calls (the :gpudatastructure:`gpu::Stream <gpu-stream>`). By default whenever you call a gpu function it will wait for the call to finish and return with the result afterwards. However, it is possible to make asynchronous calls, meaning it will call for the operation execution, make the costly data allocations for the algorithm and return back right away. Now you can call another function if you wish to do so. For the MSSIM this is a small optimization point. In our default implementation we split up the image into channels and call then for each channel the gpu functions. A small degree of parallelization is possible with the stream. By using a stream we can make the data allocation, upload operations while the GPU is already executing a given method. For example we need to upload two images. We queue these one after another and call already the function that processes it. The functions will wait for the upload to finish, however while that happens makes the output buffer allocations for the function to be executed next. \r\r   .. code-block:: cpp \r\r      gpu::Stream stream;\r\r      stream.enqueueConvert(b.gI1, b.t1, CV_32F);    // Upload\r\r      gpu::split(b.t1, b.vI1, stream);              // Methods (pass the stream as final parameter).\r      gpu::multiply(b.vI1[i], b.vI1[i], b.I1_2, stream);        // I1^2\r\rResult and conclusion\r=====================\r\rOn an Intel P8700 laptop CPU paired with a low end NVidia GT220M here are the performance numbers: \r\r.. code-block:: cpp\r\r   Time of PSNR CPU (averaged for 10 runs): 41.4122 milliseconds. With result of: 19.2506\r   Time of PSNR GPU (averaged for 10 runs): 158.977 milliseconds. With result of: 19.2506\r   Initial call GPU optimized:              31.3418 milliseconds. With result of: 19.2506\r   Time of PSNR GPU OPTIMIZED ( / 10 runs): 24.8171 milliseconds. With result of: 19.2506\r\r   Time of MSSIM CPU (averaged for 10 runs): 484.343 milliseconds. With result of B0.890964 G0.903845 R0.936934\r   Time of MSSIM GPU (averaged for 10 runs): 745.105 milliseconds. With result of B0.89922 G0.909051 R0.968223\r   Time of MSSIM GPU Initial Call            357.746 milliseconds. With result of B0.890964 G0.903845 R0.936934\r   Time of MSSIM GPU OPTIMIZED ( / 10 runs): 203.091 milliseconds. With result of B0.890964 G0.903845 R0.936934\r\rIn both cases we managed a performance increase of almost 100% compared to the CPU implementation. It may be just the improvement needed for your application to work. You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=3_ESXmFlnvY>`_. \r\r.. raw:: html\r\r  <div align="center">\r  <iframe title="Similarity check (PNSR and SSIM) on the GPU" width="560" height="349" src="http://www.youtube.com/embed/3_ESXmFlnvY?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>\r  </div>\r
\ No newline at end of file
+.. _gpuBasicsSimilarity:\r\rSimilarity check (PNSR and SSIM) on the GPU\r*******************************************\r\rGoal\r====\r\rIn the :ref:`videoInputPSNRMSSIM` tutorial I already presented the PSNR and SSIM methods for checking the similarity between the two images. And as you could see there performing these takes quite some time, especially in the case of the SSIM. However, if the performance numbers of an OpenCV implementation for the CPU do not satisfy you and you happen to have an NVidia CUDA GPU device in your system all is not lost. You may try to port or write your algorithm for the video card. \r\rThis tutorial will give a good grasp on how to approach coding by using the GPU module of OpenCV. As a prerequisite you should already know how to handle the core, highgui and imgproc modules. So, our goals are: \r\r.. container:: enumeratevisibleitemswithsquare\r\r   + What's different compared to the CPU?\r   + Create the GPU code for the PSNR and SSIM \r   + Optimize the code for maximal performance\r\rThe source code\r===============\r\rYou may also find the source code and these video file in the :file:`samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity` folder of the OpenCV source library or :download:`download it from here <../../../../samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp>`. The full source code is quite long (due to the controlling of the application via the command line arguments and performance measurement). Therefore, to avoid cluttering up these sections with those you'll find here only the functions itself. \r\rThe PSNR returns a float number, that if the two inputs are similar between 30 and 50 (higher is better). \r\r.. literalinclude:: ../../../../samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp\r   :language: cpp\r   :linenos:\r   :tab-width: 4\r   :lines: 165-210, 18-23, 210-235\r\rThe SSIM returns the MSSIM of the images. This is too a float number between zero and one (higher is better), however we have one for each channel. Therefore, we return a *Scalar* OpenCV data structure:\r\r.. literalinclude:: ../../../../samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp\r   :language: cpp\r   :linenos:\r   :tab-width: 4\r   :lines: 235-355, 26-42, 357-\r\rHow to do it? - The GPU\r=======================\r\rNow as you can see we have three types of functions for each operation. One for the CPU and two for the GPU. The reason I made two for the GPU is too illustrate that often simple porting your CPU to GPU will actually make it slower. If you want some performance gain you will need to remember a few rules, whose I'm going to detail later on.\r\rThe development of the GPU module was made so that it resembles as much as possible its CPU counterpart. This is to make porting easy. The first thing you need to do before writing any code is to link the GPU module to your project, and include the header file for the module. All the functions and data structures of the GPU are in a *gpu* sub namespace of the *cv* namespace. You may add this to the default one via the *use namespace* keyword, or mark it everywhere explicitly via the cv:: to avoid confusion. I'll do the later. \r\r.. code-block:: cpp\r\r   #include <opencv2/gpu/gpu.hpp>        // GPU structures and methods\r\rGPU stands for **g**\ raphics **p**\ rocessing **u**\ nit. It was originally build to render graphical scenes. These scenes somehow build on a lot of data. Nevertheless, these aren't all dependent one from another in a sequential way and as it is possible a parallel processing of them. Due to this a GPU will contain multiple smaller processing units. These aren't the state of the art processors and on a one on one test with a CPU it will fall behind. However, its strength lies in its numbers. In the last years there has been an increasing trend to harvest these massive parallel powers of the GPU in non-graphical scene rendering too. This gave birth to the general-purpose computation on graphics processing units (GPGPU). \r\rThe GPU has its own memory. When you read data from the hard drive with OpenCV into a *Mat* object that takes place in your systems memory. The CPU works somehow directly on this (via its cache), however the GPU cannot. He has too transferred the information he will use for calculations from the system memory to its own. This is done via an upload process and takes time. In the end the result will have to be downloaded back to your system memory for your CPU to see it and use it. Porting small functions to GPU is not recommended as the upload/download time will be larger than the amount you gain by a parallel execution. \r\r*Mat* objects are stored **only** in the system memory (or the CPU cache). For getting an OpenCV matrix to the GPU you'll need to use its GPU counterpart :gpudatastructure:`GpuMat <gpu-gpumat>`. It works similar to the *Mat* with a 2D only limitation and no reference returning for its functions (cannot mix GPU references with CPU ones). To upload a *Mat* object to the *GPU* you need to call the *upload* function after creating an instance of the class. To download you may use simple assignment to a *Mat* object or use the *download* function.\r\r.. code-block:: cpp \r\r   Mat I1;         // Main memory item - read image into with imread for example\r   gpu::GpuMat gI; // GPU matrix - for now empty\r   gI1.upload(I1); // Upload a data from the system memory to the GPU memory\r\r   I1 = gI1;       // Download, gI1.download(I1) will work too\r\rOnce you have your data up in the GPU memory you may call GPU enabled functions of OpenCV. Most of the functions keep the same name just as on the CPU, with the difference that they only accept *GpuMat* inputs. A full list of these you will find in the documentation: `online here <http://opencv.itseez.com/modules/gpu/doc/gpu.html>`_ or the OpenCV reference manual that comes with the source code.\r\rAnother thing to keep in mind is that not for all channel numbers you can make efficient algorithms on the GPU. Generally, I found that the input images for the GPU images need to be either one or four channel ones and one of the char or float type for the item sizes. No double support on the GPU, sorry. Passing other types of objects for some functions will result in an exception thrown, and an error message on the error output. The documentation details in most of the places the types accepted for the inputs. If you have three channel images as an input you can do two things: either adds a new channel (and use char elements) or split up the image and call the function for each image. The first one isn't really recommended as you waste memory. \r\rFor some functions, where the position of the elements (neighbor items) doesn't matter quick solution is to just reshape it into a single channel image. This is the case for the PSNR implementation where for the *absdiff* method the value of the neighbors is not important. However, for the *GaussianBlur* this isn't an option and such need to use the split method for the SSIM. With this knowledge you can already make a GPU viable code (like mine GPU one) and run it. You'll be surprised to see that it might turn out slower than your CPU implementation. \r\rOptimization\r============\r\rThe reason for this is that you're throwing out on the window the price for memory allocation and data transfer. And on the GPU this is damn high. Another possibility for optimization is to introduce asynchronous OpenCV GPU calls too with the help of the :gpudatastructure:`gpu::Stream <gpu-stream>`. \r\r1. Memory allocation on the GPU is considerable. Therefore, if it’s possible allocate new memory as few times as possible. If you create a function what you intend to call multiple times it is a good idea to allocate any local parameters for the function only once, during the first call. To do this you create a data structure containing all the local variables you will use. For instance in case of the PSNR these are: \r\r   .. code-block:: cpp \r\r      struct BufferPSNR                                     // Optimized GPU versions\r        {   // Data allocations are very expensive on GPU. Use a buffer to solve: allocate once reuse later.\r        gpu::GpuMat gI1, gI2, gs, t1,t2;\r\r        gpu::GpuMat buf;\r      };\r\r   Then create an instance of this in the main program: \r\r   .. code-block:: cpp\r\r      BufferPSNR bufferPSNR;\r\r   And finally pass this to the function each time you call it: \r\r   .. code-block:: cpp\r\r      double getPSNR_GPU_optimized(const Mat& I1, const Mat& I2, BufferPSNR& b)\r\r   Now you access these local parameters as: *b.gI1*, *b.buf* and so on. The GpuMat will only reallocate itself on a new call if the new matrix size is different from the previous one. \r\r#. Avoid unnecessary function data transfers. Any small data transfer will be significant one once you go to the GPU. Therefore, if possible make all calculations in-place (in other words do not create new memory objects - for reasons explained at the previous point). For example, although expressing arithmetical operations may be easier to express in one line formulas, it will be slower. In case of the SSIM at one point I need to calculate:\r\r   .. code-block:: cpp \r\r      b.t1 = 2 * b.mu1_mu2 + C1;  \r\r   Although the upper call will succeed observe that there is a hidden data transfer present. Before it makes the addition it needs to store somewhere the multiplication. Therefore, it will create a local matrix in the background, add to that the *C1* value and finally assign that to *t1*. To avoid this we use the gpu functions, instead of the arithmetic operators: \r\r   .. code-block:: cpp\r\r      gpu::multiply(b.mu1_mu2, 2, b.t1); //b.t1 = 2 * b.mu1_mu2 + C1; \r      gpu::add(b.t1, C1, b.t1);\r\r#. Use asynchronous calls (the :gpudatastructure:`gpu::Stream <gpu-stream>`). By default whenever you call a gpu function it will wait for the call to finish and return with the result afterwards. However, it is possible to make asynchronous calls, meaning it will call for the operation execution, make the costly data allocations for the algorithm and return back right away. Now you can call another function if you wish to do so. For the MSSIM this is a small optimization point. In our default implementation we split up the image into channels and call then for each channel the gpu functions. A small degree of parallelization is possible with the stream. By using a stream we can make the data allocation, upload operations while the GPU is already executing a given method. For example we need to upload two images. We queue these one after another and call already the function that processes it. The functions will wait for the upload to finish, however while that happens makes the output buffer allocations for the function to be executed next. \r\r   .. code-block:: cpp \r\r      gpu::Stream stream;\r\r      stream.enqueueConvert(b.gI1, b.t1, CV_32F);    // Upload\r\r      gpu::split(b.t1, b.vI1, stream);              // Methods (pass the stream as final parameter).\r      gpu::multiply(b.vI1[i], b.vI1[i], b.I1_2, stream);        // I1^2\r\rResult and conclusion\r=====================\r\rOn an Intel P8700 laptop CPU paired with a low end NVidia GT220M here are the performance numbers: \r\r.. code-block:: cpp\r\r   Time of PSNR CPU (averaged for 10 runs): 41.4122 milliseconds. With result of: 19.2506\r   Time of PSNR GPU (averaged for 10 runs): 158.977 milliseconds. With result of: 19.2506\r   Initial call GPU optimized:              31.3418 milliseconds. With result of: 19.2506\r   Time of PSNR GPU OPTIMIZED ( / 10 runs): 24.8171 milliseconds. With result of: 19.2506\r\r   Time of MSSIM CPU (averaged for 10 runs): 484.343 milliseconds. With result of B0.890964 G0.903845 R0.936934\r   Time of MSSIM GPU (averaged for 10 runs): 745.105 milliseconds. With result of B0.89922 G0.909051 R0.968223\r   Time of MSSIM GPU Initial Call            357.746 milliseconds. With result of B0.890964 G0.903845 R0.936934\r   Time of MSSIM GPU OPTIMIZED ( / 10 runs): 203.091 milliseconds. With result of B0.890964 G0.903845 R0.936934\r\rIn both cases we managed a performance increase of almost 100% compared to the CPU implementation. It may be just the improvement needed for your application to work. You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=3_ESXmFlnvY>`_. \r\r.. raw:: html\r\r  <div align="center">\r  <iframe title="Similarity check (PNSR and SSIM) on the GPU" width="560" height="349" src="http://www.youtube.com/embed/3_ESXmFlnvY?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>\r  </div>
\ No newline at end of file
index a3fef43..91b2583 100644 (file)
@@ -7,7 +7,7 @@ Squeeze out every little computation power from your system by using the power o
 
 .. include:: ../../definitions/tocDefinitions.rst
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
@@ -18,7 +18,7 @@ Squeeze out every little computation power from your system by using the power o
 
                   *Author:* |Author_BernatG|
 
-                  This will give a good grasp on how to approach coding on the GPU module, once you already know how to handle the other modules. As a test case it will port the similarity methods from the tutorial :ref:`videoInputPSNRMSSIM` to the GPU. 
+                  This will give a good grasp on how to approach coding on the GPU module, once you already know how to handle the other modules. As a test case it will port the similarity methods from the tutorial :ref:`videoInputPSNRMSSIM` to the GPU.
 
   =============== ======================================================
 
index 36fbc92..0ba7c32 100644 (file)
@@ -3,30 +3,30 @@
 *highgui* module. High Level GUI and Media
 ------------------------------------------
 
-This section contains valuable tutorials about how to read/save your image/video files and how to use the built-in graphical user interface of the library. 
+This section contains valuable tutorials about how to read/save your image/video files and how to use the built-in graphical user interface of the library.
 
 .. include:: ../../definitions/tocDefinitions.rst
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   =============== ======================================================
   |Beginners_5|   *Title:* :ref:`Adding_Trackbars`
-  
+
                   *Compatibility:* > OpenCV 2.0
 
                   *Author:* |Author_AnaH|
-  
+
                   We will learn how to add a Trackbar to our applications
-  
+
   =============== ======================================================
-  
+
   .. |Beginners_5| image:: images/Adding_Trackbars_Tutorial_Cover.jpg
                    :height: 90pt
                    :width:  90pt
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
@@ -34,7 +34,7 @@ This section contains valuable tutorials about how to read/save your image/video
   |hVideoInput|   *Title:* :ref:`videoInputPSNRMSSIM`
 
                   *Compatibility:* > OpenCV 2.0
-                  
+
                   *Author:* |Author_BernatG|
 
                   You will learn how to read video streams, and how to calculate similarity values such as PSNR or SSIM.
@@ -45,7 +45,7 @@ This section contains valuable tutorials about how to read/save your image/video
                    :height: 90pt
                    :width:  90pt
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
index 21f8b36..d6f7202 100644 (file)
@@ -5,11 +5,11 @@ Adding a Trackbar to our applications!
 
 * In the previous tutorials (about *linear blending* and the *brightness and contrast adjustments*) you might have noted that we needed to give some **input** to our programs, such as :math:`\alpha` and :math:`beta`. We accomplished that by entering this data using the Terminal
 
-* Well, it is time to use some fancy GUI tools. OpenCV provides some GUI utilities (*highgui.h*) for you. An example of this is a **Trackbar** 
+* Well, it is time to use some fancy GUI tools. OpenCV provides some GUI utilities (*highgui.h*) for you. An example of this is a **Trackbar**
 
   .. image:: images/Adding_Trackbars_Tutorial_Trackbar.png
      :alt: Trackbar example
-     :align: center 
+     :align: center
 
 * In this tutorial we will just modify our two previous programs so that they get the input information from the trackbar.
 
@@ -19,7 +19,7 @@ Goals
 
 In this tutorial you will learn how to:
 
-* Add a Trackbar in an OpenCV window by using  :create_trackbar:`createTrackbar <>` 
+* Add a Trackbar in an OpenCV window by using  :create_trackbar:`createTrackbar <>`
 
 Code
 =====
@@ -33,13 +33,13 @@ Let's modify the program made in the tutorial :ref:`Adding_Images`. We will let
 
    using namespace cv;
 
-   /// Global Variables 
+   /// Global Variables
    const int alpha_slider_max = 100;
-   int alpha_slider; 
+   int alpha_slider;
    double alpha;
-   double beta;  
+   double beta;
 
-   /// Matrices to store images 
+   /// Matrices to store images
    Mat src1;
    Mat src2;
    Mat dst;
@@ -49,12 +49,12 @@ Let's modify the program made in the tutorial :ref:`Adding_Images`. We will let
     * @brief Callback for trackbar
     */
    void on_trackbar( int, void* )
-   { 
+   {
     alpha = (double) alpha_slider/alpha_slider_max ;
     beta = ( 1.0 - alpha );
 
     addWeighted( src1, alpha, src2, beta, 0.0, dst);
-  
+
     imshow( "Linear Blend", dst );
    }
 
@@ -67,7 +67,7 @@ Let's modify the program made in the tutorial :ref:`Adding_Images`. We will let
     if( !src1.data ) { printf("Error loading src1 \n"); return -1; }
     if( !src2.data ) { printf("Error loading src2 \n"); return -1; }
 
-    /// Initialize values 
+    /// Initialize values
     alpha_slider = 0;
 
     /// Create Windows
@@ -75,13 +75,13 @@ Let's modify the program made in the tutorial :ref:`Adding_Images`. We will let
 
     /// Create Trackbars
     char TrackbarName[50];
-    sprintf( TrackbarName, "Alpha x %d", alpha_slider_max ); 
+    sprintf( TrackbarName, "Alpha x %d", alpha_slider_max );
 
     createTrackbar( TrackbarName, "Linear Blend", &alpha_slider, alpha_slider_max, on_trackbar );
 
     /// Show some stuff
     on_trackbar( alpha_slider, 0 );
-  
+
     /// Wait until user press some key
     waitKey(0);
     return 0;
@@ -113,7 +113,7 @@ We only analyze the code that is related to Trackbar:
       createTrackbar( TrackbarName, "Linear Blend", &alpha_slider, alpha_slider_max, on_trackbar );
 
    Note the following:
-   
+
    * Our Trackbar has a label **TrackbarName**
    * The Trackbar is located in the window named **"Linear Blend"**
    * The Trackbar values will be in the range from :math:`0` to **alpha_slider_max** (the minimum limit is always **zero**).
@@ -125,21 +125,21 @@ We only analyze the code that is related to Trackbar:
    .. code-block:: cpp
 
       void on_trackbar( int, void* )
-      { 
+      {
        alpha = (double) alpha_slider/alpha_slider_max ;
        beta = ( 1.0 - alpha );
 
        addWeighted( src1, alpha, src2, beta, 0.0, dst);
-  
+
        imshow( "Linear Blend", dst );
       }
 
    Note that:
-   * We use the value of **alpha_slider** (integer) to get a double value for **alpha**. 
+
+   * We use the value of **alpha_slider** (integer) to get a double value for **alpha**.
    * **alpha_slider** is updated each time the trackbar is displaced by the user.
    * We define *src1*, *src2*, *dist*, *alpha*, *alpha_slider* and *beta* as global  variables, so they can be used everywhere.
+
 Result
 =======
 
@@ -147,13 +147,13 @@ Result
 
   .. image:: images/Adding_Trackbars_Tutorial_Result_0.jpg
      :alt: Adding Trackbars - Windows Linux
-     :align: center 
+     :align: center
 
 * As a manner of practice, you can also add 02 trackbars for the program made in :ref:`Basic_Linear_Transform`. One trackbar to set :math:`\alpha` and another for :math:`\beta`. The output might look like:
 
   .. image:: images/Adding_Trackbars_Tutorial_Result_1.jpg
      :alt: Adding Trackbars - Lena
-     :align: center 
+     :align: center
 
 
 
index f99656e..1f0012e 100644 (file)
@@ -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 :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.
 
-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 :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:
 
 .. code-block:: bash
 
@@ -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 :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:
 
 .. code-block:: cpp
 
@@ -64,7 +64,7 @@ Closing the video is automatic when the objects destructor is called. However, i
    captRefrnc >> frameReference;
    captUndTst.open(frameUnderTest);
 
-The upper read operations will leave empty the *Mat* objects if no frame could be acquired (either cause the video stream was closed or you got to the end of the video file). We can check this with a simple if: 
+The upper read operations will leave empty the *Mat* objects if no frame could be acquired (either cause the video stream was closed or you got to the end of the video file). We can check this with a simple if:
 
 .. 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 :huivideo:`grab <videocapture-grab>` and then the :huivideo:`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 :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.
 
 .. 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 :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:
 
 .. 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 :huivideo:`get <videocapture-get>` and :huivideo:`set <videocapture-set>` functions.
 
 
 Image similarity - PSNR and SSIM
@@ -111,7 +111,7 @@ Then the PSNR is expressed as:
 
    PSNR = 10 \cdot \log_{10} \left( \frac{MAX_I^2}{MSE} \right)
 
-Here the :math:`MAX_I^2` is the maximum valid value for a pixel. In case of the simple single byte image per pixel per channel this is 255. When two images are the same the MSE will give zero, resulting in an invalid divide by zero operation in the PSNR formula. In this case the PSNR is undefined and as we'll need to handle this case separately. The transition to a logarithmic scale is made because the pixel values have a very wide dynamic range. All this translated to OpenCV and a C++ function looks like: 
+Here the :math:`MAX_I^2` is the maximum valid value for a pixel. In case of the simple single byte image per pixel per channel this is 255. When two images are the same the MSE will give zero, resulting in an invalid divide by zero operation in the PSNR formula. In this case the PSNR is undefined and as we'll need to handle this case separately. The transition to a logarithmic scale is made because the pixel values have a very wide dynamic range. All this translated to OpenCV and a C++ function looks like:
 
 .. code-block:: cpp
 
@@ -136,13 +136,13 @@ Here the :math:`MAX_I^2` is the maximum valid value for a pixel. In case of the
     }
    }
 
-Typically result values are anywhere between 30 and 50 for video compression, where higher is better. If the images significantly differ you'll get much lower ones like 15 and so. This similarity check is easy and fast to calculate, however in practice it may turn out somewhat inconsistent with human eye perception. The **structural similarity** algorithm aims to correct this. 
+Typically result values are anywhere between 30 and 50 for video compression, where higher is better. If the images significantly differ you'll get much lower ones like 15 and so. This similarity check is easy and fast to calculate, however in practice it may turn out somewhat inconsistent with human eye perception. The **structural similarity** algorithm aims to correct this.
 
-Describing the methods goes well beyond the purpose of this tutorial. For that I invite you to read the article introducing it. Nevertheless, you can get a good image of it by looking at the OpenCV implementation below. 
+Describing the methods goes well beyond the purpose of this tutorial. For that I invite you to read the article introducing it. Nevertheless, you can get a good image of it by looking at the OpenCV implementation below.
 
 .. seealso::
 
-   SSIM is described more in-depth in the: "Z. Wang, A. C. Bovik, H. R. Sheikh and E. P. Simoncelli, "Image quality assessment: From error visibility to structural similarity," IEEE Transactions on Image Processing, vol. 13, no. 4, pp. 600-612, Apr. 2004." article. 
+   SSIM is described more in-depth in the: "Z. Wang, A. C. Bovik, H. R. Sheikh and E. P. Simoncelli, "Image quality assessment: From error visibility to structural similarity," IEEE Transactions on Image Processing, vol. 13, no. 4, pp. 600-612, Apr. 2004." article.
 
 .. code-block:: cpp
 
@@ -162,7 +162,7 @@ Describing the methods goes well beyond the purpose of this tutorial. For that I
 
     /***********************PRELIMINARY COMPUTING ******************************/
 
-    Mat mu1, mu2;   // 
+    Mat mu1, mu2;   //
     GaussianBlur(I1, mu1, Size(11, 11), 1.5);
     GaussianBlur(I2, mu2, Size(11, 11), 1.5);
 
@@ -199,7 +199,7 @@ Describing the methods goes well beyond the purpose of this tutorial. For that I
     return mssim;
    }
 
-This will return a similarity index for each channel of the image. This value is between zero and one, where one corresponds to perfect fit. Unfortunately, the many Gaussian blurring is quite costly, so while the PSNR may work in a real time like environment (24 frame per second) this will take significantly more than to accomplish similar performance results. 
+This will return a similarity index for each channel of the image. This value is between zero and one, where one corresponds to perfect fit. Unfortunately, the many Gaussian blurring is quite costly, so while the PSNR may work in a real time like environment (24 frame per second) this will take significantly more than to accomplish similar performance results.
 
 Therefore, the source code presented at the start of the tutorial will perform the PSNR measurement for each frame, and the SSIM only for the frames where the PSNR falls below an input value. For visualization purpose we show both images in an OpenCV window and print the PSNR and MSSIM values to the console. Expect to see something like:
 
@@ -207,7 +207,7 @@ Therefore, the source code presented at the start of the tutorial will perform t
    :alt: A sample output
    :align: center
 
-You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=iOcNljutOgg>`_. 
+You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=iOcNljutOgg>`_.
 
 .. raw:: html
 
index 665e82f..369f1ba 100644 (file)
@@ -1 +1 @@
-.. _videoWriteHighGui:\r\rCreating a video with OpenCV\r****************************\r\rGoal\r====\r\rWhenever 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. \r\r.. container:: enumeratevisibleitemswithsquare\r\r   + How to create a video file with OpenCV\r   + What type of video files you can create with OpenCV\r   + How to extract a given color channel from a video\r\rAs 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:\r\r.. container:: enumeratevisibleitemswithsquare\r\r   + The first argument points to the video file to work on\r   + The second argument may be one of the characters: R G B. This will specify which of the channels to extract.\r   + 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.\r\rFor example, a valid command line would look like:\r\r.. code-block:: bash\r\r   video-write.exe video/Megamind.avi R Y\r\rThe source code\r===============\r\rYou 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>`.\r\r.. literalinclude:: ../../../../samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp\r   :language: cpp\r   :linenos:\r   :tab-width: 4\r   :lines: 1-8, 21-22, 24-97\r\rThe structure of a video\r========================\r\rFor 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. \r\r.. image:: images/videoFileStructure.png\r   :alt: The Structure of the video\r   :align: center\r\rAs 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*.\r\rThe *VideoWriter* class\r=======================\r\rThe content written here builds on the assumption you already read the :ref:`videoInputPSNRMSSIM` tutorial and you know how to read video files.\r\rTo 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:\r\r1. 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.\r\r   .. code-block:: cpp\r\r      const string source      = argv[1];            // the source file name\r      string::size_type pAt = source.find_last_of('.');   // Find extension point\r      const string NAME = source.substr(0, pAt) + argv[2][0] + ".avi";   // Form the new name with container\r\r#. 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*: \r\r   .. code-block:: cpp\r\r      VideoCapture inputVideo(source);                                   // Open input\r      int ex = static_cast<int>(inputVideo.get(CV_CAP_PROP_FOURCC));     // Get Codec Type- Int form\r\r   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):\r\r   .. code-block:: cpp\r\r      char EXT[] = {ex & 0XFF , (ex & 0XFF00) >> 8,(ex & 0XFF0000) >> 16,(ex & 0XFF000000) >> 24, 0};\r\r   You can do the same thing with the *union* as:\r\r   .. code-block:: cpp\r\r      union { int v; char c[5];} uEx ;\r      uEx.v = ex;                              // From Int to char via union\r      uEx.c[4]='\0';\r\r   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:\r\r   .. code-block::cpp\r\r      CV_FOURCC('P','I','M,'1') // this is an MPEG1 codec from the characters to integer\r\r   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: \r\r   .. image:: images/videoCompressSelect.png\r      :alt: Select the codec type to use\r      :align: center\r\r#. The frame per second for the output video. Again, here I keep the input videos frame per second by using the *get* function.\r\r#. 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.\r\r#. 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.\r\rHere it is, how I use it in the sample:\r\r.. code-block:: cpp\r\r   VideoWriter outputVideo;\r   Size S = Size((int) inputVideo.get(CV_CAP_PROP_FRAME_WIDTH),    //Acquire input size\r                 (int) inputVideo.get(CV_CAP_PROP_FRAME_HEIGHT));    \r\r   outputVideo.open(NAME , ex, inputVideo.get(CV_CAP_PROP_FPS),S, true);\r\rAfterwards, 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 << : \r\r.. code-block:: cpp\r\r    outputVideo.write(res);  //or\r    outputVideo << res;\r\rExtracting 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: \r\r.. code-block:: cpp\r\r   split(src, spl);                 // process - extract only the correct channel\r   for( int i =0; i < 3; ++i)       \r      if (i != channel)\r         spl[i] = Mat::zeros(S, spl[0].type());\r   merge(spl, res);\r\rPut all this together and you'll get the upper source code, whose runtime result will show something around the idea: \r\r.. image:: images/resultOutputWideoWrite.png\r   :alt: A sample output\r   :align: center\r\rYou may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=jpBwHxsl1_0>`_. \r\r.. raw:: html\r\r  <div align="center">\r  <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>\r  </div>\r
\ No newline at end of file
+.. _videoWriteHighGui:\r\rCreating a video with OpenCV\r****************************\r\rGoal\r====\r\rWhenever 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. \r\r.. container:: enumeratevisibleitemswithsquare\r\r   + How to create a video file with OpenCV\r   + What type of video files you can create with OpenCV\r   + How to extract a given color channel from a video\r\rAs 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:\r\r.. container:: enumeratevisibleitemswithsquare\r\r   + The first argument points to the video file to work on\r   + The second argument may be one of the characters: R G B. This will specify which of the channels to extract.\r   + 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.\r\rFor example, a valid command line would look like:\r\r.. code-block:: bash\r\r   video-write.exe video/Megamind.avi R Y\r\rThe source code\r===============\r\rYou 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>`.\r\r.. literalinclude:: ../../../../samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp\r   :language: cpp\r   :linenos:\r   :tab-width: 4\r   :lines: 1-8, 21-22, 24-97\r\rThe structure of a video\r========================\r\rFor 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. \r\r.. image:: images/videoFileStructure.png\r   :alt: The Structure of the video\r   :align: center\r\rAs 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*.\r\rThe *VideoWriter* class\r=======================\r\rThe content written here builds on the assumption you already read the :ref:`videoInputPSNRMSSIM` tutorial and you know how to read video files.\r\rTo 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:\r\r1. 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.\r\r   .. code-block:: cpp\r\r      const string source      = argv[1];            // the source file name\r      string::size_type pAt = source.find_last_of('.');   // Find extension point\r      const string NAME = source.substr(0, pAt) + argv[2][0] + ".avi";   // Form the new name with container\r\r#. 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*: \r\r   .. code-block:: cpp\r\r      VideoCapture inputVideo(source);                                   // Open input\r      int ex = static_cast<int>(inputVideo.get(CV_CAP_PROP_FOURCC));     // Get Codec Type- Int form\r\r   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):\r\r   .. code-block:: cpp\r\r      char EXT[] = {ex & 0XFF , (ex & 0XFF00) >> 8,(ex & 0XFF0000) >> 16,(ex & 0XFF000000) >> 24, 0};\r\r   You can do the same thing with the *union* as:\r\r   .. code-block:: cpp\r\r      union { int v; char c[5];} uEx ;\r      uEx.v = ex;                              // From Int to char via union\r      uEx.c[4]='\0';\r\r   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:\r\r   .. code-block::cpp\r\r      CV_FOURCC('P','I','M,'1') // this is an MPEG1 codec from the characters to integer\r\r   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: \r\r   .. image:: images/videoCompressSelect.png\r      :alt: Select the codec type to use\r      :align: center\r\r#. The frame per second for the output video. Again, here I keep the input videos frame per second by using the *get* function.\r\r#. 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.\r\r#. 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.\r\rHere it is, how I use it in the sample:\r\r.. code-block:: cpp\r\r   VideoWriter outputVideo;\r   Size S = Size((int) inputVideo.get(CV_CAP_PROP_FRAME_WIDTH),    //Acquire input size\r                 (int) inputVideo.get(CV_CAP_PROP_FRAME_HEIGHT));    \r\r   outputVideo.open(NAME , ex, inputVideo.get(CV_CAP_PROP_FPS),S, true);\r\rAfterwards, 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 << : \r\r.. code-block:: cpp\r\r    outputVideo.write(res);  //or\r    outputVideo << res;\r\rExtracting 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: \r\r.. code-block:: cpp\r\r   split(src, spl);                 // process - extract only the correct channel\r   for( int i =0; i < 3; ++i)       \r      if (i != channel)\r         spl[i] = Mat::zeros(S, spl[0].type());\r   merge(spl, res);\r\rPut all this together and you'll get the upper source code, whose runtime result will show something around the idea: \r\r.. image:: images/resultOutputWideoWrite.png\r   :alt: A sample output\r   :align: center\r\rYou may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=jpBwHxsl1_0>`_. \r\r.. raw:: html\r\r  <div align="center">\r  <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>\r  </div>
\ No newline at end of file
index 9bd460d..77b44f1 100644 (file)
@@ -112,21 +112,21 @@ This tutorial code's is shown lines below. You can also download it from `here <
 
      /// Create Erosion Trackbar
      createTrackbar( "Element:\n 0: Rect \n 1: Cross \n 2: Ellipse", "Erosion Demo",
-                    &erosion_elem, max_elem,
-                    Erosion );
+                 &erosion_elem, max_elem,
+             Erosion );
 
      createTrackbar( "Kernel size:\n 2n +1", "Erosion Demo",
-                    &erosion_size, max_kernel_size,
-                    Erosion );
+             &erosion_size, max_kernel_size,
+             Erosion );
 
      /// Create Dilation Trackbar
      createTrackbar( "Element:\n 0: Rect \n 1: Cross \n 2: Ellipse", "Dilation Demo",
-                    &dilation_elem, max_elem,
-                    Dilation );
+             &dilation_elem, max_elem,
+             Dilation );
 
      createTrackbar( "Kernel size:\n 2n +1", "Dilation Demo",
-                    &dilation_size, max_kernel_size,
-                    Dilation );
+             &dilation_size, max_kernel_size,
+             Dilation );
 
      /// Default start
      Erosion( 0, 0 );
@@ -145,8 +145,8 @@ This tutorial code's is shown lines below. You can also download it from `here <
      else if( erosion_elem == 2) { erosion_type = MORPH_ELLIPSE; }
 
      Mat element = getStructuringElement( erosion_type,
-                                         Size( 2*erosion_size + 1, 2*erosion_size+1 ),
-                                         Point( erosion_size, erosion_size ) );
+                          Size( 2*erosion_size + 1, 2*erosion_size+1 ),
+                          Point( erosion_size, erosion_size ) );
 
      /// Apply the erosion operation
      erode( src, erosion_dst, element );
@@ -162,8 +162,8 @@ This tutorial code's is shown lines below. You can also download it from `here <
      else if( dilation_elem == 2) { dilation_type = MORPH_ELLIPSE; }
 
      Mat element = getStructuringElement( dilation_type,
-                                         Size( 2*dilation_size + 1, 2*dilation_size+1 ),
-                                         Point( dilation_size, dilation_size ) );
+                          Size( 2*dilation_size + 1, 2*dilation_size+1 ),
+                          Point( dilation_size, dilation_size ) );
      /// Apply the dilation operation
      dilate( src, dilation_dst, element );
      imshow( "Dilation Demo", dilation_dst );
@@ -201,8 +201,8 @@ Explanation
         else if( erosion_elem == 2) { erosion_type = MORPH_ELLIPSE; }
 
         Mat element = getStructuringElement( erosion_type,
-                                            Size( 2*erosion_size + 1, 2*erosion_size+1 ),
-                                            Point( erosion_size, erosion_size ) );
+                                 Size( 2*erosion_size + 1, 2*erosion_size+1 ),
+                             Point( erosion_size, erosion_size ) );
         /// Apply the erosion operation
         erode( src, erosion_dst, element );
         imshow( "Erosion Demo", erosion_dst );
@@ -216,17 +216,17 @@ Explanation
 
         .. code-block:: cpp
 
-          Mat element = getStructuringElement( erosion_type,
-                                               Size( 2*erosion_size + 1, 2*erosion_size+1 ),
-                                               Point( erosion_size, erosion_size ) );
+       Mat element = getStructuringElement( erosion_type,
+                                    Size( 2*erosion_size + 1, 2*erosion_size+1 ),
+                                Point( erosion_size, erosion_size ) );
 
        We can choose any of three shapes for our kernel:
 
        .. container:: enumeratevisibleitemswithsquare
 
-         + Rectangular box: MORPH_RECT
-         + Cross:  MORPH_CROSS
-         + Ellipse: MORPH_ELLIPSE
+      + Rectangular box: MORPH_RECT
+      + Cross:  MORPH_CROSS
+      + Ellipse: MORPH_ELLIPSE
 
        Then, we just have to specify the size of our kernel and the *anchor point*. If not specified, it is assumed to be in the center.
 
@@ -251,8 +251,8 @@ The code is below. As you can see, it is completely similar to the snippet of co
      else if( dilation_elem == 2) { dilation_type = MORPH_ELLIPSE; }
 
      Mat element = getStructuringElement( dilation_type,
-                                                 Size( 2*dilation_size + 1, 2*dilation_size+1 ),
-                                         Point( dilation_size, dilation_size ) );
+                                          Size( 2*dilation_size + 1, 2*dilation_size+1 ),
+                          Point( dilation_size, dilation_size ) );
      /// Apply the dilation operation
      dilate( src, dilation_dst, element );
      imshow( "Dilation Demo", dilation_dst );
index 30dfdf8..0e82e50 100644 (file)
@@ -159,35 +159,35 @@ Code
       if( display_caption( "Homogeneous Blur" ) != 0 ) { return 0; }
 
       for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
-         { blur( src, dst, Size( i, i ), Point(-1,-1) );
+          { blur( src, dst, Size( i, i ), Point(-1,-1) );
             if( display_dst( DELAY_BLUR ) != 0 ) { return 0; } }
 
        /// Applying Gaussian blur
        if( display_caption( "Gaussian Blur" ) != 0 ) { return 0; }
 
        for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
-                  { GaussianBlur( src, dst, Size( i, i ), 0, 0 );
+           { GaussianBlur( src, dst, Size( i, i ), 0, 0 );
              if( display_dst( DELAY_BLUR ) != 0 ) { return 0; } }
 
         /// Applying Median blur
-       if( display_caption( "Median Blur" ) != 0 ) { return 0; }
+    if( display_caption( "Median Blur" ) != 0 ) { return 0; }
 
-       for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
-           { medianBlur ( src, dst, i );
+    for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
+            { medianBlur ( src, dst, i );
               if( display_dst( DELAY_BLUR ) != 0 ) { return 0; } }
 
-       /// Applying Bilateral Filter
-       if( display_caption( "Bilateral Blur" ) != 0 ) { return 0; }
+    /// Applying Bilateral Filter
+    if( display_caption( "Bilateral Blur" ) != 0 ) { return 0; }
 
-       for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
-           { bilateralFilter ( src, dst, i, i*2, i/2 );
+    for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
+            { bilateralFilter ( src, dst, i, i*2, i/2 );
               if( display_dst( DELAY_BLUR ) != 0 ) { return 0; } }
 
-       /// Wait until user press a key
-       display_caption( "End: Press a key!" );
+    /// Wait until user press a key
+    display_caption( "End: Press a key!" );
 
-       waitKey(0);
-       return 0;
+    waitKey(0);
+    return 0;
     }
 
     int display_caption( char* caption )
index f8b1343..122c904 100644 (file)
@@ -94,7 +94,7 @@ Code
         * Loads an image
         * Convert the original to HSV format and separate only *Hue* channel to be used for the Histogram (using the OpenCV function :mix_channels:`mixChannels <>`)
         * Let the user to enter the number of bins to be used in the calculation of the histogram.
-       * Calculate the histogram (and update it if the bins change) and the backprojection of the same image.
+    * Calculate the histogram (and update it if the bins change) and the backprojection of the same image.
         * Display the backprojection and the histogram in windows.
 
    * **Downloadable code**:
index 27eef0d..1aa3b38 100644 (file)
@@ -124,34 +124,34 @@ Code
 
      for( int j = 0; j < src.rows; j++ )
      { for( int i = 0; i < src.cols; i++ )
-        {
+     {
            switch( ind )
-          {
-            case 0:
-              if( i > src.cols*0.25 && i < src.cols*0.75 && j > src.rows*0.25 && j < src.rows*0.75 )
+       {
+         case 0:
+           if( i > src.cols*0.25 && i < src.cols*0.75 && j > src.rows*0.25 && j < src.rows*0.75 )
                  {
-                  map_x.at<float>(j,i) = 2*( i - src.cols*0.25 ) + 0.5 ;
-                  map_y.at<float>(j,i) = 2*( j - src.rows*0.25 ) + 0.5 ;
-                 }
-              else
-                { map_x.at<float>(j,i) = 0 ;
-                  map_y.at<float>(j,i) = 0 ;
+               map_x.at<float>(j,i) = 2*( i - src.cols*0.25 ) + 0.5 ;
+               map_y.at<float>(j,i) = 2*( j - src.rows*0.25 ) + 0.5 ;
+              }
+           else
+         { map_x.at<float>(j,i) = 0 ;
+               map_y.at<float>(j,i) = 0 ;
                  }
                    break;
-            case 1:
-                  map_x.at<float>(j,i) = i ;
-                  map_y.at<float>(j,i) = src.rows - j ;
-                  break;
+         case 1:
+               map_x.at<float>(j,i) = i ;
+               map_y.at<float>(j,i) = src.rows - j ;
+           break;
              case 2:
-                  map_x.at<float>(j,i) = src.cols - i ;
-                  map_y.at<float>(j,i) = j ;
-                  break;
+               map_x.at<float>(j,i) = src.cols - i ;
+               map_y.at<float>(j,i) = j ;
+           break;
              case 3:
-                  map_x.at<float>(j,i) = src.cols - i ;
-                  map_y.at<float>(j,i) = src.rows - j ;
-                  break;
+               map_x.at<float>(j,i) = src.cols - i ;
+               map_y.at<float>(j,i) = src.rows - j ;
+           break;
            } // end of switch
-        }
+     }
       }
     ind++;
   }
@@ -241,34 +241,34 @@ Explanation
 
      for( int j = 0; j < src.rows; j++ )
      { for( int i = 0; i < src.cols; i++ )
-        {
+     {
            switch( ind )
-          {
-            case 0:
-              if( i > src.cols*0.25 && i < src.cols*0.75 && j > src.rows*0.25 && j < src.rows*0.75 )
+       {
+         case 0:
+           if( i > src.cols*0.25 && i < src.cols*0.75 && j > src.rows*0.25 && j < src.rows*0.75 )
                  {
-                  map_x.at<float>(j,i) = 2*( i - src.cols*0.25 ) + 0.5 ;
-                  map_y.at<float>(j,i) = 2*( j - src.rows*0.25 ) + 0.5 ;
-                 }
-              else
-                { map_x.at<float>(j,i) = 0 ;
-                  map_y.at<float>(j,i) = 0 ;
+               map_x.at<float>(j,i) = 2*( i - src.cols*0.25 ) + 0.5 ;
+               map_y.at<float>(j,i) = 2*( j - src.rows*0.25 ) + 0.5 ;
+              }
+           else
+         { map_x.at<float>(j,i) = 0 ;
+               map_y.at<float>(j,i) = 0 ;
                  }
                    break;
-            case 1:
-                  map_x.at<float>(j,i) = i ;
-                  map_y.at<float>(j,i) = src.rows - j ;
-                  break;
+         case 1:
+               map_x.at<float>(j,i) = i ;
+               map_y.at<float>(j,i) = src.rows - j ;
+           break;
              case 2:
-                  map_x.at<float>(j,i) = src.cols - i ;
-                  map_y.at<float>(j,i) = j ;
-                  break;
+               map_x.at<float>(j,i) = src.cols - i ;
+               map_y.at<float>(j,i) = j ;
+           break;
              case 3:
-                  map_x.at<float>(j,i) = src.cols - i ;
-                  map_y.at<float>(j,i) = src.rows - j ;
-                  break;
+               map_x.at<float>(j,i) = src.cols - i ;
+               map_y.at<float>(j,i) = src.rows - j ;
+           break;
            } // end of switch
-        }
+     }
        }
       ind++;
      }
index db96faa..4fe6323 100644 (file)
@@ -154,13 +154,13 @@ This tutorial code's is shown lines below. You can also download it from `here <
 
     /// Create Trackbar to select kernel type
     createTrackbar( "Element:\n 0: Rect - 1: Cross - 2: Ellipse", window_name,
-                   &morph_elem, max_elem,
-                   Morphology_Operations );
+            &morph_elem, max_elem,
+            Morphology_Operations );
 
     /// Create Trackbar to choose kernel size
     createTrackbar( "Kernel size:\n 2n +1", window_name,
-                   &morph_size, max_kernel_size,
-                   Morphology_Operations );
+            &morph_size, max_kernel_size,
+            Morphology_Operations );
 
     /// Default start
     Morphology_Operations( 0, 0 );
@@ -211,16 +211,16 @@ Explanation
        .. code-block:: cpp
 
           createTrackbar( "Element:\n 0: Rect - 1: Cross - 2: Ellipse", window_name,
-                         &morph_elem, max_elem,
-                         Morphology_Operations );
+                  &morph_elem, max_elem,
+                  Morphology_Operations );
 
      * The final trackbar **"Kernel Size"** returns the size of the kernel to be used (**morph_size**)
 
        .. code-block:: cpp
 
           createTrackbar( "Kernel size:\n 2n +1", window_name,
-                         &morph_size, max_kernel_size,
-                         Morphology_Operations );
+                  &morph_size, max_kernel_size,
+                  Morphology_Operations );
 
 
    * Every time we move any slider, the user's function **Morphology_Operations** will be called to effectuate a new morphology operation and it will update the output image based on the current trackbar values.
index ee40bf7..8b8d11a 100644 (file)
@@ -129,7 +129,7 @@ This tutorial code's is shown lines below. You can also download it from `here <
        c = waitKey(10);
 
        if( (char)c == 27 )
-                { break; }
+         { break; }
        if( (char)c == 'u' )
          { pyrUp( tmp, dst, Size( tmp.cols*2, tmp.rows*2 ) );
            printf( "** Zoom In: Image x 2 \n" );
@@ -188,7 +188,7 @@ Explanation
           c = waitKey(10);
 
           if( (char)c == 27 )
-                   { break; }
+            { break; }
           if( (char)c == 'u' )
             { pyrUp( tmp, dst, Size( tmp.cols*2, tmp.rows*2 ) );
               printf( "** Zoom In: Image x 2 \n" );
index 011dedd..1be239c 100644 (file)
@@ -7,502 +7,502 @@ In this section you will learn about the image processing (manipulation) functio
 
 .. include:: ../../definitions/tocDefinitions.rst
 
-+ 
+
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
   ===================== ==============================================
    |ImageProcessing_1|  **Title:** :ref:`Smoothing`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-                        
+
                         Let's take a look at some basic linear filters!
-  
+
   ===================== ==============================================
-  
+
   .. |ImageProcessing_1| image:: images/Smoothing_Tutorial_Cover.jpg
                          :height: 90pt
                          :width:  90pt
-  
-+ 
+
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
   ===================== ==============================================
    |ImageProcessing_2|  **Title:** :ref:`Morphology_1`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         Author: |Author_AnaH|
-  
+
                         Let's *change* the shape of objects!
-  
+
   ===================== ==============================================
-  
+
   .. |ImageProcessing_2| image:: images/Morphology_1_Tutorial_Cover.jpg
                          :height: 90pt
                          :width:  90pt
-     
-+ 
+
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
   ================= ==================================================
    |Morphology_2|   **Title:** :ref:`Morphology_2`
-  
+
                     *Compatibility:* > OpenCV 2.0
-                    
+
                     *Author:* |Author_AnaH|
-                    
+
                     Here we investigate different morphology operators
-  
+
   ================= ==================================================
-  
+
   .. |Morphology_2| image:: images/Morphology_2_Tutorial_Cover.jpg
                      :height: 90pt
                      :width:  90pt
-  
-+ 
+
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |Pyramids|           **Title:** :ref:`Pyramids`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-  
+
                         What if I need a bigger/smaller image?
-  
+
   ===================== ==============================================
-  
+
   .. |Pyramids| image:: images/Pyramids_Tutorial_Cover.jpg
                       :height: 90pt
                       :width:  90pt
-  
-+ 
+
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |Threshold|          **Title:** :ref:`Basic_Threshold`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-  
+
                         After so much processing, it is time to decide which pixels stay!
-  
+
   ===================== ==============================================
-  
+
   .. |Threshold| image:: images/Threshold_Tutorial_Cover.jpg
                       :height: 90pt
                       :width:  90pt
-  
+
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-    
-+ 
+
++
   ===================== ==============================================
    |Filter_2D|          **Title:** :ref:`filter_2d`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-  
+
                         Where we learn to design our own filters by using OpenCV functions
-  
+
   ===================== ==============================================
-  
+
   .. |Filter_2D| image:: images/imgtrans/Filter_2D_Tutorial_Cover.jpg
                       :height: 90pt
                       :width:  90pt
-  
+
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-    
-+ 
+
++
   ===================== ==============================================
    |CopyMakeBorder|     **Title:** :ref:`copyMakeBorderTutorial`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-  
+
                         Where we learn how to pad our images!
-  
+
   ===================== ==============================================
-  
+
   .. |CopyMakeBorder| image:: images/imgtrans/CopyMakeBorder_Tutorial_Cover.jpg
                            :height: 90pt
                            :width:  90pt
-  
-+ 
+
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |SobelDerivatives|   **Title:** :ref:`sobel_derivatives`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-  
+
                         Where we learn how to calculate gradients and use them to detect edges!
-  
+
   ===================== ==============================================
-  
+
   .. |SobelDerivatives| image:: images/imgtrans/Sobel_Derivatives_Tutorial_Cover.jpg
                              :height: 90pt
                              :width:  90pt
-  
-+ 
+
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |LaplaceOperator|    **Title:** :ref:`laplace_operator`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-  
+
                         Where we learn about the *Laplace* operator and how to detect edges with it.
-  
+
   ===================== ==============================================
-  
+
   .. |LaplaceOperator| image:: images/imgtrans/Laplace_Operator_Tutorial_Cover.jpg
                              :height: 90pt
                              :width:  90pt
-  
-+ 
+
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |CannyDetector|      **Title:** :ref:`canny_detector`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-  
+
                         Where we learn a sophisticated alternative to detect edges.
-  
+
   ===================== ==============================================
-  
+
   .. |CannyDetector| image:: images/imgtrans/Canny_Detector_Tutorial_Cover.jpg
                            :height: 90pt
                            :width:  90pt
-  
-+ 
+
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |HoughLines|         **Title:** :ref:`hough_lines`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-  
+
                         Where we learn how to detect lines
-  
+
   ===================== ==============================================
-  
+
   .. |HoughLines| image:: images/imgtrans/Hough_Lines_Tutorial_Cover.jpg
                         :height: 90pt
                         :width:  90pt
-  
-+ 
+
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |HoughCircle|        **Title:** :ref:`hough_circle`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-  
+
                         Where we learn how to detect circles
-  
+
   ===================== ==============================================
-  
+
   .. |HoughCircle| image:: images/imgtrans/Hough_Circle_Tutorial_Cover.jpg
                          :height: 90pt
                          :width:  90pt
-  
-+ 
+
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |Remap|              **Title:** :ref:`remap`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-  
+
                         Where we learn how to manipulate pixels locations
-  
+
   ===================== ==============================================
-  
+
   .. |Remap| image:: images/imgtrans/Remap_Tutorial_Cover.jpg
                    :height: 90pt
                    :width:  90pt
-  
-+ 
+
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |WarpAffine|         **Title:** :ref:`warp_affine`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-  
+
                         Where we learn how to rotate, translate and scale our images
-  
+
   ===================== ==============================================
-  
+
   .. |WarpAffine| image:: images/imgtrans/Warp_Affine_Tutorial_Cover.jpg
                         :height: 90pt
                         :width:  90pt
 
-+ 
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |HistEqualization|   **Title:** :ref:`histogram_equalization`
 
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
 
                         Where we learn how to improve the contrast in our images
 
   ===================== ==============================================
-  
+
   .. |HistEqualization| image:: images/histograms/Histogram_Equalization_Tutorial_Cover.jpg
                               :height: 90pt
                               :width:  90pt
 
-+ 
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |HistCalculation|    **Title:** :ref:`histogram_calculation`
 
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
 
                         Where we learn how to create and generate histograms
 
   ===================== ==============================================
-  
+
   .. |HistCalculation| image:: images/histograms/Histogram_Calculation_Tutorial_Cover.jpg
                              :height: 90pt
                              :width:  90pt
 
-+ 
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |HistComparison|     **Title:** :ref:`histogram_comparison`
 
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
 
                         Where we learn to calculate metrics between histograms
 
   ===================== ==============================================
-  
+
   .. |HistComparison| image:: images/histograms/Histogram_Comparison_Tutorial_Cover.jpg
                             :height: 90pt
                             :width:  90pt
 
-+ 
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |BackProjection|     **Title:** :ref:`back_projection`
 
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
 
                         Where we learn how to use histograms to find similar objects in images
 
   ===================== ==============================================
-  
+
   .. |BackProjection| image:: images/histograms/Back_Projection_Tutorial_Cover.jpg
                             :height: 90pt
                             :width:  90pt
 
-+ 
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |TemplateMatching|   **Title:** :ref:`template_matching`
 
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
 
                         Where we learn how to match templates in an image
 
   ===================== ==============================================
-  
+
   .. |TemplateMatching| image:: images/histograms/Template_Matching_Tutorial_Cover.jpg
                               :height: 90pt
                               :width:  90pt
 
-+ 
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |FindContours|       **Title:** :ref:`find_contours`
 
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
 
                         Where we learn how to find contours of objects in our image
 
   ===================== ==============================================
-  
+
   .. |FindContours| image:: images/shapedescriptors/Find_Contours_Tutorial_Cover.jpg
                           :height: 90pt
                           :width:  90pt
 
-+ 
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |Hull|               **Title:** :ref:`hull`
 
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
 
                         Where we learn how to get hull contours and draw them!
 
   ===================== ==============================================
-  
+
   .. |Hull| image:: images/shapedescriptors/Hull_Tutorial_Cover.jpg
                  :height: 90pt
                  :width:  90pt
 
-+ 
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
+
   ===================== ==============================================
    |BRC|                **Title:** :ref:`bounding_rects_circles`
 
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
 
                         Where we learn how to obtain bounding boxes and circles for our contours.
 
   ===================== ==============================================
-  
+
   .. |BRC| image:: images/shapedescriptors/Bounding_Rects_Circles_Tutorial_Cover.jpg
                 :height: 90pt
                 :width:  90pt
 
-+ 
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
-  
+
+
   ===================== ==============================================
    |BRE|                **Title:** :ref:`bounding_rotated_ellipses`
 
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
 
                         Where we learn how to obtain rotated bounding boxes and ellipses for our contours.
 
   ===================== ==============================================
-  
+
   .. |BRE| image:: images/shapedescriptors/Bounding_Rotated_Ellipses_Tutorial_Cover.jpg
                 :height: 90pt
                 :width:  90pt
 
-+ 
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
-  
+
+
   ===================== ==============================================
    |MU|                 **Title:** :ref:`moments`
 
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
 
                         Where we learn to calculate the moments of an image
 
   ===================== ==============================================
-  
+
   .. |MU| image:: images/shapedescriptors/Moments_Tutorial_Cover.jpg
                :height: 90pt
                :width:  90pt
 
 
-+ 
++
 
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
-  
-  
+
+
   ===================== ==============================================
    |PPT|                **Title:** :ref:`point_polygon_test`
 
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
 
                         Where we learn how to calculate distances from the image to contours
 
   ===================== ==============================================
-  
+
   .. |PPT| image:: images/shapedescriptors/Point_Polygon_Test_Tutorial_Cover.jpg
                 :height: 90pt
                 :width:  90pt
index 7788e6c..d76c057 100644 (file)
@@ -174,12 +174,12 @@ The tutorial code's is shown lines below. You can also download it from `here <h
 
      /// Create Trackbar to choose type of Threshold
      createTrackbar( trackbar_type,
-                    window_name, &threshold_type,
-                    max_type, Threshold_Demo );
+             window_name, &threshold_type,
+             max_type, Threshold_Demo );
 
      createTrackbar( trackbar_value,
-                    window_name, &threshold_value,
-                    max_value, Threshold_Demo );
+             window_name, &threshold_value,
+             max_value, Threshold_Demo );
 
      /// Call the function to initialize
      Threshold_Demo( 0, 0 );
@@ -190,7 +190,7 @@ The tutorial code's is shown lines below. You can also download it from `here <h
        int c;
        c = waitKey( 20 );
        if( (char)c == 27 )
-        { break; }
+     { break; }
       }
 
    }
@@ -245,12 +245,12 @@ Explanation
      .. code-block:: cpp
 
         createTrackbar( trackbar_type,
-                    window_name, &threshold_type,
-                    max_type, Threshold_Demo );
+             window_name, &threshold_type,
+             max_type, Threshold_Demo );
 
         createTrackbar( trackbar_value,
-                    window_name, &threshold_value,
-                    max_value, Threshold_Demo );
+             window_name, &threshold_value,
+             max_value, Threshold_Demo );
 
    * Wait until the user enters the threshold value, the type of thresholding (or until the program exits)
 
index a37ef14..52e68c7 100644 (file)
@@ -1 +1 @@
-.. _howToWriteTutorial:\r\rHow to write a tutorial for OpenCV?\r***********************************\r\rOkay, 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.\r\rGoal\r====\r\r.. _reST: http://docutils.sourceforge.net/rst.html\r.. |reST| replace:: reStructuredText\r.. |Sphinx| replace:: Sphinx\r.. _Sphinx: http://sphinx.pocoo.org/\r\rThe 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.\r\rUsually, an OpenCV tutorial has the following parts:\r\r1. A source code demonstration of an OpenCV feature:\r\r   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.\r   #. Occasionaly, input resource files required for running your tutorials application.\r\r\r#. A table of content entry (so people may easily find the tutorial):\r\r   a. Adding your stuff to the tutorials table of content (**reST** file).\r   #. Add an image file near the TOC entry.\r\r\r#. The content of the tutorial itself:\r\r   a. The **reST** text of the tutorial\r   #. Images following the idea that "*A picture is worth a thousand words*".\r   #. For more complex demonstrations you may create a video.\r\rAs 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.\r\rIn 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.\r\rNow 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.\r\rOnce 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.\r\rFormat the Source Code\r======================\r\rBefore 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.\r\rIn 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:\r\r.. container:: enumeratevisibleitemswithsquare\r\r   + 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:\r\r     .. code-block:: cpp\r\r        void help()\r        {\r        cout\r        << "--------------------------------------------------------------------------"   << endl\r        << "This program shows how to write video files. You can extract the R or G or B color channel "\r        << " of the input video. You can choose to use the source codec (Y) or select a custom one. (N)"<< endl\r        << "Usage:"                                                                       << endl\r        << "./video-write inputvideoName [ R | G | B] [Y | N]"                            << endl\r        << "--------------------------------------------------------------------------"   << endl\r        << endl;\r        }\r        // ...\r        int main(int argc, char *argv[], char *window_name)\r        {\r        help();\r        // here comes the actual source code\r        }\r\r     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.\r\r   + 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.\r\r   + 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.\r\r   + 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.\r\r   + 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.\r\r   + 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!\r\rAdd the TOC entry\r=================\r\rFor 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.\r\rAdding 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.\r\rNavigate 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:\r\r.. code-block:: rst\r\r  .. _Table-Of-Content-Section:\r\r   Section title\r   -----------------------------------------------------------\r\r   Description about the section.\r\r   .. include:: ../../definitions/noContent.rst\r\r   .. raw:: latex\r\r      \pagebreak\r\rThe 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.\r\rIf you have one of this, try to transform it to the following form:\r\r.. include:: ../../definitions/tocDefinitions.rst\r\r.. code-block:: rst\r\r   .. _Table-Of-Content-Section:\r\r   Section title\r   -----------------------------------------------------------\r\r   .. include:: ../../definitions/tocDefinitions.rst\r\r   +\r     .. tabularcolumns:: m{100pt} m{300pt}\r     .. cssclass:: toctableopencv\r\r     =============== ======================================================\r      |MatBasicIma|  **Title:** :ref:`matTheBasicImageContainer`\r\r                     *Compatibility:* > OpenCV 2.0\r\r                     *Author:* |Author_BernatG|\r\r                     You will learn how to store images in the memory and how to print out their content to the console.\r\r     =============== =====================================================\r\r     .. |MatBasicIma| image:: images/matTheBasicImageStructure.jpg\r                      :height: 90pt\r                      :width:  90pt\r\r   .. raw:: latex\r\r      \pagebreak\r\r   .. toctree::\r      :hidden:\r\r      ../mat - the basic image container/mat - the basic image container\r\rIf 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:\r\r.. code-block:: rst\r\r   .. |Author_BernatG| unicode:: Bern U+00E1 t U+0020 G U+00E1 bor\r\rThe ``|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).\r\rUntil the *raw* directive what you can see is a TOC tree entry. Here's how a TOC entry will look like:\r\r+\r  .. tabularcolumns:: m{100pt} m{300pt}\r  .. cssclass:: toctableopencv\r\r  =============== ======================================================\r   |MatBasicIma|  **Title:** :ref:`matTheBasicImageContainer`\r\r                  *Compatibility:* > OpenCV 2.0\r\r                  *Author:* |Author_BernatG|\r\r                  You will learn how to store images in the memory and how to print out their content to the console.\r\r  =============== ======================================================\r\r  .. |MatBasicIma| image:: images/matTheBasicImageStructure.jpg\r                   :height: 90pt\r                   :width:  90pt\r\rAs 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.\r\rNow 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!\r\r.. note::\r\r   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!\r\rGenerally 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.\r\rThe 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.\r\rNow on the right side column of the table we add the information about the tutorial:\r\r.. container:: enumeratevisibleitemswithsquare\r\r   + 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:\r\r     .. code-block:: rst\r\r        .. _matTheBasicImageContainer:\r\r           Mat - The Basic Image Container\r           *******************************\r\r     Note, that according to the |reST|_ rules the * should be as long as your title.\r\r   + Compatibility. What version of OpenCV is required to run your sample code.\r\r   + Author. Use the substitution markup of |reST|_.\r\r   + A short sentence describing the essence of your tutorial.\r\rNow before each TOC entry you need to add the three lines of:\r\r.. code-block:: cpp\r\r   +\r     .. tabularcolumns:: m{100pt} m{300pt}\r     .. cssclass:: toctableopencv\r\rThe 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.\r\rHere, 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.\r\rIt 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.\r\r.. code-block:: css\r\r   .toctableopencv\r   {\r    width: 100% ;\r    table-layout: fixed;\r   }\r\r\r   .toctableopencv colgroup col:first-child\r   {\r    width: 100pt !important;\r    max-width: 100pt !important;\r    min-width: 100pt !important;\r   }\r\r   .toctableopencv colgroup col:nth-child(2)\r   {\r    width: 100% !important;\r   }\r\rHowever, 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:\r\r.. code-block:: rst\r\r   .. raw:: latex\r\r      \pagebreak\r\r   .. toctree::\r      :hidden:\r\r      ../mat - the basic image container/mat - the basic image container\r\rThe 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.\r\rThe 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.\r\rWrite the tutorial\r==================\r\rCreate 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!\r\rNow 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!):\r\r\r.. container:: enumeratevisibleitemswithsquare\r\r   + Create the reference point and the title.\r\r     .. code-block:: rst\r\r        .. _matTheBasicImageContainer:\r\r        Mat - The Basic Image Container\r        *******************************\r\r     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.\r\r   + 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:\r\r     .. code-block:: rst\r\r        .. container:: enumeratevisibleitemswithsquare\r\r           + Create the reference point and the title.\r           + Second entry\r           + Third entry\r\r     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.\r\r   + 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:\r\r     .. code-block:: rst\r\r        Text :file:`samples/cpp/tutorial_code/highgui/video-write/` folder of the OpenCV source library\r        or :download:`text to appear in the webpage\r        <../../../../samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp>`.\r\r     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:\r\r     .. code-block:: rst\r\r        .. code-block:: cpp\r\r           int i = 0;\r           l = ++j;\r\r     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:\r\r     .. code-block:: rst\r\r        .. literalinclude:: ../../../../samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp\r           :language: cpp\r           :linenos:\r           :tab-width: 4\r           :lines: 1-8, 21-22, 24-\r\r     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.\r\r   + 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.\r\r     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:\r\r     .. code-block:: py\r\r       # ---- External links for tutorials -----------------\r       extlinks = {\r           'huivideo' : ('http://opencv.itseez.com/modules/highgui/doc/reading_and_writing_images_and_video.html#%s', None)\r           }\r\r     In short here we defined a new **huivideo** directive that refers to an external webpage link. Its usage is:\r\r     .. code-block:: rst\r\r       A sample function of the highgui modules image write and read page is the :huivideo:`imread() function <imread>`.\r\r     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.\r\r     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:\r\r     .. code-block:: latex\r\r        .. math::\r\r           MSE = \frac{1}{c*i*j} \sum{(I_1-I_2)^2}\r\r     That after build turns into:\r\r     .. math::\r\r        MSE = \frac{1}{c*i*j} \sum{(I_1-I_2)^2}\r\r     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}`.\r\r     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.\r\r   + Results. Well, here depending on your program show one of more of the following:\r\r     - Console outputs by using the code block directive.\r     - Output images.\r     - 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:\r\r       .. code-block:: rst\r\r          You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=jpBwHxsl1_0>`_.\r\r          .. raw:: html\r\r             <div align="center">\r             <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>\r             </div>\r\r       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>`_.\r\r       .. raw:: html\r\r          <div align="center">\r          <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>\r          </div>\r\r     When these aren't self-explanatory make sure to throw in a few guiding lines about what and why we can see.\r\r   + 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.\r\r   + Read again your tutorial and check for both programming and spelling errors. If found any, please correct them.\r\r\rTake home the pride and joy of a job well done!\r===============================================\r\rOnce 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.\r\rNow, 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.\r\rIf 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.\r
\ No newline at end of file
+.. _howToWriteTutorial:\r\rHow to write a tutorial for OpenCV?\r***********************************\r\rOkay, 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.\r\rGoal\r====\r\r.. _reST: http://docutils.sourceforge.net/rst.html\r.. |reST| replace:: reStructuredText\r.. |Sphinx| replace:: Sphinx\r.. _Sphinx: http://sphinx.pocoo.org/\r\rThe 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.\r\rUsually, an OpenCV tutorial has the following parts:\r\r1. A source code demonstration of an OpenCV feature:\r\r   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.\r   #. Occasionaly, input resource files required for running your tutorials application.\r\r\r#. A table of content entry (so people may easily find the tutorial):\r\r   a. Adding your stuff to the tutorials table of content (**reST** file).\r   #. Add an image file near the TOC entry.\r\r\r#. The content of the tutorial itself:\r\r   a. The **reST** text of the tutorial\r   #. Images following the idea that "*A picture is worth a thousand words*".\r   #. For more complex demonstrations you may create a video.\r\rAs 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.\r\rIn 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.\r\rNow 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.\r\rOnce 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.\r\rFormat the Source Code\r======================\r\rBefore 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.\r\rIn 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:\r\r.. container:: enumeratevisibleitemswithsquare\r\r   + 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:\r\r     .. code-block:: cpp\r\r        void help()\r        {\r        cout\r        << "--------------------------------------------------------------------------"   << endl\r        << "This program shows how to write video files. You can extract the R or G or B color channel "\r        << " of the input video. You can choose to use the source codec (Y) or select a custom one. (N)"<< endl\r        << "Usage:"                                                                       << endl\r        << "./video-write inputvideoName [ R | G | B] [Y | N]"                            << endl\r        << "--------------------------------------------------------------------------"   << endl\r        << endl;\r        }\r        // ...\r        int main(int argc, char *argv[], char *window_name)\r        {\r        help();\r        // here comes the actual source code\r        }\r\r     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.\r\r   + 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.\r\r   + 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.\r\r   + 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.\r\r   + 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.\r\r   + 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!\r\rAdd the TOC entry\r=================\r\rFor 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.\r\rAdding 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.\r\rNavigate 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:\r\r.. code-block:: rst\r\r  .. _Table-Of-Content-Section:\r\r   Section title\r   -----------------------------------------------------------\r\r   Description about the section.\r\r   .. include:: ../../definitions/noContent.rst\r\r   .. raw:: latex\r\r      \pagebreak\r\rThe 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.\r\rIf you have one of this, try to transform it to the following form:\r\r.. include:: ../../definitions/tocDefinitions.rst\r\r.. code-block:: rst\r\r   .. _Table-Of-Content-Section:\r\r   Section title\r   -----------------------------------------------------------\r\r   .. include:: ../../definitions/tocDefinitions.rst\r\r   +\r     .. tabularcolumns:: m{100pt} m{300pt}\r     .. cssclass:: toctableopencv\r\r     =============== ======================================================\r      |MatBasicIma|  **Title:** :ref:`matTheBasicImageContainer`\r\r                     *Compatibility:* > OpenCV 2.0\r\r                     *Author:* |Author_BernatG|\r\r                     You will learn how to store images in the memory and how to print out their content to the console.\r\r     =============== =====================================================\r\r     .. |MatBasicIma| image:: images/matTheBasicImageStructure.jpg\r                      :height: 90pt\r                      :width:  90pt\r\r   .. raw:: latex\r\r      \pagebreak\r\r   .. toctree::\r      :hidden:\r\r      ../mat - the basic image container/mat - the basic image container\r\rIf 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:\r\r.. code-block:: rst\r\r   .. |Author_BernatG| unicode:: Bern U+00E1 t U+0020 G U+00E1 bor\r\rThe ``|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).\r\rUntil the *raw* directive what you can see is a TOC tree entry. Here's how a TOC entry will look like:\r\r+\r  .. tabularcolumns:: m{100pt} m{300pt}\r  .. cssclass:: toctableopencv\r\r  =============== ======================================================\r   |MatBasicIma|  **Title:** :ref:`matTheBasicImageContainer`\r\r                  *Compatibility:* > OpenCV 2.0\r\r                  *Author:* |Author_BernatG|\r\r                  You will learn how to store images in the memory and how to print out their content to the console.\r\r  =============== ======================================================\r\r  .. |MatBasicIma| image:: images/matTheBasicImageStructure.jpg\r                   :height: 90pt\r                   :width:  90pt\r\rAs 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.\r\rNow 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!\r\r.. note::\r\r   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!\r\rGenerally 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.\r\rThe 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.\r\rNow on the right side column of the table we add the information about the tutorial:\r\r.. container:: enumeratevisibleitemswithsquare\r\r   + 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:\r\r     .. code-block:: rst\r\r        .. _matTheBasicImageContainer:\r\r           Mat - The Basic Image Container\r           *******************************\r\r     Note, that according to the |reST|_ rules the * should be as long as your title.\r\r   + Compatibility. What version of OpenCV is required to run your sample code.\r\r   + Author. Use the substitution markup of |reST|_.\r\r   + A short sentence describing the essence of your tutorial.\r\rNow before each TOC entry you need to add the three lines of:\r\r.. code-block:: cpp\r\r   +\r     .. tabularcolumns:: m{100pt} m{300pt}\r     .. cssclass:: toctableopencv\r\rThe 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.\r\rHere, 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.\r\rIt 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.\r\r.. code-block:: css\r\r   .toctableopencv\r   {\r    width: 100% ;\r    table-layout: fixed;\r   }\r\r\r   .toctableopencv colgroup col:first-child\r   {\r    width: 100pt !important;\r    max-width: 100pt !important;\r    min-width: 100pt !important;\r   }\r\r   .toctableopencv colgroup col:nth-child(2)\r   {\r    width: 100% !important;\r   }\r\rHowever, 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:\r\r.. code-block:: rst\r\r   .. raw:: latex\r\r      \pagebreak\r\r   .. toctree::\r      :hidden:\r\r      ../mat - the basic image container/mat - the basic image container\r\rThe 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.\r\rThe 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.\r\rWrite the tutorial\r==================\r\rCreate 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!\r\rNow 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!):\r\r\r.. container:: enumeratevisibleitemswithsquare\r\r   + Create the reference point and the title.\r\r     .. code-block:: rst\r\r        .. _matTheBasicImageContainer:\r\r        Mat - The Basic Image Container\r        *******************************\r\r     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.\r\r   + 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:\r\r     .. code-block:: rst\r\r        .. container:: enumeratevisibleitemswithsquare\r\r           + Create the reference point and the title.\r           + Second entry\r           + Third entry\r\r     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.\r\r   + 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:\r\r     .. code-block:: rst\r\r        Text :file:`samples/cpp/tutorial_code/highgui/video-write/` folder of the OpenCV source library\r        or :download:`text to appear in the webpage\r        <../../../../samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp>`.\r\r     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:\r\r     .. code-block:: rst\r\r        .. code-block:: cpp\r\r           int i = 0;\r           l = ++j;\r\r     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:\r\r     .. code-block:: rst\r\r        .. literalinclude:: ../../../../samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp\r           :language: cpp\r           :linenos:\r           :tab-width: 4\r           :lines: 1-8, 21-22, 24-\r\r     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.\r\r   + 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.\r\r     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:\r\r     .. code-block:: py\r\r       # ---- External links for tutorials -----------------\r       extlinks = {\r           'huivideo' : ('http://opencv.itseez.com/modules/highgui/doc/reading_and_writing_images_and_video.html#%s', None)\r           }\r\r     In short here we defined a new **huivideo** directive that refers to an external webpage link. Its usage is:\r\r     .. code-block:: rst\r\r       A sample function of the highgui modules image write and read page is the :huivideo:`imread() function <imread>`.\r\r     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.\r\r     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:\r\r     .. code-block:: latex\r\r        .. math::\r\r           MSE = \frac{1}{c*i*j} \sum{(I_1-I_2)^2}\r\r     That after build turns into:\r\r     .. math::\r\r        MSE = \frac{1}{c*i*j} \sum{(I_1-I_2)^2}\r\r     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}`.\r\r     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.\r\r   + Results. Well, here depending on your program show one of more of the following:\r\r     - Console outputs by using the code block directive.\r     - Output images.\r     - 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:\r\r       .. code-block:: rst\r\r          You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=jpBwHxsl1_0>`_.\r\r          .. raw:: html\r\r             <div align="center">\r             <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>\r             </div>\r\r       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>`_.\r\r       .. raw:: html\r\r          <div align="center">\r          <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>\r          </div>\r\r     When these aren't self-explanatory make sure to throw in a few guiding lines about what and why we can see.\r\r   + 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.\r\r   + Read again your tutorial and check for both programming and spelling errors. If found any, please correct them.\r\r\rTake home the pride and joy of a job well done!\r===============================================\r\rOnce 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.\r\rNow, 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.\r\rIf 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.
\ No newline at end of file
index ace657b..cb9e065 100644 (file)
@@ -20,7 +20,7 @@ In MacOS it can be done using the following command in Terminal:
 
    cd ~/<my_working _directory>
    git clone https://github.com/Itseez/opencv.git
+
 
 Building OpenCV from Source, using CMake and Command Line
 =========================================================
@@ -28,10 +28,10 @@ Building OpenCV from Source, using CMake and Command Line
 #. Make symbolic link for Xcode to let OpenCV build scripts find the compiler, header files etc.
 
     .. code-block:: bash
-    
+
        cd /
        sudo ln -s /Applications/Xcode.app/Contents/Developer Developer
-       
+
 #. Build OpenCV framework:
 
     .. code-block:: bash
index 0e3f329..c1a6fac 100644 (file)
@@ -11,7 +11,7 @@ Prerequisites
 
 1. Having installed `Eclipse <http://www.eclipse.org/>`_ in your workstation (only the CDT plugin for C/C++ is needed). You can follow the following steps:
 
-   * Go to the Eclipse site  
+   * Go to the Eclipse site
 
    * Download `Eclipse IDE for C/C++ Developers <http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/heliossr2>`_ . Choose the link according to your workstation.
 
@@ -20,7 +20,7 @@ Prerequisites
 Making a project
 =================
 
-1. Start Eclipse. Just run the executable that comes in the folder. 
+1. Start Eclipse. Just run the executable that comes in the folder.
 
 #. Go to **File -> New -> C/C++ Project**
 
@@ -28,13 +28,13 @@ Making a project
       :alt: Eclipse Tutorial Screenshot 0
       :align: center
 
-#. Choose a name for your project (i.e. DisplayImage). An **Empty Project** should be okay for this example. 
+#. Choose a name for your project (i.e. DisplayImage). An **Empty Project** should be okay for this example.
 
    .. image:: images/a1.png
       :alt: Eclipse Tutorial Screenshot 1
       :align: center
 
-#. Leave everything else by default. Press **Finish**. 
+#. Leave everything else by default. Press **Finish**.
 
 #. Your project (in this case DisplayImage) should appear in the **Project Navigator** (usually at the left side of your window).
 
@@ -45,7 +45,7 @@ Making a project
 
 #. Now, let's add a source file using OpenCV:
 
-   * Right click on **DisplayImage** (in the Navigator). **New -> Folder** . 
+   * Right click on **DisplayImage** (in the Navigator). **New -> Folder** .
 
      .. image:: images/a4.png
         :alt: Eclipse Tutorial Screenshot 4
@@ -76,9 +76,9 @@ Making a project
         image = imread( argv[1], 1 );
 
         if( argc != 2 || !image.data )
-          { 
+          {
             printf( "No image data \n" );
-            return -1; 
+            return -1;
           }
 
         namedWindow( "Display Image", CV_WINDOW_AUTOSIZE );
@@ -102,7 +102,7 @@ Making a project
             :align: center
 
          .. note::
-            If you do not know where your opencv files are, open the **Terminal** and type: 
+            If you do not know where your opencv files are, open the **Terminal** and type:
 
             .. code-block:: bash
 
@@ -112,56 +112,56 @@ Making a project
 
             .. code-block:: bash
 
-               -I/usr/local/include/opencv -I/usr/local/include 
+               -I/usr/local/include/opencv -I/usr/local/include
 
 
       b. Now go to **GCC C++ Linker**,there you have to fill two spaces:
 
          First in **Library search path (-L)** you have to write the path to where the opencv libraries reside, in my case the path is:
          ::
-          
+
             /usr/local/lib
-          
+
          Then in **Libraries(-l)** add the OpenCV libraries that you may need. Usually just the 3 first on the list below are enough (for simple applications) . In my case, I am putting all of them since I plan to use the whole bunch:
 
 
-         opencv_core      
-         opencv_imgproc     
+         opencv_core
+         opencv_imgproc
          opencv_highgui
-         opencv_ml       
-         opencv_video      
+         opencv_ml
+         opencv_video
          opencv_features2d
-         opencv_calib3d   
-         opencv_objdetect   
+         opencv_calib3d
+         opencv_objdetect
          opencv_contrib
-         opencv_legacy    
+         opencv_legacy
          opencv_flann
 
          .. image:: images/a10.png
              :alt: Eclipse Tutorial Screenshot 10
-             :align: center 
-             
+             :align: center
+
          If you don't know where your libraries are (or you are just psychotic and want to make sure the path is fine), type in **Terminal**:
 
          .. code-block:: bash
-         
+
             pkg-config --libs opencv
 
 
          My output (in case you want to check) was:
          .. code-block:: bash
-            
-            -L/usr/local/lib -lopencv_core -lopencv_imgproc -lopencv_highgui -lopencv_ml -lopencv_video -lopencv_features2d -lopencv_calib3d -lopencv_objdetect -lopencv_contrib -lopencv_legacy -lopencv_flann  
+
+            -L/usr/local/lib -lopencv_core -lopencv_imgproc -lopencv_highgui -lopencv_ml -lopencv_video -lopencv_features2d -lopencv_calib3d -lopencv_objdetect -lopencv_contrib -lopencv_legacy -lopencv_flann
 
          Now you are done. Click **OK**
 
-    * Your project should be ready to be built. For this, go to **Project->Build all**   
+    * Your project should be ready to be built. For this, go to **Project->Build all**
 
-      In the Console you should get something like 
+      In the Console you should get something like
 
       .. image:: images/a12.png
          :alt: Eclipse Tutorial Screenshot 12
-         :align: center 
+         :align: center
 
       If you check in your folder, there should be an executable there.
 
@@ -179,21 +179,21 @@ So, now we have an executable ready to run. If we were to use the Terminal, we w
 Assuming that the image to use as the argument would be located in <DisplayImage_directory>/images/HappyLittleFish.png. We can still do this, but let's do it from Eclipse:
 
 
-#. Go to **Run->Run Configurations** 
+#. Go to **Run->Run Configurations**
 
-#. Under C/C++ Application you will see the name of your executable + Debug (if not, click over C/C++ Application a couple of times). Select the name (in this case **DisplayImage Debug**). 
+#. Under C/C++ Application you will see the name of your executable + Debug (if not, click over C/C++ Application a couple of times). Select the name (in this case **DisplayImage Debug**).
 
 #. Now, in the right side of the window, choose the **Arguments** Tab. Write the path of the image file we want to open (path relative to the workspace/DisplayImage folder). Let's use **HappyLittleFish.png**:
 
    .. image:: images/a14.png
       :alt: Eclipse Tutorial Screenshot 14
-      :align: center 
+      :align: center
 
 #. Click on the **Apply** button and then in Run. An OpenCV window should pop up with the fish image (or whatever you used).
 
    .. image:: images/a15.jpg
       :alt: Eclipse Tutorial Screenshot 15
-      :align: center 
+      :align: center
 
 #. Congratulations! You are ready to have fun with OpenCV using Eclipse.
 
@@ -238,7 +238,7 @@ Say you have or create a new file, *helloworld.cpp* in a directory called *foo*:
    ADD_EXECUTABLE( helloworld helloworld.cxx )
    TARGET_LINK_LIBRARIES( helloworld ${OpenCV_LIBS} )
 
-#. Run: ``cmake-gui ..`` and make sure you fill in where opencv was built. 
+#. Run: ``cmake-gui ..`` and make sure you fill in where opencv was built.
 
 #. Then click ``configure`` and then ``generate``. If it's OK, **quit cmake-gui**
 
index 3e31917..e4c089c 100644 (file)
@@ -11,7 +11,7 @@ Using OpenCV with gcc and CMake
    * The easiest way of using OpenCV in your code is to use `CMake <http://www.cmake.org/>`_. A few advantages (taken from the Wiki):
 
      #. No need to change anything when porting between Linux and Windows
-     #. Can easily be combined with other tools by CMake( i.e. Qt, ITK and VTK ) 
+     #. Can easily be combined with other tools by CMake( i.e. Qt, ITK and VTK )
 
    * If you are not familiar with CMake, checkout the `tutorial <http://www.cmake.org/cmake/help/cmake_tutorial.html>`_ on its website.
 
@@ -21,7 +21,7 @@ Steps
 Create a program using OpenCV
 -------------------------------
 
-Let's use a simple program such as DisplayImage.cpp shown below. 
+Let's use a simple program such as DisplayImage.cpp shown below.
 
 .. code-block:: cpp
 
@@ -36,9 +36,9 @@ Let's use a simple program such as DisplayImage.cpp shown below.
      image = imread( argv[1], 1 );
 
      if( argc != 2 || !image.data )
-       { 
+       {
          printf( "No image data \n" );
-         return -1; 
+         return -1;
        }
 
      namedWindow( "Display Image", CV_WINDOW_AUTOSIZE );
index e3039ca..e8b96da 100644 (file)
@@ -11,8 +11,8 @@ Required Packages
 
     .. code-block:: bash
 
-       sudo apt-get install build-essential 
+       sudo apt-get install build-essential
+
   * CMake 2.6 or higher;
   * Git;
   * GTK+2.x or higher, including headers (libgtk2.0-dev);
@@ -48,7 +48,7 @@ In Linux it can be achieved with the following command in Terminal:
 
    cd ~/<my_working _directory>
    git clone https://github.com/Itseez/opencv.git
+
 
 Building OpenCV from Source Using CMake, Using the Command Line
 ===============================================================
@@ -58,26 +58,26 @@ Building OpenCV from Source Using CMake, Using the Command Line
 #. Enter the <cmake_binary_dir> and type
 
    .. code-block:: bash
-     
+
       cmake [<some optional parameters>] <path to the OpenCV source directory>
 
    For example
 
    .. code-block:: bash
-       
+
       cd ~/opencv
       mkdir release
       cd release
       cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local ..
-       
+
 #. Enter the created temporary directory (<cmake_binary_dir>) and proceed with:
 
    .. code-block:: bash
-      
+
       make
       sudo make install
 
 .. note::
-  
+
    If the size of the created library is a critical issue (like in case of an Android build) you can use the ``install/strip`` command to get the smallest size as possible. The *stripped* version appears to be twice as small. However, we do not recommend using this unless those extra megabytes do really matter.
 
index 6ea6499..7dfd8c9 100644 (file)
@@ -5,8 +5,8 @@ Load, Modify, and Save an Image
 
 .. note::
 
-   We assume that by now you know how to load an image using :imread:`imread <>` and to display it in a window (using :imshow:`imshow <>`). Read the :ref:`Display_Image` tutorial otherwise. 
+   We assume that by now you know how to load an image using :imread:`imread <>` and to display it in a window (using :imshow:`imshow <>`). Read the :ref:`Display_Image` tutorial otherwise.
+
 Goals
 ======
 
@@ -35,9 +35,9 @@ Here it is:
    {
     char* imageName = argv[1];
 
-    Mat image; 
+    Mat image;
     image = imread( imageName, 1 );
-  
+
     if( argc != 2 || !image.data )
     {
       printf( " No image data \n " );
@@ -53,7 +53,7 @@ Here it is:
     namedWindow( "Gray image", CV_WINDOW_AUTOSIZE );
 
     imshow( imageName, image );
-    imshow( "Gray image", gray_image ); 
+    imshow( "Gray image", gray_image );
 
     waitKey(0);
 
@@ -67,18 +67,18 @@ Explanation
 
    * Creating a Mat object to store the image information
    * Load an image using :imread:`imread <>`, located in the path given by *imageName*. Fort this example, assume you are loading a RGB image.
-   
-#. Now we are going to convert our image from RGB to Grayscale format. OpenCV has a really nice function to do this kind of transformations: 
+
+#. Now we are going to convert our image from RGB to Grayscale format. OpenCV has a really nice function to do this kind of transformations:
 
    .. code-block:: cpp
-     
+
       cvtColor( image, gray_image, CV_RGB2GRAY );
 
    As you can see, :cvt_color:`cvtColor <>` takes as arguments:
 
    .. container:: enumeratevisibleitemswithsquare
 
-      * a source image (*image*) 
+      * a source image (*image*)
       * a destination image (*gray_image*), in which we will save the converted image.
       * an additional parameter that indicates what kind of transformation will be performed. In this case we use **CV_RGB2GRAY** (self-explanatory).
 
@@ -86,7 +86,7 @@ Explanation
 
    .. code-block:: cpp
 
-      imwrite( "../../images/Gray_Image.jpg", gray_image );   
+      imwrite( "../../images/Gray_Image.jpg", gray_image );
 
    Which will save our *gray_image* as *Gray_Image.jpg* in the folder *images* located two levels up of my current location.
 
index 62acf0e..fd96ba0 100644 (file)
@@ -130,7 +130,7 @@ Building the library
 
 #. Install |TortoiseGit|_. Choose the 32 or 64 bit version according to the type of OS you work in. While installing, locate your msysgit (if it doesn't do that automatically). Follow the wizard -- the default options are OK for the most part.
 
-#. Choose a directory in your file system, where you will download the OpenCV libraries to. I recommend creating a new one that has short path and no special charachters in it, for example :file:`D:/OpenCV`. For this tutorial I'll suggest you do so. If you use your own path and know, what you're doing -- it's OK. 
+#. Choose a directory in your file system, where you will download the OpenCV libraries to. I recommend creating a new one that has short path and no special charachters in it, for example :file:`D:/OpenCV`. For this tutorial I'll suggest you do so. If you use your own path and know, what you're doing -- it's OK.
 
    a) Clone the repository to the selected directory. After clicking *Clone* button, a window will appear where you can select from what repository you want to download source files (https://github.com/Itseez/opencv.git) and to what directory (:file:`D:/OpenCV`).
 
index 71be06f..ec227e7 100644 (file)
@@ -10,16 +10,16 @@ I start out from the assumption that you have read and completed with success th
    :alt: You should have a folder looking like this.
    :align: center
 
-The OpenCV libraries, distributed by us, on the Microsoft Windows operating system are in a **D**\ ynamic **L**\ inked **L**\ ibraries (*DLL*). These have the advantage that all the content of the library are loaded only at runtime, on demand, and that countless programs may use the same library file. This means that if you have ten applications using the OpenCV library, no need to have around a version for each one of them. Of course you need to have the *dll* of the OpenCV on all systems where you want to run your application. 
+The OpenCV libraries, distributed by us, on the Microsoft Windows operating system are in a **D**\ ynamic **L**\ inked **L**\ ibraries (*DLL*). These have the advantage that all the content of the library are loaded only at runtime, on demand, and that countless programs may use the same library file. This means that if you have ten applications using the OpenCV library, no need to have around a version for each one of them. Of course you need to have the *dll* of the OpenCV on all systems where you want to run your application.
 
 Another approach is to use static libraries that have *lib* extensions. You may build these by using our source files as described in the :ref:`Windows_Installation` tutorial. When you use this the library will be built-in inside your *exe* file.  So there is no chance that the user deletes them, for some reason. As a drawback your application will be larger one and as, it will take more time to load it during its startup.
 
-To build an application with OpenCV you need to do two things: 
+To build an application with OpenCV you need to do two things:
 
 .. container:: enumeratevisibleitemswithsquare
 
-  + *Tell* to the compiler how the OpenCV library *looks*. You do this by *showing* it the header files. 
-  + *Tell* to the linker from where to get the functions or data structures of OpenCV, when they are needed. 
+  + *Tell* to the compiler how the OpenCV library *looks*. You do this by *showing* it the header files.
+  + *Tell* to the linker from where to get the functions or data structures of OpenCV, when they are needed.
 
     If you use the *lib* system you must set the path where the library files are and specify in which one of them to look. During the build the linker will look into these libraries and add the definitions and implementation of all *used* functions and data structures to the executable file.
 
@@ -27,7 +27,7 @@ To build an application with OpenCV you need to do two things:
 
 To pass on all this information to the Visual Studio IDE you can either do it globally (so all your future projects will get these information) or locally (so only for you current project). The advantage of the global one is that you only need to do it once; however, it may be undesirable to clump all your projects all the time with all these information. In case of the global one how you do it depends on the Microsoft Visual Studio you use. There is a **2008 and previous versions** and a **2010 way** of doing it. Inside the global section of this tutorial I'll show what the main differences are.
 
-The base item of a project in Visual Studio is a solution. A solution may contain multiple projects. Projects are the building blocks of an application. Every project will realize something and you will have a main project in which you can put together this project puzzle. In case of the many simple applications (like many of the tutorials will be) you do not need to break down the application into modules. In these cases your main project will be the only existing one. Now go create a new solution inside Visual studio by going through the :menuselection:`File --> New --> Project` menu selection. Choose *Win32 Console Application* as type. Enter its name and select the path where to create it. Then in the upcoming dialog make sure you create an empty project. 
+The base item of a project in Visual Studio is a solution. A solution may contain multiple projects. Projects are the building blocks of an application. Every project will realize something and you will have a main project in which you can put together this project puzzle. In case of the many simple applications (like many of the tutorials will be) you do not need to break down the application into modules. In these cases your main project will be the only existing one. Now go create a new solution inside Visual studio by going through the :menuselection:`File --> New --> Project` menu selection. Choose *Win32 Console Application* as type. Enter its name and select the path where to create it. Then in the upcoming dialog make sure you create an empty project.
 
 .. image:: images/NewProjectVisualStudio.jpg
    :alt: Which options to select
@@ -36,7 +36,7 @@ The base item of a project in Visual Studio is a solution. A solution may contai
 The *local* method
 ==================
 
-Every project is built separately from the others. Due to this every project has its own rule package. Inside this rule packages are stored all the information the *IDE* needs to know to build your project. For any application there are at least two build modes: a *Release* and a *Debug* one. The *Debug* has many features that exist so you can find and resolve easier bugs inside your application. In contrast the *Release* is an optimized version, where the goal is to make the application run as fast as possible or to be as small as possible. You may figure that these modes also require different rules to use during build. Therefore, there exist different rule packages for each of your build modes. These rule packages are called inside the IDE as *project properties* and you can view and modify them by using the *Property Manger*. You can bring up this with :menuselection:`View --> Property Pages`. Expand it and you can see the existing rule packages (called *Proporty Sheets*). 
+Every project is built separately from the others. Due to this every project has its own rule package. Inside this rule packages are stored all the information the *IDE* needs to know to build your project. For any application there are at least two build modes: a *Release* and a *Debug* one. The *Debug* has many features that exist so you can find and resolve easier bugs inside your application. In contrast the *Release* is an optimized version, where the goal is to make the application run as fast as possible or to be as small as possible. You may figure that these modes also require different rules to use during build. Therefore, there exist different rule packages for each of your build modes. These rule packages are called inside the IDE as *project properties* and you can view and modify them by using the *Property Manger*. You can bring up this with :menuselection:`View --> Property Pages`. Expand it and you can see the existing rule packages (called *Proporty Sheets*).
 
 .. image:: images/PropertyPageExample.jpg
    :alt: An example of Property Sheet
@@ -55,10 +55,10 @@ Use for example the *OpenCV_Debug* name. Then by selecting the sheet :menuselect
    $(OPENCV_DIR)\include
 
 .. image:: images/PropertySheetOpenCVInclude.jpg
-   :alt: Add the include dir like this. 
+   :alt: Add the include dir like this.
    :align: center
 
-When adding third party libraries settings it is generally a good idea to use the power behind the environment variables. The full location of the OpenCV library may change on each system. Moreover, you may even end up yourself with moving the install directory for some reason. If you would give explicit paths inside your property sheet your project will end up not working when you pass it further to someone else who has a different OpenCV install path. Moreover, fixing this would require to manually modifying every explicit path. A more elegant solution is to use the environment variables. Anything that you put inside a parenthesis started with a dollar sign will be replaced at runtime with the current environment variables value. Here comes in play the environment variable setting we already made in our :ref:`previous tutorial <WindowsSetPathAndEnviromentVariable>`. 
+When adding third party libraries settings it is generally a good idea to use the power behind the environment variables. The full location of the OpenCV library may change on each system. Moreover, you may even end up yourself with moving the install directory for some reason. If you would give explicit paths inside your property sheet your project will end up not working when you pass it further to someone else who has a different OpenCV install path. Moreover, fixing this would require to manually modifying every explicit path. A more elegant solution is to use the environment variables. Anything that you put inside a parenthesis started with a dollar sign will be replaced at runtime with the current environment variables value. Here comes in play the environment variable setting we already made in our :ref:`previous tutorial <WindowsSetPathAndEnviromentVariable>`.
 
 Next go to the :menuselection:`Linker --> General` and under the *"Additional Library Directories"* add the libs directory:
 
@@ -67,7 +67,7 @@ Next go to the :menuselection:`Linker --> General` and under the *"Additional Li
    $(OPENCV_DIR)\libs
 
 .. image:: images/PropertySheetOpenCVLib.jpg
-   :alt: Add the library folder like this. 
+   :alt: Add the library folder like this.
    :align: center
 
 Then you need to specify the libraries in which the linker should look into. To do this go to the :menuselection:`Linker --> Input` and under the *"Additional Dependencies"* entry add the name of all modules which you want to use:
@@ -77,7 +77,7 @@ Then you need to specify the libraries in which the linker should look into. To
    :align: center
 
 .. image:: images/PropertySheetOpenCVLibrariesDebug.jpg
-   :alt: Like this. 
+   :alt: Like this.
    :align: center
 
 The names of the libraries are as follow:
@@ -105,33 +105,33 @@ A full list, for the currently latest trunk version would contain:
 The letter *d* at the end just indicates that these are the libraries required for the debug. Now click ok to save and do the same with a new property inside the Release rule section. Make sure to omit the *d* letters from the library names and to save the property sheets with the save icon above them.
 
 .. image:: images/PropertySheetOpenCVLibrariesRelease.jpg
-   :alt: And the release ones. 
+   :alt: And the release ones.
    :align: center
 
-You can find your property sheets inside your projects directory. At this point it is a wise decision to back them up into some special directory, to always have them at hand in the future, whenever you create an OpenCV project. Note that for Visual Studio 2010 the file extension is *props*, while for 2008 this is *vsprops*. 
+You can find your property sheets inside your projects directory. At this point it is a wise decision to back them up into some special directory, to always have them at hand in the future, whenever you create an OpenCV project. Note that for Visual Studio 2010 the file extension is *props*, while for 2008 this is *vsprops*.
 
 .. image:: images/PropertySheetInsideFolder.jpg
-   :alt: And the release ones. 
+   :alt: And the release ones.
    :align: center
 
-Next time when you make a new OpenCV project just use the "Add Existing Property Sheet..." menu entry inside the Property Manager to easily add the OpenCV build rules. 
+Next time when you make a new OpenCV project just use the "Add Existing Property Sheet..." menu entry inside the Property Manager to easily add the OpenCV build rules.
 
 .. image:: images/PropertyPageAddExisting.jpg
-   :alt: Use this option. 
+   :alt: Use this option.
    :align: center
 
 The *global* method
 ===================
 
-In case you find to troublesome to add the property pages to each and every one of your projects you can also add this rules to a *"global property page"*. However, this applies only to the additional include and library directories. The name of the libraries to use you still need to specify manually by using for instance: a Property page. 
+In case you find to troublesome to add the property pages to each and every one of your projects you can also add this rules to a *"global property page"*. However, this applies only to the additional include and library directories. The name of the libraries to use you still need to specify manually by using for instance: a Property page.
 
-In Visual Studio 2008 you can find this under the:  :menuselection:`Tools --> Options --> Projects and Solutions --> VC++ Directories`. 
+In Visual Studio 2008 you can find this under the:  :menuselection:`Tools --> Options --> Projects and Solutions --> VC++ Directories`.
 
 .. image:: images/VCDirectories2008.jpg
    :alt: VC++ Directories in VS 2008.
    :align: center
 
-In Visual Studio 2010 this has been moved to a global property sheet which is automatically added to every project you create: 
+In Visual Studio 2010 this has been moved to a global property sheet which is automatically added to every project you create:
 
 .. image:: images/VCDirectories2010.jpg
    :alt: VC++ Directories in VS 2010.
@@ -153,10 +153,10 @@ You can start a Visual Studio build from two places. Either inside from the *IDE
 
 .. |voila| unicode:: voil U+00E1
 
-This is important to remember when you code inside the code open and save commands. You're resources will be saved ( and queried for at opening!!!) relatively to your working directory. This is unless you give a full, explicit path as parameter for the I/O functions. In the code above we open :download:`this OpenCV logo<../../../../samples/cpp/tutorial_code/images/opencv-logo.png>`. Before starting up the application make sure you place the image file in your current working directory. Modify the image file name inside the code to try it out on other images too. Run it and |voila|: 
+This is important to remember when you code inside the code open and save commands. You're resources will be saved ( and queried for at opening!!!) relatively to your working directory. This is unless you give a full, explicit path as parameter for the I/O functions. In the code above we open :download:`this OpenCV logo<../../../../samples/cpp/tutorial_code/images/opencv-logo.png>`. Before starting up the application make sure you place the image file in your current working directory. Modify the image file name inside the code to try it out on other images too. Run it and |voila|:
 
 .. image:: images/SuccessVisualStudioWindows.jpg
-   :alt: You should have this. 
+   :alt: You should have this.
    :align: center
 
 Command line arguments with Visual Studio
@@ -167,11 +167,11 @@ Throughout some of our future tutorials you'll see that the programs main input
 .. code-block:: bash
    :linenos:
 
-   D: 
+   D:
    CD OpenCV\MySolutionName\Release
    MySolutionName.exe exampleImage.jpg
 
-Here I first changed my drive (if your project isn't on the OS local drive), navigated to my project and start it with an example image argument. While under Linux system it is common to fiddle around with the console window on the Microsoft Windows many people come to use it almost never. Besides, adding the same argument again and again while you are testing your application is, somewhat, a cumbersome task. Luckily, in the Visual Studio there is a menu to automate all this: 
+Here I first changed my drive (if your project isn't on the OS local drive), navigated to my project and start it with an example image argument. While under Linux system it is common to fiddle around with the console window on the Microsoft Windows many people come to use it almost never. Besides, adding the same argument again and again while you are testing your application is, somewhat, a cumbersome task. Luckily, in the Visual Studio there is a menu to automate all this:
 
 .. image:: images/VisualStudioCommandLineArguments.jpg
    :alt: Visual Studio Command Line Arguments
index 8e6ddb8..b2a37aa 100644 (file)
@@ -19,7 +19,7 @@ Follow this step by step guide to link OpenCV to iOS.
 
 1. Create a new XCode project.
 
-2. Now we need to link *opencv2.framework* with Xcode. Select the project Navigator in the left hand panel and click on project name.  
+2. Now we need to link *opencv2.framework* with Xcode. Select the project Navigator in the left hand panel and click on project name.
 
 3. Under the TARGETS click on Build Phases. Expand Link Binary With Libraries option.
 
@@ -29,10 +29,10 @@ Follow this step by step guide to link OpenCV to iOS.
 
 .. image:: images/linking_opencv_ios.png
      :alt: OpenCV iOS in Xcode
-     :align: center 
+     :align: center
 
 *Hello OpenCV iOS Application*
-=============================== 
+===============================
 
 Now we will learn how to write a simple Hello World Application in Xcode using OpenCV.
 
@@ -43,13 +43,13 @@ Now we will learn how to write a simple Hello World Application in Xcode using O
 
 .. code-block:: cpp
 
-       #ifdef __cplusplus
-       #import <opencv2/opencv.hpp>
-       #endif
+    #ifdef __cplusplus
+    #import <opencv2/opencv.hpp>
+    #endif
 
 .. image:: images/header_directive.png
      :alt: header
-     :align: center 
+     :align: center
 
 .. container:: enumeratevisibleitemswithsquare
 
@@ -61,7 +61,7 @@ Now we will learn how to write a simple Hello World Application in Xcode using O
 
 .. image:: images/view_did_load.png
      :alt: view did load
-     :align: center 
+     :align: center
 
 .. container:: enumeratevisibleitemswithsquare
 
@@ -73,4 +73,4 @@ Now we will learn how to write a simple Hello World Application in Xcode using O
 .. image:: images/output.png
      :alt: output
      :align: center
-                
+
index e8d4aad..fd2d9c6 100644 (file)
@@ -21,9 +21,9 @@ In *OpenCV* all the image processing operations are done on *Mat*. iOS uses UIIm
      CGColorSpaceRef colorSpace = CGImageGetColorSpace(image.CGImage);
      CGFloat cols = image.size.width;
      CGFloat rows = image.size.height;
-    
+
      cv::Mat cvMat(rows, cols, CV_8UC4); // 8 bits per component, 4 channels
-    
+
      CGContextRef contextRef = CGBitmapContextCreate(cvMat.data,                 // Pointer to  data
                                                     cols,                       // Width of bitmap
                                                     rows,                       // Height of bitmap
@@ -32,11 +32,11 @@ In *OpenCV* all the image processing operations are done on *Mat*. iOS uses UIIm
                                                     colorSpace,                 // Colorspace
                                                     kCGImageAlphaNoneSkipLast |
                                                     kCGBitmapByteOrderDefault); // Bitmap info flags
-    
+
      CGContextDrawImage(contextRef, CGRectMake(0, 0, cols, rows), image.CGImage);
      CGContextRelease(contextRef);
      CGColorSpaceRelease(colorSpace);
-    
+
      return cvMat;
    }
 
@@ -47,9 +47,9 @@ In *OpenCV* all the image processing operations are done on *Mat*. iOS uses UIIm
      CGColorSpaceRef colorSpace = CGImageGetColorSpace(image.CGImage);
      CGFloat cols = image.size.width;
      CGFloat rows = image.size.height;
-    
+
      cv::Mat cvMat(rows, cols, CV_8UC1); // 8 bits per component, 1 channels
-    
+
      CGContextRef contextRef = CGBitmapContextCreate(cvMat.data,                 // Pointer to data
                                                     cols,                       // Width of bitmap
                                                     rows,                       // Height of bitmap
@@ -58,11 +58,11 @@ In *OpenCV* all the image processing operations are done on *Mat*. iOS uses UIIm
                                                     colorSpace,                 // Colorspace
                                                     kCGImageAlphaNoneSkipLast |
                                                     kCGBitmapByteOrderDefault); // Bitmap info flags
-    
+
      CGContextDrawImage(contextRef, CGRectMake(0, 0, cols, rows), image.CGImage);
      CGContextRelease(contextRef);
      CGColorSpaceRelease(colorSpace);
-    
+
      return cvMat;
     }
 
@@ -81,15 +81,15 @@ After the processing we need to convert it back to UIImage.
    {
      NSData *data = [NSData dataWithBytes:cvMat.data length:cvMat.elemSize()*cvMat.total()];
      CGColorSpaceRef colorSpace;
-    
+
      if (cvMat.elemSize() == 1) {
          colorSpace = CGColorSpaceCreateDeviceGray();
      } else {
          colorSpace = CGColorSpaceCreateDeviceRGB();
      }
-    
+
      CGDataProviderRef provider = CGDataProviderCreateWithCFData((__bridge CFDataRef)data);
-    
+
      // Creating CGImage from cv::Mat
      CGImageRef imageRef = CGImageCreate(cvMat.cols,                                 //width
                                         cvMat.rows,                                 //height
@@ -103,15 +103,15 @@ After the processing we need to convert it back to UIImage.
                                         false,                                      //should interpolate
                                         kCGRenderingIntentDefault                   //intent
                                         );
-    
-    
+
+
      // Getting UIImage from CGImage
      UIImage *finalImage = [UIImage imageWithCGImage:imageRef];
      CGImageRelease(imageRef);
      CGDataProviderRelease(provider);
      CGColorSpaceRelease(colorSpace);
-    
-     return finalImage; 
+
+     return finalImage;
     }
 
 *Output*
@@ -119,9 +119,9 @@ After the processing we need to convert it back to UIImage.
 
 .. image:: images/output.jpg
      :alt: header
-     :align: center 
+     :align: center
 
-Check out an instance of running code with more Image Effects on `YouTube <http://www.youtube.com/watch?v=Ko3K_xdhJ1I>`_ . 
+Check out an instance of running code with more Image Effects on `YouTube <http://www.youtube.com/watch?v=Ko3K_xdhJ1I>`_ .
 
 .. raw:: html
 
index 5ecda41..377446d 100644 (file)
@@ -69,7 +69,7 @@
 
 .. toctree::
    :hidden:
-   
+
    ../hello/hello
    ../image_manipulation/image_manipulation
    ../video_processing/video_processing
index 6143f77..84ccfcf 100644 (file)
@@ -17,35 +17,35 @@ Including OpenCV library in your iOS project
 
 The OpenCV library comes as a so-called framework, which you can directly drag-and-drop into your XCode project. Download the latest binary from <http://sourceforge.net/projects/opencvlibrary/files/opencv-ios/>. Alternatively follow this guide :ref:`iOS-Installation` to compile the framework manually. Once you have the framework, just drag-and-drop into XCode:
 
-       .. image:: images/xcode_hello_ios_framework_drag_and_drop.png
-       
-       
+    .. image:: images/xcode_hello_ios_framework_drag_and_drop.png
+
+
 Also you have to locate the prefix header that is used for all header files in the project. The file is typically located at "ProjectName/Supporting Files/ProjectName-Prefix.pch". There, you have add an include statement to import the opencv library. However, make sure you include opencv before you include UIKit and Foundation, because else you will get some weird compile errors that some macros like min and max are defined multiple times. For example the prefix header could look like the following:
 
 .. code-block:: objc
-       :linenos:
-       
-       //
-       // Prefix header for all source files of the 'VideoFilters' target in the 'VideoFilters' project
-       //
-       
-       #import <Availability.h>
-       
-       #ifndef __IPHONE_4_0
-       #warning "This project uses features only available in iOS SDK 4.0 and later."
-       #endif
-       
-       #ifdef __cplusplus
-       #import <opencv2/opencv.hpp>
-       #endif
-       
-       #ifdef __OBJC__
-               #import <UIKit/UIKit.h>
-               #import <Foundation/Foundation.h>
-       #endif
-       
-       
-       
+    :linenos:
+
+    //
+    // Prefix header for all source files of the 'VideoFilters' target in the 'VideoFilters' project
+    //
+
+    #import <Availability.h>
+
+    #ifndef __IPHONE_4_0
+    #warning "This project uses features only available in iOS SDK 4.0 and later."
+    #endif
+
+    #ifdef __cplusplus
+    #import <opencv2/opencv.hpp>
+    #endif
+
+    #ifdef __OBJC__
+        #import <UIKit/UIKit.h>
+        #import <Foundation/Foundation.h>
+    #endif
+
+
+
 Example video frame processing project
 --------------------------------------
 User Interface
@@ -53,63 +53,63 @@ User Interface
 
 First, we create a simple iOS project, for example Single View Application. Then, we create and add an UIImageView and UIButton to start the camera and display the video frames. The storyboard could look like that:
 
-       .. image:: images/xcode_hello_ios_viewcontroller_layout.png
+    .. image:: images/xcode_hello_ios_viewcontroller_layout.png
 
 
 Make sure to add and connect the IBOutlets and IBActions to the corresponding ViewController:
 
 .. code-block:: objc
-       :linenos:
-       
-       @interface ViewController : UIViewController
-       {
-               IBOutlet UIImageView* imageView;
-               IBOutlet UIButton* button;
-       }
-       
-       - (IBAction)actionStart:(id)sender;
-       
-       @end
-       
-       
+    :linenos:
+
+    @interface ViewController : UIViewController
+    {
+        IBOutlet UIImageView* imageView;
+        IBOutlet UIButton* button;
+    }
+
+    - (IBAction)actionStart:(id)sender;
+
+    @end
+
+
 Adding the Camera
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We add a camera controller to the view controller and initialize it when the view has loaded:
 
 .. code-block:: objc
-       :linenos:
-       
-       #import <opencv2/highgui/cap_ios.h>
-       using namespace cv;
-       
-       
-       @interface ViewController : UIViewController
-       {
-               ...     
-               CvVideoCamera* videoCamera;
-       }
-       ...
-       @property (nonatomic, retain) CvVideoCamera* videoCamera;
-       
-       @end
-       
+    :linenos:
+
+    #import <opencv2/highgui/cap_ios.h>
+    using namespace cv;
+
+
+    @interface ViewController : UIViewController
+    {
+        ...
+        CvVideoCamera* videoCamera;
+    }
+    ...
+    @property (nonatomic, retain) CvVideoCamera* videoCamera;
+
+    @end
+
 .. code-block:: objc
-       :linenos:
-
-       - (void)viewDidLoad
-       {
-               [super viewDidLoad];
-               // Do any additional setup after loading the view, typically from a nib.
-               
-               self.videoCamera = [[CvVideoCamera alloc] initWithParentView:imageView];
-               self.videoCamera.defaultAVCaptureDevicePosition = AVCaptureDevicePositionFront;
-               self.videoCamera.defaultAVCaptureSessionPreset = AVCaptureSessionPreset352x288;
-               self.videoCamera.defaultAVCaptureVideoOrientation = AVCaptureVideoOrientationPortrait;
-               self.videoCamera.defaultFPS = 30;
-               self.videoCamera.grayscale = NO;
-       }
-       
+    :linenos:
+
+    - (void)viewDidLoad
+    {
+        [super viewDidLoad];
+        // Do any additional setup after loading the view, typically from a nib.
+
+        self.videoCamera = [[CvVideoCamera alloc] initWithParentView:imageView];
+        self.videoCamera.defaultAVCaptureDevicePosition = AVCaptureDevicePositionFront;
+        self.videoCamera.defaultAVCaptureSessionPreset = AVCaptureSessionPreset352x288;
+        self.videoCamera.defaultAVCaptureVideoOrientation = AVCaptureVideoOrientationPortrait;
+        self.videoCamera.defaultFPS = 30;
+        self.videoCamera.grayscale = NO;
+    }
+
 In this case, we initialize the camera and provide the imageView as a target for rendering each frame. CvVideoCamera is basically a wrapper around AVFoundation, so we provie as properties some of the AVFoundation camera options. For example we want to use the front camera, set the video size to 352x288 and a video orientation (the video camera normally outputs in landscape mode, which results in transposed data when you design a portrait application).
 
 The property defaultFPS sets the FPS of the camera. If the processing is less fast than the desired FPS, frames are automatically dropped.
@@ -143,7 +143,7 @@ Additionally, we have to manually add framework dependencies of the opencv frame
 * Foundation
 
 
-       .. image:: images/xcode_hello_ios_frameworks_add_dependencies.png
+    .. image:: images/xcode_hello_ios_frameworks_add_dependencies.png
 
 
 Processing frames
@@ -152,35 +152,35 @@ Processing frames
 We follow the delegation pattern, which is very common in iOS, to provide access to each camera frame. Basically, the View Controller has to implement the CvVideoCameraDelegate protocol and has to be set as delegate to the video camera:
 
 .. code-block:: objc
-       :linenos:
-       
-       @interface ViewController : UIViewController<CvVideoCameraDelegate>
-       
+    :linenos:
+
+    @interface ViewController : UIViewController<CvVideoCameraDelegate>
+
 
 
 .. code-block:: objc
-       :linenos:
-       
-       - (void)viewDidLoad
-       {
-               ...
-               self.videoCamera = [[CvVideoCamera alloc] initWithParentView:imageView];
-               self.videoCamera.delegate = self;
-               ...
-       }
+    :linenos:
+
+    - (void)viewDidLoad
+    {
+        ...
+        self.videoCamera = [[CvVideoCamera alloc] initWithParentView:imageView];
+        self.videoCamera.delegate = self;
+        ...
+    }
 
 
 .. code-block:: objc
-       :linenos:
+    :linenos:
 
-       #pragma mark - Protocol CvVideoCameraDelegate
+    #pragma mark - Protocol CvVideoCameraDelegate
 
-       #ifdef __cplusplus
-       - (void)processImage:(Mat&)image;
-       {
-               // Do some OpenCV stuff with the image
-       }
-       #endif
+    #ifdef __cplusplus
+    - (void)processImage:(Mat&)image;
+    {
+        // Do some OpenCV stuff with the image
+    }
+    #endif
 
 Note that we are using C++ here (cv::Mat).
 Important: You have to rename the view controller's extension .m into .mm, so that the compiler compiles it under the assumption of Objective-C++ (Objective-C and C++ mixed). Then, __cplusplus is defined when the compiler is processing the file for C++ code. Therefore, we put our code within a block where __cplusplus is defined.
@@ -193,18 +193,18 @@ From here you can start processing video frames. For example the following snipp
 
 
 .. code-block:: objc
-       :linenos:
-       
-       - (void)processImage:(Mat&)image;
-       {
-               // Do some OpenCV stuff with the image
-               Mat image_copy;
-               cvtColor(image, image_copy, CV_BGRA2BGR);
-               
-               // invert image
-               bitwise_not(image_copy, image_copy);
-               cvtColor(image_copy, image, CV_BGR2BGRA);
-       }
+    :linenos:
+
+    - (void)processImage:(Mat&)image;
+    {
+        // Do some OpenCV stuff with the image
+        Mat image_copy;
+        cvtColor(image, image_copy, CV_BGRA2BGR);
+
+        // invert image
+        bitwise_not(image_copy, image_copy);
+        cvtColor(image_copy, image, CV_BGR2BGRA);
+    }
 
 
 Start!
@@ -213,14 +213,14 @@ Start!
 Finally, we have to tell the camera to actually start/stop working. The following code will start the camera when you press the button, assuming you connected the UI properly:
 
 .. code-block:: objc
-       :linenos:
-       
-       #pragma mark - UI Actions
-       
-       - (IBAction)actionStart:(id)sender;
-       {
-               [self.videoCamera start];
-       }
+    :linenos:
+
+    #pragma mark - UI Actions
+
+    - (IBAction)actionStart:(id)sender;
+    {
+        [self.videoCamera start];
+    }
 
 
 
index cdad3de..051765d 100644 (file)
@@ -10,7 +10,7 @@ In this tutorial you will learn how to:
 
 .. container:: enumeratevisibleitemswithsquare
 
-   + Use the OpenCV functions :svms:`CvSVM::train <cvsvm-train>` to build a classifier based on SVMs and :svms:`CvSVM::predict <cvsvm-predict>` to test its performance.  
+   + Use the OpenCV functions :svms:`CvSVM::train <cvsvm-train>` to build a classifier based on SVMs and :svms:`CvSVM::predict <cvsvm-predict>` to test its performance.
 
 What is a SVM?
 ==============
@@ -36,14 +36,14 @@ Then, the operation of the SVM algorithm is based on finding the hyperplane that
 
 .. image:: images/optimal-hyperplane.png
    :alt: The Optimal hyperplane
-   :align: center 
+   :align: center
 
 How is the optimal hyperplane computed?
 =======================================
 
 Let's introduce the notation used to define formally a hyperplane:
 
-.. math:: 
+.. math::
   f(x) = \beta_{0} + \beta^{T} x,
 
 where :math:`\beta` is known as the *weight vector* and :math:`\beta_{0}` as the *bias*.
@@ -106,7 +106,7 @@ Explanation
   .. code-block:: cpp
 
      Mat trainingDataMat(3, 2, CV_32FC1, trainingData);
-     Mat labelsMat      (3, 1, CV_32FC1, labels);    
+     Mat labelsMat      (3, 1, CV_32FC1, labels);
 
 2. **Set up SVM's parameters**
 
@@ -143,7 +143,7 @@ Explanation
   .. code-block:: cpp
 
      Vec3b green(0,255,0), blue (255,0,0);
-     
+
      for (int i = 0; i < image.rows; ++i)
          for (int j = 0; j < image.cols; ++j)
          {
@@ -152,8 +152,8 @@ Explanation
 
          if (response == 1)
             image.at<Vec3b>(j, i)  = green;
-         else 
-         if (response == -1) 
+         else
+         if (response == -1)
             image.at<Vec3b>(j, i)  = blue;
          }
 
@@ -184,5 +184,5 @@ Results
 
 .. image:: images/result.png
   :alt: The seperated planes
-  :align: center 
+  :align: center
 
index 452b896..4691756 100644 (file)
@@ -5,9 +5,9 @@
 
 Use the powerfull machine learning classes for statistical classification, regression and clustering of data.
 
-.. include:: ../../definitions/tocDefinitions.rst 
+.. include:: ../../definitions/tocDefinitions.rst
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
@@ -18,7 +18,7 @@ Use the powerfull machine learning classes for statistical classification, regre
 
                *Author:* |Author_FernandoI|
 
-               Learn what a Suport Vector Machine is. 
+               Learn what a Suport Vector Machine is.
 
   ============ ==============================================
 
@@ -26,7 +26,7 @@ Use the powerfull machine learning classes for statistical classification, regre
      :height: 90pt
      :width:  90pt
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
@@ -51,6 +51,6 @@ Use the powerfull machine learning classes for statistical classification, regre
 
 .. toctree::
    :hidden:
-   
+
    ../introduction_to_svm/introduction_to_svm
    ../non_linear_svms/non_linear_svms
index 64ed109..c9df3eb 100644 (file)
@@ -5,23 +5,23 @@
 
 Ever wondered how your digital camera detects peoples and faces? Look here to find out!
 
-.. include:: ../../definitions/tocDefinitions.rst 
+.. include:: ../../definitions/tocDefinitions.rst
 
-+ 
++
   .. tabularcolumns:: m{100pt} m{300pt}
   .. cssclass:: toctableopencv
 
   ===================== ==============================================
    |CascadeClassif|     **Title:** :ref:`cascade_classifier`
-  
+
                         *Compatibility:* > OpenCV 2.0
-                        
+
                         *Author:* |Author_AnaH|
-                        
+
                         Here we learn how to use *objdetect* to find objects in our images or videos
-  
+
   ===================== ==============================================
-  
+
   .. |CascadeClassif| image:: images/Cascade_Classifier_Tutorial_Cover.jpg
                       :height: 90pt
                       :width:  90pt
index 778bc5c..a2521d6 100644 (file)
@@ -3,7 +3,7 @@
 *video* module. Video analysis
 -----------------------------------------------------------
 
-Look here in order to find use on your video stream algoritms like: motion extraction, feature tracking and foreground extractions. 
+Look here in order to find use on your video stream algoritms like: motion extraction, feature tracking and foreground extractions.
 
 .. include:: ../../definitions/noContent.rst
 
index ac56336..e3ef302 100644 (file)
@@ -78,7 +78,7 @@ First, we create an instance of a keypoint detector. All detectors inherit the a
     extractor.compute(img1, keypoints1, descriptors1);
     extractor.compute(img2, keypoints2, descriptors2);
 
-We create an instance of descriptor extractor. The most of OpenCV descriptors inherit ``DescriptorExtractor`` abstract interface. Then we compute descriptors for each of the keypoints. The output ``Mat`` of the ``DescriptorExtractor::compute`` method contains a descriptor in a row *i* for each *i*-th keypoint. Note that the method can modify the keypoints vector by removing the keypoints such that a descriptor for them is not defined (usually these are the keypoints near image border). The method makes sure that the ouptut keypoints and descriptors are consistent with each other (so that the number of keypoints is equal to the descriptors row count). :: 
+We create an instance of descriptor extractor. The most of OpenCV descriptors inherit ``DescriptorExtractor`` abstract interface. Then we compute descriptors for each of the keypoints. The output ``Mat`` of the ``DescriptorExtractor::compute`` method contains a descriptor in a row *i* for each *i*-th keypoint. Note that the method can modify the keypoints vector by removing the keypoints such that a descriptor for them is not defined (usually these are the keypoints near image border). The method makes sure that the ouptut keypoints and descriptors are consistent with each other (so that the number of keypoints is equal to the descriptors row count). ::
 
     // matching descriptors
     BruteForceMatcher<L2<float> > matcher;
index f4a75ea..ad930ba 100644 (file)
@@ -13,7 +13,7 @@ Images
 Load an image from a file: ::
 
     Mat img = imread(filename)
-    
+
 If you read a jpg file, a 3 channel image is created by default. If you need a grayscale image, use: ::
 
     Mat img = imread(filename, 0);
@@ -23,14 +23,14 @@ If you read a jpg file, a 3 channel image is created by default. If you need a g
 Save an image to a file: ::
 
     imwrite(filename, img);
-    
+
 .. note:: format of the file is determined by its extension.
 
 .. note:: use ``imdecode`` and ``imencode`` to read and write image from/to memory rather than a file.
 
 XML/YAML
 --------
-    
+
 TBD
 
 Basic operations with images
@@ -85,7 +85,7 @@ Memory management and reference counting
     // .. fill the array
     Mat pointsMat = Mat(points).reshape(1);
 
-As a result we get a 32FC1 matrix with 3 columns instead of 32FC3 matrix with 1 column. ``pointsMat`` uses data from ``points`` and will not deallocate the memory when destroyed. In this particular instance, however, developer has to make sure that lifetime of ``points`` is longer than of ``pointsMat``. 
+As a result we get a 32FC1 matrix with 3 columns instead of 32FC3 matrix with 1 column. ``pointsMat`` uses data from ``points`` and will not deallocate the memory when destroyed. In this particular instance, however, developer has to make sure that lifetime of ``points`` is longer than of ``pointsMat``.
 If we need to copy the data, this is done using, for example, ``Mat::copyTo`` or ``Mat::clone``: ::
 
     Mat img = imread("image.jpg");
@@ -115,7 +115,7 @@ A convertion from \texttt{Mat} to C API data structures: ::
     IplImage img1 = img;
     CvMat m = img;
 
-Note that there is no data copying here. 
+Note that there is no data copying here.
 
 Conversion from color to grey scale: ::
 
index cb5190b..601f504 100644 (file)
@@ -6,7 +6,7 @@ Cascade Classifier Training
 
 Introduction
 ============
-The work with a cascade classifier inlcudes two major stages: training and detection. 
+The work with a cascade classifier inlcudes two major stages: training and detection.
 Detection stage is described in a documentation of ``objdetect`` module of general OpenCV documentation. Documentation gives some basic information about cascade classifier.
 Current guide is describing how to train a cascade classifier: preparation of a training data and running the training application.
 
@@ -18,10 +18,10 @@ There are two applications in OpenCV to train cascade classifier: ``opencv_haart
 
 Note that ``opencv_traincascade`` application can use TBB for multi-threading. To use it in multicore mode OpenCV must be built with TBB.
 
-Also there are some auxilary utilities related to the training. 
+Also there are some auxilary utilities related to the training.
 
     * ``opencv_createsamples`` is used to prepare a training dataset of positive and test samples. ``opencv_createsamples`` produces dataset of positive samples in a format that is supported by both ``opencv_haartraining`` and ``opencv_traincascade`` applications. The output is a file with \*.vec extension, it is a binary format which contains images.
-    
+
     * ``opencv_performance`` may be used to evaluate the quality of classifiers, but for trained by ``opencv_haartraining`` only. It takes a collection of marked up images, runs the classifier and reports the performance, i.e. number of found objects, number of missed objects, number of false alarms and other information.
 
 Since ``opencv_haartraining`` is an obsolete application, only ``opencv_traincascade`` will be described futher. ``opencv_createsamples`` utility is  needed to prepare a training data for ``opencv_traincascade``, so it will be described too.
@@ -36,7 +36,7 @@ Negative Samples
 Negative samples are taken from arbitrary images. These images must not contain detected objects. Negative samples are enumerated in a special file. It is a text file in which each line contains an image filename (relative to the directory of the description file) of negative sample image. This file must be created manually. Note that negative samples and sample images are also called background samples or background samples images, and are used interchangeably in this document. Described images may be of different sizes. But each image should be (but not nessesarily) larger then a training window size, because these images are used to subsample negative image to the training size.
 
 An example of description file:
+
 Directory structure:
 
     .. code-block:: text
@@ -45,14 +45,14 @@ Directory structure:
           img1.jpg
           img2.jpg
         bg.txt
+
 File bg.txt:
 
     .. code-block:: text
 
         img/img1.jpg
         img/img2.jpg
-        
+
 Positive Samples
 ----------------
 Positive samples are created by ``opencv_createsamples`` utility. They may be created from a single image with object or from a collection of previously marked up images.
@@ -66,37 +66,37 @@ Command line arguments:
 * ``-vec <vec_file_name>``
 
     Name of the output file containing the positive samples for training.
-    
+
 * ``-img <image_file_name>``
 
     Source object image (e.g., a company logo).
-    
+
 * ``-bg <background_file_name>``
 
     Background description file; contains a list of images which are used as a background for randomly distorted versions of the object.
 
 * ``-num <number_of_samples>``
-    
+
     Number of positive samples to generate.
-    
+
 * ``-bgcolor <background_color>``
 
     Background color (currently grayscale images are assumed); the background color denotes the transparent color. Since there might be compression artifacts, the amount of color tolerance can be specified by ``-bgthresh``. All pixels withing ``bgcolor-bgthresh`` and ``bgcolor+bgthresh`` range are interpreted as transparent.
-    
+
 * ``-bgthresh <background_color_threshold>``
 
 * ``-inv``
-    
+
     If specified, colors will be inverted.
-    
+
 * ``-randinv``
 
     If specified, colors will be inverted randomly.
-      
+
 * ``-maxidev <max_intensity_deviation>``
+
     Maximal intensity deviation of pixels in foreground samples.
-    
+
 * ``-maxxangle <max_x_rotation_angle>``
 
 * ``-maxyangle <max_y_rotation_angle>``
@@ -104,15 +104,15 @@ Command line arguments:
 * ``-maxzangle <max_z_rotation_angle>``
 
       Maximum rotation angles must be given in radians.
-      
+
 * ``-show``
 
     Useful debugging option. If specified, each sample will be shown. Pressing ``Esc`` will continue the samples creation process without.
-    
+
 * ``-w <sample_width>``
 
     Width (in pixels) of the output samples.
-  
+
 * ``-h <sample_height>``
 
     Height (in pixels) of the output samples.
@@ -123,7 +123,7 @@ The source image is rotated randomly around all three axes. The chosen angle is
 Positive samples also may be obtained from a collection of previously marked up images. This collection is described by a text file similar to background description file. Each line of this file corresponds to an image. The first element of the line is the filename. It is followed by the number of object instances. The following numbers are the coordinates of objects bounding rectangles (x, y, width, height).
 
 An example of description file:
+
 Directory structure:
 
     .. code-block:: text
@@ -132,27 +132,27 @@ Directory structure:
           img1.jpg
           img2.jpg
         info.dat
+
 File info.dat:
 
     .. code-block:: text
-    
+
         img/img1.jpg  1  140 100 45 45
         img/img2.jpg  2  100 200 50 50   50 30 25 25
+
 Image img1.jpg contains single object instance with the following coordinates of bounding rectangle: (140, 100, 45, 45). Image img2.jpg contains two object instances.
+
 In order to create positive samples from such collection, ``-info`` argument should be specified instead of ``-img``:
 
 * ``-info <collection_file_name>``
 
     Description file of marked up images collection.
+
 The scheme of samples creation in this case is as follows. The object instances are taken from images. Then they are resized to target samples size and stored in output vec-file. No distortion is applied, so the only affecting arguments are ``-w``, ``-h``, ``-show`` and ``-num``.
+
 ``opencv_createsamples`` utility may be used for examining samples stored in positive samples file. In order to do this only ``-vec``, ``-w`` and ``-h`` parameters should be specified.
-Note that for training, it does not matter how vec-files with positive samples are generated. But ``opencv_createsamples`` utility is the only one way to collect/create a vector file of positive samples, provided by OpenCV. 
+
+Note that for training, it does not matter how vec-files with positive samples are generated. But ``opencv_createsamples`` utility is the only one way to collect/create a vector file of positive samples, provided by OpenCV.
 
 Example of vec-file is available here ``opencv/data/vec_files/trainingfaces_24-24.vec``. It can be used to train a face detector with the following window size: ``-w 24 -h 24``.
 
@@ -165,99 +165,99 @@ Command line arguments of ``opencv_traincascade`` application grouped by purpose
 #.
 
     Common arguments:
-    
+
     * ``-data <cascade_dir_name>``
-    
+
         Where the trained classifier should be stored.
-      
+
     * ``-vec <vec_file_name>``
-    
+
         vec-file with positive samples (created by ``opencv_createsamples`` utility).
-      
+
     * ``-bg <background_file_name>``
-    
+
         Background description file.
-      
+
     * ``-numPos <number_of_positive_samples>``
-    
+
     * ``-numNeg <number_of_negative_samples>``
-    
+
         Number of positive/negative samples used in training for every classifier stage.
-        
+
     * ``-numStages <number_of_stages>``
-    
+
         Number of cascade stages to be trained.
-        
+
     * ``-precalcValBufSize <precalculated_vals_buffer_size_in_Mb>``
-        
+
         Size of buffer for precalculated feature values (in Mb).
-        
+
     * ``-precalcIdxBufSize <precalculated_idxs_buffer_size_in_Mb>``
-    
+
         Size of buffer for precalculated feature indices (in Mb). The more memory you have the faster the training process.
-        
+
     * ``-baseFormatSave``
-        
+
         This argument is actual in case of Haar-like features. If it is specified, the cascade will be saved in the old format.
-        
+
 #.
 
     Cascade parameters:
 
     * ``-stageType <BOOST(default)>``
-    
+
         Type of stages. Only boosted classifier are supported as a stage type at the moment.
-        
+
     * ``-featureType<{HAAR(default), LBP}>``
-    
+
         Type of features: ``HAAR`` - Haar-like features, ``LBP`` - local binary patterns.
-    
+
     * ``-w <sampleWidth>``
-    
+
     * ``-h <sampleHeight>``
-    
+
         Size of training samples (in pixels). Must have exactly the same values as used during training samples creation (``opencv_createsamples`` utility).
-        
+
 #.
 
     Boosted classifer parameters:
-    
+
     * ``-bt <{DAB, RAB, LB, GAB(default)}>``
-    
+
         Type of boosted classifiers: ``DAB`` - Discrete AdaBoost, ``RAB`` - Real AdaBoost, ``LB`` - LogitBoost, ``GAB`` - Gentle AdaBoost.
-        
+
     * ``-minHitRate <min_hit_rate>``
-        
+
         Minimal desired hit rate for each stage of the classifier. Overall hit rate may be estimated as (min_hit_rate^number_of_stages).
-        
+
     * ``-maxFalseAlarmRate <max_false_alarm_rate>``
-    
+
       Maximal desired false alarm rate for each stage of the classifier. Overall false alarm rate may be estimated as (max_false_alarm_rate^number_of_stages).
-      
+
     * ``-weightTrimRate <weight_trim_rate>``
-    
+
         Specifies whether trimming should be used and its weight. A decent choice is 0.95.
-        
+
     * ``-maxDepth <max_depth_of_weak_tree>``
-    
+
         Maximal depth of a weak tree. A decent choice is 1, that is case of stumps.
-        
+
     * ``-maxWeakCount <max_weak_tree_count>``
-    
+
         Maximal count of weak trees for every cascade stage. The boosted classifier (stage) will have so many weak trees (``<=maxWeakCount``), as needed to achieve the given ``-maxFalseAlarmRate``.
-        
+
 #.
 
     Haar-like feature parameters:
-    
+
     * ``-mode <BASIC (default) | CORE | ALL>``
-    
+
         Selects the type of Haar features set used in training. ``BASIC`` use only upright features, while ``ALL`` uses the full set of upright and 45 degree rotated feature set. See [Rainer2002]_ for more details.
-    
-#.    
+
+#.
 
     Local Binary Patterns parameters:
-    
+
     Local Binary Patterns don't have parameters.
 
 After the ``opencv_traincascade`` application has finished its work, the trained cascade will be saved in cascade.xml file in the folder, which was passed as ``-data`` parameter. Other files in this folder are created for the case of interrupted training, so you may delete them after completion of training.
index 887accd..b072ba7 100644 (file)
@@ -1462,7 +1462,7 @@ Reconstructs points by triangulation.
 
     :param points4D: 4xN array of reconstructed points in homogeneous coordinates.
 
-The function reconstructs 3-dimensional points (in homogeneous coordinates) by using their observations with a stereo camera. Projections matrices can be obtained from :ocv:func:`stereoRectify`. 
+The function reconstructs 3-dimensional points (in homogeneous coordinates) by using their observations with a stereo camera. Projections matrices can be obtained from :ocv:func:`stereoRectify`.
 
 .. seealso::
 
index fc8b1ad..1071358 100644 (file)
@@ -4,19 +4,19 @@ Changelog
 Release 0.05
 ------------
 
-This library is now included in the official OpenCV distribution (from 2.4 on). 
+This library is now included in the official OpenCV distribution (from 2.4 on).
 The :ocv:class`FaceRecognizer` is now an :ocv:class:`Algorithm`, which better fits into the overall
-OpenCV API. 
+OpenCV API.
 
-To reduce the confusion on user side and minimize my work, libfacerec and OpenCV 
-have been synchronized and are now based on the same interfaces and implementation. 
+To reduce the confusion on user side and minimize my work, libfacerec and OpenCV
+have been synchronized and are now based on the same interfaces and implementation.
 
 The library now has an extensive documentation:
 
 * The API is explained in detail and with a lot of code examples.
-* The face recognition guide I had written for Python and GNU Octave/MATLAB has been adapted to the new OpenCV C++ ``cv::FaceRecognizer``. 
+* The face recognition guide I had written for Python and GNU Octave/MATLAB has been adapted to the new OpenCV C++ ``cv::FaceRecognizer``.
 * A tutorial for gender classification with Fisherfaces.
-* A tutorial for face recognition in videos (e.g. webcam). 
+* A tutorial for face recognition in videos (e.g. webcam).
 
 
 Release highlights
@@ -27,8 +27,8 @@ Release highlights
 Release 0.04
 ------------
 
-This version is fully Windows-compatible and works with OpenCV 2.3.1. Several 
-bugfixes, but none influenced the recognition rate. 
+This version is fully Windows-compatible and works with OpenCV 2.3.1. Several
+bugfixes, but none influenced the recognition rate.
 
 Release highlights
 ++++++++++++++++++
@@ -40,9 +40,9 @@ Release highlights
 Release 0.03
 ------------
 
-Reworked the library to provide separate implementations in cpp files, because 
-it's the preferred way of contributing OpenCV libraries. This means the library 
-is not header-only anymore. Slight API changes were done, please see the 
+Reworked the library to provide separate implementations in cpp files, because
+it's the preferred way of contributing OpenCV libraries. This means the library
+is not header-only anymore. Slight API changes were done, please see the
 documentation for details.
 
 Release highlights
@@ -55,9 +55,9 @@ Release highlights
 Release 0.02
 ------------
 
-Reworked the library to provide separate implementations in cpp files, because 
-it's the preferred way of contributing OpenCV libraries. This means the library 
-is not header-only anymore. Slight API changes were done, please see the 
+Reworked the library to provide separate implementations in cpp files, because
+it's the preferred way of contributing OpenCV libraries. This means the library
+is not header-only anymore. Slight API changes were done, please see the
 documentation for details.
 
 Release highlights
@@ -80,7 +80,7 @@ Release highlights
   * Eigenfaces [TP91]_
   * Fisherfaces [BHK97]_
   * Local Binary Patterns Histograms [AHP04]_
-  
+
 * Added persistence facilities to store the models with a common API.
 * Unit Tests (using `gtest <http://code.google.com/p/googletest/>`_).
 * Providing a CMakeLists.txt to enable easy cross-platform building.
index cc2aa41..170da8f 100644 (file)
@@ -201,7 +201,7 @@ For the first source code example, I'll go through it with you. I am first givin
 .. literalinclude:: src/facerec_eigenfaces.cpp
    :language: cpp
    :linenos:
-   
+
 The source code for this demo application is also available in the ``src`` folder coming with this documentation:
 
 * :download:`src/facerec_eigenfaces.cpp <src/facerec_eigenfaces.cpp>`
index faa77df..7948bcd 100644 (file)
@@ -6,7 +6,7 @@ Introduction
 
 Saving and loading a :ocv:class:`FaceRecognizer` is very important. Training a FaceRecognizer can be a very time-intense task, plus it's often impossible to ship the whole face database to the user of your product. The task of saving and loading a FaceRecognizer is easy with :ocv:class:`FaceRecognizer`. You only have to call :ocv:func:`FaceRecognizer::load` for loading and :ocv:func:`FaceRecognizer::save` for saving a :ocv:class:`FaceRecognizer`.
 
-I'll adapt the Eigenfaces example from the :doc:`../facerec_tutorial`: Imagine we want to learn the Eigenfaces of the `AT&T Facedatabase <http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html>`_, store the model to a YAML file and then load it again. 
+I'll adapt the Eigenfaces example from the :doc:`../facerec_tutorial`: Imagine we want to learn the Eigenfaces of the `AT&T Facedatabase <http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html>`_, store the model to a YAML file and then load it again.
 
 From the loaded model, we'll get a prediction, show the mean, Eigenfaces and the image reconstruction.
 
index ecb979d..b692fe5 100644 (file)
@@ -111,7 +111,7 @@ An example. If the haar-cascade is at ``C:/opencv/data/haarcascades/haarcascade_
 
     facerec_video.exe C:/opencv/data/haarcascades/haarcascade_frontalface_default.xml C:/facerec/data/celebrities.txt 1
 
-That's it. 
+That's it.
 
 Results
 -------
index 46130bc..5b00d04 100644 (file)
@@ -66,8 +66,8 @@ Splits an element set into equivalency classes.
 
     :param vec: Set of elements stored as a vector.
 
-    :param labels: Output vector of labels. It contains as many elements as  ``vec``. Each label  ``labels[i]``  is a 0-based cluster index of  ``vec[i]`` .   
-    
+    :param labels: Output vector of labels. It contains as many elements as  ``vec``. Each label  ``labels[i]``  is a 0-based cluster index of  ``vec[i]`` .
+
     :param predicate: Equivalence predicate (pointer to a boolean function of two arguments or an instance of the class that has the method  ``bool operator()(const _Tp& a, const _Tp& b)`` ). The predicate returns ``true`` when the elements are certainly in the same class, and returns ``false`` if they may or may not be in the same class.
 
 The generic function ``partition`` implements an
index c54e65b..644684d 100644 (file)
@@ -12,30 +12,30 @@ The CommandLineParser class is designed for command line arguments parsing
 
     .. ocv:function:: CommandLineParser::CommandLineParser(int argc, const char * const argv[], const std::string keys)
 
-        :param argc: 
-        :param argv: 
-        :param keys: 
+        :param argc:
+        :param argv:
+        :param keys:
 
     .. ocv:function:: T CommandLineParser::get<T>(const std::string& name, bool space_delete = true)
 
-        :param name: 
-        :param space_delete: 
+        :param name:
+        :param space_delete:
 
     .. ocv:function:: T CommandLineParser::get<T>(int index, bool space_delete = true)
 
-        :param index: 
-        :param space_delete:  
+        :param index:
+        :param space_delete:
 
     .. ocv:function:: bool CommandLineParser::has(const std::string& name)
 
-        :param name: 
+        :param name:
 
     .. ocv:function:: bool CommandLineParser::check()
 
 
     .. ocv:function:: void CommandLineParser::about(std::string message)
-    
-        :param message: 
+
+        :param message:
 
     .. ocv:function:: void CommandLineParser::printMessage()
 
@@ -78,7 +78,7 @@ Syntax:
 
 ::
 
-    const std::string keys = 
+    const std::string keys =
         "{help h usage ? |      | print this message   }"
         "{@image1        |      | image1 for compare   }"
         "{@image2        |      | image2 for compare   }"
index 1f209ec..c8b1e58 100644 (file)
@@ -405,8 +405,8 @@ The number of pixels along the line is stored in ``LineIterator::count`` . The m
 
     for(int i = 0; i < it.count; i++, ++it)
         buf[i] = *(const Vec3b)*it;
-    
-    // alternative way of iterating through the line    
+
+    // alternative way of iterating through the line
     for(int i = 0; i < it2.count; i++, ++it2)
     {
         Vec3b val = img.at<Vec3b>(it2.pos());
index 106d698..a672365 100644 (file)
@@ -91,8 +91,8 @@ you can use::
 
    Ptr<T> ptr = new T(...);
 
-That is, ``Ptr<T> ptr`` encapsulates a pointer to a ``T`` instance and a reference counter associated with the pointer. See the 
-:ocv:class:`Ptr` 
+That is, ``Ptr<T> ptr`` encapsulates a pointer to a ``T`` instance and a reference counter associated with the pointer. See the
+:ocv:class:`Ptr`
 description for details.
 
 .. _AutomaticAllocation:
index 4ce6bce..1489334 100644 (file)
@@ -2283,7 +2283,7 @@ PCA constructors
         * **CV_PCA_DATA_AS_COL** indicates that the input samples are stored as matrix columns.
 
     :param maxComponents: maximum number of components that PCA should retain; by default, all the components are retained.
-    
+
     :param retainedVariance: Percentage of variance that PCA should retain. Using this parameter will let the PCA decided how many components to retain but it will always keep at least 2.
 
 The default constructor initializes an empty PCA structure. The other constructors initialize the structure and call
@@ -2312,7 +2312,7 @@ Performs Principal Component Analysis of the supplied dataset.
         * **CV_PCA_DATA_AS_COL** indicates that the input samples are stored as matrix columns.
 
     :param maxComponents: maximum number of components that PCA should retain; by default, all the components are retained.
-    
+
     :param retainedVariance: Percentage of variance that PCA should retain. Using this parameter will let the PCA decided how many components to retain but it will always keep at least 2.
 
 The operator performs PCA of the supplied dataset. It is safe to reuse the same PCA structure for multiple datasets. That is, if the  structure has been previously used with another dataset, the existing internal data is reclaimed and the new ``eigenvalues``, ``eigenvectors`` , and ``mean`` are allocated and computed.
index 6c50049..d785baf 100644 (file)
@@ -41,7 +41,7 @@ Abstract base class for computing descriptors for image keypoints. ::
 
 
 In this interface, a keypoint descriptor can be represented as a
-dense, fixed-dimension vector of a basic type. Most descriptors 
+dense, fixed-dimension vector of a basic type. Most descriptors
 follow this pattern as it simplifies computing
 distances between descriptors. Therefore, a collection of
 descriptors is represented as
index d7b34af..73089ce 100644 (file)
@@ -34,7 +34,7 @@ Lixin Fan, Jutta Willamowski, Cedric Bray, 2004. ::
 
 BOWTrainer::add
 -------------------
-Adds descriptors to a training set. 
+Adds descriptors to a training set.
 
 .. ocv:function:: void BOWTrainer::add( const Mat& descriptors )
 
@@ -60,7 +60,7 @@ Returns the count of all descriptors stored in the training set.
 
 BOWTrainer::cluster
 -----------------------
-Clusters train descriptors. 
+Clusters train descriptors.
 
 .. ocv:function:: Mat BOWTrainer::cluster() const
 
@@ -110,7 +110,7 @@ Class to compute an image descriptor using the *bag of visual words*. Such a com
     #. Compute descriptors for a given image and its keypoints set.
     #. Find the nearest visual words from the vocabulary for each keypoint descriptor.
     #. Compute the bag-of-words image descriptor as is a normalized histogram of vocabulary words encountered in the image. The ``i``-th bin of the histogram is a frequency of ``i``-th word of the vocabulary in the given image.
-    
+
 The class declaration is the following: ::
 
         class BOWImgDescriptorExtractor
index 1e065d3..13025c0 100644 (file)
@@ -10,11 +10,11 @@ Clusters features using hierarchical k-means algorithm.
 .. ocv:function:: template<typename Distance> int flann::hierarchicalClustering(const Mat& features, Mat& centers, const cvflann::KMeansIndexParams& params, Distance d = Distance())
 
     :param features: The points to be clustered. The matrix must have elements of type ``Distance::ElementType``.
-    
-    :param centers: The centers of the clusters obtained. The matrix must have type ``Distance::ResultType``. The number of rows in this matrix represents the number of clusters desired, however, because of the way the cut in the hierarchical tree is chosen, the number of clusters computed will be the highest number of the form  ``(branching-1)*k+1``  that's lower than the number of clusters desired, where  ``branching``  is the tree's branching factor (see description of the KMeansIndexParams). 
-    
+
+    :param centers: The centers of the clusters obtained. The matrix must have type ``Distance::ResultType``. The number of rows in this matrix represents the number of clusters desired, however, because of the way the cut in the hierarchical tree is chosen, the number of clusters computed will be the highest number of the form  ``(branching-1)*k+1``  that's lower than the number of clusters desired, where  ``branching``  is the tree's branching factor (see description of the KMeansIndexParams).
+
     :param params: Parameters used in the construction of the hierarchical k-means tree.
 
     :param d: Distance to be used for clustering.
-    
+
 The method clusters the given feature vectors by constructing a hierarchical k-means tree and choosing a cut in the tree that minimizes the cluster's variance. It returns the number of clusters found.
index de2781a..923e568 100644 (file)
@@ -20,40 +20,40 @@ flann::Index_<T>::Index\_
 Constructs a nearest neighbor search index for a given dataset.
 
 .. ocv:function:: flann::Index_<T>::Index_(const Mat& features, const IndexParams& params)
-    
-    :param features:  Matrix of containing the features(points) to index. The size of the matrix is ``num_features x feature_dimensionality`` and the data type of the elements in the matrix must coincide with the type of the index. 
-    
+
+    :param features:  Matrix of containing the features(points) to index. The size of the matrix is ``num_features x feature_dimensionality`` and the data type of the elements in the matrix must coincide with the type of the index.
+
     :param params: Structure containing the index parameters. The type of index that will be constructed depends on the type of this parameter. See the description.
-    
+
 The method constructs a fast search structure from a set of features using the specified algorithm with specified parameters, as defined by ``params``. ``params`` is a reference to one of the following class ``IndexParams`` descendants:
-    
+
     *
-    
+
        **LinearIndexParams** When passing an object of this type, the index will perform a linear, brute-force search. ::
-    
+
             struct LinearIndexParams : public IndexParams
             {
             };
-            
+
        ..
 
     *
-    
+
        **KDTreeIndexParams** When passing an object of this type the index constructed will consist of a set of randomized kd-trees which will be searched in parallel. ::
-    
+
             struct KDTreeIndexParams : public IndexParams
             {
                 KDTreeIndexParams( int trees = 4 );
             };
 
        ..
-    
-            * **trees** The number of parallel kd-trees to use. Good values are in the range [1..16] 
+
+            * **trees** The number of parallel kd-trees to use. Good values are in the range [1..16]
 
     *
-    
+
        **KMeansIndexParams** When passing an object of this type the index constructed will be a hierarchical k-means tree. ::
-    
+
             struct KMeansIndexParams : public IndexParams
             {
                 KMeansIndexParams(
@@ -62,20 +62,20 @@ The method constructs a fast search structure from a set of features using the s
                     flann_centers_init_t centers_init = CENTERS_RANDOM,
                     float cb_index = 0.2 );
             };
-    
+
        ..
-    
-           * **branching**  The branching factor to use for the hierarchical k-means tree  
-    
-           * **iterations**  The maximum number of iterations to use in the k-means clustering stage when building the k-means tree. A value of -1 used here means that the k-means clustering should be iterated until convergence 
-    
-           * **centers_init** The algorithm to use for selecting the initial centers when performing a k-means clustering step. The possible values are  ``CENTERS_RANDOM``  (picks the initial cluster centers randomly),  ``CENTERS_GONZALES``  (picks the initial centers using Gonzales' algorithm) and  ``CENTERS_KMEANSPP``  (picks the initial centers using the algorithm suggested in  arthur_kmeanspp_2007 ) 
-    
-           * **cb_index** This parameter (cluster boundary index) influences the way exploration is performed in the hierarchical kmeans tree. When  ``cb_index``  is zero the next kmeans domain to be explored is chosen to be the one with the closest center. A value greater then zero also takes into account the size of the domain. 
+
+           * **branching**  The branching factor to use for the hierarchical k-means tree
+
+           * **iterations**  The maximum number of iterations to use in the k-means clustering stage when building the k-means tree. A value of -1 used here means that the k-means clustering should be iterated until convergence
+
+           * **centers_init** The algorithm to use for selecting the initial centers when performing a k-means clustering step. The possible values are  ``CENTERS_RANDOM``  (picks the initial cluster centers randomly),  ``CENTERS_GONZALES``  (picks the initial centers using Gonzales' algorithm) and  ``CENTERS_KMEANSPP``  (picks the initial centers using the algorithm suggested in  arthur_kmeanspp_2007 )
+
+           * **cb_index** This parameter (cluster boundary index) influences the way exploration is performed in the hierarchical kmeans tree. When  ``cb_index``  is zero the next kmeans domain to be explored is chosen to be the one with the closest center. A value greater then zero also takes into account the size of the domain.
 
     *
        **CompositeIndexParams** When using a parameters object of this type the index created combines the randomized kd-trees  and the hierarchical k-means tree. ::
-    
+
             struct CompositeIndexParams : public IndexParams
             {
                 CompositeIndexParams(
@@ -88,7 +88,7 @@ The method constructs a fast search structure from a set of features using the s
 
     *
        **LshIndexParams** When using a parameters object of this type the index created uses multi-probe LSH (by ``Multi-Probe LSH: Efficient Indexing for High-Dimensional Similarity Search`` by Qin Lv, William Josephson, Zhe Wang, Moses Charikar, Kai Li., Proceedings of the 33rd International Conference on Very Large Data Bases (VLDB). Vienna, Austria. September 2007) ::
-    
+
             struct LshIndexParams : public IndexParams
             {
                 LshIndexParams(
@@ -96,9 +96,9 @@ The method constructs a fast search structure from a set of features using the s
                     unsigned int key_size,
                     unsigned int multi_probe_level );
             };
-    
+
        ..
-    
+
            * **table_number**  the number of hash tables to use (between 10 and 30 usually).
 
 
@@ -109,7 +109,7 @@ The method constructs a fast search structure from a set of features using the s
 
     *
        **AutotunedIndexParams** When passing an object of this type the index created is automatically tuned to offer  the best performance, by choosing the optimal index type (randomized kd-trees, hierarchical kmeans, linear) and parameters for the dataset provided. ::
-    
+
             struct AutotunedIndexParams : public IndexParams
             {
                 AutotunedIndexParams(
@@ -118,33 +118,33 @@ The method constructs a fast search structure from a set of features using the s
                     float memory_weight = 0,
                     float sample_fraction = 0.1 );
             };
-    
+
        ..
-    
-           * **target_precision**  Is a number between 0 and 1 specifying the percentage of the approximate nearest-neighbor searches that return the exact nearest-neighbor. Using a higher value for this parameter gives more accurate results, but the search takes longer. The optimum value usually depends on the application.  
-    
-    
-           * **build_weight**  Specifies the importance of the index build time raported to the nearest-neighbor search time. In some applications it's acceptable for the index build step to take a long time if the subsequent searches in the index can be performed very fast. In other applications it's required that the index be build as fast as possible even if that leads to slightly longer search times. 
-    
-    
-           * **memory_weight** Is used to specify the tradeoff between time (index build time and search time) and memory used by the index. A value less than 1 gives more importance to the time spent and a value greater than 1 gives more importance to the memory usage. 
-    
-    
-           * **sample_fraction** Is a number between 0 and 1 indicating what fraction of the dataset to use in the automatic parameter configuration algorithm. Running the algorithm on the full dataset gives the most accurate results, but for very large datasets can take longer than desired. In such case using just a fraction of the data helps speeding up this algorithm while still giving good approximations of the optimum parameters. 
+
+           * **target_precision**  Is a number between 0 and 1 specifying the percentage of the approximate nearest-neighbor searches that return the exact nearest-neighbor. Using a higher value for this parameter gives more accurate results, but the search takes longer. The optimum value usually depends on the application.
+
+
+           * **build_weight**  Specifies the importance of the index build time raported to the nearest-neighbor search time. In some applications it's acceptable for the index build step to take a long time if the subsequent searches in the index can be performed very fast. In other applications it's required that the index be build as fast as possible even if that leads to slightly longer search times.
+
+
+           * **memory_weight** Is used to specify the tradeoff between time (index build time and search time) and memory used by the index. A value less than 1 gives more importance to the time spent and a value greater than 1 gives more importance to the memory usage.
+
+
+           * **sample_fraction** Is a number between 0 and 1 indicating what fraction of the dataset to use in the automatic parameter configuration algorithm. Running the algorithm on the full dataset gives the most accurate results, but for very large datasets can take longer than desired. In such case using just a fraction of the data helps speeding up this algorithm while still giving good approximations of the optimum parameters.
 
     *
        **SavedIndexParams** This object type is used for loading a previously saved index from the disk. ::
-    
+
             struct SavedIndexParams : public IndexParams
             {
                 SavedIndexParams( std::string filename );
             };
-    
+
 
        ..
-    
-          * **filename**  The filename in which the index was saved.  
-    
+
+          * **filename**  The filename in which the index was saved.
+
 
 flann::Index_<T>::knnSearch
 ----------------------------
@@ -154,25 +154,25 @@ Performs a K-nearest neighbor search for a given query point using the index.
 
 .. ocv:function:: void flann::Index_<T>::knnSearch(const Mat& queries, Mat& indices, Mat& dists, int knn, const SearchParams& params)
 
-    :param query: The query point 
-    
-    :param indices: Vector that will contain the indices of the K-nearest neighbors found. It must have at least knn size. 
-    
-    :param dists: Vector that will contain the distances to the K-nearest neighbors found. It must have at least knn size. 
-    
-    :param knn: Number of nearest neighbors to search for. 
-    
+    :param query: The query point
+
+    :param indices: Vector that will contain the indices of the K-nearest neighbors found. It must have at least knn size.
+
+    :param dists: Vector that will contain the distances to the K-nearest neighbors found. It must have at least knn size.
+
+    :param knn: Number of nearest neighbors to search for.
+
     :param params:
-    
+
                 Search parameters ::
-        
+
                       struct SearchParams {
                               SearchParams(int checks = 32);
                       };
-        
+
                 ..
-        
-                    * **checks**  The number of times the tree(s) in the index should be recursively traversed. A higher value for this parameter would give better search precision, but also take more time. If automatic configuration was used when the index was created, the number of checks required to achieve the specified precision was also computed, in which case this parameter is ignored. 
+
+                    * **checks**  The number of times the tree(s) in the index should be recursively traversed. A higher value for this parameter would give better search precision, but also take more time. If automatic configuration was used when the index was created, the number of checks required to achieve the specified precision was also computed, in which case this parameter is ignored.
 
 
 flann::Index_<T>::radiusSearch
@@ -183,15 +183,15 @@ Performs a radius nearest neighbor search for a given query point.
 
 .. ocv:function:: int flann::Index_<T>::radiusSearch(const Mat& query, Mat& indices, Mat& dists,                   float radius, const SearchParams& params)
 
-    :param query: The query point 
-    
-    :param indices: Vector that will contain the indices of the points found within the search radius in decreasing order of the distance to the query point. If the number of neighbors in the search radius is bigger than the size of this vector, the ones that don't fit in the vector are ignored.  
-    
-    :param dists: Vector that will contain the distances to the points found within the search radius 
-    
-    :param radius: The search radius 
-    
-    :param params: Search parameters 
+    :param query: The query point
+
+    :param indices: Vector that will contain the indices of the points found within the search radius in decreasing order of the distance to the query point. If the number of neighbors in the search radius is bigger than the size of this vector, the ones that don't fit in the vector are ignored.
+
+    :param dists: Vector that will contain the distances to the points found within the search radius
+
+    :param radius: The search radius
+
+    :param params: Search parameters
 
 
 flann::Index_<T>::save
@@ -199,8 +199,8 @@ flann::Index_<T>::save
 Saves the index to a file.
 
 .. ocv:function:: void flann::Index_<T>::save(std::string filename)
-    
-    :param filename: The file to save the index to 
+
+    :param filename: The file to save the index to
 
 
 flann::Index_<T>::getIndexParameters
index 3d6bc76..ce05089 100644 (file)
@@ -868,7 +868,7 @@ Performs pure non local means denoising without any simplification, and thus it
 .. seealso::
 
     :ocv:func:`fastNlMeansDenoising`
-    
+
 gpu::FastNonLocalMeansDenoising
 -------------------------------
 .. ocv:class:: gpu::FastNonLocalMeansDenoising
@@ -894,19 +894,19 @@ Perform image denoising using Non-local Means Denoising algorithm http://www.ipo
     :param src: Input 8-bit 1-channel, 2-channel or 3-channel image.
 
     :param dst: Output image with the same size and type as  ``src`` .
-    
+
     :param h: Parameter regulating filter strength. Big h value perfectly removes noise but also removes image details, smaller h value preserves details but also preserves some noise
 
     :param search_window: Size in pixels of the window that is used to compute weighted average for given pixel. Should be odd. Affect performance linearly: greater search_window - greater denoising time. Recommended value 21 pixels
-    
+
     :param block_size: Size in pixels of the template patch that is used to compute weights. Should be odd. Recommended value 7 pixels
-           
+
     :param stream: Stream for the asynchronous invocations.
 
-This function expected to be applied to grayscale images. For colored images look at ``FastNonLocalMeansDenoising::labMethod``. 
+This function expected to be applied to grayscale images. For colored images look at ``FastNonLocalMeansDenoising::labMethod``.
+
+.. seealso::
 
-.. seealso:: 
-    
     :ocv:func:`fastNlMeansDenoising`
 
 gpu::FastNonLocalMeansDenoising::labMethod()
@@ -920,21 +920,21 @@ Modification of ``FastNonLocalMeansDenoising::simpleMethod`` for color images
     :param dst: Output image with the same size and type as  ``src`` .
 
     :param h_luminance: Parameter regulating filter strength. Big h value perfectly removes noise but also removes image details, smaller h value preserves details but also preserves some noise
-    
+
     :param float: The same as h but for color components. For most images value equals 10 will be enought to remove colored noise and do not distort colors
 
     :param search_window: Size in pixels of the window that is used to compute weighted average for given pixel. Should be odd. Affect performance linearly: greater search_window - greater denoising time. Recommended value 21 pixels
-    
+
     :param block_size: Size in pixels of the template patch that is used to compute weights. Should be odd. Recommended value 7 pixels
-           
+
     :param stream: Stream for the asynchronous invocations.
-    
+
 The function converts image to CIELAB colorspace and then separately denoise L and AB components with given h parameters using ``FastNonLocalMeansDenoising::simpleMethod`` function.
 
-.. seealso:: 
+.. seealso::
 
     :ocv:func:`fastNlMeansDenoisingColored`
-    
+
 gpu::alphaComp
 -------------------
 Composites two images using alpha opacity values contained in each image.
index ee2250a..538267e 100644 (file)
@@ -185,7 +185,7 @@ Reduces a matrix to a vector.
             * **CV_REDUCE_MIN** The output is the minimum (column/row-wise) of all rows/columns of the matrix.
 
     :param dtype: When it is negative, the destination vector will have the same type as the source matrix. Otherwise, its type will be  ``CV_MAKE_TYPE(CV_MAT_DEPTH(dtype), mtx.channels())`` .
-    
+
 The function ``reduce`` reduces the matrix to a vector by treating the matrix rows/columns as a set of 1D vectors and performing the specified operation on the vectors until a single row/column is obtained. For example, the function can be used to compute horizontal and vertical projections of a raster image. In case of ``CV_REDUCE_SUM`` and ``CV_REDUCE_AVG`` , the output may have a larger element bit-depth to preserve accuracy. And multi-channel arrays are also supported in these two reduction modes.
 
 .. seealso:: :ocv:func:`reduce`
index 4644796..5911b3f 100644 (file)
@@ -20,7 +20,7 @@ Reads an image from a buffer in memory.
     :param buf: Input array or vector of bytes.
 
     :param flags: The same flags as in :ocv:func:`imread` .
-    
+
     :param dst: The optional output placeholder for the decoded matrix. It can save the image reallocations when the function is called repeatedly for images of the same size.
 
 The function reads an image from the specified buffer in the memory.
@@ -74,12 +74,12 @@ Loads an image from a file.
     :param filename: Name of file to be loaded.
 
     :param flags: Flags specifying the color type of a loaded image:
-    
-        * 1 - 
-        * CV_LOAD_IMAGE_ANYDEPTH - 
+
+        * 1 -
+        * CV_LOAD_IMAGE_ANYDEPTH -
         CV_LOAD_IMAGE_COLOR
         CV_LOAD_IMAGE_GRAYSCALE
-        
+
 
         * **>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.
index a257e5a..df2a2e8 100644 (file)
@@ -16,4 +16,4 @@ The license does not permit the following uses:
 
 You may not use, or allow anyone else to use the icons to create pornographic, libelous, obscene, or defamatory material.
 
-All icon files are provided "as is". You agree not to hold IconEden.com liable for any damages that may occur due to use, or inability to use, icons or image data from IconEden.com. 
\ No newline at end of file
+All icon files are provided "as is". You agree not to hold IconEden.com liable for any damages that may occur due to use, or inability to use, icons or image data from IconEden.com.
\ No newline at end of file
index f576d5d..f478566 100644 (file)
@@ -174,7 +174,7 @@ Compares two histograms.
             * **CV_COMP_INTERSECT**     Intersection
 
             * **CV_COMP_BHATTACHARYYA**     Bhattacharyya distance
-            
+
             * **CV_COMP_HELLINGER**     Synonym for ``CV_COMP_BHATTACHARYYA``
 
 The functions ``compareHist`` compare two dense or two sparse histograms using the specified method:
index 4bace30..93d0d82 100644 (file)
@@ -67,7 +67,7 @@ The following loss functions are implemented for regression problems:
     :math:`L(y,f(x)) = \left\{ \begin{array}{lr}
     \delta\cdot\left(|y-f(x)|-\dfrac{\delta}{2}\right) & : |y-f(x)|>\delta\\
     \dfrac{1}{2}\cdot(y-f(x))^2 & : |y-f(x)|\leq\delta \end{array} \right.`,
-    
+
     where :math:`\delta` is the :math:`\alpha`-quantile estimation of the
     :math:`|y-f(x)|`. In the current implementation :math:`\alpha=0.2`.
 
@@ -129,9 +129,9 @@ CvGBTreesParams::CvGBTreesParams
    :param weak_count: Count of boosting algorithm iterations. ``weak_count*K`` is the total
     count of trees in the GBT model, where ``K`` is the output classes count
     (equal to one in case of a regression).
-  
+
    :param shrinkage: Regularization parameter (see :ref:`Training GBT`).
-    
+
    :param subsample_portion: Portion of the whole training set used for each algorithm iteration.
     Subset is generated randomly. For more information see
     http://www.salfordsystems.com/doc/StochasticBoostingSS.pdf.
@@ -139,7 +139,7 @@ CvGBTreesParams::CvGBTreesParams
    :param max_depth: Maximal depth of each decision tree in the ensemble (see :ocv:class:`CvDTree`).
 
    :param use_surrogates: If ``true``, surrogate splits are built (see :ocv:class:`CvDTree`).
-    
+
 By default the following constructor is used:
 
 .. code-block:: cpp
@@ -178,7 +178,7 @@ Trains a Gradient boosted tree model.
 .. ocv:function:: bool CvGBTrees::train(CvMLData* data, CvGBTreesParams params=CvGBTreesParams(), bool update=false)
 
 .. ocv:pyfunction:: cv2.GBTrees.train(trainData, tflag, responses[, varIdx[, sampleIdx[, varType[, missingDataMask[, params[, update]]]]]]) -> retval
-    
+
 The first train method follows the common template (see :ocv:func:`CvStatModel::train`).
 Both ``tflag`` values (``CV_ROW_SAMPLE``, ``CV_COL_SAMPLE``) are supported.
 ``trainData`` must be of the ``CV_32F`` type. ``responses`` must be a matrix of type
@@ -188,7 +188,7 @@ list of indices (``CV_32S``) or a mask (``CV_8U`` or ``CV_8S``). ``update`` is
 a dummy parameter.
 
 The second form of :ocv:func:`CvGBTrees::train` function uses :ocv:class:`CvMLData` as a
-data set container. ``update`` is still a dummy parameter. 
+data set container. ``update`` is still a dummy parameter.
 
 All parameters specific to the GBT model are passed into the training function
 as a :ocv:class:`CvGBTreesParams` structure.
@@ -207,42 +207,42 @@ Predicts a response for an input sample.
    :param sample: Input feature vector that has the same format as every training set
     element. If not all the variables were actually used during training,
     ``sample`` contains forged values at the appropriate places.
-    
+
    :param missing: Missing values mask, which is a dimensional matrix of the same size as
     ``sample`` having the ``CV_8U`` type. ``1`` corresponds to the missing value
     in the same position in the ``sample`` vector. If there are no missing values
     in the feature vector, an empty matrix can be passed instead of the missing mask.
-    
+
    :param weakResponses: Matrix used to obtain predictions of all the trees.
     The matrix has :math:`K` rows,
     where :math:`K` is the count of output classes (1 for the regression case).
     The matrix has as many columns as the ``slice`` length.
-    
+
    :param slice: Parameter defining the part of the ensemble used for prediction.
     If ``slice = Range::all()``, all trees are used. Use this parameter to
     get predictions of the GBT models with different ensemble sizes learning
     only one model.
-    
+
    :param k: Number of tree ensembles built in case of the classification problem
     (see :ref:`Training GBT`). Use this
     parameter to change the output to sum of the trees' predictions in the
     ``k``-th ensemble only. To get the total GBT model prediction, ``k`` value
     must be -1. For regression problems, ``k`` is also equal to -1.
+
 The method predicts the response corresponding to the given sample
 (see :ref:`Predicting with GBT`).
 The result is either the class label or the estimated function value. The
 :ocv:func:`CvGBTrees::predict` method enables using the parallel version of the GBT model
 prediction if the OpenCV is built with the TBB library. In this case, predictions
-of single trees are computed in a parallel fashion. 
+of single trees are computed in a parallel fashion.
+
 
-    
 CvGBTrees::clear
 ----------------
 Clears the model.
 
 .. ocv:function:: void CvGBTrees::clear()
-    
+
 .. ocv:pyfunction:: cv2.GBTrees.clear() -> None
 
 The function deletes the data set information and all the weak models and sets all internal
@@ -257,7 +257,7 @@ Calculates a training or testing error.
 .. ocv:function:: float CvGBTrees::calc_error( CvMLData* _data, int type, std::vector<float> *resp = 0 )
 
    :param _data: Data set.
-    
+
    :param type: Parameter defining the error that should be computed: train (``CV_TRAIN_ERROR``) or test
     (``CV_TEST_ERROR``).
 
index 739f52d..e018717 100644 (file)
@@ -9,7 +9,7 @@ CvKNearest
 ----------
 .. ocv:class:: CvKNearest : public CvStatModel
 
-The class implements K-Nearest Neighbors model as described in the beginning of this section. 
+The class implements K-Nearest Neighbors model as described in the beginning of this section.
 
 CvKNearest::CvKNearest
 ----------------------
@@ -39,7 +39,7 @@ Trains the model.
 
     :param updateBase: Specifies whether the model is trained from scratch (``update_base=false``), or it is updated using the new training data (``update_base=true``). In the latter case, the parameter ``maxK`` must not be larger than the original value.
 
-The method trains the K-Nearest model. It follows the conventions of the generic :ocv:func:`CvStatModel::train` approach with the following limitations: 
+The method trains the K-Nearest model. It follows the conventions of the generic :ocv:func:`CvStatModel::train` approach with the following limitations:
 
 * Only ``CV_ROW_SAMPLE`` data layout is supported.
 * Input variables are all ordered.
index 5a3896c..bae342e 100644 (file)
@@ -9,7 +9,7 @@ CvMLData
 --------
 .. ocv:class:: CvMLData
 
-Class for loading the data from a ``.csv`` file. 
+Class for loading the data from a ``.csv`` file.
 ::
 
     class CV_EXPORTS CvMLData
@@ -27,42 +27,42 @@ Class for loading the data from a ``.csv`` file.
         void set_response_idx( int idx );
         int get_response_idx() const;
 
-        
+
         void set_train_test_split( const CvTrainTestSplit * spl);
         const CvMat* get_train_sample_idx() const;
         const CvMat* get_test_sample_idx() const;
         void mix_train_and_test_idx();
-        
+
         const CvMat* get_var_idx();
         void change_var_idx( int vi, bool state );
 
         const CvMat* get_var_types();
         void set_var_types( const char* str );
-        
+
         int get_var_type( int var_idx ) const;
         void change_var_type( int var_idx, int type);
-     
+
         void set_delimiter( char ch );
         char get_delimiter() const;
 
         void set_miss_ch( char ch );
         char get_miss_ch() const;
-        
+
         const std::map<std::string, int>& get_class_labels_map() const;
-        
-    protected: 
-        ... 
+
+    protected:
+        ...
     };
 
 CvMLData::read_csv
 ------------------
-Reads the data set from a ``.csv``-like ``filename`` file and stores all read values in a matrix. 
+Reads the data set from a ``.csv``-like ``filename`` file and stores all read values in a matrix.
 
 .. ocv:function:: int CvMLData::read_csv(const char* filename)
 
     :param filename: The input file name
 
-While reading the data, the method tries to define the type of variables (predictors and responses): ordered or categorical. If a value of the variable is not numerical (except for the label for a missing value), the type of the variable is set to ``CV_VAR_CATEGORICAL``. If all existing values of the variable are numerical, the type of the variable is set to ``CV_VAR_ORDERED``. So, the default definition of variables types works correctly for all cases except the case of a categorical variable with numerical class labels. In this case, the type ``CV_VAR_ORDERED`` is set. You should change the type to ``CV_VAR_CATEGORICAL`` using the method :ocv:func:`CvMLData::change_var_type`. For categorical variables, a common map is built to convert a string class label to the numerical class label. Use :ocv:func:`CvMLData::get_class_labels_map` to obtain this map. 
+While reading the data, the method tries to define the type of variables (predictors and responses): ordered or categorical. If a value of the variable is not numerical (except for the label for a missing value), the type of the variable is set to ``CV_VAR_CATEGORICAL``. If all existing values of the variable are numerical, the type of the variable is set to ``CV_VAR_ORDERED``. So, the default definition of variables types works correctly for all cases except the case of a categorical variable with numerical class labels. In this case, the type ``CV_VAR_ORDERED`` is set. You should change the type to ``CV_VAR_CATEGORICAL`` using the method :ocv:func:`CvMLData::change_var_type`. For categorical variables, a common map is built to convert a string class label to the numerical class label. Use :ocv:func:`CvMLData::get_class_labels_map` to obtain this map.
 
 Also, when reading the data, the method constructs the mask of missing values. For example, values are equal to `'?'`.
 
@@ -72,7 +72,7 @@ Returns a pointer to the matrix of predictors and response values
 
 .. ocv:function:: const CvMat* CvMLData::get_values() const
 
-The method returns a pointer to the matrix of predictor and response ``values``  or ``0`` if the data has not been loaded from the file yet. 
+The method returns a pointer to the matrix of predictor and response ``values``  or ``0`` if the data has not been loaded from the file yet.
 
 The row count of this matrix equals the sample count. The column count equals predictors ``+ 1`` for the response (if exists) count. This means that each row of the matrix contains values of one sample predictor and response. The matrix type is ``CV_32FC1``.
 
@@ -82,7 +82,7 @@ Returns a pointer to the matrix of response values
 
 .. ocv:function:: const CvMat* CvMLData::get_responses()
 
-The method returns a pointer to the matrix of response values or throws an exception if the data has not been loaded from the file yet. 
+The method returns a pointer to the matrix of response values or throws an exception if the data has not been loaded from the file yet.
 
 This is a single-column matrix of the type ``CV_32FC1``. Its row count is equal to the sample count, one column and .
 
@@ -92,7 +92,7 @@ Returns a pointer to the mask matrix of missing values
 
 .. ocv:function:: const CvMat* CvMLData::get_missing() const
 
-The method returns a pointer to the mask matrix of missing values or throws an exception if the data has not been loaded from the file yet. 
+The method returns a pointer to the mask matrix of missing values or throws an exception if the data has not been loaded from the file yet.
 
 This matrix has the same size as the  ``values`` matrix (see :ocv:func:`CvMLData::get_values`) and the type ``CV_8UC1``.
 
@@ -102,7 +102,7 @@ Specifies index of response column in the data matrix
 
 .. ocv:function:: void CvMLData::set_response_idx( int idx )
 
-The method sets the index of a response column in the ``values`` matrix (see :ocv:func:`CvMLData::get_values`) or throws an exception if the data has not been loaded from the file yet. 
+The method sets the index of a response column in the ``values`` matrix (see :ocv:func:`CvMLData::get_values`) or throws an exception if the data has not been loaded from the file yet.
 
 The old response columns become predictors. If ``idx < 0``, there is no response.
 
@@ -115,15 +115,15 @@ Returns index of the response column in the loaded data matrix
 The method returns the index of a response column in the ``values`` matrix (see :ocv:func:`CvMLData::get_values`) or throws an exception if the data has not been loaded from the file yet.
 
 If ``idx < 0``, there is no response.
-    
+
 
 CvMLData::set_train_test_split
 ------------------------------
-Divides the read data set into two disjoint training and test subsets. 
+Divides the read data set into two disjoint training and test subsets.
 
 .. ocv:function:: void CvMLData::set_train_test_split( const CvTrainTestSplit * spl )
 
-This method sets parameters for such a split using ``spl`` (see :ocv:class:`CvTrainTestSplit`) or throws an exception if the data has not been loaded from the file yet. 
+This method sets parameters for such a split using ``spl`` (see :ocv:class:`CvTrainTestSplit`) or throws an exception if the data has not been loaded from the file yet.
 
 CvMLData::get_train_sample_idx
 ------------------------------
@@ -139,13 +139,13 @@ Returns the matrix of sample indices for a testing subset
 
 .. ocv:function:: const CvMat* CvMLData::get_test_sample_idx() const
 
-    
+
 CvMLData::mix_train_and_test_idx
 --------------------------------
 Mixes the indices of training and test samples
 
 .. ocv:function:: void CvMLData::mix_train_and_test_idx()
-    
+
 The method shuffles the indices of training and test samples preserving sizes of training and test subsets if the data split is set by :ocv:func:`CvMLData::get_values`. If the data has not been loaded from the file yet, an exception is thrown.
 
 CvMLData::get_var_idx
@@ -153,8 +153,8 @@ CvMLData::get_var_idx
 Returns the indices of the active variables in the data matrix
 
 .. ocv:function:: const CvMat* CvMLData::get_var_idx()
-    
-The method returns the indices of variables (columns) used in the ``values`` matrix (see :ocv:func:`CvMLData::get_values`). 
+
+The method returns the indices of variables (columns) used in the ``values`` matrix (see :ocv:func:`CvMLData::get_values`).
 
 It returns ``0`` if the used subset is not set. It throws an exception if the data has not been loaded from the file yet. Returned matrix is a single-row matrix of the type ``CV_32SC1``. Its column count is equal to the size of the used variable subset.
 
@@ -165,29 +165,29 @@ Enables or disables particular variable in the loaded data
 .. ocv:function:: void CvMLData::change_var_idx( int vi, bool state )
 
 By default, after reading the data set all variables in the ``values`` matrix (see :ocv:func:`CvMLData::get_values`) are used. But you may want to use only a subset of variables and include/exclude (depending on ``state`` value) a variable with the ``vi`` index from the used subset. If the data has not been loaded from the file yet, an exception is thrown.
-    
+
 CvMLData::get_var_types
 -----------------------
-Returns a matrix of the variable types. 
+Returns a matrix of the variable types.
 
 .. ocv:function:: const CvMat* CvMLData::get_var_types()
-    
+
 The function returns a single-row matrix of the type ``CV_8UC1``, where each element is set to either ``CV_VAR_ORDERED`` or ``CV_VAR_CATEGORICAL``. The number of columns is equal to the number of variables. If data has not been loaded from file yet an exception is thrown.
-    
+
 CvMLData::set_var_types
 -----------------------
 Sets the variables types in the loaded data.
 
 .. ocv:function:: void CvMLData::set_var_types( const char* str )
 
-In the string, a variable type is followed by a list of variables indices. For example: ``"ord[0-17],cat[18]"``, ``"ord[0,2,4,10-12], cat[1,3,5-9,13,14]"``, ``"cat"`` (all variables are categorical), ``"ord"`` (all variables are ordered). 
+In the string, a variable type is followed by a list of variables indices. For example: ``"ord[0-17],cat[18]"``, ``"ord[0,2,4,10-12], cat[1,3,5-9,13,14]"``, ``"cat"`` (all variables are categorical), ``"ord"`` (all variables are ordered).
 
 CvMLData::get_header_lines_number
 ---------------------------------
-Returns a number of the table header lines. 
+Returns a number of the table header lines.
 
 .. ocv:function:: int CvMLData::get_header_lines_number() const
-    
+
 CvMLData::set_header_lines_number
 ---------------------------------
 Sets a number of the table header lines.
@@ -203,15 +203,15 @@ Returns type of the specified variable
 .. ocv:function:: int CvMLData::get_var_type( int var_idx ) const
 
 The method returns the type of a variable by the index ``var_idx`` ( ``CV_VAR_ORDERED`` or ``CV_VAR_CATEGORICAL``).
-    
+
 CvMLData::change_var_type
 -------------------------
 Changes type of the specified variable
 
 .. ocv:function:: void CvMLData::change_var_type( int var_idx, int type)
-    
+
 The method changes type of variable with index ``var_idx`` from existing type to ``type`` ( ``CV_VAR_ORDERED`` or ``CV_VAR_CATEGORICAL``).
-     
+
 CvMLData::set_delimiter
 -----------------------
 Sets the delimiter in the file used to separate input numbers
@@ -274,6 +274,6 @@ Structure setting the split of a data set read by :ocv:class:`CvMLData`.
 
 There are two ways to construct a split:
 
-* Set the training sample count (subset size) ``train_sample_count``. Other existing samples are located in a test subset. 
+* Set the training sample count (subset size) ``train_sample_count``. Other existing samples are located in a test subset.
 
 * Set a training sample portion in ``[0,..1]``. The flag ``mix`` is used to mix training and test samples indices when the split is set. Otherwise, the data set is split in the storing order: the first part of samples of a given size is a training subset, the second part is a test subset.
index f86a985..b66769c 100644 (file)
@@ -177,7 +177,7 @@ Loads a classifier from a file.
 
 CascadeClassifier::read
 ---------------------------
-Reads a classifier from a FileStorage node. 
+Reads a classifier from a FileStorage node.
 
 .. ocv:function:: bool CascadeClassifier::read(const FileNode& node)
 
index aba4b70..474558f 100644 (file)
@@ -16,8 +16,8 @@ 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.
 
index 957ec88..8e53e5a 100644 (file)
@@ -15,13 +15,13 @@ with several computational optimizations. Noise expected to be a gaussian white
     :param dst: Output image with the same size and type as  ``src`` .
 
     :param templateWindowSize: Size in pixels of the template patch that is used to compute weights. Should be odd. Recommended value 7 pixels
-    
+
     :param searchWindowSize: Size in pixels of the window that is used to compute weighted average for given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater denoising time. Recommended value 21 pixels
-    
+
     :param h: Parameter regulating filter strength. Big h value perfectly removes noise but also removes image details, smaller h value preserves details but also preserves some noise
 
 This function expected to be applied to grayscale images. For colored images look at ``fastNlMeansDenoisingColored``.
-Advanced usage of this functions can be manual denoising of colored image in different colorspaces. 
+Advanced usage of this functions can be manual denoising of colored image in different colorspaces.
 Such approach is used in ``fastNlMeansDenoisingColored`` by converting image to CIELAB colorspace and then separately denoise L and AB components with different h parameter.
 
 fastNlMeansDenoisingColored
@@ -35,9 +35,9 @@ Modification of ``fastNlMeansDenoising`` function for colored images
     :param dst: Output image with the same size and type as  ``src`` .
 
     :param templateWindowSize: Size in pixels of the template patch that is used to compute weights. Should be odd. Recommended value 7 pixels
-    
+
     :param searchWindowSize: Size in pixels of the window that is used to compute weighted average for given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater denoising time. Recommended value 21 pixels
-    
+
     :param h: Parameter regulating filter strength for luminance component. Bigger h value perfectly removes noise but also removes image details, smaller h value preserves details but also preserves some noise
 
     :param hForColorComponents: The same as h but for color components. For most images value equals 10 will be enought to remove colored noise and do not distort colors
@@ -60,9 +60,9 @@ For more details see http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.131
     :param dst: Output image with the same size and type as ``srcImgs`` images.
 
     :param templateWindowSize: Size in pixels of the template patch that is used to compute weights. Should be odd. Recommended value 7 pixels
-    
+
     :param searchWindowSize: Size in pixels of the window that is used to compute weighted average for given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater denoising time. Recommended value 21 pixels
-    
+
     :param h: Parameter regulating filter strength for luminance component. Bigger h value perfectly removes noise but also removes image details, smaller h value preserves details but also preserves some noise
 
 fastNlMeansDenoisingColoredMulti
@@ -80,9 +80,9 @@ Modification of ``fastNlMeansDenoisingMulti`` function for colored images sequen
     :param dst: Output image with the same size and type as ``srcImgs`` images.
 
     :param templateWindowSize: Size in pixels of the template patch that is used to compute weights. Should be odd. Recommended value 7 pixels
-    
+
     :param searchWindowSize: Size in pixels of the window that is used to compute weighted average for given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater denoising time. Recommended value 21 pixels
-    
+
     :param h: Parameter regulating filter strength for luminance component. Bigger h value perfectly removes noise but also removes image details, smaller h value preserves details but also preserves some noise.
 
     :param hForColorComponents: The same as h but for color components.
index 6f05239..fa2aa1e 100644 (file)
@@ -7,5 +7,5 @@ photo. Computational Photography
 .. toctree::
     :maxdepth: 2
 
-    inpainting 
+    inpainting
     denoising
index dc0b99e..f6e9f73 100644 (file)
@@ -9,7 +9,7 @@ detail::CameraParams
 
 Describes camera parameters.
 
-.. note:: Translation is assumed to be zero during the whole stitching pipeline. 
+.. note:: Translation is assumed to be zero during the whole stitching pipeline.
 
 ::
 
index 5834072..dec3362 100644 (file)
@@ -57,9 +57,9 @@ High level image stitcher. It's possible to use this class without being aware o
 
         const cv::Mat& matchingMask() const { return matching_mask_; }
         void setMatchingMask(const cv::Mat &mask)
-        { 
+        {
             CV_Assert(mask.type() == CV_8U && mask.cols == mask.rows);
-            matching_mask_ = mask.clone(); 
+            matching_mask_ = mask.clone();
         }
 
         Ptr<detail::BundleAdjusterBase> bundleAdjuster() { return bundle_adjuster_; }
@@ -84,7 +84,7 @@ High level image stitcher. It's possible to use this class without being aware o
         const Ptr<detail::Blender> blender() const { return blender_; }
         void setBlender(Ptr<detail::Blender> blender) { blender_ = blender; }
 
-    private: 
+    private:
         /* hidden */
     };
 
@@ -112,7 +112,7 @@ These functions try to match the given images and to estimate rotations of each
     :param images: Input images.
 
     :param rois: Region of interest rectangles.
-    
+
     :return: Status code.
 
 Stitcher::composePanorama
@@ -127,7 +127,7 @@ These functions try to compose the given images (or images stored internally fro
 .. ocv:function:: Status Stitcher::composePanorama(InputArray images, OutputArray pano)
 
     :param images: Input images.
-    
+
     :param pano: Final pano.
 
     :return: Status code.
@@ -142,7 +142,7 @@ These functions try to stitch the given images.
 .. ocv:function:: Status Stitcher::stitch(InputArray images, const std::vector<std::vector<Rect> > &rois, OutputArray pano)
 
     :param images: Input images.
-    
+
     :param rois: Region of interest rectangles.
 
     :param pano: Final pano.
index f2b1240..119fb1e 100644 (file)
@@ -130,6 +130,6 @@ Minimum graph cut-based seam estimator. See details in [V03]_. ::
         /* hidden */
     };
 
-.. seealso:: 
+.. seealso::
     :ocv:class:`detail::GraphCutSeamFinderBase`,
     :ocv:class:`detail::SeamFinder`
index eb1577d..983b310 100644 (file)
@@ -4,7 +4,7 @@ stitching. Images stitching
 
 .. toctree::
     :maxdepth: 2
-    
+
     introduction
     high_level
     camera
index 6db525a..53b2a70 100644 (file)
@@ -607,7 +607,7 @@ Calculate an optical flow using "SimpleFlow" algorithm.
 
     :param prev: First 8-bit 3-channel image.
 
-    :param next: Second 8-bit 3-channel image 
+    :param next: Second 8-bit 3-channel image
 
     :param flowX: X-coordinate of estimated flow
 
@@ -639,7 +639,7 @@ Calculate an optical flow using "SimpleFlow" algorithm.
 
     :param speed_up_thr: threshold to detect point with irregular flow - where flow should be recalculated after upscale
 
-See [Tao2012]_. And site of project - http://graphics.berkeley.edu/papers/Tao-SAN-2012-05/. 
+See [Tao2012]_. And site of project - http://graphics.berkeley.edu/papers/Tao-SAN-2012-05/.
 
 .. [Bouguet00] Jean-Yves Bouguet. Pyramidal Implementation of the Lucas Kanade Feature Tracker.
 
index 8ba65e9..7332302 100644 (file)
@@ -10,7 +10,7 @@ videostab::FastMarchingMethod
 
 .. ocv:class:: videostab::FastMarchingMethod
 
-Describes the Fast Marching Method implementation. 
+Describes the Fast Marching Method implementation.
 
 ::
 
@@ -29,7 +29,7 @@ Describes the Fast Marching Method implementation.
 videostab::FastMarchingMethod::FastMarchingMethod
 -------------------------------------------------
 
-Constructor. 
+Constructor.
 
 .. ocv:function:: videostab::FastMarchingMethod::FastMarchingMethod()
 
@@ -37,7 +37,7 @@ Constructor.
 videostab::FastMarchingMethod::run
 ----------------------------------
 
-Template method that runs the Fast Marching Method. 
+Template method that runs the Fast Marching Method.
 
 .. ocv:function:: Inpaint FastMarchingMethod::run(const Mat &mask, Inpaint inpaint)
 
@@ -45,7 +45,7 @@ Template method that runs the Fast Marching Method.
 
     :param inpaint: Inpainting functor that overloads ``void operator ()(int x, int y)``.
 
-    :return: Inpainting functor. 
+    :return: Inpainting functor.
 
 
 videostab::FastMarchingMethod::distanceMap
index b595c5e..c4c764f 100644 (file)
@@ -10,7 +10,7 @@ videostab::MotionModel
 
 .. ocv:class:: videostab::MotionModel
 
-Describes motion model between two point clouds. 
+Describes motion model between two point clouds.
 
 ::
 
@@ -187,7 +187,7 @@ videostab::MotionEstimatorBase::motionModel
 
 .. ocv:function:: MotionModel MotionEstimatorBase::motionModel() const
 
-    :return: Motion model. See :ocv:class:`videostab::MotionModel`.    
+    :return: Motion model. See :ocv:class:`videostab::MotionModel`.
 
 
 videostab::MotionEstimatorBase::estimate
index 3c2dc42..11f433e 100644 (file)
@@ -11,16 +11,16 @@ to build a universal binary framework. Invoke this script from Terminal.app, wai
 and you are done.
 
 OpenCV is a Private Framework:
-On Mac OS X the concept of Framework bundles is meant to simplify distribution of shared libraries, 
-accompanying headers and documentation. There are however to subtly different 'flavours' of 
-Frameworks: public and private ones. The public frameworks get installed into the Frameworks 
-diretories in /Library, /System/Library or ~/Library and are meant to be shared amongst 
-applications. The private frameworks are only distributed as parts of an Application Bundle. 
-This makes it easier to deploy applications because they bring their own framework invisibly to 
-the user. No installation of the framework is necessary and different applications can bring 
+On Mac OS X the concept of Framework bundles is meant to simplify distribution of shared libraries,
+accompanying headers and documentation. There are however to subtly different 'flavours' of
+Frameworks: public and private ones. The public frameworks get installed into the Frameworks
+diretories in /Library, /System/Library or ~/Library and are meant to be shared amongst
+applications. The private frameworks are only distributed as parts of an Application Bundle.
+This makes it easier to deploy applications because they bring their own framework invisibly to
+the user. No installation of the framework is necessary and different applications can bring
 different versions of the same framework without any conflict.
-Since OpenCV is still a moving target, it seems best to avoid any installation and versioning issues 
-for an end user. The OpenCV framework that currently comes with this demo application therefore 
+Since OpenCV is still a moving target, it seems best to avoid any installation and versioning issues
+for an end user. The OpenCV framework that currently comes with this demo application therefore
 is a Private Framework.
 
 Use it for targets that result in an Application Bundle:
old mode 100755 (executable)
new mode 100644 (file)
index b33908f..7bf53e7
@@ -16,10 +16,10 @@ Then create the binary directory for the example with:
 
 Then, if "make install" have been executed, directly running
  $ cmake <OPENCV_SRC_PATH>/samples/c/example_cmake/
+
 will detect the "OpenCVConfig.cmake" file and the project is ready to compile.
 
-If "make install" has not been executed, you'll have to manually pick the opencv 
+If "make install" has not been executed, you'll have to manually pick the opencv
 binary directory (Under Windows CMake may remember the correct directory). Open
 the CMake gui with:
  $ cmake-gui <OPENCV_SRC_PATH>/samples/c/example_cmake/
@@ -27,6 +27,6 @@ the CMake gui with:
 And pick the correct value for OpenCV_DIR.
 
 
+