Doxygen tutorials: python basic

This commit is contained in:
Maksim Shabunin
2014-11-28 17:18:32 +03:00
parent 36a04ef8de
commit 875f922332
80 changed files with 9240 additions and 2 deletions

View File

@@ -0,0 +1,87 @@
Introduction to OpenCV-Python Tutorials {#tutorial_py_intro}
=======================================
OpenCV
------
OpenCV was started at Intel in 1999 by **Gary Bradsky**, and the first release came out in 2000.
**Vadim Pisarevsky** joined Gary Bradsky to manage Intel's Russian software OpenCV team. In 2005,
OpenCV was used on Stanley, the vehicle that won the 2005 DARPA Grand Challenge. Later, its active
development continued under the support of Willow Garage with Gary Bradsky and Vadim Pisarevsky
leading the project. OpenCV now supports a multitude of algorithms related to Computer Vision and
Machine Learning and is expanding day by day.
OpenCV supports a wide variety of programming languages such as C++, Python, Java, etc., and is
available on different platforms including Windows, Linux, OS X, Android, and iOS. Interfaces for
high-speed GPU operations based on CUDA and OpenCL are also under active development.
OpenCV-Python is the Python API for OpenCV, combining the best qualities of the OpenCV C++ API and
the Python language.
OpenCV-Python
-------------
OpenCV-Python is a library of Python bindings designed to solve computer vision problems.
Python is a general purpose programming language started by **Guido van Rossum** that became very
popular very quickly, mainly because of its simplicity and code readability. It enables the
programmer to express ideas in fewer lines of code without reducing readability.
Compared to languages like C/C++, Python is slower. That said, Python can be easily extended with
C/C++, which allows us to write computationally intensive code in C/C++ and create Python wrappers
that can be used as Python modules. This gives us two advantages: first, the code is as fast as the
original C/C++ code (since it is the actual C++ code working in background) and second, it easier to
code in Python than C/C++. OpenCV-Python is a Python wrapper for the original OpenCV C++
implementation.
OpenCV-Python makes use of **Numpy**, which is a highly optimized library for numerical operations
with a MATLAB-style syntax. All the OpenCV array structures are converted to and from Numpy arrays.
This also makes it easier to integrate with other libraries that use Numpy such as SciPy and
Matplotlib.
OpenCV-Python Tutorials
-----------------------
OpenCV introduces a new set of tutorials which will guide you through various functions available in
OpenCV-Python. **This guide is mainly focused on OpenCV 3.x version** (although most of the
tutorials will also work with OpenCV 2.x).
Prior knowledge of Python and Numpy is recommended as they won't be covered in this guide.
**Proficiency with Numpy is a must in order to write optimized code using OpenCV-Python.**
This tutorial was originally started by *Abid Rahman K.* as part of the Google Summer of Code 2013
program under the guidance of *Alexander Mordvintsev*.
OpenCV Needs You !!!
--------------------
Since OpenCV is an open source initiative, all are welcome to make contributions to the library,
documentation, and tutorials. If you find any mistake in this tutorial (from a small spelling
mistake to an egregious error in code or concept), feel free to correct it by cloning OpenCV in
[GitHub](https://github.com/Itseez/opencv) and submitting a pull request. OpenCV developers will
check your pull request, give you important feedback and (once it passes the approval of the
reviewer) it will be merged into OpenCV. You will then become an open source contributor :-)
As new modules are added to OpenCV-Python, this tutorial will have to be expanded. If you are
familiar with a particular algorithm and can write up a tutorial including basic theory of the
algorithm and code showing example usage, please do so.
Remember, we **together** can make this project a great success !!!
Contributors
------------
Below is the list of contributors who submitted tutorials to OpenCV-Python.
-# Alexander Mordvintsev (GSoC-2013 mentor)
2. Abid Rahman K. (GSoC-2013 intern)
Additional Resources
--------------------
-# A Quick guide to Python - [A Byte of Python](http://swaroopch.com/notes/python/)
2. [Basic Numpy Tutorials](http://wiki.scipy.org/Tentative_NumPy_Tutorial)
3. [Numpy Examples List](http://wiki.scipy.org/Numpy_Example_List)
4. [OpenCV Documentation](http://docs.opencv.org/)
5. [OpenCV Forum](http://answers.opencv.org/questions/)

View File

@@ -0,0 +1,259 @@
Install OpenCV-Python in Fedora {#tutorial_py_setup_in_fedora}
===============================
Goals
-----
In this tutorial
- We will learn to setup OpenCV-Python in your Fedora system. Below steps are tested for
Fedora 18 (64-bit) and Fedora 19 (32-bit).
Introduction
------------
OpenCV-Python can be installed in Fedora in two ways, 1) Install from pre-built binaries available
in fedora repositories, 2) Compile from the source. In this section, we will see both.
Another important thing is the additional libraries required. OpenCV-Python requires only **Numpy**
(in addition to other dependencies, which we will see later). But in this tutorials, we also use
**Matplotlib** for some easy and nice plotting purposes (which I feel much better compared to
OpenCV). Matplotlib is optional, but highly recommended. Similarly we will also see **IPython**, an
Interactive Python Terminal, which is also highly recommended.
Installing OpenCV-Python from Pre-built Binaries
------------------------------------------------
Install all packages with following command in terminal as root.
@code{.bash}
\f$ yum install numpy opencv*
@endcode
Open Python IDLE (or IPython) and type following codes in Python terminal.
@code{.python}
import cv2
print cv2.__version__
@endcode
If the results are printed out without any errors, congratulations !!! You have installed
OpenCV-Python successfully.
It is quite easy. But there is a problem with this. Yum repositories may not contain the latest
version of OpenCV always. For example, at the time of writing this tutorial, yum repository contains
2.4.5 while latest OpenCV version is 2.4.6. With respect to Python API, latest version will always
contain much better support. Also, there may be chance of problems with camera support, video
playback etc depending upon the drivers, ffmpeg, gstreamer packages present etc.
So my personnel preference is next method, i.e. compiling from source. Also at some point of time,
if you want to contribute to OpenCV, you will need this.
Installing OpenCV from source
-----------------------------
Compiling from source may seem a little complicated at first, but once you succeeded in it, there is
nothing complicated.
First we will install some dependencies. Some are compulsory, some are optional. Optional
dependencies, you can leave if you don't want.
### Compulsory Dependencies
We need **CMake** to configure the installation, **GCC** for compilation, **Python-devel** and
**Numpy** for creating Python extensions etc.
@code{.bash}
yum install cmake
yum install python-devel numpy
yum install gcc gcc-c++
@endcode
Next we need **GTK** support for GUI features, Camera support (libdc1394, libv4l), Media Support
(ffmpeg, gstreamer) etc.
@code{.bash}
yum install gtk2-devel
yum install libdc1394-devel
yum install libv4l-devel
yum install ffmpeg-devel
yum install gstreamer-plugins-base-devel
@endcode
### Optional Dependencies
Above dependencies are sufficient to install OpenCV in your fedora machine. But depending upon your
requirements, you may need some extra dependencies. A list of such optional dependencies are given
below. You can either leave it or install it, your call :)
OpenCV comes with supporting files for image formats like PNG, JPEG, JPEG2000, TIFF, WebP etc. But
it may be a little old. If you want to get latest libraries, you can install development files for
these formats.
@code{.bash}
yum install libpng-devel
yum install libjpeg-turbo-devel
yum install jasper-devel
yum install openexr-devel
yum install libtiff-devel
yum install libwebp-devel
@endcode
Several OpenCV functions are parallelized with **Intel's Threading Building Blocks** (TBB). But if
you want to enable it, you need to install TBB first. ( Also while configuring installation with
CMake, don't forget to pass -D WITH_TBB=ON. More details below.)
@code{.bash}
yum install tbb-devel
@endcode
OpenCV uses another library **Eigen** for optimized mathematical operations. So if you have Eigen
installed in your system, you can exploit it. ( Also while configuring installation with CMake,
don't forget to pass -D WITH_EIGEN=ON. More details below.)
@code{.bash}
yum install eigen3-devel
@endcode
If you want to build **documentation** ( *Yes, you can create offline version of OpenCV's complete
official documentation in your system in HTML with full search facility so that you need not access
internet always if any question, and it is quite FAST!!!* ), you need to install **Sphinx** (a
documentation generation tool) and **pdflatex** (if you want to create a PDF version of it). ( Also
while configuring installation with CMake, don't forget to pass -D BUILD_DOCS=ON. More details
below.)
@code{.bash}
yum install python-sphinx
yum install texlive
@endcode
### Downloading OpenCV
Next we have to download OpenCV. You can download the latest release of OpenCV from [sourceforge
site](http://sourceforge.net/projects/opencvlibrary/). Then extract the folder.
Or you can download latest source from OpenCV's github repo. (If you want to contribute to OpenCV,
choose this. It always keeps your OpenCV up-to-date). For that, you need to install **Git** first.
@code{.bash}
yum install git
git clone https://github.com/Itseez/opencv.git
@endcode
It will create a folder OpenCV in home directory (or the directory you specify). The cloning may
take some time depending upon your internet connection.
Now open a terminal window and navigate to the downloaded OpenCV folder. Create a new build folder
and navigate to it.
@code{.bash}
mkdir build
cd build
@endcode
### Configuring and Installing
Now we have installed all the required dependencies, let's install OpenCV. Installation has to be
configured with CMake. It specifies which modules are to be installed, installation path, which
additional libraries to be used, whether documentation and examples to be compiled etc. Below
command is normally used for configuration (executed from build folder).
@code{.bash}
cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local ..
@endcode
It specifies that build type is "Release Mode" and installation path is /usr/local. Observe the -D
before each option and .. at the end. In short, this is the format:
@code{.bash}
cmake [-D <flag>] [-D <flag>] ..
@endcode
You can specify as many flags you want, but each flag should be preceded by -D.
So in this tutorial, we are installing OpenCV with TBB and Eigen support. We also build the
documentation, but we exclude Performance tests and building samples. We also disable GPU related
modules (since we use OpenCV-Python, we don't need GPU related modules. It saves us some time).
*(All the below commands can be done in a single cmake statement, but it is split here for better
understanding.)*
- Enable TBB and Eigen support:
@code{.bash}
cmake -D WITH_TBB=ON -D WITH_EIGEN=ON ..
@endcode
- Enable documentation and disable tests and samples
@code{.bash}
cmake -D BUILD_DOCS=ON -D BUILD_TESTS=OFF -D BUILD_PERF_TESTS=OFF -D BUILD_EXAMPLES=OFF ..
@endcode
- Disable all GPU related modules.
@code{.bash}
cmake -D WITH_OPENCL=OFF -D WITH_CUDA=OFF -D BUILD_opencv_gpu=OFF -D BUILD_opencv_gpuarithm=OFF -D BUILD_opencv_gpubgsegm=OFF -D BUILD_opencv_gpucodec=OFF -D BUILD_opencv_gpufeatures2d=OFF -D BUILD_opencv_gpufilters=OFF -D BUILD_opencv_gpuimgproc=OFF -D BUILD_opencv_gpulegacy=OFF -D BUILD_opencv_gpuoptflow=OFF -D BUILD_opencv_gpustereo=OFF -D BUILD_opencv_gpuwarping=OFF ..
@endcode
- Set installation path and build type
@code{.bash}
cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local ..
@endcode
Each time you enter cmake statement, it prints out the resulting configuration setup. In the final
setup you got, make sure that following fields are filled (below is the some important parts of
configuration I got). These fields should be filled appropriately in your system also. Otherwise
some problem has happened. So check if you have correctly performed above steps.
@code{.bash}
-- GUI:
-- GTK+ 2.x: YES (ver 2.24.19)
-- GThread : YES (ver 2.36.3)
-- Video I/O:
-- DC1394 2.x: YES (ver 2.2.0)
-- FFMPEG: YES
-- codec: YES (ver 54.92.100)
-- format: YES (ver 54.63.104)
-- util: YES (ver 52.18.100)
-- swscale: YES (ver 2.2.100)
-- gentoo-style: YES
-- GStreamer:
-- base: YES (ver 0.10.36)
-- video: YES (ver 0.10.36)
-- app: YES (ver 0.10.36)
-- riff: YES (ver 0.10.36)
-- pbutils: YES (ver 0.10.36)
-- V4L/V4L2: Using libv4l (ver 1.0.0)
-- Other third-party libraries:
-- Use Eigen: YES (ver 3.1.4)
-- Use TBB: YES (ver 4.0 interface 6004)
-- Python:
-- Interpreter: /usr/bin/python2 (ver 2.7.5)
-- Libraries: /lib/libpython2.7.so (ver 2.7.5)
-- numpy: /usr/lib/python2.7/site-packages/numpy/core/include (ver 1.7.1)
-- packages path: lib/python2.7/site-packages
-- Documentation:
-- Build Documentation: YES
-- Sphinx: /usr/bin/sphinx-build (ver 1.1.3)
-- PdfLaTeX compiler: /usr/bin/pdflatex
--
-- Tests and samples:
-- Tests: NO
-- Performance tests: NO
-- C/C++ Examples: NO
@endcode
Many other flags and settings are there. It is left for you for further exploration.
Now you build the files using make command and install it using make install command. make install
should be executed as root.
@code{.bash}
make
su
make install
@endcode
Installation is over. All files are installed in /usr/local/ folder. But to use it, your Python
should be able to find OpenCV module. You have two options for that.
-# **Move the module to any folder in Python Path** : Python path can be found out by entering
import sys;print sys.path in Python terminal. It will print out many locations. Move
/usr/local/lib/python2.7/site-packages/cv2.so to any of this folder. For example,
@code{.bash}
su mv /usr/local/lib/python2.7/site-packages/cv2.so /usr/lib/python2.7/site-packages
@endcode
But you will have to do this every time you install OpenCV.
-# **Add /usr/local/lib/python2.7/site-packages to the PYTHON_PATH**: It is to be done only once.
Just open \~/.bashrc and add following line to it, then log out and come back.
@code{.bash}
export PYTHONPATH=\f$PYTHONPATH:/usr/local/lib/python2.7/site-packages
@endcode
Thus OpenCV installation is finished. Open a terminal and try import cv2.
To build the documentation, just enter following commands:
@code{.bash}
make docs
make html_docs
@endcode
Then open opencv/build/doc/_html/index.html and bookmark it in the browser.
Additional Resources
--------------------
Exercises
---------
-# Compile OpenCV from source in your Fedora machine.

View File

@@ -0,0 +1,145 @@
Install OpenCV-Python in Windows {#tutorial_py_setup_in_windows}
================================
Goals
-----
In this tutorial
- We will learn to setup OpenCV-Python in your Windows system.
Below steps are tested in a Windows 7-64 bit machine with Visual Studio 2010 and Visual Studio
2012. The screenshots shows VS2012.
Installing OpenCV from prebuilt binaries
----------------------------------------
-# Below Python packages are to be downloaded and installed to their default locations.
1.1. [Python-2.7.x](http://python.org/ftp/python/2.7.5/python-2.7.5.msi).
1.2.
[Numpy](http://sourceforge.net/projects/numpy/files/NumPy/1.7.1/numpy-1.7.1-win32-superpack-python2.7.exe/download).
1.3.
[Matplotlib](https://downloads.sourceforge.net/project/matplotlib/matplotlib/matplotlib-1.3.0/matplotlib-1.3.0.win32-py2.7.exe)
(*Matplotlib is optional, but recommended since we use it a lot in our tutorials*).
-# Install all packages into their default locations. Python will be installed to **C:/Python27/**.
3. After installation, open Python IDLE. Enter import numpy and make sure Numpy is working fine.
4. Download latest OpenCV release from [sourceforge
site](http://sourceforge.net/projects/opencvlibrary/files/opencv-win/2.4.6/OpenCV-2.4.6.0.exe/download)
and double-click to extract it.
5. Goto **opencv/build/python/2.7** folder.
6. Copy **cv2.pyd** to **C:/Python27/lib/site-packages**.
7. Open Python IDLE and type following codes in Python terminal.
\>\>\> import cv2 \>\>\> print cv2.__version__
If the results are printed out without any errors, congratulations !!! You have installed
OpenCV-Python successfully.
Building OpenCV from source
---------------------------
-# Download and install Visual Studio and CMake.
1.1. [Visual Studio 2012](http://go.microsoft.com/?linkid=9816768)
1.2. [CMake](http://www.cmake.org/files/v2.8/cmake-2.8.11.2-win32-x86.exe)
-# Download and install necessary Python packages to their default locations
2.1. [Python 2.7.x](http://python.org/ftp/python/2.7.5/python-2.7.5.msi)
2.2.
[Numpy](http://sourceforge.net/projects/numpy/files/NumPy/1.7.1/numpy-1.7.1-win32-superpack-python2.7.exe/download)
2.3.
[Matplotlib](https://downloads.sourceforge.net/project/matplotlib/matplotlib/matplotlib-1.3.0/matplotlib-1.3.0.win32-py2.7.exe)
(*Matplotlib is optional, but recommended since we use it a lot in our tutorials.*)
@note In this case, we are using 32-bit binaries of Python packages. But if you want to use OpenCV
for x64, 64-bit binaries of Python packages are to be installed. Problem is that, there is no
official 64-bit binaries of Numpy. You have to build it on your own. For that, you have to use the
same compiler used to build Python. When you start Python IDLE, it shows the compiler details. You
can get more [information here](http://stackoverflow.com/q/2676763/1134940). So your system must
have the same Visual Studio version and build Numpy from source.
@note Another method to have 64-bit Python packages is to use ready-made Python distributions from
third-parties like [Anaconda](http://www.continuum.io/downloads),
[Enthought](https://www.enthought.com/downloads/) etc. It will be bigger in size, but will have
everything you need. Everything in a single shell. You can also download 32-bit versions also. 3.
Make sure Python and Numpy are working fine.
-# Download OpenCV source. It can be from
[Sourceforge](http://sourceforge.net/projects/opencvlibrary/) (for official release version) or
from [Github](https://github.com/Itseez/opencv) (for latest source).
5. Extract it to a folder, opencv and create a new folder build in it.
6. Open CMake-gui (*Start \> All Programs \> CMake-gui*)
7. Fill the fields as follows (see the image below):
7.1. Click on **Browse Source...** and locate the opencv folder.
7.2. Click on **Browse Build...** and locate the build folder we created.
7.3. Click on **Configure**.
![image](images/Capture1.jpg)
7.4. It will open a new window to select the compiler. Choose appropriate compiler (here,
Visual Studio 11) and click **Finish**.
![image](images/Capture2.png)
7.5. Wait until analysis is finished.
-# You will see all the fields are marked in red. Click on the **WITH** field to expand it. It
decides what extra features you need. So mark appropriate fields. See the below image:
![image](images/Capture3.png)
-# Now click on **BUILD** field to expand it. First few fields configure the build method. See the
below image:
![image](images/Capture5.png)
-# Remaining fields specify what modules are to be built. Since GPU modules are not yet supported
by OpenCV-Python, you can completely avoid it to save time (But if you work with them, keep it
there). See the image below:
![image](images/Capture6.png)
-# Now click on **ENABLE** field to expand it. Make sure **ENABLE_SOLUTION_FOLDERS** is unchecked
(Solution folders are not supported by Visual Studio Express edition). See the image below:
![image](images/Capture7.png)
-# Also make sure that in the **PYTHON** field, everything is filled. (Ignore
PYTHON_DEBUG_LIBRARY). See image below:
![image](images/Capture80.png)
-# Finally click the **Generate** button.
14. Now go to our **opencv/build** folder. There you will find **OpenCV.sln** file. Open it with
Visual Studio.
15. Check build mode as **Release** instead of **Debug**.
16. In the solution explorer, right-click on the **Solution** (or **ALL_BUILD**) and build it. It
will take some time to finish.
17. Again, right-click on **INSTALL** and build it. Now OpenCV-Python will be installed.
![image](images/Capture8.png)
-# Open Python IDLE and enter import cv2. If no error, it is installed correctly.
@note We have installed with no other support like TBB, Eigen, Qt, Documentation etc. It would be
difficult to explain it here. A more detailed video will be added soon or you can just hack around.
Additional Resources
--------------------
Exercises
---------
-# If you have a windows machine, compile the OpenCV from source. Do all kinds of hacks. If you
meet any problem, visit OpenCV forum and explain your problem.

View File

@@ -0,0 +1,17 @@
Introduction to OpenCV {#tutorial_py_table_of_contents_setup}
======================
- @subpage tutorial_py_intro
Getting Started with
OpenCV-Python
- @subpage tutorial_py_setup_in_windows
Set Up
OpenCV-Python in Windows
- @subpage tutorial_py_setup_in_fedora
Set Up
OpenCV-Python in Fedora