doc/tutorials/introduction/windows_install/windows_install.rst

   1 .. _Windows_Installation:
   2
   3 Installation in Windows
   4 ***********************
   5
   6 .. include:: <isonum.txt>
   7
   8 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.
   9
  10 .. 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.
  11
  12 .. _Windows_Install_Prebuild:
  13
  14 Installation by Using the Pre-built Libraries
  15 =============================================
  16
  17 #. Launch a web browser of choice and go to our `page on Sourceforge <http://sourceforge.net/projects/opencvlibrary/files/opencv-win/>`_.
  18
  19 #. Choose a build you want to use and download it.
  20
  21    .. If you downloaded the source files present here see :ref:`CppTutWindowsMakeOwn`.
  22
  23 #. Make sure you have admin rights. Unpack the self-extracting archive.
  24
  25 #. You can check the installation at the chosen path as you can see below.
  26
  27    .. image:: images/OpenCV_Install_Directory.png
  28       :alt: An example of how the installation directory should look in case of successful install.
  29       :align: center
  30
  31 #. To finalize the installation go to the :ref:`WindowsSetPathAndEnviromentVariable` section.
  32
  33 .. _CppTutWindowsMakeOwn:
  34
  35 Installation by Making Your Own Libraries from the Source Files
  36 ===============================================================
  37
  38 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.
  39
  40 .. raw:: html
  41
  42   <div align="center">
  43   <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>
  44   <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>
  45   </div>
  46
  47 .. 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.
  48
  49 If you are building your own libraries you can take the source files from our `Git repository <https://github.com/Itseez/opencv.git>`_.
  50
  51 Building the OpenCV library from scratch requires a couple of tools installed beforehand:
  52
  53 .. |CMake| replace:: CMake
  54 .. _CMake: http://www.cmake.org/cmake/resources/software.html
  55 .. |TortoiseGit| replace:: TortoiseGit
  56 .. _TortoiseGit: http://code.google.com/p/tortoisegit/wiki/Download
  57 .. |Python_Libraries| replace:: Python libraries
  58 .. _Python_Libraries: http://www.python.org/getit/
  59 .. |Numpy| replace:: Numpy
  60 .. _Numpy: http://numpy.scipy.org/
  61 .. |IntelTBB| replace:: Intel |copy| Threading Building Blocks (*TBB*)
  62 .. _IntelTBB: http://threadingbuildingblocks.org/file.php?fid=77
  63 .. |IntelIIP| replace:: Intel |copy| Integrated Performance Primitives (*IPP*)
  64 .. _IntelIIP: http://software.intel.com/en-us/articles/intel-ipp/
  65 .. |IntelIIPA| replace:: Intel |copy| IPP Asynchronous C/C++
  66 .. _IntelIIPA: http://software.intel.com/en-us/intel-ipp-preview
  67 .. |qtframework| replace:: Qt framework
  68 .. _qtframework: http://qt.nokia.com/downloads
  69 .. |Eigen| replace:: Eigen
  70 .. _Eigen: http://eigen.tuxfamily.org/index.php?title=Main_Page#Download
  71 .. |CUDA_Toolkit| replace:: CUDA Toolkit
  72 .. _CUDA_Toolkit: http://developer.nvidia.com/cuda-downloads
  73 .. |OpenEXR| replace:: OpenEXR
  74 .. _OpenEXR: http://www.openexr.com/downloads.html
  75 .. |OpenNI_Framework| replace:: OpenNI Framework
  76 .. _OpenNI_Framework: http://www.openni.org/
  77 .. |Miktex| replace:: Miktex
  78 .. _Miktex: http://miktex.org/2.9/setup
  79 .. |Sphinx| replace:: Sphinx
  80 .. _Sphinx: http://sphinx.pocoo.org/
  81
  82 .. container:: enumeratevisibleitemswithsquare
  83
  84    + 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.
  85
  86    + |CMake|_, which is a neat tool to make the project files (for your chosen 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.
  87
  88    + 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/>`_
  89
  90 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.
  91
  92 .. container:: enumeratevisibleitemswithsquare
  93
  94    + 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*.
  95
  96    + |Numpy|_ is a scientific computing package for Python. Required for the *Python interface*.
  97
  98    + |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.
  99
 100    + |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.
 101
 102    + |IntelIIPA|_ is currently focused delivering Intel |copy| Graphics support for advanced image processing and computer vision functions.
 103
 104    + 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.
 105
 106    + |Eigen|_ is a C++ template library for linear algebra.
 107
 108    + 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.
 109
 110    + |OpenEXR|_ source files are required for the library to work with this high dynamic range (HDR) image file format.
 111
 112    + 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.
 113
 114    + |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*.
 115
 116    + |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.
 117
 118 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.
 119
 120 .. _WindowsBuildLibrary:
 121
 122 Building the library
 123 ^^^^^^^^^^^^^^^^^^^^
 124
 125 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.
 126
 127 #. Install |CMake|_. Simply follow the wizard, no need to add it to the path. The default install options are OK.
 128
 129 #. 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.
 130
 131 #. 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.
 132
 133 #. 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.
 134
 135    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`).
 136
 137    #) 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.
 138
 139 #. In this section I will cover installing the 3rd party libraries.
 140
 141    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.
 142
 143    #) .. _HereInstallSphinx:
 144
 145       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.
 146
 147       .. image:: images/cmsdstartwindows.jpg
 148          :alt: The Windows Command Startup
 149          :align: center
 150
 151       .. image:: images/Sphinx_Install.png
 152          :alt: How to start the command window
 153          :align: center
 154
 155       .. note::
 156
 157          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.
 158
 159       This will also install its prerequisites `Jinja2 <http://jinja.pocoo.org/docs/>`_ and `Pygments <http://pygments.org/>`_.
 160
 161    #) 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`).
 162
 163    #) 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.
 164
 165       .. image:: images/MiktexInstall.png
 166          :alt: The Miktex Install Screen
 167          :align: center
 168
 169    #) 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.
 170
 171       .. image:: images/IntelTBB.png
 172          :alt: The Miktex Install Screen
 173          :align: center
 174
 175    #) For the |IntelIIPA|_ download the source files and set environment variable **IPP_ASYNC_ROOT**. It should point to :file:`<your Program Files(x86) directory>/Intel/IPP Preview */ipp directory`. Here ``*`` denotes the particular preview name.
 176
 177    #) In case of the |Eigen|_ library it is again a case of download and extract to the :file:`D:/OpenCV/dep` directory.
 178
 179    #) Same as above with |OpenEXR|_.
 180
 181    #) 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>`_.
 182
 183    #) 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.
 184
 185    #) 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!!!):
 186
 187       .. image:: images/qtDownloadThisPackage.png
 188          :alt: Download this Qt Package
 189          :align: center
 190
 191       Extract it into a nice and short named directory like :file:`D:/OpenCV/dep/qt/` .
 192       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)`).
 193
 194       .. image:: images/visualstudiocommandprompt.jpg
 195          :alt: The Visual Studio command prompt
 196          :align: center
 197
 198       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:
 199
 200       .. code-block:: bash
 201
 202          configure.exe -release -no-webkit -no-phonon -no-phonon-backend -no-script -no-scripttools
 203                        -no-qt3support -no-multimedia -no-ltcg
 204
 205       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):
 206
 207       .. code-block:: bash
 208
 209          nmake
 210
 211       After this set the Qt enviroment variables using the following command on Windows 7:
 212
 213       .. code-block:: bash
 214
 215          setx -m QTDIR D:/OpenCV/dep/qt/qt-everywhere-opensource-src-4.7.3
 216
 217       .. |PathEditor| replace:: Path Editor
 218       .. _PathEditor: http://www.redfernplace.com/software-projects/patheditor/
 219
 220       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`.
 221
 222       .. note::
 223
 224          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.
 225
 226 #. 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).
 227
 228    .. image:: images/CMakeSelectBin.jpg
 229       :alt: Select the directories
 230       :align: center
 231
 232    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.
 233
 234    .. image:: images/CMake_Configure_Windows.jpg
 235       :alt: How CMake should look at build time.
 236       :align: center
 237
 238    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:
 239
 240    .. image:: images/CMakeBuildWithWindowsGUI.jpg
 241       :alt: The packages OpenCV may use
 242       :align: center
 243
 244    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:
 245
 246    .. image:: images/CMakePackageNotFoundWindows.jpg
 247       :alt: Constant for not found packages
 248       :align: center
 249
 250    .. image:: images/CMakeOutputPackageNotFound.jpg
 251       :alt: Error (warning) thrown in output window of the CMake GUI
 252       :align: center
 253
 254    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.
 255    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.
 256
 257    .. image:: images/CMakeBuildOptionsOpenCV.jpg
 258       :alt: Set the Solution Folders and the parts you want to build
 259       :align: center
 260
 261    Furthermore, you need to select what part of OpenCV you want to build.
 262
 263    .. container:: enumeratevisibleitemswithsquare
 264
 265       + *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.
 266       + *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.
 267       + *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.
 268       + *BUILD_SHARED_LIBS* -> With this you can control to build DLL files (when turned on) or static library files (\*.lib) otherwise.
 269       + *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.
 270       + *BUILD_PERF_TESTS* -> There are also performance tests for many OpenCV functions. If you're concerned about performance, build them and run.
 271       + *BUILD_opencv_python* -> Self-explanatory. Create the binaries to use OpenCV from the Python language.
 272
 273    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.
 274    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.
 275    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.
 276
 277    .. image:: images/ChangeBuildVisualStudio.jpg
 278       :alt: Look here for changing the Build Type
 279       :align: center
 280
 281    In the end you can observe the built binary files inside the bin directory:
 282
 283    .. image:: images/OpenCVBuildResultWindows.jpg
 284       :alt: The Result of the build.
 285       :align: center
 286
 287    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.
 288
 289    .. image:: images/WindowsBuildDoc.png
 290       :alt: The Documentation Projects
 291       :align: center
 292
 293    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.
 294
 295    .. image:: images/WindowsBuildInstall.png
 296       :alt: The Install Project
 297       :align: center
 298
 299    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.
 300
 301    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 at our :opencv_qa:`Q&A forum <>`.
 302    If everything is okay the *contours.exe* output should resemble the following image (if built with Qt support):
 303
 304    .. image:: images/WindowsQtContoursOutput.png
 305       :alt: A good output result
 306       :align: center
 307
 308    .. note::
 309
 310       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.
 311
 312 .. _WindowsSetPathAndEnviromentVariable:
 313
 314 Set the OpenCV enviroment variable and add it to the systems path
 315 =================================================================
 316
 317 First we set an enviroment variable to make easier our work. This will hold the build directory of our OpenCV library that we use in our projects. Start up a command window and enter:
 318
 319 ::
 320
 321    setx -m OPENCV_DIR D:\OpenCV\Build\x86\vc10     (suggested for Visual Studio 2010 - 32 bit Windows)
 322    setx -m OPENCV_DIR D:\OpenCV\Build\x64\vc10     (suggested for Visual Studio 2010 - 64 bit Windows)
 323
 324    setx -m OPENCV_DIR D:\OpenCV\Build\x86\vc11     (suggested for Visual Studio 2012 - 32 bit Windows)
 325    setx -m OPENCV_DIR D:\OpenCV\Build\x64\vc11     (suggested for Visual Studio 2012 - 64 bit Windows)
 326
 327 Here the directory is where you have your OpenCV binaries (*extracted* or *built*). You can have different platform (e.g. x64 instead of x86) or compiler type, so substitute appropriate value. Inside this you should have two folders called *lib* and *bin*. The -m should be added if you wish to make the settings computer wise, instead of user wise.
 328
 329 If you built static libraries then you are done. Otherwise, you need to add the *bin* folders path to the systems path. This is because 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 the operating system 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):
 330
 331 ::
 332
 333    %OPENCV_DIR%\bin
 334
 335 .. image:: images/PathEditorOpenCVInsertNew.png
 336    :alt: Right click to insert new path manually.
 337    :align: center
 338
 339 .. image:: images/PathEditorOpenCVSetPath.png
 340    :alt: Add the entry.
 341    :align: center
 342
 343 Save it to the registry and you are done. If you ever change the location of your build 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.
 344
 345 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.