generic-library/opencv
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Normalize line endings and whitespace

Browse Source
This commit is contained in:
OpenCV Buildbot
2012-10-17 11:12:04 +04:00
committed by Andrey Kamaev
parent 0442bca235
commit 81f826db2b
1511 changed files with 258678 additions and 258624 deletions
Download Patch File Download Diff File Expand all files Collapse all files

520
doc/tutorials/introduction/linux_eclipse/linux_eclipse.rst
View File

@@ -1,260 +1,260 @@
.. _Linux_Eclipse_Usage:
Using OpenCV with Eclipse (plugin CDT)
****************************************
.. note::
Two ways, one by forming a project directly, and another by CMake
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
* 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
=================
1. Start Eclipse. Just run the executable that comes in the folder.
#. Go to **File -> New -> C/C++ Project**
.. image:: images/a0.png
: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/a1.png
:alt: Eclipse Tutorial Screenshot 1
:align: center
#. 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).
.. image:: images/a3.png
: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/a4.png
:alt: Eclipse Tutorial Screenshot 4
:align: center
* Name your folder **src** and then hit **Finish**
* Right click on your newly created **src** folder. Choose **New source file**:
* Call it **DisplayImage.cpp**. Hit **Finish**
.. image:: images/a7.png
: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**
* 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/a9.png
: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:
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_highgui
opencv_ml
opencv_video
opencv_features2d
opencv_calib3d
opencv_objdetect
opencv_contrib
opencv_legacy
opencv_flann
.. image:: images/a10.png
:alt: Eclipse Tutorial Screenshot 10
: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
Now you are done. Click **OK**
* Your project should be ready to be built. For this, go to **Project->Build all**
In the Console you should get something like
.. image:: images/a12.png
: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.png
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**
#. 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
#. 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
#. Congratulations! You are ready to have fun with OpenCV using Eclipse.
==================================================
V2: Using CMake+OpenCV with Eclipse (plugin CDT)
==================================================
(See the `getting started <http://opencv.willowgarage.com/wiki/Getting_started>` section of the OpenCV Wiki)
Say you have or create a new file, *helloworld.cpp* in a directory called *foo*:
.. code-block:: cpp
#include <cv.h>
#include <highgui.h>
int main ( int argc, char **argv )
{
cvNamedWindow( "My Window", 1 );
IplImage *img = cvCreateImage( cvSize( 640, 480 ), IPL_DEPTH_8U, 1 );
CvFont font;
double hScale = 1.0;
double vScale = 1.0;
int lineWidth = 1;
cvInitFont( &font, CV_FONT_HERSHEY_SIMPLEX | CV_FONT_ITALIC,
hScale, vScale, 0, lineWidth );
cvPutText( img, "Hello World!", cvPoint( 200, 400 ), &font,
cvScalar( 255, 255, 0 ) );
cvShowImage( "My Window", img );
cvWaitKey();
return 0;
}
1. Create a build directory, say, under *foo*: ``mkdir /build``. Then ``cd build``.
#. Put a *CmakeLists.txt* file in build:
.. code-block:: bash
PROJECT( helloworld_proj )
FIND_PACKAGE( OpenCV REQUIRED )
ADD_EXECUTABLE( helloworld helloworld.cxx )
TARGET_LINK_LIBRARIES( helloworld ${OpenCV_LIBS} )
#. 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**
#. Run ``make -j4`` *(the ``-j4`` is optional, it just tells the compiler to build in 4 threads)*. Make sure it builds.
#. Start ``eclipse`` . Put the workspace in some directory but **not** in ``foo`` or ``foo\\build``
#. Right click in the ``Project Explorer`` section. Select ``Import`` And then open the ``C/C++`` filter. Choose *Existing Code* as a Makefile Project``
#. Name your project, say *helloworld*. Browse to the Existing Code location ``foo\\build`` (where you ran your cmake-gui from). Select *Linux GCC* in the *"Toolchain for Indexer Settings"* and press *Finish*.
#. Right click in the ``Project Explorer`` section. Select ``Properties``. Under ``C/C++ Build``, set the *build directory:* from something like ``${workspace_loc:/helloworld}`` to ``${workspace_loc:/helloworld}/build`` since that's where you are building to.
a. You can also optionally modify the ``Build command:`` from ``make`` to something like ``make VERBOSE=1 -j4`` which tells the compiler to produce detailed symbol files for debugging and also to compile in 4 parallel threads.
#. Done!
.. _Linux_Eclipse_Usage:
Using OpenCV with Eclipse (plugin CDT)
****************************************
.. note::
Two ways, one by forming a project directly, and another by CMake
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
* 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
=================
1. Start Eclipse. Just run the executable that comes in the folder.
#. Go to **File -> New -> C/C++ Project**
.. image:: images/a0.png
: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/a1.png
:alt: Eclipse Tutorial Screenshot 1
:align: center
#. 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).
.. image:: images/a3.png
: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/a4.png
:alt: Eclipse Tutorial Screenshot 4
:align: center
* Name your folder **src** and then hit **Finish**
* Right click on your newly created **src** folder. Choose **New source file**:
* Call it **DisplayImage.cpp**. Hit **Finish**
.. image:: images/a7.png
: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**
* 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/a9.png
: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:
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_highgui
opencv_ml
opencv_video
opencv_features2d
opencv_calib3d
opencv_objdetect
opencv_contrib
opencv_legacy
opencv_flann
.. image:: images/a10.png
:alt: Eclipse Tutorial Screenshot 10
: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
Now you are done. Click **OK**
* Your project should be ready to be built. For this, go to **Project->Build all**
In the Console you should get something like
.. image:: images/a12.png
: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.png
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**
#. 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
#. 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
#. Congratulations! You are ready to have fun with OpenCV using Eclipse.
==================================================
V2: Using CMake+OpenCV with Eclipse (plugin CDT)
==================================================
(See the `getting started <http://opencv.willowgarage.com/wiki/Getting_started>` section of the OpenCV Wiki)
Say you have or create a new file, *helloworld.cpp* in a directory called *foo*:
.. code-block:: cpp
#include <cv.h>
#include <highgui.h>
int main ( int argc, char **argv )
{
cvNamedWindow( "My Window", 1 );
IplImage *img = cvCreateImage( cvSize( 640, 480 ), IPL_DEPTH_8U, 1 );
CvFont font;
double hScale = 1.0;
double vScale = 1.0;
int lineWidth = 1;
cvInitFont( &font, CV_FONT_HERSHEY_SIMPLEX | CV_FONT_ITALIC,
hScale, vScale, 0, lineWidth );
cvPutText( img, "Hello World!", cvPoint( 200, 400 ), &font,
cvScalar( 255, 255, 0 ) );
cvShowImage( "My Window", img );
cvWaitKey();
return 0;
}
1. Create a build directory, say, under *foo*: ``mkdir /build``. Then ``cd build``.
#. Put a *CmakeLists.txt* file in build:
.. code-block:: bash
PROJECT( helloworld_proj )
FIND_PACKAGE( OpenCV REQUIRED )
ADD_EXECUTABLE( helloworld helloworld.cxx )
TARGET_LINK_LIBRARIES( helloworld ${OpenCV_LIBS} )
#. 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**
#. Run ``make -j4`` *(the ``-j4`` is optional, it just tells the compiler to build in 4 threads)*. Make sure it builds.
#. Start ``eclipse`` . Put the workspace in some directory but **not** in ``foo`` or ``foo\\build``
#. Right click in the ``Project Explorer`` section. Select ``Import`` And then open the ``C/C++`` filter. Choose *Existing Code* as a Makefile Project``
#. Name your project, say *helloworld*. Browse to the Existing Code location ``foo\\build`` (where you ran your cmake-gui from). Select *Linux GCC* in the *"Toolchain for Indexer Settings"* and press *Finish*.
#. Right click in the ``Project Explorer`` section. Select ``Properties``. Under ``C/C++ Build``, set the *build directory:* from something like ``${workspace_loc:/helloworld}`` to ``${workspace_loc:/helloworld}/build`` since that's where you are building to.
a. You can also optionally modify the ``Build command:`` from ``make`` to something like ``make VERBOSE=1 -j4`` which tells the compiler to produce detailed symbol files for debugging and also to compile in 4 parallel threads.
#. Done!

492
doc/tutorials/introduction/table_of_content_introduction/table_of_content_introduction.rst
View File

@@ -1,247 +1,247 @@
.. _Table-Of-Content-Introduction:
Introduction to OpenCV
-----------------------------------------------------------
Here you can read tutorials about how to set up your computer to work with the OpenCV library. Additionaly you can find a few very basic sample source code that will let introduce you to the world of the OpenCV.
.. include:: ../../definitions/tocDefinitions.rst
* **Linux**
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=========== ======================================================
|Install_1| **Title:** :ref:`Linux-Installation`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_AnaH|
We will learn how to setup OpenCV in your computer!
=========== ======================================================
.. |Install_1| image:: images/ubuntu-logo.jpg
:height: 90pt
:width: 90pt
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=========== ======================================================
|Usage_1| **Title:** :ref:`Linux_GCC_Usage`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_AnaH|
We will learn how to compile your first project using gcc and CMake
=========== ======================================================
.. |Usage_1| image:: images/gccegg-65.jpg
:height: 90pt
:width: 90pt
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=========== ======================================================
|Usage_2| **Title:** :ref:`Linux_Eclipse_Usage`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_AnaH|
We will learn how to compile your first project using the Eclipse environment
=========== ======================================================
.. |Usage_2| image:: images/eclipse_cpp_logo.jpeg
:height: 90pt
:width: 90pt
* **Windows**
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=========== ======================================================
|WinInstal| **Title:** :ref:`Windows_Installation`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_BernatG|
You will learn how to setup OpenCV in your Windows Operating System!
=========== ======================================================
.. |WinInstal| image:: images/windows_logo.jpg
:height: 90pt
:width: 90pt
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=========== ======================================================
|WinVSHowT| **Title:** :ref:`Windows_Visual_Studio_How_To`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_BernatG|
You will learn what steps you need to perform in order to use the OpenCV library inside a new Microsoft Visual Studio project.
=========== ======================================================
.. |WinVSHowT| image:: images/visual-studio-2010-logo.jpg
:height: 90pt
:width: 90pt
* **Android**
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
================ =================================================
|AndroidLogo| **Title:** :ref:`Android_Dev_Intro`
*Compatibility:* > OpenCV 2.4.2
*Author:* |Author_VsevolodG|
Not a tutorial, but a guide introducing Android development basics and environment setup
================ =================================================
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
================ =================================================
|AndroidLogo| **Title:** :ref:`O4A_SDK`
*Compatibility:* > OpenCV 2.4.2
*Author:* |Author_VsevolodG|
OpenCV4Android SDK: general info, installation, running samples
================ =================================================
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
================ =================================================
|AndroidLogo| **Title:** :ref:`dev_with_OCV_on_Android`
*Compatibility:* > OpenCV 2.4.2
*Author:* |Author_VsevolodG|
Development with OpenCV4Android SDK
================ =================================================
.. |AndroidLogo| image:: images/android_logo.png
:height: 90pt
:width: 90pt
* **iOS**
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
============= ======================================================
|Install_iOS| **Title:** :ref:`iOS-Installation`
*Compatibility:* > OpenCV 2.4.2
*Author:* |Author_ArtemM|, |Author_EduardF|
We will learn how to setup OpenCV for using it in iOS!
============= ======================================================
.. |Install_iOS| image:: images/opencv_ios.png
:width: 90pt
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
============= ======================================================
|Beginners_1| **Title:** :ref:`Display_Image`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_AnaH|
We will learn how to display an image using OpenCV
============= ======================================================
.. |Beginners_1| image:: images/Display_Image_Tutorial_Result.jpg
:height: 90pt
:width: 90pt
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=============== ======================================================
|Beginners_2| **Title:** :ref:`Load_Save_Image`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_AnaH|
We will learn how to save an Image in OpenCV...plus a small conversion to grayscale
=============== ======================================================
.. |Beginners_2| image:: images/Load_Save_Image_Result_1.jpg
:height: 90pt
:width: 90pt
* **Want to contribute, and see your own work between the OpenCV tutorials?**
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=============== ======================================================
|HowToWriteT| **Title:** :ref:`howToWriteTutorial`
*Compatibility:* > OpenCV 1.0
*Author:* |Author_BernatG|
If you already have a good grasp on using OpenCV and have made some projects that would be perfect presenting an OpenCV feature not yet part of these tutorials, here it is what you need to know.
=============== ======================================================
.. |HowToWriteT| image:: images/how_to_write_a_tutorial.png
:height: 90pt
:width: 90pt
.. raw:: latex
\pagebreak
.. We use a custom table of content format and as the table of content only imforms Sphinx about the hierarchy of the files, no need to show it.
.. toctree::
:hidden:
../linux_install/linux_install
../linux_gcc_cmake/linux_gcc_cmake
../linux_eclipse/linux_eclipse
../windows_install/windows_install
../windows_visual_studio_Opencv/windows_visual_studio_Opencv
../android_binary_package/android_dev_intro
../android_binary_package/O4A_SDK
../android_binary_package/dev_with_OCV_on_Android
../ios_install/ios_install
../display_image/display_image
../load_save_image/load_save_image
.. _Table-Of-Content-Introduction:
Introduction to OpenCV
-----------------------------------------------------------
Here you can read tutorials about how to set up your computer to work with the OpenCV library. Additionaly you can find a few very basic sample source code that will let introduce you to the world of the OpenCV.
.. include:: ../../definitions/tocDefinitions.rst
* **Linux**
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=========== ======================================================
|Install_1| **Title:** :ref:`Linux-Installation`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_AnaH|
We will learn how to setup OpenCV in your computer!
=========== ======================================================
.. |Install_1| image:: images/ubuntu-logo.jpg
:height: 90pt
:width: 90pt
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=========== ======================================================
|Usage_1| **Title:** :ref:`Linux_GCC_Usage`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_AnaH|
We will learn how to compile your first project using gcc and CMake
=========== ======================================================
.. |Usage_1| image:: images/gccegg-65.jpg
:height: 90pt
:width: 90pt
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=========== ======================================================
|Usage_2| **Title:** :ref:`Linux_Eclipse_Usage`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_AnaH|
We will learn how to compile your first project using the Eclipse environment
=========== ======================================================
.. |Usage_2| image:: images/eclipse_cpp_logo.jpeg
:height: 90pt
:width: 90pt
* **Windows**
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=========== ======================================================
|WinInstal| **Title:** :ref:`Windows_Installation`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_BernatG|
You will learn how to setup OpenCV in your Windows Operating System!
=========== ======================================================
.. |WinInstal| image:: images/windows_logo.jpg
:height: 90pt
:width: 90pt
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=========== ======================================================
|WinVSHowT| **Title:** :ref:`Windows_Visual_Studio_How_To`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_BernatG|
You will learn what steps you need to perform in order to use the OpenCV library inside a new Microsoft Visual Studio project.
=========== ======================================================
.. |WinVSHowT| image:: images/visual-studio-2010-logo.jpg
:height: 90pt
:width: 90pt
* **Android**
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
================ =================================================
|AndroidLogo| **Title:** :ref:`Android_Dev_Intro`
*Compatibility:* > OpenCV 2.4.2
*Author:* |Author_VsevolodG|
Not a tutorial, but a guide introducing Android development basics and environment setup
================ =================================================
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
================ =================================================
|AndroidLogo| **Title:** :ref:`O4A_SDK`
*Compatibility:* > OpenCV 2.4.2
*Author:* |Author_VsevolodG|
OpenCV4Android SDK: general info, installation, running samples
================ =================================================
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
================ =================================================
|AndroidLogo| **Title:** :ref:`dev_with_OCV_on_Android`
*Compatibility:* > OpenCV 2.4.2
*Author:* |Author_VsevolodG|
Development with OpenCV4Android SDK
================ =================================================
.. |AndroidLogo| image:: images/android_logo.png
:height: 90pt
:width: 90pt
* **iOS**
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
============= ======================================================
|Install_iOS| **Title:** :ref:`iOS-Installation`
*Compatibility:* > OpenCV 2.4.2
*Author:* |Author_ArtemM|, |Author_EduardF|
We will learn how to setup OpenCV for using it in iOS!
============= ======================================================
.. |Install_iOS| image:: images/opencv_ios.png
:width: 90pt
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
============= ======================================================
|Beginners_1| **Title:** :ref:`Display_Image`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_AnaH|
We will learn how to display an image using OpenCV
============= ======================================================
.. |Beginners_1| image:: images/Display_Image_Tutorial_Result.jpg
:height: 90pt
:width: 90pt
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=============== ======================================================
|Beginners_2| **Title:** :ref:`Load_Save_Image`
*Compatibility:* > OpenCV 2.0
*Author:* |Author_AnaH|
We will learn how to save an Image in OpenCV...plus a small conversion to grayscale
=============== ======================================================
.. |Beginners_2| image:: images/Load_Save_Image_Result_1.jpg
:height: 90pt
:width: 90pt
* **Want to contribute, and see your own work between the OpenCV tutorials?**
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=============== ======================================================
|HowToWriteT| **Title:** :ref:`howToWriteTutorial`
*Compatibility:* > OpenCV 1.0
*Author:* |Author_BernatG|
If you already have a good grasp on using OpenCV and have made some projects that would be perfect presenting an OpenCV feature not yet part of these tutorials, here it is what you need to know.
=============== ======================================================
.. |HowToWriteT| image:: images/how_to_write_a_tutorial.png
:height: 90pt
:width: 90pt
.. raw:: latex
\pagebreak
.. We use a custom table of content format and as the table of content only imforms Sphinx about the hierarchy of the files, no need to show it.
.. toctree::
:hidden:
../linux_install/linux_install
../linux_gcc_cmake/linux_gcc_cmake
../linux_eclipse/linux_eclipse
../windows_install/windows_install
../windows_visual_studio_Opencv/windows_visual_studio_Opencv
../android_binary_package/android_dev_intro
../android_binary_package/O4A_SDK
../android_binary_package/dev_with_OCV_on_Android
../ios_install/ios_install
../display_image/display_image
../load_save_image/load_save_image
../how_to_write_a_tutorial/how_to_write_a_tutorial

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

@@ -1,347 +1,347 @@
.. _Windows_Installation:
Installation in Windows
***********************
.. include:: <isonum.txt>
The description here was tested on Windows 7 SP1. Nevertheless, it should also work on any other relatively modern version of Windows OS. If you encounter errors after following the steps described below, feel free to contact us via our `OpenCV Q&A forum <http://answers.opencv.org>`_. We'll do our best to help you out.
.. note:: To use the OpenCV library you have two options: :ref:`Windows_Install_Prebuild` or :ref:`CppTutWindowsMakeOwn`. While the first one is easier to complete, it only works if you are coding with the latest Microsoft Visual Studio IDE and doesn't take advantage of the most advanced technologies we integrate into our library.
.. _Windows_Install_Prebuild:
Installation by Using the Pre-built Libraries
=============================================
#. Launch a web browser of choice and go to our `page on Sourceforge <http://sourceforge.net/projects/opencvlibrary/files/opencv-win/>`_.
#. Choose a build you want to use and download it.
.. If you downloaded the source files present here see :ref:`CppTutWindowsMakeOwn`.
#. Make sure you have admin rights. Start the setup and follow the wizard.
#. While adding the OpenCV library to the system path is a good decision for a better control, we will do it manually for the sake of this tutorial. Make sure you do not set this option.
#. Most of the time it is a good idea to install the source files too, as this will allow for you to debug into the OpenCV library, if it is necessary. Follow the default settings of the wizard and finish the installation.
#. You can check the installation at the chosen path as you can see below.
.. image:: images/OpenCV_Install_Directory.png
:alt: An example of how the installation directory should look in case of successful install.
:align: center
#. To finalize the installation go to the :ref:`WindowsSetPathAndEnviromentVariable` section.
.. _CppTutWindowsMakeOwn:
Installation by Making Your Own Libraries from the Source Files
===============================================================
You may find the content of this tutorial also inside the following videos: `Part 1 <https://www.youtube.com/watch?v=NnovZ1cTlMs>`_ and `Part 2 <https://www.youtube.com/watch?v=qGNWMcfWwPU>`_, hosted on YouTube.
.. raw:: html
<div align="center">
<iframe title="Install OpenCV by using its source files - Part 1" width="560" height="349" src="http://www.youtube.com/embed/NnovZ1cTlMs?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
<iframe title="Install OpenCV by using its source files - Part 2" width="560" height="349" src="http://www.youtube.com/embed/qGNWMcfWwPU?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
</div>
.. warning:: These videos above are long-obsolete and contain inaccurate information. Be careful, since solutions described in those videos are no longer supported and may even break your install.
If you are building your own libraries you can take the source files from our `Git repository <https://github.com/Itseez/opencv.git>`_.
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
.. |TortoiseGit| replace:: TortoiseGit
.. _TortoiseGit: http://code.google.com/p/tortoisegit/wiki/Download
.. |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 IDE of choice (preferably), or just a C\C++ compiler that will actually make the binary files. Here we will use the `Microsoft Visual Studio <https://www.microsoft.com/visualstudio/en-us>`_. However, you can use any other IDE that has a valid C\C++ compiler.
+ |CMake|_, which is a neat tool to 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.
+ Git to acquire the OpenCV source files. A good tool for this is |TortoiseGit|_. Alternatively, you can just download an archived version of the source files from our `page on Sourceforge <http://sourceforge.net/projects/opencvlibrary/files/opencv-win/>`_
OpenCV may come in multiple flavors. There is a "core" section that will work on its own. Nevertheless, there is a couple of tools, libraries made by 3rd parties that offer services of which the OpenCV may take advantage. These will improve its capabilities in many ways. 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 if you want to build the *OpenCV documentation*.
+ |Numpy|_ is a scientific computing package for Python. Required for the *Python interface*.
+ |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.
+ |IntelIIP|_ may be used to improve the performance of color conversion, Haar training and DFT functions of the OpenCV library. Watch out, since this isn't a free service.
+ 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.
+ |Eigen|_ is a C++ template library for linear algebra.
+ The latest |CUDA_Toolkit|_ will allow you to use the power lying inside your GPU. This will drastically improve performance for some algorithms (e.g the HOG descriptor). Getting more and more of our algorithms to work on the GPUs is a constant effort of the OpenCV team.
+ |OpenEXR|_ source files are required for the library to work with this high dynamic range (HDR) image file format.
+ 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.
+ |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*.
+ |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, We will cover this in depth at the :ref:`How to Install Sphinx <HereInstallSphinx>` section.
Now we 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 this section.
.. _WindowsBuildLibrary:
Building the library
^^^^^^^^^^^^^^^^^^^^
1. Make sure you have a working IDE with a valid compiler. In case of the Microsoft Visual Studio just install it and make sure it starts up.
#. Install |CMake|_. Simply follow the wizard, no need to add it to the path. The default install options are OK.
#. Download and install an up-to-date version of msysgit from its `official site <http://code.google.com/p/msysgit/downloads/list>`_. There is also the portable version, which you need only to unpack to get access to the console version of Git. Supposing that for some of us it could be quite enough.
#. 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.
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`).
#) Push the OK button and be patient as the repository is quite a heavy download. It will take some time depending on your Internet connection.
#. In this section I will cover installing the 3rd party libraries.
a) Download the |Python_Libraries|_ and install it with the default options. You will need a couple other python extensions. Luckily installing all these may be automated by a nice tool called `Setuptools <http://pypi.python.org/pypi/setuptools#downloads>`_. Download and install again.
#) .. _HereInstallSphinx:
Installing Sphinx is easy once you have installed *Setuptools*. This contains a little application that will automatically connect to the python databases and download the latest version of many python scripts. Start up a command window (enter *cmd* into the windows start menu and press enter) and use the *CD* command to navigate to your Python folders Script sub-folder. Here just pass to the *easy_install.exe* as argument the name of the program you want to install. Add the *sphinx* argument.
.. image:: images/cmsdstartwindows.jpg
:alt: The Windows Command Startup
:align: center
.. image:: images/Sphinx_Install.png
:alt: How to start the command window
:align: center
.. note::
The *CD* navigation command works only inside a drive. For example if you are somewhere in the *C:* drive you cannot use it this to go to another drive (like for example *D:*). To do so you first need to change drives letters. For this simply enter the command *D:*. Then you can use the *CD* to navigate to specific folder inside the drive. Bonus tip: you can clear the screen by using the *CLS* command.
This will also install its prerequisites `Jinja2 <http://jinja.pocoo.org/docs/>`_ and `Pygments <http://pygments.org/>`_.
#) The easiest way to install |Numpy|_ is to just download its binaries from the `sourceforga page <http://sourceforge.net/projects/numpy/files/NumPy/>`_. Make sure your download and install exactly the binary for your python version (so for version :file:`2.7`).
#) Download the |Miktex|_ and install it. Again just follow the wizard. At the fourth step make sure you select for the *"Install missing packages on-the-fly"* the *Yes* option, as you can see on the image below. Again this will take quite some time so be patient.
.. image:: images/MiktexInstall.png
:alt: The Miktex Install Screen
:align: center
#) For the |IntelTBB|_ download the source files and extract it inside a directory on your system. For example let there be :file:`D:/OpenCV/dep`. For installing the |IntelIIP|_ the story is the same. For exctracting the archives I recommend using the `7-Zip <http://www.7-zip.org/>`_ application.
.. image:: images/IntelTBB.png
:alt: The Miktex Install Screen
:align: center
#) In case of the |Eigen|_ library it is again a case of download and extract to the :file:`D:/OpenCV/dep` directory.
#) Same as above with |OpenEXR|_.
#) For the |OpenNI_Framework|_ you need to install both the `development build <http://www.openni.org/downloadfiles/opennimodules/openni-binaries/21-stable>`_ and the `PrimeSensor Module <http://www.openni.org/downloadfiles/opennimodules/openni-compliant-hardware-binaries/32-stable>`_.
#) For the CUDA you need again two modules: the latest |CUDA_Toolkit|_ and the *CUDA Tools SDK*. Download and install both of them with a *complete* option by using the 32 or 64 bit setups according to your OS.
#) In case of the |qtframework|_ you need to build yourself the binary files (unless you use the Microsoft Visual Studio 2008 with 32 bit compiler). To do this go to the `Qt Downloads <http://qt.nokia.com/downloads>`_ page. Download the source files (not the installers!!!):
.. image:: images/qtDownloadThisPackage.png
:alt: Download this Qt Package
:align: center
Extract it into a nice and short named directory like :file:`D:/OpenCV/dep/qt/` .
Then you need to build it. Start up a *Visual* *Studio* *Command* *Prompt* (*2010*) by using the start menu search (or navigate through the start menu :menuselection:`All Programs --> Microsoft Visual Studio 2010 --> Visual Studio Tools --> Visual Studio Command Prompt (2010)`).
.. image:: images/visualstudiocommandprompt.jpg
:alt: The Visual Studio command prompt
:align: center
Now navigate to the extracted folder and enter inside it by using this console window. You should have a folder containing files like *Install*, *Make* and so on. Use the *dir* command to list files inside your current directory. Once arrived at this directory enter the following command:
.. code-block:: bash
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):
.. code-block:: bash
nmake
After this set the Qt enviroment variables using the following command on Windows 7:
.. code-block:: bash
setx -m QTDIR D:/OpenCV/dep/qt/qt-everywhere-opensource-src-4.7.3
.. |PathEditor| replace:: Path Editor
.. _PathEditor: http://www.redfernplace.com/software-projects/patheditor/
Also, add the built binary files path to the system path by using the |PathEditor|_. In our case this is :file:`D:/OpenCV/dep/qt/qt-everywhere-opensource-src-4.7.3/bin`.
.. note::
If you plan on doing Qt application development you can also install at this point the *Qt Visual Studio Add-in*. After this you can make and build Qt applications without using the *Qt Creator*. Everything is nicely integrated into Visual Studio.
#. Now start the *CMake (cmake-gui)*. You may again enter it in the start menu search or get it from the :menuselection:`All Programs --> CMake 2.8 --> CMake (cmake-gui)`. First, select the directory for the source files of the OpenCV library (1). Then, specify a directory where you will build the binary files for OpenCV (2).
.. image:: images/CMakeSelectBin.jpg
:alt: Select the directories
:align: center
Press the Configure button to specify the compiler (and *IDE*) you want to use. Note that in case you can choose between different compilers for making either 64 bit or 32 bit libraries. Select the one you use in your application development.
.. image:: images/CMake_Configure_Windows.jpg
:alt: How CMake should look at build time.
:align: center
CMake will start out and based on your system variables will try to automatically locate as many packages as possible. You can modify the packages to use for the build in the :menuselection:`WITH --> WITH_X` menu points (where *X* is the package abbreviation). Here are a list of current packages you can turn on or off:
.. image:: images/CMakeBuildWithWindowsGUI.jpg
:alt: The packages OpenCV may use
:align: center
Select all the packages you want to use and press again the *Configure* button. For an easier overview of the build options make sure the *Grouped* option under the binary directory selection is turned on. For some of the packages CMake may not find all of the required files or directories. In case of these CMake will throw an error in its output window (located at the bottom of the GUI) and set its field values, to not found constants. For example:
.. image:: images/CMakePackageNotFoundWindows.jpg
:alt: Constant for not found packages
:align: center
.. image:: images/CMakeOutputPackageNotFound.jpg
:alt: Error (warning) thrown in output window of the CMake GUI
:align: center
For these you need to manually set the queried directories or files path. After this press again the *Configure* button to see if the value entered by you was accepted or not. Do this until all entries are good and you cannot see errors in the field/value or the output part of the GUI.
Now I want to emphasize an option that you will definitely love: :menuselection:`ENABLE --> ENABLE_SOLUTION_FOLDERS`. OpenCV will create many-many projects and turning this option will make sure that they are categorized inside directories in the *Solution Explorer*. It is a must have feature, if you ask me.
.. image:: images/CMakeBuildOptionsOpenCV.jpg
:alt: Set the Solution Folders and the parts you want to build
:align: center
Furthermore, you need to select what part of OpenCV you want to build.
.. container:: enumeratevisibleitemswithsquare
+ *BUILD_DOCS* -> It creates two projects for building the documentation of OpenCV (there will be a separate project for building the HTML and the PDF files). Note that these aren't built together with the solution. You need to make an explicit build project command on these to do so.
+ *BUILD_EXAMPLES* -> OpenCV comes with many example applications from which you may learn most of the libraries capabilities. This will also come handy to easily try out if OpenCV is fully functional on your computer.
+ *BUILD_PACKAGE* -> Prior to version 2.3 with this you could build a project that will build an OpenCV installer. With this you can easily install your OpenCV flavor on other systems. For the latest source files of OpenCV it generates a new project that simply creates zip archive with OpenCV sources.
+ *BUILD_SHARED_LIBS* -> With this you can control to build DLL files (when turned on) or static library files (\*.lib) otherwise.
+ *BUILD_TESTS* -> Each module of OpenCV has a test project assigned to it. Building these test projects is also a good way to try out, that the modules work just as expected on your system too.
+ *BUILD_PERF_TESTS* -> There are also performance tests for many OpenCV functions. If you're concerned about performance, build them and run.
+ *BUILD_opencv_python* -> Self-explanatory. Create the binaries to use OpenCV from the Python language.
Press again the *Configure* button and ensure no errors are reported. If this is the case you can tell CMake to create the project files by pushing the *Generate* button. Go to the build directory and open the created **OpenCV** solution.
Depending on just how much of the above options you have selected the solution may contain quite a lot of projects so be tolerant on the IDE at the startup.
Now you need to build both the *Release* and the *Debug* binaries. Use the drop-down menu on your IDE to change to another of these after building for one of them.
.. image:: images/ChangeBuildVisualStudio.jpg
:alt: Look here for changing the Build Type
:align: center
In the end you can observe the built binary files inside the bin directory:
.. image:: images/OpenCVBuildResultWindows.jpg
:alt: The Result of the build.
:align: center
For the documentation you need to explicitly issue the build commands on the *doc* project for the PDF files and on the *doc_html* for the HTML ones. Each of these will call *Sphinx* to do all the hard work. You can find the generated documentation inside the :file:`Build/Doc/_html` for the HTML pages and within the :file:`Build/Doc` the PDF manuals.
.. image:: images/WindowsBuildDoc.png
:alt: The Documentation Projects
:align: center
To collect the header and the binary files, that you will use during your own projects, into a separate directory (simillary to how the pre-built binaries ship) you need to explicitely build the *Install* project.
.. image:: images/WindowsBuildInstall.png
:alt: The Install Project
:align: center
This will create an *install* directory inside the *Build* one collecting all the built binaries into a single place. Use this only after you built both the *Release* and *Debug* versions.
.. note::
To create an installer you need to install `NSIS <http://nsis.sourceforge.net/Download>`_. Then just build the *Package* project to build the installer into the :file:`Build/_CPack_Packages/{win32}/NSIS` folder. You can then use this to distribute OpenCV with your build settings on other systems.
.. image:: images/WindowsOpenCVInstaller.png
:alt: The Installer directory
:align: center
To test your build just go into the :file:`Build/bin/Debug` or :file:`Build/bin/Release` directory and start a couple of applications like the *contours.exe*. If they run, you are done. Otherwise, something definitely went awfully wrong. In this case you should contact us via our :opencv_group:`user group <>`.
If everything is okay the *contours.exe* output should resemble the following image (if built with Qt support):
.. image:: images/WindowsQtContoursOutput.png
:alt: A good output result
:align: center
.. note::
If you use the GPU module (CUDA libraries) make sure you also upgrade to the latest drivers of your GPU. Error messages containing invalid entries in (or cannot find) the nvcuda.dll are caused mostly by old video card drivers. For testing the GPU (if built) run the *performance_gpu.exe* sample application.
.. _WindowsSetPathAndEnviromentVariable:
Set the OpenCV enviroment variable and add it to the systems path
=================================================================
First we set an enviroment variable to make easier our work. This will hold the install directory of our OpenCV library that we use in our projects. Start up a command window and enter:
::
setx -m OPENCV_DIR D:\OpenCV\Build\Install
Here the directory is where you have your OpenCV binaries (*installed* or *built*). Inside this you should have folders like *bin* and *include*. The -m should be added if you wish to make the settings computer wise, instead of user wise.
If you built static libraries then you are done. Otherwise, you need to add the *bin* folders path to the systems path.This is cause you will use the OpenCV library in form of *\"Dynamic-link libraries\"* (also known as **DLL**). Inside these are stored all the algorithms and information the OpenCV library contains. The operating system will load them only on demand, during runtime. However, to do this he needs to know where they are. The systems **PATH** contains a list of folders where DLLs can be found. Add the OpenCV library path to this and the OS will know where to look if he ever needs the OpenCV binaries. Otherwise, you will need to copy the used DLLs right beside the applications executable file (*exe*) for the OS to find it, which is highly unpleasent if you work on many projects. To do this start up again the |PathEditor|_ and add the following new entry (right click in the application to bring up the menu):
::
%OPENCV_DIR%\bin
.. image:: images/PathEditorOpenCVInsertNew.png
:alt: Right click to insert new path manually.
:align: center
.. image:: images/PathEditorOpenCVSetPath.png
:alt: Add the entry.
:align: center
Save it to the registry and you are done. If you ever change the location of your install directories or want to try out your applicaton with a different build all you will need to do is to update the OPENCV_DIR variable via the *setx* command inside a command window.
Now you can continue reading the tutorials with the :ref:`Windows_Visual_Studio_How_To` section. There you will find out how to use the OpenCV library in your own projects with the help of the Microsoft Visual Studio IDE.
.. _Windows_Installation:
Installation in Windows
***********************
.. include:: <isonum.txt>
The description here was tested on Windows 7 SP1. Nevertheless, it should also work on any other relatively modern version of Windows OS. If you encounter errors after following the steps described below, feel free to contact us via our `OpenCV Q&A forum <http://answers.opencv.org>`_. We'll do our best to help you out.
.. note:: To use the OpenCV library you have two options: :ref:`Windows_Install_Prebuild` or :ref:`CppTutWindowsMakeOwn`. While the first one is easier to complete, it only works if you are coding with the latest Microsoft Visual Studio IDE and doesn't take advantage of the most advanced technologies we integrate into our library.
.. _Windows_Install_Prebuild:
Installation by Using the Pre-built Libraries
=============================================
#. Launch a web browser of choice and go to our `page on Sourceforge <http://sourceforge.net/projects/opencvlibrary/files/opencv-win/>`_.
#. Choose a build you want to use and download it.
.. If you downloaded the source files present here see :ref:`CppTutWindowsMakeOwn`.
#. Make sure you have admin rights. Start the setup and follow the wizard.
#. While adding the OpenCV library to the system path is a good decision for a better control, we will do it manually for the sake of this tutorial. Make sure you do not set this option.
#. Most of the time it is a good idea to install the source files too, as this will allow for you to debug into the OpenCV library, if it is necessary. Follow the default settings of the wizard and finish the installation.
#. You can check the installation at the chosen path as you can see below.
.. image:: images/OpenCV_Install_Directory.png
:alt: An example of how the installation directory should look in case of successful install.
:align: center
#. To finalize the installation go to the :ref:`WindowsSetPathAndEnviromentVariable` section.
.. _CppTutWindowsMakeOwn:
Installation by Making Your Own Libraries from the Source Files
===============================================================
You may find the content of this tutorial also inside the following videos: `Part 1 <https://www.youtube.com/watch?v=NnovZ1cTlMs>`_ and `Part 2 <https://www.youtube.com/watch?v=qGNWMcfWwPU>`_, hosted on YouTube.
.. raw:: html
<div align="center">
<iframe title="Install OpenCV by using its source files - Part 1" width="560" height="349" src="http://www.youtube.com/embed/NnovZ1cTlMs?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
<iframe title="Install OpenCV by using its source files - Part 2" width="560" height="349" src="http://www.youtube.com/embed/qGNWMcfWwPU?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
</div>
.. warning:: These videos above are long-obsolete and contain inaccurate information. Be careful, since solutions described in those videos are no longer supported and may even break your install.
If you are building your own libraries you can take the source files from our `Git repository <https://github.com/Itseez/opencv.git>`_.
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
.. |TortoiseGit| replace:: TortoiseGit
.. _TortoiseGit: http://code.google.com/p/tortoisegit/wiki/Download
.. |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 IDE of choice (preferably), or just a C\C++ compiler that will actually make the binary files. Here we will use the `Microsoft Visual Studio <https://www.microsoft.com/visualstudio/en-us>`_. However, you can use any other IDE that has a valid C\C++ compiler.
+ |CMake|_, which is a neat tool to 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.
+ Git to acquire the OpenCV source files. A good tool for this is |TortoiseGit|_. Alternatively, you can just download an archived version of the source files from our `page on Sourceforge <http://sourceforge.net/projects/opencvlibrary/files/opencv-win/>`_
OpenCV may come in multiple flavors. There is a "core" section that will work on its own. Nevertheless, there is a couple of tools, libraries made by 3rd parties that offer services of which the OpenCV may take advantage. These will improve its capabilities in many ways. 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 if you want to build the *OpenCV documentation*.
+ |Numpy|_ is a scientific computing package for Python. Required for the *Python interface*.
+ |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.
+ |IntelIIP|_ may be used to improve the performance of color conversion, Haar training and DFT functions of the OpenCV library. Watch out, since this isn't a free service.
+ 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.
+ |Eigen|_ is a C++ template library for linear algebra.
+ The latest |CUDA_Toolkit|_ will allow you to use the power lying inside your GPU. This will drastically improve performance for some algorithms (e.g the HOG descriptor). Getting more and more of our algorithms to work on the GPUs is a constant effort of the OpenCV team.
+ |OpenEXR|_ source files are required for the library to work with this high dynamic range (HDR) image file format.
+ 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.
+ |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*.
+ |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, We will cover this in depth at the :ref:`How to Install Sphinx <HereInstallSphinx>` section.
Now we 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 this section.
.. _WindowsBuildLibrary:
Building the library
^^^^^^^^^^^^^^^^^^^^
1. Make sure you have a working IDE with a valid compiler. In case of the Microsoft Visual Studio just install it and make sure it starts up.
#. Install |CMake|_. Simply follow the wizard, no need to add it to the path. The default install options are OK.
#. Download and install an up-to-date version of msysgit from its `official site <http://code.google.com/p/msysgit/downloads/list>`_. There is also the portable version, which you need only to unpack to get access to the console version of Git. Supposing that for some of us it could be quite enough.
#. 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.
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`).
#) Push the OK button and be patient as the repository is quite a heavy download. It will take some time depending on your Internet connection.
#. In this section I will cover installing the 3rd party libraries.
a) Download the |Python_Libraries|_ and install it with the default options. You will need a couple other python extensions. Luckily installing all these may be automated by a nice tool called `Setuptools <http://pypi.python.org/pypi/setuptools#downloads>`_. Download and install again.
#) .. _HereInstallSphinx:
Installing Sphinx is easy once you have installed *Setuptools*. This contains a little application that will automatically connect to the python databases and download the latest version of many python scripts. Start up a command window (enter *cmd* into the windows start menu and press enter) and use the *CD* command to navigate to your Python folders Script sub-folder. Here just pass to the *easy_install.exe* as argument the name of the program you want to install. Add the *sphinx* argument.
.. image:: images/cmsdstartwindows.jpg
:alt: The Windows Command Startup
:align: center
.. image:: images/Sphinx_Install.png
:alt: How to start the command window
:align: center
.. note::
The *CD* navigation command works only inside a drive. For example if you are somewhere in the *C:* drive you cannot use it this to go to another drive (like for example *D:*). To do so you first need to change drives letters. For this simply enter the command *D:*. Then you can use the *CD* to navigate to specific folder inside the drive. Bonus tip: you can clear the screen by using the *CLS* command.
This will also install its prerequisites `Jinja2 <http://jinja.pocoo.org/docs/>`_ and `Pygments <http://pygments.org/>`_.
#) The easiest way to install |Numpy|_ is to just download its binaries from the `sourceforga page <http://sourceforge.net/projects/numpy/files/NumPy/>`_. Make sure your download and install exactly the binary for your python version (so for version :file:`2.7`).
#) Download the |Miktex|_ and install it. Again just follow the wizard. At the fourth step make sure you select for the *"Install missing packages on-the-fly"* the *Yes* option, as you can see on the image below. Again this will take quite some time so be patient.
.. image:: images/MiktexInstall.png
:alt: The Miktex Install Screen
:align: center
#) For the |IntelTBB|_ download the source files and extract it inside a directory on your system. For example let there be :file:`D:/OpenCV/dep`. For installing the |IntelIIP|_ the story is the same. For exctracting the archives I recommend using the `7-Zip <http://www.7-zip.org/>`_ application.
.. image:: images/IntelTBB.png
:alt: The Miktex Install Screen
:align: center
#) In case of the |Eigen|_ library it is again a case of download and extract to the :file:`D:/OpenCV/dep` directory.
#) Same as above with |OpenEXR|_.
#) For the |OpenNI_Framework|_ you need to install both the `development build <http://www.openni.org/downloadfiles/opennimodules/openni-binaries/21-stable>`_ and the `PrimeSensor Module <http://www.openni.org/downloadfiles/opennimodules/openni-compliant-hardware-binaries/32-stable>`_.
#) For the CUDA you need again two modules: the latest |CUDA_Toolkit|_ and the *CUDA Tools SDK*. Download and install both of them with a *complete* option by using the 32 or 64 bit setups according to your OS.
#) In case of the |qtframework|_ you need to build yourself the binary files (unless you use the Microsoft Visual Studio 2008 with 32 bit compiler). To do this go to the `Qt Downloads <http://qt.nokia.com/downloads>`_ page. Download the source files (not the installers!!!):
.. image:: images/qtDownloadThisPackage.png
:alt: Download this Qt Package
:align: center
Extract it into a nice and short named directory like :file:`D:/OpenCV/dep/qt/` .
Then you need to build it. Start up a *Visual* *Studio* *Command* *Prompt* (*2010*) by using the start menu search (or navigate through the start menu :menuselection:`All Programs --> Microsoft Visual Studio 2010 --> Visual Studio Tools --> Visual Studio Command Prompt (2010)`).
.. image:: images/visualstudiocommandprompt.jpg
:alt: The Visual Studio command prompt
:align: center
Now navigate to the extracted folder and enter inside it by using this console window. You should have a folder containing files like *Install*, *Make* and so on. Use the *dir* command to list files inside your current directory. Once arrived at this directory enter the following command:
.. code-block:: bash
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):
.. code-block:: bash
nmake
After this set the Qt enviroment variables using the following command on Windows 7:
.. code-block:: bash
setx -m QTDIR D:/OpenCV/dep/qt/qt-everywhere-opensource-src-4.7.3
.. |PathEditor| replace:: Path Editor
.. _PathEditor: http://www.redfernplace.com/software-projects/patheditor/
Also, add the built binary files path to the system path by using the |PathEditor|_. In our case this is :file:`D:/OpenCV/dep/qt/qt-everywhere-opensource-src-4.7.3/bin`.
.. note::
If you plan on doing Qt application development you can also install at this point the *Qt Visual Studio Add-in*. After this you can make and build Qt applications without using the *Qt Creator*. Everything is nicely integrated into Visual Studio.
#. Now start the *CMake (cmake-gui)*. You may again enter it in the start menu search or get it from the :menuselection:`All Programs --> CMake 2.8 --> CMake (cmake-gui)`. First, select the directory for the source files of the OpenCV library (1). Then, specify a directory where you will build the binary files for OpenCV (2).
.. image:: images/CMakeSelectBin.jpg
:alt: Select the directories
:align: center
Press the Configure button to specify the compiler (and *IDE*) you want to use. Note that in case you can choose between different compilers for making either 64 bit or 32 bit libraries. Select the one you use in your application development.
.. image:: images/CMake_Configure_Windows.jpg
:alt: How CMake should look at build time.
:align: center
CMake will start out and based on your system variables will try to automatically locate as many packages as possible. You can modify the packages to use for the build in the :menuselection:`WITH --> WITH_X` menu points (where *X* is the package abbreviation). Here are a list of current packages you can turn on or off:
.. image:: images/CMakeBuildWithWindowsGUI.jpg
:alt: The packages OpenCV may use
:align: center
Select all the packages you want to use and press again the *Configure* button. For an easier overview of the build options make sure the *Grouped* option under the binary directory selection is turned on. For some of the packages CMake may not find all of the required files or directories. In case of these CMake will throw an error in its output window (located at the bottom of the GUI) and set its field values, to not found constants. For example:
.. image:: images/CMakePackageNotFoundWindows.jpg
:alt: Constant for not found packages
:align: center
.. image:: images/CMakeOutputPackageNotFound.jpg
:alt: Error (warning) thrown in output window of the CMake GUI
:align: center
For these you need to manually set the queried directories or files path. After this press again the *Configure* button to see if the value entered by you was accepted or not. Do this until all entries are good and you cannot see errors in the field/value or the output part of the GUI.
Now I want to emphasize an option that you will definitely love: :menuselection:`ENABLE --> ENABLE_SOLUTION_FOLDERS`. OpenCV will create many-many projects and turning this option will make sure that they are categorized inside directories in the *Solution Explorer*. It is a must have feature, if you ask me.
.. image:: images/CMakeBuildOptionsOpenCV.jpg
:alt: Set the Solution Folders and the parts you want to build
:align: center
Furthermore, you need to select what part of OpenCV you want to build.
.. container:: enumeratevisibleitemswithsquare
+ *BUILD_DOCS* -> It creates two projects for building the documentation of OpenCV (there will be a separate project for building the HTML and the PDF files). Note that these aren't built together with the solution. You need to make an explicit build project command on these to do so.
+ *BUILD_EXAMPLES* -> OpenCV comes with many example applications from which you may learn most of the libraries capabilities. This will also come handy to easily try out if OpenCV is fully functional on your computer.
+ *BUILD_PACKAGE* -> Prior to version 2.3 with this you could build a project that will build an OpenCV installer. With this you can easily install your OpenCV flavor on other systems. For the latest source files of OpenCV it generates a new project that simply creates zip archive with OpenCV sources.
+ *BUILD_SHARED_LIBS* -> With this you can control to build DLL files (when turned on) or static library files (\*.lib) otherwise.
+ *BUILD_TESTS* -> Each module of OpenCV has a test project assigned to it. Building these test projects is also a good way to try out, that the modules work just as expected on your system too.
+ *BUILD_PERF_TESTS* -> There are also performance tests for many OpenCV functions. If you're concerned about performance, build them and run.
+ *BUILD_opencv_python* -> Self-explanatory. Create the binaries to use OpenCV from the Python language.
Press again the *Configure* button and ensure no errors are reported. If this is the case you can tell CMake to create the project files by pushing the *Generate* button. Go to the build directory and open the created **OpenCV** solution.
Depending on just how much of the above options you have selected the solution may contain quite a lot of projects so be tolerant on the IDE at the startup.
Now you need to build both the *Release* and the *Debug* binaries. Use the drop-down menu on your IDE to change to another of these after building for one of them.
.. image:: images/ChangeBuildVisualStudio.jpg
:alt: Look here for changing the Build Type
:align: center
In the end you can observe the built binary files inside the bin directory:
.. image:: images/OpenCVBuildResultWindows.jpg
:alt: The Result of the build.
:align: center
For the documentation you need to explicitly issue the build commands on the *doc* project for the PDF files and on the *doc_html* for the HTML ones. Each of these will call *Sphinx* to do all the hard work. You can find the generated documentation inside the :file:`Build/Doc/_html` for the HTML pages and within the :file:`Build/Doc` the PDF manuals.
.. image:: images/WindowsBuildDoc.png
:alt: The Documentation Projects
:align: center
To collect the header and the binary files, that you will use during your own projects, into a separate directory (simillary to how the pre-built binaries ship) you need to explicitely build the *Install* project.
.. image:: images/WindowsBuildInstall.png
:alt: The Install Project
:align: center
This will create an *install* directory inside the *Build* one collecting all the built binaries into a single place. Use this only after you built both the *Release* and *Debug* versions.
.. note::
To create an installer you need to install `NSIS <http://nsis.sourceforge.net/Download>`_. Then just build the *Package* project to build the installer into the :file:`Build/_CPack_Packages/{win32}/NSIS` folder. You can then use this to distribute OpenCV with your build settings on other systems.
.. image:: images/WindowsOpenCVInstaller.png
:alt: The Installer directory
:align: center
To test your build just go into the :file:`Build/bin/Debug` or :file:`Build/bin/Release` directory and start a couple of applications like the *contours.exe*. If they run, you are done. Otherwise, something definitely went awfully wrong. In this case you should contact us via our :opencv_group:`user group <>`.
If everything is okay the *contours.exe* output should resemble the following image (if built with Qt support):
.. image:: images/WindowsQtContoursOutput.png
:alt: A good output result
:align: center
.. note::
If you use the GPU module (CUDA libraries) make sure you also upgrade to the latest drivers of your GPU. Error messages containing invalid entries in (or cannot find) the nvcuda.dll are caused mostly by old video card drivers. For testing the GPU (if built) run the *performance_gpu.exe* sample application.
.. _WindowsSetPathAndEnviromentVariable:
Set the OpenCV enviroment variable and add it to the systems path
=================================================================
First we set an enviroment variable to make easier our work. This will hold the install directory of our OpenCV library that we use in our projects. Start up a command window and enter:
::
setx -m OPENCV_DIR D:\OpenCV\Build\Install
Here the directory is where you have your OpenCV binaries (*installed* or *built*). Inside this you should have folders like *bin* and *include*. The -m should be added if you wish to make the settings computer wise, instead of user wise.
If you built static libraries then you are done. Otherwise, you need to add the *bin* folders path to the systems path.This is cause you will use the OpenCV library in form of *\"Dynamic-link libraries\"* (also known as **DLL**). Inside these are stored all the algorithms and information the OpenCV library contains. The operating system will load them only on demand, during runtime. However, to do this he needs to know where they are. The systems **PATH** contains a list of folders where DLLs can be found. Add the OpenCV library path to this and the OS will know where to look if he ever needs the OpenCV binaries. Otherwise, you will need to copy the used DLLs right beside the applications executable file (*exe*) for the OS to find it, which is highly unpleasent if you work on many projects. To do this start up again the |PathEditor|_ and add the following new entry (right click in the application to bring up the menu):
::
%OPENCV_DIR%\bin
.. image:: images/PathEditorOpenCVInsertNew.png
:alt: Right click to insert new path manually.
:align: center
.. image:: images/PathEditorOpenCVSetPath.png
:alt: Add the entry.
:align: center
Save it to the registry and you are done. If you ever change the location of your install directories or want to try out your applicaton with a different build all you will need to do is to update the OPENCV_DIR variable via the *setx* command inside a command window.
Now you can continue reading the tutorials with the :ref:`Windows_Visual_Studio_How_To` section. There you will find out how to use the OpenCV library in your own projects with the help of the Microsoft Visual Studio IDE.

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

@@ -1,180 +1,180 @@
.. _Windows_Visual_Studio_How_To:
How to build applications with OpenCV inside the *Microsoft Visual Studio*
**************************************************************************
Everything I describe here will apply to the C\\C++ interface of OpenCV.
I start out from the assumption that you have read and completed with success the :ref:`Windows_Installation` tutorial. Therefore, before you go any further make sure you have an OpenCV directory that contains the OpenCV header files plus binaries and you have set the environment variables as :ref:`described here <WindowsSetPathAndEnviromentVariable>`.
.. image:: images/OpenCV_Install_Directory.jpg
: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.
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:
.. 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.
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.
If you use the *DLL* system you must again specify all this, however now for a different reason. This is a Microsoft OS specific stuff. It seems that the linker needs to know that where in the DLL to search for the data structure or function at the runtime. This information is stored inside *lib* files. Nevertheless, they aren't static libraries. They are so called import libraries. This is why when you make some *DLLs* in Windows you will also end up with some *lib* extension libraries. The good part is that at runtime only the *DLL* is required.
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.
.. image:: images/NewProjectVisualStudio.jpg
:alt: Which options to select
:align: center
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*).
.. image:: images/PropertyPageExample.jpg
:alt: An example of Property Sheet
:align: center
The really useful stuff of these is that you may create a rule package *once* and you can later just add it to your new projects. Create it once and reuse it later. We want to create a new *Property Sheet* that will contain all the rules that the compiler and linker needs to know. Of course we will need a separate one for the Debug and the Release Builds. Start up with the Debug one as shown in the image below:
.. image:: images/AddNewPropertySheet.jpg
:alt: Add a new Property Sheet
:align: center
Use for example the *OpenCV_Debug* name. Then by selecting the sheet :menuselection:`Right Click --> Properties`. In the following I will show to set the OpenCV rules locally, as I find unnecessary to pollute projects with custom rules that I do not use it. Go the C++ groups General entry and under the *"Additional Include Directories"* add the path to your OpenCV include. If you don't have *"C/C++"* group, you should add any .c/.cpp file to the project.
.. code-block:: bash
$(OPENCV_DIR)\include
.. image:: images/PropertySheetOpenCVInclude.jpg
: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>`.
Next go to the :menuselection:`Linker --> General` and under the *"Additional Library Directories"* add the libs directory:
.. code-block:: bash
$(OPENCV_DIR)\libs
.. image:: images/PropertySheetOpenCVLib.jpg
: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:
.. image:: images/PropertySheetOpenCVLibrariesDebugSmple.jpg
:alt: Add the debug library names here.
:align: center
.. image:: images/PropertySheetOpenCVLibrariesDebug.jpg
:alt: Like this.
:align: center
The names of the libraries are as follow:
.. code-block:: bash
opencv_(The Name of the module)(The version Number of the library you use)d.lib
A full list, for the currently latest trunk version would contain:
.. code-block:: bash
opencv_core231d.lib
opencv_imgproc231d.lib
opencv_highgui231d.lib
opencv_ml231d.lib
opencv_video231d.lib
opencv_features2d231d.lib
opencv_calib3d231d.lib
opencv_objdetect231d.lib
opencv_contrib231d.lib
opencv_legacy231d.lib
opencv_flann231d.lib
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.
: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*.
.. image:: images/PropertySheetInsideFolder.jpg
: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.
.. image:: images/PropertyPageAddExisting.jpg
: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 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:
.. image:: images/VCDirectories2010.jpg
:alt: VC++ Directories in VS 2010.
:align: center
The process is the same as described in case of the local approach. Just add the include directories by using the environment variable *OPENCV_DIR*.
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
:language: cpp
:tab-width: 4
:linenos:
You can start a Visual Studio build from two places. Either inside from the *IDE* (keyboard combination: :kbd:`Control-F5`) or by navigating to your build directory and start the application with a double click. The catch is that these two **aren't** the same. When you start it from the *IDE* its current working directory is the projects directory, while otherwise it is the folder where the application file currently is (so usually your build directory). Moreover, in case of starting from the *IDE* the console window will not close once finished. It will wait for a keystroke of yours.
.. |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|:
.. 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`.
.. _Windows_Visual_Studio_How_To:
How to build applications with OpenCV inside the *Microsoft Visual Studio*
**************************************************************************
Everything I describe here will apply to the C\\C++ interface of OpenCV.
I start out from the assumption that you have read and completed with success the :ref:`Windows_Installation` tutorial. Therefore, before you go any further make sure you have an OpenCV directory that contains the OpenCV header files plus binaries and you have set the environment variables as :ref:`described here <WindowsSetPathAndEnviromentVariable>`.
.. image:: images/OpenCV_Install_Directory.jpg
: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.
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:
.. 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.
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.
If you use the *DLL* system you must again specify all this, however now for a different reason. This is a Microsoft OS specific stuff. It seems that the linker needs to know that where in the DLL to search for the data structure or function at the runtime. This information is stored inside *lib* files. Nevertheless, they aren't static libraries. They are so called import libraries. This is why when you make some *DLLs* in Windows you will also end up with some *lib* extension libraries. The good part is that at runtime only the *DLL* is required.
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.
.. image:: images/NewProjectVisualStudio.jpg
:alt: Which options to select
:align: center
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*).
.. image:: images/PropertyPageExample.jpg
:alt: An example of Property Sheet
:align: center
The really useful stuff of these is that you may create a rule package *once* and you can later just add it to your new projects. Create it once and reuse it later. We want to create a new *Property Sheet* that will contain all the rules that the compiler and linker needs to know. Of course we will need a separate one for the Debug and the Release Builds. Start up with the Debug one as shown in the image below:
.. image:: images/AddNewPropertySheet.jpg
:alt: Add a new Property Sheet
:align: center
Use for example the *OpenCV_Debug* name. Then by selecting the sheet :menuselection:`Right Click --> Properties`. In the following I will show to set the OpenCV rules locally, as I find unnecessary to pollute projects with custom rules that I do not use it. Go the C++ groups General entry and under the *"Additional Include Directories"* add the path to your OpenCV include. If you don't have *"C/C++"* group, you should add any .c/.cpp file to the project.
.. code-block:: bash
$(OPENCV_DIR)\include
.. image:: images/PropertySheetOpenCVInclude.jpg
: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>`.
Next go to the :menuselection:`Linker --> General` and under the *"Additional Library Directories"* add the libs directory:
.. code-block:: bash
$(OPENCV_DIR)\libs
.. image:: images/PropertySheetOpenCVLib.jpg
: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:
.. image:: images/PropertySheetOpenCVLibrariesDebugSmple.jpg
:alt: Add the debug library names here.
:align: center
.. image:: images/PropertySheetOpenCVLibrariesDebug.jpg
:alt: Like this.
:align: center
The names of the libraries are as follow:
.. code-block:: bash
opencv_(The Name of the module)(The version Number of the library you use)d.lib
A full list, for the currently latest trunk version would contain:
.. code-block:: bash
opencv_core231d.lib
opencv_imgproc231d.lib
opencv_highgui231d.lib
opencv_ml231d.lib
opencv_video231d.lib
opencv_features2d231d.lib
opencv_calib3d231d.lib
opencv_objdetect231d.lib
opencv_contrib231d.lib
opencv_legacy231d.lib
opencv_flann231d.lib
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.
: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*.
.. image:: images/PropertySheetInsideFolder.jpg
: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.
.. image:: images/PropertyPageAddExisting.jpg
: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 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:
.. image:: images/VCDirectories2010.jpg
:alt: VC++ Directories in VS 2010.
:align: center
The process is the same as described in case of the local approach. Just add the include directories by using the environment variable *OPENCV_DIR*.
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
:language: cpp
:tab-width: 4
:linenos:
You can start a Visual Studio build from two places. Either inside from the *IDE* (keyboard combination: :kbd:`Control-F5`) or by navigating to your build directory and start the application with a double click. The catch is that these two **aren't** the same. When you start it from the *IDE* its current working directory is the projects directory, while otherwise it is the folder where the application file currently is (so usually your build directory). Moreover, in case of starting from the *IDE* the console window will not close once finished. It will wait for a keystroke of yours.
.. |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|:
.. 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`.