Folder Intro

doc/tutorials/Intro/Display_Image/Display_Image.rst

@@ -0,0 +1,112 @@
+.. _Display_Image:
+
+Display an Image
+*****************
+
+Goal
+=====
+
+In this tutorial you will learn how to:
+
+* Load an image using :imread:`imread <>`
+* Create a named window (using :named_window:`namedWindow <>`)
+* Display an image in an OpenCV window (using :imshow:`imshow <>`)
+
+Code
+=====
+
+Here it is:
+
+.. code-block:: cpp
+
+   #include <cv.h>
+   #include <highgui.h>
+
+   using namespace cv;
+
+   int main( int argc, char** argv )
+   {
+    Mat image;
+    image = imread( argv[1], 1 );
+
+    if( argc != 2 || !image.data )
+      { 
+        printf( "No image data \n" );
+        return -1; 
+      }
+
+    namedWindow( "Display Image", CV_WINDOW_AUTOSIZE );
+    imshow( "Display Image", image );
+
+    waitKey(0);
+
+    return 0;
+   }
+
+
+Explanation
+============
+
+#. .. code-block:: cpp
+
+      #include <cv.h>
+      #include <highgui.h>
+   
+      using namespace cv;
+
+   These are OpenCV headers:
+
+   * *cv.h* : Main OpenCV functions
+   * *highgui.h* : Graphical User Interface (GUI) functions
+
+   Now, let's analyze the *main* function:
+
+#. .. code-block:: cpp 
+
+      Mat image;
+   
+   We create a Mat object to store the data of the image to load.
+
+#. .. code-block:: cpp
+    
+      image = imread( argv[1], 1 );
+
+   Here, we called the function :imread:`imread <>` which basically loads the image specified by the first argument (in this case *argv[1]*). The second argument is by default.
+
+#. After checking that the image data was loaded correctly, we want to display our image, so we create a window:
+
+   .. code-block:: cpp
+
+      namedWindow( "Display Image", CV_WINDOW_AUTOSIZE );
+
+
+   :named_window:`namedWindow <>` receives as arguments the window name ("Display Image") and an additional argument that defines windows properties. In this case **CV_WINDOW_AUTOSIZE** indicates that the window will adopt the size of the image to be displayed.
+
+#. Finally, it is time to show the image, for this we use :imshow:`imshow <>` 
+
+   .. code-block:: cpp
+  
+      imshow( "Display Image", image )
+
+#. Finally, we want our window to be displayed until the user presses a key (otherwise the program would end far too quickly):
+
+   .. code-block:: cpp
+ 
+      waitKey(0);
+
+   We use the :wait_key:`waitKey <>` function, which allow us to wait for a keystroke during a number of milliseconds (determined by the argument). If the argument is zero, then it will wait indefinitely.
+
+Result
+=======
+
+* Compile your code and then run the executable giving a image path as argument:
+
+  .. code-block:: bash
+ 
+     ./DisplayImage HappyFish.jpg
+
+* You should get a nice window as the one shown below:
+
+  .. image:: images/Display_Image_Tutorial_Result.png
+     :alt: Display Image Tutorial - Final Result
+     :align: center 

doc/tutorials/Intro/Linux_Eclipse_Usage/Linux_Eclipse_Usage.rst

@@ -0,0 +1,243 @@
+.. _Linux_Eclipse_Usage:
+
+Using OpenCV with Eclipse (plugin CDT)
+****************************************
+
+.. note::
+   For me at least, this works, is simple and quick. Suggestions are welcome
+
+Prerequisites
+===============
+
+#. 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  
+
+   * 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.
+
+#. Having installed OpenCV. If not yet, go :ref:`here <Linux_Installation>`
+
+Making a project
+=================
+
+#. Start Eclipse. Just run the executable that comes in the folder. 
+
+#. Go to **File -> New -> C/C++ Project**
+
+   .. image:: images/Eclipse_Tutorial_Screenshot-0.png
+      :height: 400px 
+      :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. 
+
+   .. image:: images/Eclipse_Tutorial_Screenshot-1.png
+      :height: 400px 
+      :alt: Eclipse Tutorial Screenshot 1
+      :align: center
+
+#. Leave everything else by default. Press **Finish**. 
+
+   .. image:: images/Eclipse_Tutorial_Screenshot-2.png
+      :height: 400px 
+      :alt: Eclipse Tutorial Screenshot 2
+      :align: center
+
+#. Your project (in this case DisplayImage) should appear in the **Project Navigator** (usually at the left side of your window).
+
+   .. image:: images/Eclipse_Tutorial_Screenshot-3.png
+      :height: 400px 
+      :alt: Eclipse Tutorial Screenshot 3
+      :align: center
+
+
+#. Now, let's add a source file using OpenCV:
+
+   * Right click on **DisplayImage** (in the Navigator). **New -> Folder** . 
+
+     .. image:: images/Eclipse_Tutorial_Screenshot-4.png
+        :height: 400px 
+        :alt: Eclipse Tutorial Screenshot 4
+        :align: center
+
+   * Name your folder **src** and then hit **Finish**
+
+     .. image:: images/Eclipse_Tutorial_Screenshot-5.png
+        :height: 400px 
+        :alt: Eclipse Tutorial Screenshot 5
+        :align: center
+
+   * Right click on your newly created **src** folder. Choose **New source file**:
+
+     .. image:: images/Eclipse_Tutorial_Screenshot-6.png
+        :height: 400px 
+        :alt: Eclipse Tutorial Screenshot 6
+        :align: center
+
+   * Call it **DisplayImage.cpp**. Hit **Finish**
+
+     .. image:: images/Eclipse_Tutorial_Screenshot-7.png
+        :height: 400px 
+        :alt: Eclipse Tutorial Screenshot 7
+        :align: center
+
+#. So, now you have a project with a empty .cpp file. Let's fill it with some sample code (in other words, copy and paste the snippet below):
+
+   .. code-block:: cpp
+
+      #include <cv.h>
+      #include <highgui.h>
+
+      using namespace cv;
+
+      int main( int argc, char** argv )
+      {
+        Mat image;
+        image = imread( argv[1], 1 );
+
+        if( argc != 2 || !image.data )
+          { 
+            printf( "No image data \n" );
+            return -1; 
+          }
+
+        namedWindow( "Display Image", CV_WINDOW_AUTOSIZE );
+        imshow( "Display Image", image );
+
+        waitKey(0);
+
+        return 0;
+      }
+
+#. We are only missing one final step: To tell OpenCV where the OpenCV headers and libraries are. For this, do the following:
+
+   * Go to  **Project-->Properties**
+
+     .. image:: images/Eclipse_Tutorial_Screenshot-8.png
+        :height: 400px 
+        :alt: Eclipse Tutorial Screenshot 8
+        :align: center
+
+    * In **C/C++ Build**, click on **Settings**. At the right, choose the **Tool Settings** Tab. Here we will enter the headers and libraries info:
+
+      a. In **GCC C++ Compiler**, go to **Includes**. In **Include paths(-l)** you should include the path of the folder where opencv was installed. In our example, this is: 
+         ::
+
+         /usr/local/include/opencv
+
+         .. image:: images/Eclipse_Tutorial_Screenshot-9.png
+            :height: 400px 
+            :alt: Eclipse Tutorial Screenshot 9
+            :align: center
+
+         .. note::
+            If you do not know where your opencv files are, open the **Terminal** and type: 
+
+            .. code-block:: bash
+            
+               pkg-config --cflags opencv
+
+            For instance, that command gave me this output:
+
+            .. code-block:: bash
+
+               -I/usr/local/include/opencv -I/usr/local/include 
+
+        
+      b. Now go to **GCC C++ Linker**,there you have to fill two spaces:
+
+          * 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
+
+          * 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_highgui
+            * opencv_ml       
+            * opencv_video      
+            * opencv_features2d
+            * opencv_calib3d   
+            * opencv_objdetect   
+            * opencv_contrib
+            * opencv_legacy    
+            * opencv_flann
+          
+          .. image:: images/Eclipse_Tutorial_Screenshot-10.png
+             :height: 400px 
+             :alt: Eclipse Tutorial Screenshot 10
+             :align: center 
+
+          .. note::
+
+             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  
+
+          Now you are done. Click **OK**
+
+    * Your project should be ready to be built. For this, go to **Project->Build all**   
+ 
+      .. image:: images/Eclipse_Tutorial_Screenshot-11.png
+         :height: 400px 
+         :alt: Eclipse Tutorial Screenshot 11
+         :align: center 
+
+      In the Console you should get something like 
+
+      .. image:: images/Eclipse_Tutorial_Screenshot-12.png
+         :height: 200px 
+         :alt: Eclipse Tutorial Screenshot 12
+         :align: center 
+
+      If you check in your folder, there should be an executable there.
+
+Running the executable
+========================
+
+So, now we have an executable ready to run. If we were to use the Terminal, we would probably do something like:
+
+.. code-block:: bash
+
+   cd <DisplayImage_directory>
+   cd src
+   ./DisplayImage ../images/HappyLittleFish.jpg
+  
+Assuming that the image to use as the argument would be located in <DisplayImage_directory>/images/HappyLittleFish.jpg. We can still do this, but let's do it from Eclipse:
+
+
+#. Go to **Run->Run Configurations** 
+
+   .. image:: images/Eclipse_Tutorial_Screenshot-13.png
+      :height: 300px 
+      :alt: Eclipse Tutorial Screenshot 13
+      :align: center 
+
+#. 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.jpg**:
+
+   .. image:: images/Eclipse_Tutorial_Screenshot-14.png
+      :height: 300px 
+      :alt: Eclipse Tutorial Screenshot 14
+      :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/Eclipse_Tutorial_Screenshot-15.png
+      :alt: Eclipse Tutorial Screenshot 15
+      :align: center 
+
+
+#. Congratulations! You are ready to have fun with OpenCV using Eclipse.

doc/tutorials/Intro/Linux_GCC_Usage/Linux_GCC_Usage.rst

@@ -0,0 +1,85 @@
+.. _Linux_GCC_Usage:
+
+Using OpenCV with gcc and CMake
+*********************************
+
+.. note::
+   We assume that you have successfully installed OpenCV in your workstation.
+
+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 ) 
+
+If you are not familiar with CMake, checkout the `tutorial <http://www.cmake.org/cmake/help/cmake_tutorial.html>`_ on its website.
+
+Steps
+======
+
+Create a program using OpenCV
+-------------------------------
+
+Let's use a simple program such as DisplayImage.cpp shown below. 
+
+.. code-block:: cpp
+
+   #include <cv.h>
+   #include <highgui.h>
+
+   using namespace cv;
+
+   int main( int argc, char** argv )
+   {
+     Mat image;
+     image = imread( argv[1], 1 );
+
+     if( argc != 2 || !image.data )
+       { 
+         printf( "No image data \n" );
+         return -1; 
+       }
+
+     namedWindow( "Display Image", CV_WINDOW_AUTOSIZE );
+     imshow( "Display Image", image );
+
+     waitKey(0);
+
+     return 0;
+   }
+
+Create a CMake file
+---------------------
+Now you have to create your CMakeLists.txt file. It should look like this:
+
+.. code-block:: cmake
+
+   cmake_minimum_required(VERSION 2.8)
+   project( DisplayImage )
+   find_package( OpenCV REQUIRED )
+   add_executable( DisplayImage DisplayImage )
+   target_link_libraries( DisplayImage ${OpenCV_LIBS} )
+
+Generate the executable
+-------------------------
+This part is easy, just proceed as with any other project using CMake:
+
+.. code-block:: bash
+
+   cd <DisplayImage_directory>
+   cmake .
+   make
+
+Result
+--------
+By now you should have an executable (called DisplayImage in this case). You just have to run it giving an image location as an argument, i.e.:
+
+.. code-block:: bash
+
+   ./DisplayImage lena.jpg
+
+You should get a nice window as the one shown below:
+
+.. image:: images/GCC_CMake_Example_Tutorial.png
+   :alt: Display Image - Lena
+   :align: center
+

doc/tutorials/Intro/Linux_Installation/Linux_Installation.rst

@@ -0,0 +1,85 @@
+.. _Linux_Installation:
+
+Installation in Linux
+***********************
+These steps have been tested for Ubuntu 10.04 but should work with other distros.
+
+Required packages
+==================
+
+  * GCC 4.x or later. This can be installed with
+
+    .. code-block:: bash
+
+       sudo apt-get install build-essential 
+ 
+  * CMake 2.6 or higher
+  * Subversion (SVN) client
+  * GTK+2.x or higher, including headers
+  * pkgconfig
+  * libpng, zlib, libjpeg, libtiff, libjasper with development files (e.g. libpjeg-dev)
+  * Python 2.3 or later with developer packages (e.g. python-dev)
+  * SWIG 1.3.30 or later
+  * libavcodec
+  * libdc1394 2.x 
+
+All the libraries above can be installed via Terminal or by using Synaptic Manager
+
+Getting OpenCV source code 
+============================
+
+You can use the latest stable OpenCV version available in *sourceforge* or you can grab the latest snapshot from the SVN repository:
+
+Getting the latest stable OpenCV version
+------------------------------------------
+
+* Go to http://sourceforge.net/projects/opencvlibrary
+
+* Download the source tarball and unpack it
+
+
+Getting the cutting-edge OpenCV from SourceForge SVN repository
+-----------------------------------------------------------------
+
+Launch SVN client and checkout either
+
+a. the current OpenCV snapshot from here: https://code.ros.org/svn/opencv/trunk
+
+#. or the latest tested OpenCV snapshot from here: http://code.ros.org/svn/opencv/tags/latest_tested_snapshot
+
+In Ubuntu it can be done using the following command, e.g.:
+
+.. code-block:: bash
+
+   cd ~/<my_working _directory>
+   svn co https://code.ros.org/svn/opencv/trunk  
+ 
+
+Building OpenCV from source using CMake, using the command line
+================================================================
+
+#. Create a temporary directory, which we denote as <cmake_binary_dir>, where you want to put the generated Makefiles, project files as well the object filees and output binaries
+
+#. 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
+
+

doc/tutorials/Intro/Load_Save_Image/Load_Save_Image.rst

@@ -0,0 +1,122 @@
+.. _Load_Save_Image:
+
+Load and Save an Image
+***********************
+
+.. note::
+
+   We assume that by now you know:
+
+   * Load an image using :imread:`imread <>`
+   * Display an image in an OpenCV window (using :imshow:`imshow <>`)
+ 
+Goals
+======
+
+In this tutorial you will learn how to:
+
+* Transform an image from RGB to Grayscale format by using :cvt_color:`cvtColor <>`
+* Save your transformed image in a file on disk (using :imwrite:`imwrite <>`)
+
+Code
+======
+
+Here it is:
+
+.. code-block:: cpp
+   :linenos:
+
+   #include <cv.h>
+   #include <highgui.h>
+
+   using namespace cv;
+
+   int main( int argc, char** argv )
+   {
+    char* imageName = argv[1];
+
+    Mat image; 
+    image = imread( imageName, 1 );
+  
+    if( argc != 2 || !image.data )
+    {
+      printf( " No image data \n " );
+      return -1;
+    }
+
+    Mat gray_image;
+    cvtColor( image, gray_image, CV_RGB2GRAY );
+
+    imwrite( "../../images/Gray_Image.png", gray_image );
+
+    namedWindow( imageName, CV_WINDOW_AUTOSIZE );
+    namedWindow( "Gray image", CV_WINDOW_AUTOSIZE );
+
+    imshow( imageName, image );
+    imshow( "Gray image", gray_image ); 
+
+    waitKey(0);
+
+    return 0;
+   }
+
+Explanation
+============
+
+#. We begin by:
+
+   * 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: 
+
+   .. code-block:: cpp
+     
+      cvtColor( image, gray_image, CV_RGB2GRAY );
+
+   As you can see, :cvt_color:`cvtColor <>` takes as arguments:
+
+   * a source image (*image*) 
+   * a destination image (*gray_image*), in which we will save the converted image.
+
+   And an additional parameter that indicates what kind of transformation will be performed. In this case we use **CV_RGB2GRAY** (self-explanatory).
+
+#. So now we have our new *gray_image* and want to save it on disk (otherwise it will get lost after the program ends). To save it, we will use a function analagous to :imread:`imread <>`: :imwrite:`imwrite <>`
+
+   .. code-block:: cpp
+
+      imwrite( "../../images/Gray_Image.png", gray_image );   
+
+   Which will save our *gray_image* as *Gray_Image.png* in the folder *images* located two levels up of my current location.
+
+#. Finally, let's check out the images. We create 02 windows and use them to show the original image as well as the new one:
+
+   .. code-block:: cpp
+
+      namedWindow( imageName, CV_WINDOW_AUTOSIZE );
+      namedWindow( "Gray image", CV_WINDOW_AUTOSIZE );
+
+      imshow( imageName, image );
+      imshow( "Gray image", gray_image );
+
+#. Add the usual *waitKey(0)* for the program to wait forever until the user presses a key.
+
+
+Result
+=======
+
+When you run your program you should get something like this:
+
+ .. image:: images/Load_Save_Image_Result_1.png
+    :alt: Load Save Image Result 1
+    :height: 400px
+    :align: center
+
+And if you check in your folder (in my case *images*), you should have a newly .png file named *Gray_Image.png*:
+
+ .. image:: images/Load_Save_Image_Result_2.png
+    :alt: Load Save Image Result 2
+    :height: 250px
+    :align: center
+
+Congratulations, you are done with this tutorial! 

doc/tutorials/Intro/Windows_Installation/Windows_Installation.rst

@@ -0,0 +1,5 @@
+.. _Windows_Installation:
+
+Installation in Windows
+***********************
+For now this is just a stub article. It will be updated with valuable content as soon as possible. Make sure to check back for it!