OpenCV - Revision history

Kai at 2019-08-14T23:30:40

2019-08-14T23:30:40Z

← Older revision		Revision as of 2019-08-14T23:30:40
Line 1:		Line 1:
	=== Introduction ===		=== Introduction ===
	<br />		<br />
	OpenCV (http://opencv.org) is a successful, open-source framework full of solutions for computer vision and related tasks. The robo.fish projects ~~standardize on~~ OpenCV version 3.3, or a newer 3.x release~~, in which the ''dnn'' module is a main module~~. The OpenCV installation path is assumed to be ''/usr/local/opencv-3.x.y''.		OpenCV (http://opencv.org) is a successful, open-source framework full of solutions for computer vision and related tasks. The robo.fish projects expect OpenCV version 4.1, or a newer 4.x release. The OpenCV installation path is assumed to be ''/usr/local/opencv-4.x.y''.
	<br />		<br />
	<br />		<br />

Kai at 2019-08-14T23:27:16

2019-08-14T23:27:16Z

← Older revision		Revision as of 2019-08-14T23:27:16
Line 26:		Line 26:
	cd OpenCV		cd OpenCV
	git tag		git tag
	git checkout -b v3.4.1 ~~3.4~~.1		git checkout -b v4.1.1 4.1.1
	</pre>		</pre>
	where we created the branch ''v3.4.1'' for the release tagged ''3.4.1''.		where we created the branch ''v4.1.1'' for the release tagged ''4.1.1''.
	<br />		<br />
	Don't forget to repeat this procedure for OpenCV-Contrib using the same tag.		Don't forget to repeat this procedure for OpenCV-Contrib using the same tag.
Line 89:		Line 89:
	* '''DPYTHON3_PACKAGES_PATH''' is the folder where the shared library files for Python modules need to be installed		* '''DPYTHON3_PACKAGES_PATH''' is the folder where the shared library files for Python modules need to be installed
	* '''DPYTHON_LIBRARY''' and '''DPYTHON3_LIBRARY''' are the shared library file for Python itself		* '''DPYTHON_LIBRARY''' and '''DPYTHON3_LIBRARY''' are the shared library file for Python itself
	~~<br />~~
	~~On '''Ubuntu 16.04''', with Python 3.6 provided by a miniconda3 environment that is currently active we could use~~
	~~<pre class="terminal">~~
	~~-DPYTHON_DEFAULT_EXECUTABLE=`python3-config --prefix`/bin/python3 \~~
	~~-DPYTHON3_EXECUTABLE=`python3-config --prefix`/bin/python3 \~~
	~~-DPYTHON3_INCLUDE_DIR=`python3-config --prefix`/include/python3.6m \~~
	~~-DPYTHON3_PACKAGES_PATH=`python3-config --prefix`/lib/python3.6/site-packages \~~
	~~</pre>~~
	<br />		<br />
	On '''Ubuntu 18.04''', where Python 3.6 is available as a main package, this works fine:		On '''Ubuntu 18.04''', where Python 3.6 is available as a main package, this works fine:
Line 128:		Line 120:
	<br />		<br />
	==== CUDA Settings ====		==== CUDA Settings ====
	To enable support for [[CUDA]] use this setting		I am assuming that your system is Ubuntu 18.04.3 with [[CUDA]] 10.1 installed (via the [https://developer.nvidia.com/cuda-downloads?target_os=Linux&target_arch=x86_64&target_distro=Ubuntu&target_version=1804 CUDA Toolkit download page]). To enable support for CUDA in OpenCV use this setting
	<pre class="terminal">		<pre class="terminal">
	-DWITH_CUDA=ON \		-DWITH_CUDA=ON \
Line 146:		Line 138:
	where 61 specifies compute capability level 6.1 and is given as an example. The compute capability versions supported by your NVIDIA hardware are listed in the cmake output when you run it without setting ''CUDA_ARCH_BIN''. There is also [https://en.wikipedia.org/wiki/CUDA#GPUs_supported a list at Wikipedia] that shows which compute capability level is supported by which NVIDIA hardware.		where 61 specifies compute capability level 6.1 and is given as an example. The compute capability versions supported by your NVIDIA hardware are listed in the cmake output when you run it without setting ''CUDA_ARCH_BIN''. There is also [https://en.wikipedia.org/wiki/CUDA#GPUs_supported a list at Wikipedia] that shows which compute capability level is supported by which NVIDIA hardware.
	<br />		<br />
	====~~= CUDA 9.1 on Ubuntu 18.04 =~~====		<br />
	~~Currently,~~ the ~~CUDA 9~~.~~1 SDK can not be used with GCC 7~~, ~~which is the default version of GCC in Ubuntu 18.04. Read [[GCC~~#~~Switching_between_GCC_versions_in_Ubuntu \| Switching between GCC version in Ubuntu]] how to switch to GCC 6. You will also need to pass to cmake the flag~~		==== Fixing the ''eigen3'' Header Path ====
	<pre class="~~terminal~~">		In the file '''modules/core/include/opencv2/core/private.hpp''', edit line 66
	~~-DCUDA_NVCC_FLAGS=--expt-relaxed-constexpr~~		<pre class="code">
			# include <Eigen/Core>
			</pre>
			by inserting ''eigen/'' before ''Eigen'' like this
			<pre class="code">
			# include <eigen3/Eigen/Core>
	</pre>		</pre>
	~~in order to avoid NVCC compilation errors.~~
	~~<br />~~
	<br />		<br />

	==== Intel Optimizations ====		==== Intel Optimizations ====
	The build option ''-DWITH_IPP=ON'' is for workstations with Intel processors and enables accelerated computation by using the [https://software.intel.com/en-us/articles/intel-integrated-performance-primitives-intel-ipp-open-source-computer-vision-library-opencv-faq/ Intel IPP-ICV] library. The library will be downloaded automatically into the subfolder ''3rdparty/ippicv'' during the build process.		The build option ''-DWITH_IPP=ON'' is for workstations with Intel processors and enables accelerated computation by using the [https://software.intel.com/en-us/articles/intel-integrated-performance-primitives-intel-ipp-open-source-computer-vision-library-opencv-faq/ Intel IPP-ICV] library. The library will be downloaded automatically into the subfolder ''3rdparty/ippicv'' during the build process.

Kai: /* CUDA 9.1 on Ubuntu 18.04 */

2018-05-16T19:43:19Z

CUDA 9.1 on Ubuntu 18.04

New page

=== Introduction ===
 
OpenCV (http://opencv.org) is a successful, open-source framework full of solutions for computer vision and related tasks. The robo.fish projects standardize on OpenCV version 3.3, or a newer 3.x release, in which the ''dnn'' module is a main module. The OpenCV installation path is assumed to be ''/usr/local/opencv-3.x.y''.
 
 

=== Building From Source ===
If your system does not provide an up-to-date version of OpenCV, including Python 3 modules, you can always resort to building it from source. Make sure that ''cmake'' is installed. On [[Ubuntu]] Linux open a shell terminal and make sure ''cmake'' is installed.
 
<pre class="terminal">
sudo apt install cmake
</pre>
 
Get the source code of OpenCV from Github:
<pre class="terminal">
git clone https://github.com/opencv/opencv.git OpenCV
</pre>
 
Also get the OpenCV extra modules:
<pre class="terminal">
git clone https://github.com/opencv/opencv_contrib.git OpenCV-Contrib
</pre>
 
Change to the new ''OpenCV'' folder, look at the list of version tags, decide which tagged release version you want to build, then check out that version by creating a branch for it:
<pre class="terminal">
cd OpenCV
git tag
git checkout -b v3.4.1 3.4.1
</pre>
where we created the branch ''v3.4.1'' for the release tagged ''3.4.1''.
 
Don't forget to repeat this procedure for OpenCV-Contrib using the same tag.
 
 
Make sure all dependencies for building the OpenCV source code are installed:
<pre class="terminal">
sudo apt install gcc g++ cmake cmake-curses-gui python3.6-dev \
libavformat-dev libavcodec-dev libavutil-dev libswscale-dev libavresample-dev libswresample-dev \
libopenblas-dev libatlas-base-dev libatlas-dev liblapack-dev liblapacke-dev python3-numpy \
doxygen qt5-default python3-pyqt5 libqt5opengl5-dev libgphoto2-dev \
libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libv4l-dev
</pre>
where I assume a Ubuntu 18.04 Bionic system with Python 3.6 packages available from the default repositories. On Ubuntu 16.04 you can install Python 3.6 via [https://conda.io/miniconda.html miniconda3].
Also, there should be no previously installed OpenCV libraries in ''/usr/lib/'', which could confuse the linker. You can check by typing
<pre class="terminal">
find /usr/lib/ -name 'libopencv*'
</pre>
 
Create the ''build'' subfolder in which we will run ''cmake''.
 
<pre class="terminal">
mkdir build
cd build
</pre>
 
Running cmake with the options shown below and will generate the make files for building GUI-less OpenCV binaries.
 
<pre class="terminal">
cmake -DCMAKE_BUILD_TYPE=RELEASE \
-DCMAKE_INSTALL_PREFIX=/usr/local/opencv-3.4.1 \
-DOPENCV_EXTRA_MODULES_PATH=../../OpenCV-Contrib/modules -DBUILD_opencv_legacy=OFF \
<<< Python settings >>>
-DBUILD_TIFF=ON \
-DBUILD_opencv_java=OFF \
-DWITH_QT=ON \
-DWITH_OPENGL=ON \
-DWITH_OPENCL=ON \
<<< CUDA settings >>>
-DWITH_IPP=ON \
-DWITH_TBB=ON \
-DWITH_EIGEN=ON \
-DWITH_V4L=ON \
-DWITH_VTK=OFF \
-DBUILD_TESTS=OFF \
-DBUILD_PERF_TESTS=OFF \
..
</pre>
 
==== Python Settings ====
This part of the build settings is responsible for generating the Python bindings, so that OpenCV can be used when programming in Python. Since it's 2018 and we are not interested in Python 2.7 anymore, we will build OpenCV exclusively for Python 3.6. These two settings are therefore fixed:
<pre class="terminal">
-DBUILD_opencv_python2=OFF \
-DBUILD_opencv_python3=ON \
</pre>
 
With that settled, we need to specify the special directories of the Python installation.
* '''DPYTHON_DEFAULT_EXECUTABLE''' and '''DPYTHON3_EXECUTABLE''' are both paths to the Python 3 binary
* '''PYTHON_INCLUDE_DIR''' and '''PYTHON3_INCLUDE_DIR''' are the folder in which the C API header file is located
* '''DPYTHON3_PACKAGES_PATH''' is the folder where the shared library files for Python modules need to be installed
* '''DPYTHON_LIBRARY''' and '''DPYTHON3_LIBRARY''' are the shared library file for Python itself
 
On '''Ubuntu 16.04''', with Python 3.6 provided by a miniconda3 environment that is currently active we could use
<pre class="terminal">
-DPYTHON_DEFAULT_EXECUTABLE=`python3-config --prefix`/bin/python3 \
-DPYTHON3_EXECUTABLE=`python3-config --prefix`/bin/python3 \
-DPYTHON3_INCLUDE_DIR=`python3-config --prefix`/include/python3.6m \
-DPYTHON3_PACKAGES_PATH=`python3-config --prefix`/lib/python3.6/site-packages \
</pre>
 
On '''Ubuntu 18.04''', where Python 3.6 is available as a main package, this works fine:
<pre class="terminal">
-DPYTHON_DEFAULT_EXECUTABLE=/usr/bin/python3 \
-DPYTHON_INCLUDE_DIR=/usr/include/python3.6m \
-DPYTHON3_INCLUDE_DIR=/usr/include/python3.6m \
-DPYTHON3_NUMPY_INCLUDE_DIRS=/usr/lib/python3/dist-packages/numpy/core/include \
-DPYTHON3_PACKAGES_PATH=/usr/lib/python3/dist-packages \
-DPYTHON3_EXECUTABLE=/usr/bin/python3 \
-DPYTHON_LIBRARY=/usr/lib/x86_64-linux-gnu/libpython3.6m.so \
-DPYTHON3_LIBRARY=/usr/lib/x86_64-linux-gnu/libpython3.6m.so \
</pre>
Note that both DPYTHON_INCLUDE_DIR and DPYTHON3_INCLUDE_DIR need to point to the Python 3 directory.
 
 
The directory paths can also be extracted from the Python runtime. For example:
<pre class="terminal">
-DPYTHON3_EXECUTABLE=$(which python3) \
-DPYTHON_DEFAULT_EXECUTABLE=$(which python3) \
-DPYTHON_INCLUDE_DIR=$(python3 -c "from distutils.sysconfig import get_python_inc; print(get_python_inc())") \
-DPYTHON_INCLUDE_DIR2=$(python3 -c "from os.path import dirname; from distutils.sysconfig import get_config_h_filename; print(dirname(get_config_h_filename()))") \
-DPYTHON3_INCLUDE_DIR=$(python3 -c "from distutils.sysconfig import get_python_inc; print(get_python_inc())") \
-DPYTHON3_NUMPY_INCLUDE_DIRS=$(python3 -c "import numpy; print(numpy.get_include())") \
-DPYTHON3_PACKAGES_PATH=$(python3 -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())") \
-DPYTHON_LIBRARY=$(python3 -c "from distutils.sysconfig import get_config_var;from os.path import dirname,join ; print(join(dirname(get_config_var('LIBPC')),get_config_var('LDLIBRARY')))") \
</pre>
 
One more note on Python: If you choose to install the Python module "cv2" to a different packages folder, don't forget to add that folder to the ''PYTHONPATH'' environment variable.
 
 
==== CUDA Settings ====
To enable support for [[CUDA]] use this setting
<pre class="terminal">
-DWITH_CUDA=ON \
</pre>
 
You probably also want to enable Fast Math and cuBLAS:
<pre class="terminal">
-DENABLE_FAST_MATH=ON \
-DCUDA_FAST_MATH=ON \
-DWITH_CUBLAS=ON \
</pre>
 
To shorten the build time, you should restrict the target architectures for the CUDA compiler (''NVCC'') to the architecture (or [http://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html#compute-capabilities compute capability level]) of the installed NVIDIA card. Use the cmake option
<pre class="terminal">
-DCUDA_ARCH_BIN=61
</pre>
where 61 specifies compute capability level 6.1 and is given as an example. The compute capability versions supported by your NVIDIA hardware are listed in the cmake output when you run it without setting ''CUDA_ARCH_BIN''. There is also [https://en.wikipedia.org/wiki/CUDA#GPUs_supported a list at Wikipedia] that shows which compute capability level is supported by which NVIDIA hardware.
 
===== CUDA 9.1 on Ubuntu 18.04 =====
Currently, the CUDA 9.1 SDK can not be used with GCC 7, which is the default version of GCC in Ubuntu 18.04. Read [[GCC#Switching_between_GCC_versions_in_Ubuntu | Switching between GCC version in Ubuntu]] how to switch to GCC 6. You will also need to pass to cmake the flag
<pre class="terminal">
-DCUDA_NVCC_FLAGS=--expt-relaxed-constexpr
</pre>
in order to avoid NVCC compilation errors.
 
 

==== Intel Optimizations ====
The build option ''-DWITH_IPP=ON'' is for workstations with Intel processors and enables accelerated computation by using the [https://software.intel.com/en-us/articles/intel-integrated-performance-primitives-intel-ipp-open-source-computer-vision-library-opencv-faq/ Intel IPP-ICV] library. The library will be downloaded automatically into the subfolder ''3rdparty/ippicv'' during the build process.
 
 
==== More Options ====
All the build options can be explored with the ''ccmake'' tool
<pre class="terminal">
ccmake ..
</pre>
 
Gtk+ 3 development files need to be present if you want [http://docs.opencv.org/3.1.0/d7/dfc/group__highgui.html#ga453d42fe4cb60e5723281a89973ee563 imshow()] to work. On Debian based distros look for the ''libgtk-3-dev'' package.
 
 
==== Make & Install ====
After the configuration completes successfully simply enter
<pre class="terminal">
make -j7
</pre>
to build OpenCV, where the optional parameter ''-j<n>'' specifies the number of parallel build processes to run. After OpenCV has been built type
<pre class="terminal">
sudo make install
</pre>
to install the headers (into /usr/local/include/) and the library files (into /usr/local/lib/).
 
 
To uninstall, run
<pre class="terminal">
sudo make uninstall
</pre>
Just make sure you don't delete the ''build'' subfolder before uninstalling. The file ''install_manifest.txt'' inside the ''build'' folder is needed by the uninstaller script. Otherwise you will need to manually delete the copied files.
 
 
==== Test ====
Testing whether OpenCV was successfully installed is easy. Just check the contents of the installation folder that you provided with the setting CMAKE_INSTALL_PREFIX, which defaults to ''/usr/local''.
 
 
To check whether the Python library was successfully installed, look for the file ''cv2.cpython-36m-x86_64-linux-gnu.so'' in the Python libraries directory that you specified (PYTHON3_PACKAGES_PATH) and run the test script
<pre class="code">
import os
import cv2 # loads the OpenCV module
from cv2 import __version__
os.path.dirname(cv2.__file__) # prints the directory from which OpenCV was loaded
__version__ # prints the version of the loaded OpenCV module
</pre>
 
=== Embedding OpenCV-Python In Your C++ Application ===
[https://wiki.python.org/moin/boost.python/GettingStarted Boost Python] is often used for make integration of the Python C API into your C++ project easier. It takes care of memory management and with its more compact syntax makes your code more readable.
 
 
Recent versions of OpenCV-Python can import/export matrices from/to Numpy arrays. That's why in C++, when you want to inject an OpenCV matrix to the Python environment, you will most likely have to deal with the Numpy C API. And there is a gotcha regarding the Numpy C API: Calling the macro ''import_array()'' only once is not enough if your Python interaction code spans multiple C++ compile units, i.e., ''cpp'' file. You either need to call ''import_array()'' in each cpp file or you need to use the ''#define'' statements ''PY_ARRAY_UNIQUE_SYMBOL'' and ''NO_IMPORT_ARRAY'' as explained in the [http://docs.scipy.org/doc/numpy-1.11.0/reference/c-api.array.html#miscellaneous Numpy documentation].
 
 
=== Mat vs. GpuMat vs. UMat ===
OpenCV stores images data in matrix form. In addition to the core '''Mat''' class, there are two matrix classes that you will be potentially dealing with.
 
 
'''GpuMat''' is defined in <opencv/core/cuda.hpp> and represents image data stored in the memory space of a [[CUDA]]-capable parallel processing hardware (graphics processing unit). To convert from or into a ''Mat'' object use the GpuMat methods
<pre class="code">
void GpuMat::upload(InputArray m)
void GpuMat::download(OutputArray m)
</pre>
The full class documentation can be found [https://docs.opencv.org/3.4.1/d0/d60/classcv_1_1cuda_1_1GpuMat.html here].
 
 
'''UMat''' is defined in <opencv2/core/mat.hpp> and bridges ''Mat'' to the image data structure used in the OpenCL-accelerated functions of OpenCV (make sure OpenCV was built with the flag ''WITH_OPENCL'' set to ''ON''). Support for ''UMat'' is integrated much deeper into OpenCV functions than for ''GpuMat''. To convert from or into a ''Mat'' object use
<pre class="code">
cv::UMat m = cv::Mat::getUMat(int accessFlags, UMatUsageFlags usageFlags)
cv::Mat m = cv::UMat::getMat(int flags)
</pre>
The full documentation can be found [https://docs.opencv.org/3.4.1/d7/d45/classcv_1_1UMat.html here].