mirror/opencv
1
0
Fork 0
mirror of https://github.com/opencv/opencv.git synced 2024-11-28 21:20:18 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Some tutorial extending of the Windows install and usage. Display Image retouching.

Browse Source
This commit is contained in:
Bernat Gabor 2011-07-08 19:43:29 +00:00
parent 6f6c1c75ba
commit 4168b75edc
8 changed files with 178 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
doc/tutorials/imgproc/imgtrans/hough_circle/hough_circle.rst
View File

@ -40,7 +40,12 @@ Code
* Applies the *Hough Circle Transform* to the blurred image .
* Display the detected circle in a window.
#. The sample code that we will explain can be downloaded from `here <https://code.ros.org/svn/opencv/trunk/opencv/samples/cpp/houghlines.cpp>`_. A slightly fancier version (which shows both Hough standard and probabilistic with trackbars for changing the threshold values) can be found `here <https://code.ros.org/svn/opencv/trunk/opencv/samples/cpp/tutorial_code/ImgTrans/HoughCircle_Demo.cpp>`_
.. |TutorialHoughCirclesSimpleDownload| replace:: here
.. _TutorialHoughCirclesSimpleDownload: https://code.ros.org/svn/opencv/trunk/opencv/samples/cpp/houghlines.cpp
.. |TutorialHoughCirclesFancyDownload| replace:: here
.. _TutorialHoughCirclesFancyDownload: https://code.ros.org/svn/opencv/trunk/opencv/samples/cpp/tutorial_code/ImgTrans/HoughCircle_Demo.cpp
#. The sample code that we will explain can be downloaded from |TutorialHoughCirclesSimpleDownload|_. A slightly fancier version (which shows both Hough standard and probabilistic with trackbars for changing the threshold values) can be found |TutorialHoughCirclesFancyDownload|_.
.. code-block:: cpp

133
doc/tutorials/introduction/display_image/display_image.rst
View File

@ -1,105 +1,114 @@
.. _Display_Image:
Display an Image
*****************
Load and 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 <>`)
.. container:: enumeratevisibleitemswithsquare
Code
=====
* Load an image (using :imread:`imread <>`)
* Create a named OpenCV window (using :named_window:`namedWindow <>`)
* Display an image in an OpenCV window (using :imshow:`imshow <>`)
Here it is:
Source Code
===========
.. 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;
}
Download the :download:`source code from here <../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp>` or look it up in our library at :file:`samples/cpp/tutorial_code/introduction/display_image/display_image.cpp`.
.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
:language: cpp
:tab-width: 4
:linenos:
Explanation
============
#. .. code-block:: cpp
In OpenCV 2 we have multiple modules. Each one takes care of a different area or approach towards image processing. You could already observe this in the structure of the user guide of these tutorials itself. Before you use any of them you first need to include the header files where the content of each individual module is declared.
#include <cv.h>
#include <highgui.h>
You'll almost always end up using the:
using namespace cv;
.. container:: enumeratevisibleitemswithsquare
These are OpenCV headers:
+ *core* section, as here are defined the basic building blocks of the library
+ *highgui* module, as this contains the functions for input and output operations
* *cv.h* : Main OpenCV functions
* *highgui.h* : Graphical User Interface (GUI) functions
.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/windows_visual_studio_Opencv/Test.cpp
:language: cpp
:tab-width: 4
:lines: 1-3
Now, let's analyze the *main* function:
We also include the *iostream* to facilitate console line output and input. To avoid data structure and function name conflicts with other libraries, OpenCV has its own namespace: *cv*. To avoid the need appending prior each of these the *cv::* keyword you can import the namespace in the whole file by using the lines:
#. .. code-block:: cpp
.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
:language: cpp
:tab-width: 4
:lines: 5-6
Mat image;
This is true for the STL library too (used for console I/O). Now, let's analyze the *main* function. We start up assuring that we acquire a valid image name argument from the command line.
We create a Mat object to store the data of the image to load.
.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
:language: cpp
:tab-width: 4
:lines: 10-14
#. .. code-block:: cpp
Then create a *Mat* object that will store the data of the loaded image.
image = imread( argv[1], 1 );
.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
:language: cpp
:tab-width: 4
:lines: 16
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.
Now we call the :imread:`imread <>` function which loads the image name specified by the first argument (*argv[1]*). The second argument specifies the format in what we want the image. This may be:
#. After checking that the image data was loaded correctly, we want to display our image, so we create a window:
.. container:: enumeratevisibleitemswithsquare
.. code-block:: cpp
+ CV_LOAD_IMAGE_UNCHANGED (<0) loads the image as is (including the alpha channel if present)
+ CV_LOAD_IMAGE_GRAYSCALE ( 0) loads the image as an intensity one
+ CV_LOAD_IMAGE_COLOR (>0) loads the image in the RGB format
namedWindow( "Display Image", CV_WINDOW_AUTOSIZE );
.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
:language: cpp
:tab-width: 4
:lines: 17
.. note::
: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.
OpenCV offers support for the image formats Windows bitmap (bmp), portable image formats (pbm, pgm, ppm) and Sun raster (sr, ras). With help of plugins (you need to specify to use them if you build yourself the library, nevertheless in the packages we ship present by default) you may also load image formats like JPEG (jpeg, jpg, jpe), JPEG 2000 (jp2 - codenamed in the CMake as Jasper), TIFF files (tiff, tif) and portable network graphics (png). Furthermore, OpenEXR is also a possibility.
#. Finally, it is time to show the image, for this we use :imshow:`imshow <>`
After checking that the image data was loaded correctly, we want to display our image, so we create an OpenCV window using the :named_window:`namedWindow <>` function. These are automatically managed by OpenCV once you create them. For this you need to specify its name and how it should handle the change of the image it contains from a size point of view. It may be:
.. code-block:: cpp
.. container:: enumeratevisibleitemswithsquare
imshow( "Display Image", image )
+ *CV_WINDOW_AUTOSIZE* is the only supported one if you do not use the Qt backend. In this case the window size will take up the size of the image it shows. No resize permitted!
+ *CV_WINDOW_NORMAL* on Qt you may use this to allow window resize. The image will resize itself according to the current window size. By using the | operator you also need to specify if you would like the image to keep its aspect ratio (*CV_WINDOW_KEEPRATIO*) or not (*CV_WINDOW_FREERATIO*).
#. Finally, we want our window to be displayed until the user presses a key (otherwise the program would end far too quickly):
.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
:language: cpp
:lines: 25
:tab-width: 4
.. code-block:: cpp
Finally, to update the content of the OpenCV window with a new image use the :imshow:`imshow <>` function. Specify the OpenCV window name to update and the image to use during this operation:
waitKey(0);
.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
:language: cpp
:lines: 26
:tab-width: 4
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.
Because we want our window to be displayed until the user presses a key (otherwise the program would end far too quickly), we use the :wait_key:`waitKey <>` function whose only parameter is just how long should it wait for a user input (measured in milliseconds). Zero means to wait forever.
.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
:language: cpp
:lines: 28
:tab-width: 4
Result
=======
* Compile your code and then run the executable giving a image path as argument:
* Compile your code and then run the executable giving an image path as argument. If you're on Windows the executable will of course contain an *exe* extension too. Of course assure the image file is near your program file.
.. code-block:: bash
@ -110,3 +119,9 @@ Result
.. image:: images/Display_Image_Tutorial_Result.png
:alt: Display Image Tutorial - Final Result
:align: center
.. raw:: html
<div align="center">
<iframe title="Introduction - Display an Image" width="560" height="349" src="http://www.youtube.com/embed/1OJEqpuaGc4?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
</div>

56
doc/tutorials/introduction/windows_install/windows_install.rst
View File

@ -67,65 +67,66 @@ While the later one may contain a couple of new and experimental algorithms, per
Building the OpenCV library from scratch requires a couple of tools installed beforehand:
.. |CMake| replace:: CMake
.. _CMake: http://www.cmake.org/cmake/resources/software.html
.. |TortoiseSVN| replace:: TortoiseSVN
.. _TortoiseSVN: http://tortoisesvn.net/downloads.html
.. |Python_Libraries| replace:: Python libraries
.. _Python_Libraries: http://www.python.org/getit/
.. |Numpy| replace:: Numpy
.. _Numpy: http://numpy.scipy.org/
.. |IntelTBB| replace:: Intel |copy| Threading Building Blocks (*TBB*)
.. _IntelTBB: http://threadingbuildingblocks.org/file.php?fid=77
.. |IntelIIP| replace:: Intel |copy| Integrated Performance Primitives (*IPP*)
.. _IntelIIP: http://software.intel.com/en-us/articles/intel-ipp/
.. |qtframework| replace:: Qt framework
.. _qtframework: http://qt.nokia.com/downloads
.. |Eigen| replace:: Eigen
.. _Eigen: http://eigen.tuxfamily.org/index.php?title=Main_Page#Download
.. |CUDA_Toolkit| replace:: CUDA Toolkit
.. _CUDA_Toolkit: http://developer.nvidia.com/cuda-downloads
.. |OpenEXR| replace:: OpenEXR
.. _OpenEXR: http://www.openexr.com/downloads.html
.. |OpenNI_Framework| replace:: OpenNI Framework
.. _OpenNI_Framework: http://www.openni.org/
.. |Miktex| replace:: Miktex
.. _Miktex: http://miktex.org/2.9/setup
.. |Sphinx| replace:: Sphinx
.. _Sphinx: http://sphinx.pocoo.org/
.. container:: enumeratevisibleitemswithsquare
+ An **I**\ ntegrated **D**\ eveloper **E**\ nviroment (*IDE*) preferably, or just a C\C++ compiler that will actually make the binary files. Here I will use the `Microsoft Visual Studio <https://www.microsoft.com/visualstudio/en-us>`_. Nevertheless, you can use any other *IDE* that has a valid C\\C++ compiler.
+ Then |CMake|_ is a neat tool that will make the project files (for your choosen *IDE*) from the OpenCV source files. It will also allow an easy configuration of the OpenCV build files, in order to make binary files that fits exactly to your needs.
.. |CMake| replace:: CMake
.. _CMake: http://www.cmake.org/cmake/resources/software.html
+ A **S**\ ubversion **C**\ ontrol **S**\ ystem (*SVN*) to acquire the OpenCV source files. A good tool for this is |TortoiseSVN|_. Alternatively, you can just download an archived version of the source files from the `Sourceforge OpenCV page <http://sourceforge.net/projects/opencvlibrary/files/opencv-win/>`_.
.. |TortoiseSVN| replace:: TortoiseSVN
.. _TortoiseSVN: http://tortoisesvn.net/downloads.html
OpenCV may come in multiple flavors. There is a "core" section that will work on its own. Nevertheless, they are a couple of tools, libraries made by other organizations (so called 3rd parties) that offer services of which the OpenCV may take advantage. These will improve in many ways its capabilities. In order to use any of them, you need to download and install them on your system.
.. container:: enumeratevisibleitemswithsquare
+ The |Python_Libraries|_ are required to build the *Python interface* of OpenCV. For now use the version :file:`2.7.{x}`. This is also a must have if you want to build the *OpenCV documentation*.
.. |Python_Libraries| replace:: Python libraries
.. _Python_Libraries: http://www.python.org/getit/
+ |Numpy|_ is a scientific computing package for Python. Required for the *Python interface*.
.. |Numpy| replace:: Numpy
.. _Numpy: http://numpy.scipy.org/
+ |IntelTBB|_ is used inside OpenCV for parallel code snippets. Using this will make sure that the OpenCV library will take advantage of all the cores you have in your systems CPU.
.. |IntelTBB| replace:: Intel |copy| Threading Building Blocks (*TBB*)
.. _IntelTBB: http://threadingbuildingblocks.org/file.php?fid=77
+ |IntelIIP|_ may be used to improve the performance of color conversion, Haar training and DFT functions of the OpenCV library. Watch out as this isn't a *free* service.
.. |IntelIIP| replace:: Intel |copy| Integrated Performance Primitives (*IPP*)
.. _IntelIIP: http://software.intel.com/en-us/articles/intel-ipp/
+ OpenCV offers a somewhat fancier and more useful graphical user interface, than the default one by using the |qtframework|_. For a quick overview of what this has to offer look into the documentations *highgui* module, under the *Qt New Functions* section. Version 4.6 or later of the framework is required.
.. |qtframework| replace:: Qt framework
.. _qtframework: http://qt.nokia.com/downloads
+ |Eigen|_ is a C++ template library for linear algebra.
.. |Eigen| replace:: Eigen
.. _Eigen: http://eigen.tuxfamily.org/index.php?title=Main_Page#Download
+ The latest |CUDA_Toolkit|_ will allow you to use the power lying inside your GPU. This will drastically improve performance for some of the algorithms, like the HOG descriptor. Getting to work more and more of our algorithms on the GPUs is a constant effort of the OpenCV team.
.. |CUDA_Toolkit| replace:: CUDA Toolkit
.. _CUDA_Toolkit: http://developer.nvidia.com/cuda-downloads
+ |OpenEXR|_ source files are required for the library to work with this high dynamic range (HDR) image file format.
.. |OpenEXR| replace:: OpenEXR
.. _OpenEXR: http://www.openexr.com/downloads.html
+ The |OpenNI_Framework|_ contains a set of open source APIs that provide support for natural interaction with devices via methods such as voice command recognition, hand gestures and body motion tracking.
.. |OpenNI_Framework| replace:: OpenNI Framework
.. _OpenNI_Framework: http://www.openni.org/
+ |Miktex|_ is the best `TEX <https://secure.wikimedia.org/wikipedia/en/wiki/TeX>`_ implementation on the Windows OS. It is required to build the *OpenCV documentation*.
.. |Miktex| replace:: Miktex
.. _Miktex: http://miktex.org/2.9/setup
+ |Sphinx|_ is a python documentation generator and is the tool that will actually create the *OpenCV documentation*. This on its own requires a couple of tools installed, I will cover this in depth at the :ref:`How to Install Sphinx <HereInstallSphinx>` section.
.. |Sphinx| replace:: Sphinx
.. _Sphinx: http://sphinx.pocoo.org/
Now I will describe the steps to follow for a full build (using all the above frameworks, tools and libraries). If you do not need the support for some of these you can just freely skip those parts.
@ -221,7 +222,8 @@ Building the library
.. code-block:: bash
configure.exe -release -no-webkit -no-phonon -no-phonon-backend -no-script -no-scripttools -no-qt3support -no-multimedia -no-ltcg
configure.exe -release -no-webkit -no-phonon -no-phonon-backend -no-script -no-scripttools
-no-qt3support -no-multimedia -no-ltcg
Completing this will take around 10-20 minutes. Then enter the next command that will take a lot longer (can easily take even more than a full hour):

BIN
doc/tutorials/introduction/windows_visual_studio_Opencv/images/VisualStudioCommandLineArguments.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

21
doc/tutorials/introduction/windows_visual_studio_Opencv/windows_visual_studio_Opencv.rst
View File

@ -142,7 +142,6 @@ The process is the same as described in case of the local approach. Just add the
Test it!
========
Now to try this out download our little test :download:`source code <../../../../samples/cpp/tutorial_code/introduction/windows_visual_studio_Opencv/Test.cpp>` or get it from the sample code folder of the OpenCV sources. Add this to your project and build it. Here's its content:
.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/windows_visual_studio_Opencv/Test.cpp
@ -154,10 +153,28 @@ 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/introduction/windows_visual_studio_Opencv/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.
:align: center
Command line arguments with Visual Studio
=========================================
Throughout some of our future tutorials you'll see that the programs main input method will be by giving a runtime argument. To do this you can just start up a commmand windows (:kbd:`cmd + Enter` in the start menu), navigate to your executable file and start it with an argument. So for example in case of my upper project this would look like:
.. code-block:: bash
:linenos:
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:
.. image:: images/VisualStudioCommandLineArguments.jpg
:alt: Visual Studio Command Line Arguments
:align: center
Specify here the name of the inputs and while you start your application from the Visual Studio enviroment you have automatic argument passing. In the next introductionary tutorial you'll see an in-depth explanation of the upper source code: :ref:`Display_Image`.

4
doc/tutorials/tutorials.rst
View File

@ -1,6 +1,6 @@
###############
################
OpenCV Tutorials
###############
################
The following links describe a set of basic OpenCV tutorials. All the source code mentioned here is provide as part of the OpenCV regular releases, so check before you start copy & pasting the code. The list of tutorials below is automatically generated from reST files located in our SVN repository.

0
samples/cpp/tutorial_code/introduction/windows_visual_studio_Opencv/opencv-logo.png → samples/cpp/tutorial_code/images/opencv-logo.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 14 KiB

30
samples/cpp/tutorial_code/introduction/display_image/display_image.cpp Normal file
View File

@ -0,0 +1,30 @@
#include <opencv2/core/core.hpp>
#include <opencv2/highgui/highgui.hpp>
#include <iostream>
using namespace cv;
using namespace std;
int main( int argc, char** argv )
{
if( argc != 2)
{
cout <<" Usage: display_image ImageToLoadAndDisplay" << endl;
return -1;
}
Mat image;
image = imread(argv[1], CV_LOAD_IMAGE_COLOR); // Read the file
if(! image.data ) // Check for invalid input
{
cout << "Could not open or find the image" << std::endl ;
return -1;
}
namedWindow( "Display window", CV_WINDOW_AUTOSIZE );// Create a window for display.
imshow( "Display window", image ); // Show our image inside it.
waitKey(0); // Wait for a keystroke in the window
return 0;
}