Fr

Second Edition
Learning OpenCV 3 Computer Vision with Python,
Second Edition, takes you through building a
theoretical foundation for image processing and video
analysis and progress to the concepts of classification
through machine learning, acquiring the technical
know-how that will allow you to create and use object
detectors and classifiers, and even track objects in
movies or video camera feeds.
Finally, this journey ends at the world of artificial neural
networks, along with the development of a hand-written
digit recognition application.

Who this book is written for

Install and familiarize yourself with

OpenCV 3's Python API
Grasp the basics of image processing and
video analysis
Identify and recognize objects in images
and videos
Detect and recognize faces using OpenCV
Train and use your own object classifiers
Learn about machine learning concepts in a
computer vision context
Work with artificial neural networks
using OpenCV
Develop your own real-life computer
vision applications

P U B L I S H I N G

Prices do not include

local sales tax or VAT
where applicable

Visit www.PacktPub.com for books, eBooks,

code, downloads, and PacktLib.

Joe Minichino
Joseph Howse

$ 44.99 US
28.99 UK

community experience distilled

Second Edition

Intended for novices to the world of OpenCV and

computer vision, as well as OpenCV veterans who
want to learn about what's new in OpenCV 3, this
book is useful as a reference for experts and a training
manual for beginners, or for anybody who wants to
familiarize themselves with the concepts of object
classification and detection in simple and understandable
terms. Basic knowledge of Python and programming
concepts is required, although the book has an easy
learning curve both from a theoretical and coding
point of view.

What you will learn from this book

Learning OpenCV 3 Computer Vision with Python

Learning OpenCV 3 Computer

Vision with Python

ee

Sa
m

pl

C o m m u n i t y

E x p e r i e n c e

D i s t i l l e d

Learning OpenCV 3 Computer

Vision with Python
Second Edition
Unleash the power of computer vision with Python using OpenCV

Joe Minichino
Joseph Howse

In this package, you will find:

The author biography

A preview chapter from the book, Chapter 1 'Setting Up OpenCV'
A synopsis of the books content
More information on Learning OpenCV 3 Computer Vision with Python
Second Edition

About the Authors

Joe Minichino is a computer vision engineer for Hoolux Medical by day and a

developer of the NoSQL database LokiJS by night. On weekends, he is a heavy metal

singer/songwriter. He is a passionate programmer who is immensely curious about
programming languages and technologies and constantly experiments with them. At
Hoolux, Joe leads the development of an Android computer vision-based advertising
platform for the medical industry.
Born and raised in Varese, Lombardy, Italy, and coming from a humanistic
background in philosophy (at Milan's Universit Statale), Joe has spent his last
11 years living in Cork, Ireland, which is where he became a computer science
graduate at the Cork Institute of Technology.

Joseph Howse lives in Canada. During the winters, he grows his beard, while

his four cats grow their thick coats of fur. He loves combing his cats every day and
sometimes, his cats also pull his beard.

He has been writing for Packt Publishing since 2012. His books include OpenCV for
Secret Agents, OpenCV Blueprints, Android Application Programming with OpenCV 3,
OpenCV Computer Vision with Python, and Python Game Programming by Example.
When he is not writing books or grooming his cats, he provides consulting,
training, and software development services through his company,
Nummist Media (http://nummist.com).

Preface
OpenCV 3 is a state-of-the-art computer vision library that is used for a variety
of image and video processing operations. Some of the more spectacular and
futuristic features, such as face recognition or object tracking, are easily achievable
with OpenCV 3. Learning the basic concepts behind computer vision algorithms,
models, and OpenCV's API will enable the development of all sorts of real-world
applications, including security and surveillance tools.
Starting with basic image processing operations, this book will take you through
a journey that explores advanced computer vision concepts. Computer vision is a
rapidly evolving science whose applications in the real world are exploding, so this
book will appeal to computer vision novices as well as experts of the subject who
want to learn about the brand new OpenCV 3.0.0.

What this book covers

Chapter 1, Setting Up OpenCV, explains how to set up OpenCV 3 with Python on
different platforms. It will also troubleshoot common problems.
Chapter 2, Handling Files, Cameras, and GUIs, introduces OpenCV's I/O functionalities.
It will also discuss the concept of a project and the beginnings of an object-oriented
design for this project.
Chapter 3, Processing Images with OpenCV 3, presents some techniques required to
alter images, such as detecting skin tone in an image, sharpening an image, marking
contours of subjects, and detecting crosswalks using a line segment detector.
Chapter 4, Depth Estimation and Segmentation, shows you how to use data from a
depth camera to identify foreground and background regions, such that we can
limit an effect to only the foreground or background.

Preface

Chapter 5, Detecting and Recognizing Faces, introduces some of OpenCV's face

detection functionalities, along with the data files that define particular types
of trackable objects.
Chapter 6, Retrieving Images and Searching Using Image Descriptors, shows how to
detect the features of an image with the help of OpenCV and make use of them
to match and search for images.
Chapter 7, Detecting and Recognizing Objects, introduces the concept of detecting and
recognizing objects, which is one of the most common challenges in computer vision.
Chapter 8, Tracking Objects, explores the vast topic of object tracking, which is the
process of locating a moving object in a movie or video feed with the help of a camera.
Chapter 9, Neural Networks with OpenCV an Introduction, introduces you to Artificial
Neural Networks in OpenCV and illustrates their usage in a real-life application.

Setting Up OpenCV
You picked up this book so you may already have an idea of what OpenCV is.
Maybe, you heard of Sci-Fi-sounding features, such as face detection, and got
intrigued. If this is the case, you've made the perfect choice. OpenCV stands for
Open Source Computer Vision. It is a free computer vision library that allows you
to manipulate images and videos to accomplish a variety of tasks from displaying
the feed of a webcam to potentially teaching a robot to recognize real-life objects.
In this book, you will learn to leverage the immense potential of OpenCV with the
Python programming language. Python is an elegant language with a relatively
shallow learning curve and very powerful features. This chapter is a quick guide to
setting up Python 2.7, OpenCV, and other related libraries. After setup, we also look
at OpenCV's Python sample scripts and documentation.
If you wish to skip the installation process and jump right into action,
you can download the virtual machine (VM) I've made available at
http://techfort.github.io/pycv/.
This file is compatible with VirtualBox, a free-to-use virtualization
application that lets you build and run VMs. The VM I've built is
based on Ubuntu Linux 14.04 and has all the necessary software
installed so that you can start coding right away.
This VM requires at least 2 GB of RAM to run smoothly, so make sure
that you allocate at least 2 (but, ideally, more than 4) GB of RAM to
the VM, which means that your host machine will need at least 6 GB
of RAM to sustain it.

[1]

Setting Up OpenCV

The following related libraries are covered in this chapter:

NumPy: This library is a dependency of OpenCV's Python bindings.

It provides numeric computing functionality, including efficient arrays.

SciPy: This library is a scientific computing library that is closely related to

NumPy. It is not required by OpenCV, but it is useful for manipulating data
in OpenCV images.

OpenNI: This library is an optional dependency of OpenCV. It adds the

support for certain depth cameras, such as Asus XtionPRO.

SensorKinect: This library is an OpenNI plugin and optional dependency of

OpenCV. It adds support for the Microsoft Kinect depth camera.

For this book's purposes, OpenNI and SensorKinect can be considered optional.
They are used throughout Chapter 4, Depth Estimation and Segmentation, but are
not used in the other chapters or appendices.
This book focuses on OpenCV 3, the new major release of the
OpenCV library. All additional information about OpenCV is
available at http://opencv.org, and its documentation is
available at http://docs.opencv.org/master.

Choosing and using the right setup tools

We are free to choose various setup tools, depending on our operating system and
how much configuration we want to do. Let's take an overview of the tools for
Windows, Mac, Ubuntu, and other Unix-like systems.

Installation on Windows
Windows does not come with Python preinstalled. However, installation wizards are
available for precompiled Python, NumPy, SciPy, and OpenCV. Alternatively, we
can build from a source. OpenCV's build system uses CMake for configuration and
either Visual Studio or MinGW for compilation.
If we want support for depth cameras, including Kinect, we should first install
OpenNI and SensorKinect, which are available as precompiled binaries with
installation wizards. Then, we must build OpenCV from a source.
The precompiled version of OpenCV does not offer support
for depth cameras.

[2]

Chapter 1

On Windows, OpenCV 2 offers better support for 32-bit Python than 64-bit Python;
however, with the majority of computers sold today being 64-bit systems, our
instructions will refer to 64-bit. All installers have 32-bit versions available from the
same site as the 64-bit.
Some of the following steps refer to editing the system's PATH variable. This task can
be done in the Environment Variables window of Control Panel.
1. On Windows Vista / Windows 7 / Windows 8, click on the Start menu and
launch Control Panel. Now, navigate to System and Security | System |
Advanced system settings. Click on the Environment Variables button.
2. On Windows XP, click on the Start menu and navigate to Control Panel |
System. Select the Advanced tab. Click on the Environment Variables
button.
3. Now, under System variables, select Path and click on the Edit button.
4. Make changes as directed.
5. To apply the changes, click on all the OK buttons (until we are back in the
main window of Control Panel).
6. Then, log out and log back in (alternatively, reboot).

Using binary installers (no support for depth

cameras)
You can choose to install Python and its related libraries separately if you prefer;
however, there are Python distributions that come with installers that will set up the
entire SciPy stack (which includes Python and NumPy), which make it very trivial to
set up the development environment.
One such distribution is Anaconda Python (downloadable at
http://09c8d0b2229f813c1b93c95ac804525aac4b6dba79b00b39d1d3.r79.
cf1.rackcdn.com/Anaconda-2.1.0Windows-x86_64.exe). Once the installer is

downloaded, run it and remember to add the path to the Anaconda installation to
your PATH variable following the preceding procedure.

[3]

Setting Up OpenCV

Here are the steps to set up Python7, NumPy, SciPy, and OpenCV:
1. Download and install the 32-bit Python 2.7.9 from https://www.python.
org/ftp/python/2.7.9/python-2.7.9.amd64.msi.
2. Download and install NumPy 1.6.2 from http://www.lfd.uci.
edu/~gohlke/pythonlibs/#numpyhttp://sourceforge.net/projects/
numpy/files/NumPy/1.6.2/numpy-1.6.2-win32-superpackpython2.7.exe/download (note that installing NumPy on Windows 64-bit

is a bit tricky due to the lack of a 64-bit Fortran compiler on Windows, which
NumPy depends on. The binary at the preceding link is unofficial).
3. Download and install SciPy 11.0 from http://www.lfd.uci.edu/~gohlke/
pythonlibs/#scipyhttp://sourceforge.net/projects/scipy/files/
scipy/0.11.0/scipy-0.11.0win32-superpack-python2.7.exe/download

(this is the same as NumPy and these are community installers).

4. Download the self-extracting ZIP of OpenCV 3.0.0 from https://github.
com/Itseez/opencv. Run this ZIP, and when prompted, enter a destination
folder, which we will refer to as <unzip_destination>. A subfolder,
<unzip_destination>\opencv, is created.
5. Copy <unzip_destination>\opencv\build\python\2.7\cv2.pyd to C:\
Python2.7\Lib\site-packages (assuming that we had installed Python 2.7
to the default location). If you installed Python 2.7 with Anaconda, use the
Anaconda installation folder instead of the default Python installation. Now,
the new Python installation can find OpenCV.
6. A final step is necessary if we want Python scripts to run using the new
Python installation by default. Edit the system's PATH variable and append
;C:\Python2.7 (assuming that we had installed Python 2.7 to the default
location) or your Anaconda installation folder. Remove any previous Python
paths, such as ;C:\Python2.6. Log out and log back in (alternatively, reboot).

Using CMake and compilers

Windows does not come with any compilers or CMake. We need to install them.
If we want support for depth cameras, including Kinect, we also need to install
OpenNI and SensorKinect.

[4]

Chapter 1

Let's assume that we have already installed 32-bit Python 2.7, NumPy, and SciPy
either from binaries (as described previously) or from a source. Now, we can
proceed with installing compilers and CMake, optionally installing OpenNI and
SensorKinect, and then building OpenCV from the source:
1. Download and install CMake 3.1.2 from http://www.cmake.org/files/
v3.1/cmake-3.1.2-win32-x86.exe. When running the installer, select
either Add CMake to the system PATH for all users or Add CMake to
the system PATH for current user. Don't worry about the fact that a 64-bit
version of CMake is not available CMake is only a configuration tool and
does not perform any compilations itself. Instead, on Windows, it creates
project files that can be opened with Visual Studio.
2. Download and install Microsoft Visual Studio 2013 (the Desktop edition if
you are working on Windows 7) from https://www.visualstudio.com/
products/free-developer-offers-vs.aspx?slcid=0x409&type=web
or MinGW.

Note that you will need to sign in with your Microsoft account and if you
don't have one, you can create one on the spot. Install the software and
reboot after installation is complete.
For MinGW, get the installer from http://sourceforge.net/projects/
mingw/files/Installer/mingw-get-setup.exe/download and http://
sourceforge.net/projects/mingw/files/OldFiles/mingw-get-inst/
mingw-get-inst-20120426/mingw-get-inst-20120426.exe/download.

When running the installer, make sure that the destination path does not
contain spaces and that the optional C++ compiler is included. Edit the
system's PATH variable and append ;C:\MinGW\bin (assuming that MinGW
is installed to the default location). Reboot the system.
3. Optionally, download and install OpenNI 1.5.4.0 from the links provided in
the GitHub homepage of OpenNI at https://github.com/OpenNI/OpenNI.
4. You can download and install SensorKinect 0.93 from https://github.com/
avin2/SensorKinect/blob/unstable/Bin/SensorKinect093-Bin-Win32v5.1.2.1.msi?raw=true (32-bit). Alternatively, for 64-bit Python, download
the setup from https://github.com/avin2/SensorKinect/blob/
unstable/Bin/SensorKinect093-Bin-Win64-v5.1.2.1.msi?raw=true

(64-bit). Note that this repository has been inactive for more than three years.
5. Download the self-extracting ZIP of OpenCV 3.0.0 from https://github.
com/Itseez/opencv. Run the self-extracting ZIP, and when prompted, enter
any destination folder, which we will refer to as <unzip_destination>. A
subfolder, <unzip_destination>\opencv, is then created.

[5]

Setting Up OpenCV

6. Open Command Prompt and make another folder where our build will go
using this command:
> mkdir<build_folder>

Change the directory of the build folder:

> cd <build_folder>

7. Now, we are ready to configure our build. To understand all the options,
we can read the code in <unzip_destination>\opencv\CMakeLists.txt.
However, for this book's purposes, we only need to use the options that will
give us a release build with Python bindings, and optionally, depth camera
support via OpenNI and SensorKinect.
8. Open CMake (cmake-gui) and specify the location of the source code of
OpenCV and the folder where you would like to build the library. Click on
Configure. Select the project to be generated. In this case, select Visual Studio
12 (which corresponds to Visual Studio 2013). After CMake has finished
configuring the project, it will output a list of build options. If you see a red
background, it means that your project may need to be reconfigured: CMake
might report that it has failed to find some dependencies. Many of OpenCV's
dependencies are optional, so do not be too concerned yet.
If the build fails to complete or you run into problems later,
try installing missing dependencies (often available as prebuilt
binaries), and then rebuild OpenCV from this step.
You have the option of selecting/deselecting build options
(according to the libraries you have installed on your machine) and
click on Configure again, until you get a clear background (white).

9. At the end of this process, you can click on Generate, which will create
an OpenCV.sln file in the folder you've chosen for the build. You can then
navigate to <build_folder>/OpenCV.sln and open the file with Visual
Studio 2013, and proceed with building the project, ALL_BUILD. You will
need to build both the Debug and Release versions of OpenCV, so go ahead
and build the library in the Debug mode, then select Release and rebuild it
(F7 is the key to launch the build).
10. At this stage, you will have a bin folder in the OpenCV build directory,
which will contain all the generated .dll files that will allow you to include
OpenCV in your projects.
Alternatively, for MinGW, run the following command:
> cmake -D:CMAKE_BUILD_TYPE=RELEASE -D:WITH_OPENNI=ON -G
"MinGWMakefiles" <unzip_destination>\opencv
[6]

Chapter 1

If OpenNI is not installed, omit -D:WITH_OPENNI=ON. (In this case, depth

cameras will not be supported.) If OpenNI and SensorKinect are installed
to nondefault locations, modify the command to include -D:OPENNI_
LIB_DIR=<openni_install_destination>\Lib -D:OPENNI_INCLUDE_
DIR=<openni_install_destination>\Include -D:OPENNI_PRIME_
SENSOR_MODULE_BIN_DIR=<sensorkinect_install_destination>\
Sensor\Bin.

Alternatively, for MinGW, run this command:

> mingw32-make

11. Copy <build_folder>\lib\Release\cv2.pyd (from a Visual Studio build)

or <build_folder>\lib\cv2.pyd (from a MinGW build) to <python_
installation_folder>\site-packages.
12. Finally, edit the system's PATH variable and append ;<build_folder>/bin/
Release (for a Visual Studio build) or ;<build_folder>/bin (for a MinGW
build). Reboot your system.

Installing on OS X
Some versions of Mac used to come with a version of Python 2.7 preinstalled that
were customized by Apple for a system's internal needs. However, this has changed
and the standard version of OS X ships with a standard installation of Python. On
python.org, you can also find a universal binary that is compatible with both the
new Intel systems and the legacy PowerPC.
You can obtain this installer at https://www.python.org/
downloads/release/python-279/ (refer to the Mac OS X 32-bit
PPC or the Mac OS X 64-bit Intel links). Installing Python from the
downloaded .dmg file will simply overwrite your current system
installation of Python.

For Mac, there are several possible approaches for obtaining standard Python 2.7,
NumPy, SciPy, and OpenCV. All approaches ultimately require OpenCV to be
compiled from a source using Xcode Developer Tools. However, depending on the
approach, this task is automated for us in various ways by third-party tools. We will
look at these kinds of approaches using MacPorts or Homebrew. These tools can
potentially do everything that CMake can, plus they help us resolve dependencies
and separate our development libraries from system libraries.

[7]

Setting Up OpenCV

I recommend MacPorts, especially if you want to compile OpenCV with

depth camera support via OpenNI and SensorKinect. Relevant patches
and build scripts, including some that I maintain, are ready-made
for MacPorts. By contrast, Homebrew does not currently provide a
ready-made solution to compile OpenCV with depth camera support.

Before proceeding, let's make sure that the Xcode Developer Tools are properly
set up:
1. Download and install Xcode from the Mac App Store or
https://developer.apple.com/xcode/downloads/. During
installation, if there is an option to install Command Line Tools, select it.
2. Open Xcode and accept the license agreement.
3. A final step is necessary if the installer does not give us the option to install
Command Line Tools. Navigate to Xcode | Preferences | Downloads,
and click on the Install button next to Command Line Tools. Wait for the
installation to finish and quit Xcode.
Alternatively, you can install Xcode command-line tools by running the following
command (in the terminal):
$ xcode-select install

Now, we have the required compilers for any approach.

Using MacPorts with ready-made packages

We can use the MacPorts package manager to help us set up Python 2.7, NumPy,
and OpenCV. MacPorts provides terminal commands that automate the process
of downloading, compiling, and installing various pieces of open source software
(OSS). MacPorts also installs dependencies as needed. For each piece of software, the
dependencies and build recipes are defined in a configuration file called a Portfile. A
MacPorts repository is a collection of Portfiles.
Starting from a system where Xcode and its command-line tools are already set up,
the following steps will give us an OpenCV installation via MacPorts:
1. Download and install MacPorts from

http://www.macports.org/install.php.

[8]

Chapter 1

2. If you want support for the Kinect depth camera, you need to tell MacPorts
where to download the custom Portfiles that I have written. To do so, edit
/opt/local/etc/macports/sources.conf (assuming that MacPorts
is installed to the default location). Just above the line, rsync://rsync.
macports.org/release/ports/ [default], add the following line:
http://nummist.com/opencv/ports.tar.gz

Save the file. Now, MacPorts knows that it has to search for Portfiles in my
online repository first, and then the default online repository.
3. Open the terminal and run the following command to update MacPorts:
$ sudo port selfupdate

When prompted, enter your password.

4. Now (if we are using my repository), run the following command to
install OpenCV with Python 2.7 bindings and support for depth cameras,
including Kinect:
$ sudo port install opencv +python27 +openni_sensorkinect

Alternatively (with or without my repository), run the following command

to install OpenCV with Python 2.7 bindings and support for depth cameras,
excluding Kinect:
$ sudo port install opencv +python27 +openni

Dependencies, including Python 2.7, NumPy, OpenNI, and (in the

first example) SensorKinect, are automatically installed as well.
By adding +python27 to the command, we specify that we want
the opencv variant (build configuration) with Python 2.7 bindings.
Similarly, +openni_sensorkinect specifies the variant with
the broadest possible support for depth cameras via OpenNI and
SensorKinect. You may omit +openni_sensorkinect if you do not
intend to use depth cameras, or you may replace it with +openni if
you do intend to use OpenNI-compatible depth cameras but just not
Kinect. To see the full list of the available variants before installing,
we can enter the following command:
$ port variants opencv

Depending on our customization needs, we can add other variants to

the install command. For even more flexibility, we can write our
own variants (as described in the next section).

[9]

Setting Up OpenCV

5. Also, run the following command to install SciPy:

$ sudo port install py27-scipy

6. The Python installation's executable is named python2.7. If we want to link

the default python executable to python2.7, let's also run this command:
$ sudo port install python_select
$ sudo port select python python27

Using MacPorts with your own custom packages

With a few extra steps, we can change the way that MacPorts compiles OpenCV or
any other piece of software. As previously mentioned, MacPorts' build recipes are
defined in configuration files called Portfiles. By creating or editing Portfiles, we can
access highly configurable build tools, such as CMake, while also benefitting from
MacPorts' features, such as dependency resolution.
Let's assume that we already have MacPorts installed. Now, we can configure
MacPorts to use the custom Portfiles that we write:
1. Create a folder somewhere to hold our custom Portfiles. We will refer to this
folder as <local_repository>.
2. Edit the /opt/local/etc/macports/sources.conf file (assuming that
MacPorts is installed to the default location). Just above the rsync://rsync.
macports.org/release/ports/ [default] line, add this line:
file://<local_repository>

For example, if <local_repository> is /Users/Joe/Portfiles, add the

following line:
file:///Users/Joe/Portfiles

Note the triple slashes and save the file. Now, MacPorts knows that it has
to search for Portfiles in <local_repository> first, and then, its default
online repository.
3. Open the terminal and update MacPorts to ensure that we have the latest
Portfiles from the default repository:
$ sudo port selfupdate

[ 10 ]

Chapter 1

4. Let's copy the default repository's opencv Portfile as an example. We should

also copy the directory structure, which determines how the package is
categorized by MacPorts:
$ mkdir <local_repository>/graphics/
$ cp /opt/local/var/macports/sources/rsync.macports.org/release/
ports/graphics/opencv <local_repository>/graphics

Alternatively, for an example that includes Kinect support, we could download

my online repository from http://nummist.com/opencv/ports.tar.gz,
unzip it, and copy its entire graphics folder into <local_repository>:
$ cp <unzip_destination>/graphics <local_repository>

5. Edit <local_repository>/graphics/opencv/Portfile. Note that this

file specifies the CMake configuration flags, dependencies, and variants.
For details on the Portfile editing, go to http://guide.macports.
org/#development.
To see which CMake configuration flags are relevant to OpenCV, we
need to look at its source code. Download the source code archive from
https://github.com/Itseez/opencv/archive/3.0.0.zip, unzip it to any
location, and read <unzip_destination>/OpenCV-3.0.0/CMakeLists.txt.
After making any edits to the Portfile, save it.
6. Now, we need to generate an index file in our local repository so that
MacPorts can find the new Portfile:
$ cd <local_repository>
$ portindex

7. From now on, we can treat our custom opencv file just like any other
MacPorts package. For example, we can install it as follows:
$ sudo port install opencv +python27 +openni_sensorkinect

Note that our local repository's Portfile takes precedence over the default
repository's Portfile because of the order in which they are listed in /opt/
local/etc/macports/sources.conf.

[ 11 ]

Setting Up OpenCV

Using Homebrew with ready-made packages (no

support for depth cameras)
Homebrew is another package manager that can help us. Normally, MacPorts and
Homebrew should not be installed on the same machine.
Starting from a system where Xcode and its command-line tools are already set up,
the following steps will give us an OpenCV installation via Homebrew:
1. Open the terminal and run the following command to install Homebrew:
$ ruby -e "$(curl -fsSkLraw.github.com/mxcl/homebrew/go)"

2. Unlike MacPorts, Homebrew does not automatically put its executables in

PATH. To do so, create or edit the ~/.profile file and add this line at the top
of the code:
export PATH=/usr/local/bin:/usr/local/sbin:$PATH

Save the file and run this command to refresh PATH:

$ source ~/.profile

Note that executables installed by Homebrew now take precedence over

executables installed by the system.
3. For Homebrew's self-diagnostic report, run the following command:
$ brew doctor

Follow any troubleshooting advice it gives.

4. Now, update Homebrew:
$ brew update

5. Run the following command to install Python 2.7:

$ brew install python

6. Now, we can install NumPy. Homebrew's selection of the Python library

packages is limited, so we use a separate package management tool called
pip, which comes with Homebrew's Python:
$ pip install numpy

7. SciPy contains some Fortran code, so we need an appropriate compiler. We

can use Homebrew to install the gfortran compiler:
$ brew install gfortran

Now, we can install SciPy:

$ pip install scipy
[ 12 ]

Chapter 1

8. To install OpenCV on a 64-bit system (all new Mac hardware since late 2006),
run the following command:
$ brew install opencv

Downloading the example code

You can download the example code files for all Packt Publishing
books that you have purchased from your account at http://www.
packtpub.com. If you purchased this book elsewhere, you can visit
http://www.packtpub.com/support and register to have the
files e-mailed directly to you.

Using Homebrew with your own custom packages

Homebrew makes it easy to edit existing package definitions:
$ brew edit opencv

The package definitions are actually scripts in the Ruby programming language. Tips
on editing them can be found on the Homebrew Wiki page at https://github.com/
mxcl/homebrew/wiki/Formula-Cookbook. A script may specify Make or CMake
configuration flags, among other things.
To see which CMake configuration flags are relevant to OpenCV, we need to look
at its source code. Download the source code archive from https://github.com/
Itseez/opencv/archive/3.0.0.zip, unzip it to any location, and read
<unzip_destination>/OpenCV-2.4.3/CMakeLists.txt.
After making edits to the Ruby script, save it.
The customized package can be treated as normal. For example, it can be installed
as follows:
$ brew install opencv

Installation on Ubuntu and its derivatives

First and foremost, here is a quick note on Ubuntu's versions of an operating
system: Ubuntu has a 6-month release cycle in which each release is either a .04 or
a .10 minor version of a major version (14 at the time of writing). Every two years,
however, Ubuntu releases a version classified as long-term support (LTS) which will
grant you a five year support by Canonical (the company behind Ubuntu). If you
work in an enterprise environment, it is certainly advisable to install one of the LTS
versions. The latest one available is 14.04.

[ 13 ]

Setting Up OpenCV

Ubuntu comes with Python 2.7 preinstalled. The standard Ubuntu repository
contains OpenCV 2.4.9 packages without support for depth cameras. At the time
of writing this, OpenCV 3 is not yet available through the Ubuntu repositories, so
we will have to build it from source. Fortunately, the vast majority of Unix-like and
Linux systems come with all the necessary software to build a project from scratch
already installed. When built from source, OpenCV can support depth cameras
via OpenNI and SensorKinect, which are available as precompiled binaries with
installation scripts.

Using the Ubuntu repository (no support for depth

cameras)
We can install Python and all its necessary dependencies using the apt package
manager, by running the following commands:
> sudo apt-get install build-essential
> sudo apt-get install cmake git libgtk2.0-dev pkg-config libavcodecdev
libavformat-dev libswscale-dev
> sudo apt-get install python-dev python-numpy libtbb2 libtbb-dev
libjpeg-dev libpng-dev libtiff-dev libjasper-dev libdc1394-22-dev

Equivalently, we could have used Ubuntu Software Center, which is the apt package
manager's graphical frontend.

Building OpenCV from a source

Now that we have the entire Python stack and cmake installed, we can build
OpenCV. First, we need to download the source code from https://github.com/
Itseez/opencv/archive/3.0.0-beta.zip.
Extract the archive and move it into the unzipped folder in a terminal.
Then, run the following commands:
> mkdir build
> cd build
> cmake -D CMAKE_BUILD_TYPE=Release -D
CMAKE_INSTALL_PREFIX=/usr/local ..
> make
> make install

After the installation terminates, you might want to look at OpenCV's Python
samples in <opencv_folder>/opencv/samples/python and <script_folder>/
opencv/samples/python2.
[ 14 ]

Chapter 1

Installation on other Unix-like systems

The approaches for Ubuntu (as described previously) are likely to work on any
Linux distribution derived from Ubuntu 14.04 LTS or Ubuntu 14.10 as follows:

Kubuntu 14.04 LTS or Kubuntu 14.10

Xubuntu 14.04 LTS or Xubuntu 14.10

Linux Mint 17

On Debian Linux and its derivatives, the apt package manager works the same as on
Ubuntu, though the available packages may differ.
On Gentoo Linux and its derivatives, the Portage package manager is similar to
MacPorts (as described previously), though the available packages may differ.
On FreeBSD derivatives, the process of installation is again similar to MacPorts;
in fact, MacPorts derives from the ports installation system adopted on FreeBSD.
Consult the remarkable FreeBSD Handbook at https://www.freebsd.org/doc/
handbook/ for an overview of the software installation process.
On other Unix-like systems, the package manager and available packages may
differ. Consult your package manager's documentation and search for packages with
opencv in their names. Remember that OpenCV and its Python bindings might be
split into multiple packages.
Also, look for any installation notes published by the system provider, the repository
maintainer, or the community. Since OpenCV uses camera drivers and media codecs,
getting all of its functionality to work can be tricky on systems with poor multimedia
support. Under some circumstances, system packages might need to be reconfigured
or reinstalled for compatibility.
If packages are available for OpenCV, check their version number. OpenCV 3 or
higher is recommended for this book's purposes. Also, check whether the packages
offer Python bindings and depth camera support via OpenNI and SensorKinect.
Finally, check whether anyone in the developer community has reported success or
failure in using the packages.
If, instead, we want to do a custom build of OpenCV from source, it might be helpful
to refer to the installation script for Ubuntu (as discussed previously) and adapt it to
the package manager and packages that are present on another system.

[ 15 ]

Setting Up OpenCV

Installing the Contrib modules

Unlike with OpenCV 2.4, some modules are contained in a repository called opencv_
contrib, which is available at https://github.com/Itseez/opencv_contrib. I
highly recommend installing these modules as they contain extra functionalities that
are not included in OpenCV, such as the face recognition module.
Once downloaded (either through zip or git, I recommend git so that you can keep
up to date with a simple git pull command), you can rerun your cmake command
to include the building of OpenCV with the opencv_contrib modules as follows:
cmake -DOPENCV_EXTRA_MODULES_PATH=<opencv_contrib>/modules <opencv_
source_directory>

So, if you've followed the standard procedure and created a build directory in your
OpenCV download folder, you should run the following command:
mkdir build && cd build
cmake -D CMAKE_BUILD_TYPE=Release -DOPENCV_EXTRA_MODULES_PATH=<opencv_
contrib>/modules -D CMAKE_INSTALL_PREFIX=/usr/local ..
make

Running samples
Running a few sample scripts is a good way to test whether OpenCV is correctly set
up. The samples are included in OpenCV's source code archive.
On Windows, we should have already downloaded and unzipped OpenCV's
self-extracting ZIP. Find the samples in <unzip_destination>/opencv/samples.
On Unix-like systems, including Mac, download the source code archive from
https://github.com/Itseez/opencv/archive/3.0.0.zip and unzip it to
any location (if we have not already done so). Find the samples in <unzip_
destination>/OpenCV-3.0.0/samples.

[ 16 ]

Chapter 1

Some of the sample scripts require command-line arguments. However, the

following scripts (among others) should work without any arguments:

python/camera.py: This script displays a webcam feed (assuming that a

webcam is plugged in).

python/drawing.py: This script draws a series of shapes, such as

python2/hist.py: This script displays a photo. Press A, B, C, D, or E to see

the variations of the photo along with a corresponding histogram of color or
grayscale values.

python2/opt_flow.py (missing from the Ubuntu package): This script

a screensaver.

displays a webcam feed with a superimposed visualization of an optical flow

(such as the direction of motion). For example, slowly wave your hand at the
webcam to see the effect. Press 1 or 2 for alternative visualizations.

To exit a script, press Esc (not the window's close button).

If we encounter the ImportError: No module named cv2.cv message, then this
means that we are running the script from a Python installation that does not know
anything about OpenCV. There are two possible explanations for this:

Some steps in the OpenCV installation might have failed or been missed.
Go back and review the steps.

If we have multiple Python installations on the machine, we might be using

the wrong version of Python to launch the script. For example, on Mac, it
might be the case that OpenCV is installed for MacPorts Python, but we
are running the script with the system's Python. Go back and review the
installation steps about editing the system path. Also, try launching the
script manually from the command line using commands such as this:
$ python python/camera.py

You can also use the following command:

$ python2.7 python/camera.py

As another possible means of selecting a different Python installation,

try editing the sample script to remove the #! lines. These lines might
explicitly associate the script with the wrong Python installation
(for our particular setup).

[ 17 ]

Setting Up OpenCV

Finding documentation, help, and

updates
OpenCV's documentation can be found online at http://docs.opencv.org/. The
documentation includes a combined API reference for OpenCV's new C++ API, its
new Python API (which is based on the C++ API), old C API, and its old Python API
(which is based on the C API). When looking up a class or function, be sure to read
the section about the new Python API (the cv2 module), and not the old Python API
(the cv module).
The documentation is also available as several downloadable PDF files:

API reference: This documentation can be found at http://docs.opencv.

org/modules/refman.html

Tutorials: These documents can be found at http://docs.opencv.org/

doc/tutorials/tutorials.html (these tutorials use the C++ code; for a
Python port of the tutorials' code, see the repository of Abid Rahman K. at
http://goo.gl/EPsD1)

If you write code on airplanes or other places without Internet access, you will
definitely want to keep offline copies of the documentation.
If the documentation does not seem to answer your questions, try talking to the
OpenCV community. Here are some sites where you will find helpful people:

The OpenCV forum: http://www.answers.opencv.org/questions/

David Milln Escriv's blog (one of this book's reviewers): http://blog.
damiles.com/

Abid Rahman K.'s blog (one of this book's reviewers): http://www.

opencvpython.blogspot.com/

Adrian Rosebrock's website (one of this book's reviewers): http://www.

pyimagesearch.com/

Joe Minichino's website for this book (author of this book): http://
techfort.github.io/pycv/

Joe Howse's website for this book (author of the first edition of this book):
http://nummist.com/opencv/

Lastly, if you are an advanced user who wants to try new features, bug fixes, and
sample scripts from the latest (unstable) OpenCV source code, have a look at the
project's repository at https://github.com/Itseez/opencv/.

[ 18 ]

Chapter 1

Summary
By now, we should have an OpenCV installation that can do everything we need for
the project described in this book. Depending on which approach we took, we might
also have a set of tools and scripts that are usable to reconfigure and rebuild OpenCV
for our future needs.
We know where to find OpenCV's Python samples. These samples covered a
different range of functionalities outside this book's scope, but they are useful as
additional learning aids.
In the next chapter, we will familiarize ourselves with the most basic functions of
the OpenCV API, namely, displaying images, videos, capturing videos through a
webcam, and handling basic keyboard and mouse inputs.

[ 19 ]

Get more information Learning OpenCV 3 Computer Vision with Python

Second Edition

Where to buy this book

You can buy Learning OpenCV 3 Computer Vision with Python Second Edition from the
Packt Publishing website.
Alternatively, you can buy the book from Amazon, BN.com, Computer Manuals and most internet
book retailers.
Click here for ordering and shipping details.

www.PacktPub.com

Stay Connected: