doc/tutorials/introduction/windows_visual_studio_opencv/windows_visual_studio_opencv.markdown

   1 How to build applications with OpenCV inside the "Microsoft Visual Studio" {#tutorial_windows_visual_studio_opencv}
   2 ==========================================================================
   3
   4 @prev_tutorial{tutorial_windows_install}
   5 @next_tutorial{tutorial_windows_visual_studio_image_watch}
   6
   7
   8 Everything I describe here will apply to the `C\C++` interface of OpenCV. I start out from the
   9 assumption that you have read and completed with success the @ref tutorial_windows_install tutorial.
  10 Therefore, before you go any further make sure you have an OpenCV directory that contains the OpenCV
  11 header files plus binaries and you have set the environment variables as described here
  12 @ref tutorial_windows_install_path.
  13
  14 ![](images/OpenCV_Install_Directory.jpg)
  15
  16 The OpenCV libraries, distributed by us, on the Microsoft Windows operating system are in a
  17 Dynamic Linked Libraries (*DLL*). These have the advantage that all the content of the
  18 library is loaded only at runtime, on demand, and that countless programs may use the same library
  19 file. This means that if you have ten applications using the OpenCV library, no need to have around
  20 a version for each one of them. Of course you need to have the *dll* of the OpenCV on all systems
  21 where you want to run your application.
  22
  23 Another approach is to use static libraries that have *lib* extensions. You may build these by using
  24 our source files as described in the @ref tutorial_windows_install tutorial. When you use this the
  25 library will be built-in inside your *exe* file. So there is no chance that the user deletes them,
  26 for some reason. As a drawback your application will be larger one and as, it will take more time to
  27 load it during its startup.
  28
  29 To build an application with OpenCV you need to do two things:
  30
  31 -   *Tell* to the compiler how the OpenCV library *looks*. You do this by *showing* it the header
  32     files.
  33 -   *Tell* to the linker from where to get the functions or data structures of OpenCV, when they are
  34     needed.
  35
  36     If you use the *lib* system you must set the path where the library files are and specify in
  37     which one of them to look. During the build the linker will look into these libraries and add
  38     the definitions and implementation of all *used* functions and data structures to the executable
  39     file.
  40
  41     If you use the *DLL* system you must again specify all this, however now for a different reason.
  42     This is a Microsoft OS specific stuff. It seems that the linker needs to know that where in the
  43     DLL to search for the data structure or function at the runtime. This information is stored
  44     inside *lib* files. Nevertheless, they aren't static libraries. They are so called import
  45     libraries. This is why when you make some *DLLs* in Windows you will also end up with some *lib*
  46     extension libraries. The good part is that at runtime only the *DLL* is required.
  47
  48 To pass on all this information to the Visual Studio IDE you can either do it globally (so all your
  49 future projects will get this information) or locally (so only for you current project). The
  50 advantage of the global one is that you only need to do it once; however, it may be undesirable to
  51 clump all your projects all the time with all this information. In case of the global one how you
  52 do it depends on the Microsoft Visual Studio you use. There is a **2008 and previous versions** and
  53 a **2010 way** of doing it. Inside the global section of this tutorial I'll show what the main
  54 differences are.
  55
  56 The base item of a project in Visual Studio is a solution. A solution may contain multiple projects.
  57 Projects are the building blocks of an application. Every project will realize something and you
  58 will have a main project in which you can put together this project puzzle. In case of the many
  59 simple applications (like many of the tutorials will be) you do not need to break down the
  60 application into modules. In these cases, your main project will be the only existing one. Now go
  61 create a new solution inside Visual studio by going through the File --\> New --\> Project menu
  62 selection. Choose *Win32 Console Application* as type. Enter its name and select the path where to
  63 create it. Then in the upcoming dialog make sure you create an empty project.
  64
  65 ![](images/NewProjectVisualStudio.jpg)
  66
  67 The *local* method
  68 ------------------
  69
  70 Every project is built separately from the others. Due to this every project has its own rule
  71 package. Inside this rule packages are stored all the information the *IDE* needs to know to build
  72 your project. For any application there are at least two build modes: a *Release* and a *Debug* one.
  73 The *Debug* has many features that exist so you can find and resolve easier bugs inside your
  74 application. In contrast the *Release* is an optimized version, where the goal is to make the
  75 application run as fast as possible or to be as small as possible. You may figure that these modes
  76 also require different rules to use during build. Therefore, there exist different rule packages for
  77 each of your build modes. These rule packages are called inside the IDE as *project properties* and
  78 you can view and modify them by using the *Property Manager*. You can bring this up with
  79 View --\> Property Pages (For Visual Studio 2013 onwards, go to View --\> Other Windows --\> Property Manager).
  80 Expand it and you can see the existing rule packages (called *Property Sheets*).
  81
  82 ![](images/PropertyPageExample.jpg)
  83
  84 The really useful stuff of these is that you may create a rule package *once* and you can later just
  85 add it to your new projects. Create it once and reuse it later. We want to create a new *Property
  86 Sheet* that will contain all the rules that the compiler and linker needs to know. Of course we will
  87 need a separate one for the Debug and the Release Builds. Start up with the Debug one as shown in
  88 the image below:
  89
  90 ![](images/AddNewPropertySheet.jpg)
  91
  92 Use for example the *OpenCV_Debug* name. Then by selecting the sheet Right Click --\> Properties.
  93 In the following I will show to set the OpenCV rules locally, as I find unnecessary to pollute
  94 projects with custom rules that I do not use it. Go the C++ groups General entry and under the
  95 *"Additional Include Directories"* add the path to your OpenCV include. If you don't have *"C/C++"*
  96 group, you should add any .c/.cpp file to the project.
  97 @code{.bash}
  98 $(OPENCV_DIR)\..\..\include
  99 @endcode
 100 ![](images/PropertySheetOpenCVInclude.jpg)
 101
 102 When adding third party libraries settings it is generally a good idea to use the power behind the
 103 environment variables. The full location of the OpenCV library may change on each system. Moreover,
 104 you may even end up yourself with moving the install directory for some reason. If you would give
 105 explicit paths inside your property sheet your project will end up not working when you pass it
 106 further to someone else who has a different OpenCV install path. Moreover, fixing this would require
 107 to manually modifying every explicit path. A more elegant solution is to use the environment
 108 variables. Anything that you put inside a parenthesis started with a dollar sign will be replaced at
 109 runtime with the current environment variables value. Here comes in play the environment variable
 110 setting we already made in our previous tutorial @ref tutorial_windows_install_path.
 111
 112 Next go to the Linker --\> General and under the *"Additional Library Directories"* add the libs
 113 directory:
 114 @code{.bash}
 115 $(OPENCV_DIR)\lib
 116 @endcode
 117
 118 ![](images/PropertySheetOpenCVLib.jpg)
 119
 120 Then you need to specify the libraries in which the linker should look into. To do this go to the
 121 Linker --\> Input and under the *"Additional Dependencies"* entry add the name of all modules which
 122 you want to use:
 123
 124 ![](images/PropertySheetOpenCVLibrariesDebugSmple.jpg)
 125
 126 ![](images/PropertySheetOpenCVLibrariesDebug.jpg)
 127
 128 The names of the libraries are as follow:
 129 @code{.bash}
 130 opencv_(The Name of the module)(The version Number of the library you use)d.lib
 131 @endcode
 132 A full list, for the latest version would contain:
 133 @code{.bash}
 134 opencv_calib3d300d.lib
 135 opencv_core300d.lib
 136 opencv_features2d300d.lib
 137 opencv_flann300d.lib
 138 opencv_highgui300d.lib
 139 opencv_imgcodecs300d.lib
 140 opencv_imgproc300d.lib
 141 opencv_ml300d.lib
 142 opencv_objdetect300d.lib
 143 opencv_photo300d.lib
 144 opencv_shape300d.lib
 145 opencv_stitching300d.lib
 146 opencv_superres300d.lib
 147 opencv_ts300d.lib
 148 opencv_video300d.lib
 149 opencv_videoio300d.lib
 150 opencv_videostab300d.lib
 151 @endcode
 152
 153 Alternatively, your OpenCV download may have been built into one large .lib file. Check by looking in OpenCV\\build\\architecture\\vc14\\lib. In this case all you would add is, for the version 3.3.0:
 154 @code{.bash}
 155 opencv_world330.lib
 156 @endcode
 157 The letter *d* at the end just indicates that these are the libraries required for the debug. Now
 158 click ok to save and do the same with a new property inside the Release rule section. Make sure to
 159 omit the *d* letters from the library names and to save the property sheets with the save icon above
 160 them.
 161
 162 ![](images/PropertySheetOpenCVLibrariesRelease.jpg)
 163
 164 You can find your property sheets inside your projects directory. At this point, it is a wise
 165 decision to back them up into some special directory, to always have them at hand in the future,
 166 whenever you create an OpenCV project. Note that for Visual Studio 2010 the file extension is
 167 *props*, while for 2008 this is *vsprops*.
 168
 169 ![](images/PropertySheetInsideFolder.jpg)
 170
 171 Next time when you make a new OpenCV project just use the "Add Existing Property Sheet..." menu
 172 entry inside the Property Manager to easily add the OpenCV build rules.
 173
 174 ![](images/PropertyPageAddExisting.jpg)
 175
 176 The *global* method
 177 -------------------
 178
 179 In case you find it too troublesome to add the property pages to each and every one of your projects you
 180 can also add this rules to a *"global property page"*. However, this applies only to the additional
 181 include and library directories. The name of the libraries to use you still need to specify manually
 182 by using for instance: a Property page.
 183
 184 In Visual Studio 2008 you can find this under the:
 185 Tools --\> Options --\> Projects and Solutions --\> VC++ Directories.
 186
 187 ![](images/VCDirectories2008.jpg)
 188
 189 In Visual Studio 2010 this has been moved to a global property sheet which is automatically added to
 190 every project you create:
 191
 192 ![](images/VCDirectories2010.jpg)
 193
 194 The process is the same as described in case of the local approach. Just add the include directories
 195 by using the environment variable *OPENCV_DIR*.
 196
 197 Test it!
 198 --------
 199
 200 Now to try this out download our little test [source code
 201 ](https://github.com/opencv/opencv/tree/3.4/samples/cpp/tutorial_code/introduction/windows_visual_studio_opencv/introduction_windows_vs.cpp)
 202 or get it from the sample code folder of the OpenCV sources. Add this to your project and build it.
 203 Here's its content:
 204
 205 @include cpp/tutorial_code/introduction/windows_visual_studio_opencv/introduction_windows_vs.cpp
 206
 207 You can start a Visual Studio build from two places. Either inside from the *IDE* (keyboard
 208 combination: Control-F5) or by navigating to your build directory and start the application with a
 209 double click. The catch is that these two **aren't** the same. When you start it from the *IDE* its
 210 current working directory is the projects directory, while otherwise it is the folder where the
 211 application file currently is (so usually your build directory). Moreover, in case of starting from
 212 the *IDE* the console window will not close once finished. It will wait for a keystroke of yours.
 213
 214 This is important to remember when you code inside the code open and save commands. Your resources
 215 will be saved ( and queried for at opening!!!) relatively to your working directory. This is unless
 216 you give a full, explicit path as a parameter for the I/O functions. In the code above we open [this
 217 OpenCV logo](https://github.com/opencv/opencv/tree/3.4/samples/data/opencv-logo.png). Before starting up the application,
 218 make sure you place
 219 the image file in your current working directory. Modify the image file name inside the code to try
 220 it out on other images too. Run it and voil á:
 221
 222 ![](images/SuccessVisualStudioWindows.jpg)
 223
 224 Command line arguments with Visual Studio
 225 -----------------------------------------
 226
 227 Throughout some of our future tutorials, you'll see that the programs main input method will be by
 228 giving a runtime argument. To do this you can just start up a command windows (cmd + Enter in the
 229 start menu), navigate to your executable file and start it with an argument. So for example in case
 230 of my upper project this would look like:
 231 @code{.bash}
 232 D:
 233 CD OpenCV\MySolutionName\Release
 234 MySolutionName.exe exampleImage.jpg
 235 @endcode
 236 Here I first changed my drive (if your project isn't on the OS local drive), navigated to my project
 237 and start it with an example image argument. While under Linux system it is common to fiddle around
 238 with the console window on the Microsoft Windows many people come to use it almost never. Besides,
 239 adding the same argument again and again while you are testing your application is, somewhat, a
 240 cumbersome task. Luckily, in the Visual Studio there is a menu to automate all this:
 241
 242 ![](images/VisualStudioCommandLineArguments.jpg)
 243
 244 Specify here the name of the inputs and while you start your application from the Visual Studio
 245 environment you have automatic argument passing. In the next introductory tutorial you'll see an
 246 in-depth explanation of the upper source code: @ref tutorial_display_image.