As I mentioned last week, OpenCV 3.0 is finally here!
And if you’ve been paying attention to my Twitter stream, you may have noticed a bunch of tweets regarding installing OpenCV on OSX and Ubuntu (yep, I’ve been tweeting a lot lately, but that’s just because I’m so excited about the 3.0 release!)
To celebrate OpenCV 3.0, I have decided to perform a series of blog posts that detail how to install OpenCV 3.0 on both Python 2.7+ and Python 3+.
We’ll also be performing these Python 2.7 and Python 3+ installations on a variety of platforms including OSX, Ubuntu, and yes, the Raspberry Pi.
As I’m sure you already know, OpenCV has never been an effortless library to install. It’s not like you can let pip
or easy_install
to the heavy-lifting for you. In most cases you’ll be pulling down the repo, installing prerequisites, compiling by hand, and hoping that your installation goes smoothly.
With OpenCV 3.0 it doesn’t get any easier — and there are definitely some caveats and gotchas that you need to look out for (such as the opencv_contrib repository — without it, you’ll be missing out on some important features, such as SIFT, SURF, etc.)
But don’t worry, I’ve got you covered! Just keep following along with the PyImageSearch blog and I promise these tutorials will get you up and running with OpenCV 3.0 in no time.
We’ll go ahead and kick-off our OpenCV 3.0 install fest by installing v3.0 with Python 2.7+ bindings on the OSX platform.
If you’re an Ubuntu or Raspberry Pi user, be sure to keep an eye on PyImageSearch as I’ll be posting OpenCV 3.0 install instructions for Ubuntu and the Raspberry Pi as well.
A quick note before we get started: While OpenCV 3.0 is indeed compatible with Python 3+, most computer vision developers are still using Python 2.7 (since OpenCV 2.4.X is only compatible with Python 2.7). If you’re a Python 3 user and excited to give the bindings a try — don’t worry! I’ll be covering OpenCV 3.0 and Python 3+ installation in a future tutorial. But for now, let’s stick with what we know and use Python 2.7.
UPDATE: The tutorial you are reading now covers how to install OpenCV 3.0 with Python 2.7 bindings on OSX Yosemite and below. This tutorial still works perfectly if you are using OSX Yosemite or prior, but if you want to install OpenCV on the newer El Capitan and macOS Sierra please use this freshly updated tutorial.
How to Install OpenCV 3.0 and Python 2.7+ on OSX
This is our first tutorial in our OpenCV 3.0 install-fest series. In this tutorial I’ll be detailing how to install OpenCV 3.0 and Python 2.7+ on the OSX operating system — I’ll be covering Python 3+ in a future post.
Let’s go ahead and dive into the OpenCV 3.0 and Python 2.7+ install instructions.
Step 1:
The first step we need to do is install Xcode, which is a combination of IDE and software development tools for developing applications on the OSX and iOS platforms — most of us already have Xcode installed.
But if you don’t, you’ll want to open up the App Store application and search for Xcode. From there, just click Get and Install App (and when prompted, you’ll need to enter your Apple ID username and password):
Step 2:
Now that Xcode is installed, we need to install Homebrew, which is labeled as “The missing package manager for OSX” (and they really are not joking about that one). Think of Homebrew as an (almost) equivalent of apt-get for Ubuntu.
To install Homebrew, simply head to the Homebrew website and simply copy and paste the command underneath the “Install Homebrew” section into your terminal:
$ cd ~ $ $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Now that Homebrew is installed, you’ll need to update it and grab the latest package (i.e. “formula”) definitions. These formula are simply instructions on how to install a given package or library.
To update Homebrew, simply execute:
$ brew update
Step 3:
It’s bad form to use the system Python as your main interpreter. And this is especially true if you intend on using virtualenv
and virtualenvwrapper
(which we will be).
Let’s go ahead and use Homebrew to install our user-specific version of Python 2.7:
$ brew install python
Note: This tutorial will be covering how to install and setup OpenCV 3.0 with Python 2.7. I will be covering how to install OpenCV 3.0 with Python 3+ later this month.
However, before we proceed, we need to update our PATH
in our ~/.bash_profile
file to indicate that we want to use Homebrew packages before any system libraries or packages. This is an absolutely critical step, so be sure not to skip it!
Open up your ~/.bash_profile
file in your favorite editor (if it does not exist, create it), and append the following lines to the file:
# Homebrew export PATH=/usr/local/bin:$PATH
From there, reload your ~./bash_profile
file to ensure the changes have been made:
$ source ~/.bash_profile
As a sanity check, let’s confirm that we are using the Homebrew version of Python rather than the system one:
$ which python /usr/local/bin/python
If your output of which python
is /usr/local/bin/python
, then you are indeed using the Homebrew version of Python. And if your output is /usr/bin/python
, then you are still using the system version of Python — and you need to go back and ensure that your ~/.bash_profile
file is updated and reloaded correctly.
Again, this is a very important step, so be sure not to skip it!
Step 4:
Alright, time to get virtualenv and virtualenvwrapper installed and configured correctly. These packages allow us to create separate Python environments for each project we are working on. This is especially useful if you have projects that require different (or conflicting) versions of a given library.
It’s important to note that virtualenv
and virtualenvwrapper
are by no means required to install OpenCV 3.0 and Python 2.7+ on OSX. However, you really should be using these packages when doing Python development. It’s cleaner. Easier to maintain. And well worth the upfront effort.
Anyway, to install virtualenv
and virtualenvwrapper
, just execute the following command:
$ pip install virtualenv virtualenvwrapper
Again, we need to update our ~/.bash_profile
file by appending the following two lines:
# Virtualenv/VirtualenvWrapper source /usr/local/bin/virtualenvwrapper.sh
After updating the ~/.bash_profile
file, we need to reload it:
$ source ~/.bash_profile
At this point, both virtualenv
and virtualenvwrapper
are installed correctly, so we can create our cv
virtual environment:
$ mkvirtualenv cv
This command will create a new Python environment that is entirely sequestered from our system and Homebrew Python installations. The cv
virtual environment is where we’ll be doing all of our computer vision development (and not to mention, compiling OpenCV 3.0 with Python 2.7+ support).
Step 5:
Now we can start installing some Python packages. We need to install NumPy since the OpenCV Python bindings represent images as multi-dimensional NumPy arrays:
$ pip install numpy
Step 6:
Up until this point we have been mainly focusing on actually setting up and configuring our development environment to compile and install OpenCV — here is where the real work starts.
First, we’ll use brew to install the required developers tools, such as the wonderful CMake utility:
$ brew install cmake pkg-config
And here we are going to install the necessary image I/O packages. These packages allow you to load various image file formats such as JPEG, PNG, TIFF, etc.
$ brew install jpeg libpng libtiff openexr
And finally, let’s install libraries that are used to optimize various operations within OpenCV (if we so choose):
$ brew install eigen tbb
Step 7:
Alright, our system is all setup — time to compile and install OpenCV 3.0 with Python 2.7+ support.
The first thing we’ll do is change directory to our home directory, followed by pulling down OpenCV from GitHub, and checking out the 3.0.0
version:
$ cd ~ $ git clone https://github.com/Itseez/opencv.git $ cd opencv $ git checkout 3.0.0
Update (3 January 2016): You can replace the 3.0.0
version with whatever the current release is (as of right now, it’s 3.1.0
). Be sure to check OpenCV.org for information on the latest release.
Unlike previous versions of OpenCV that were (essentially) self-contained, we need to pull down the extra opencv_contrib repo from GitHub as well. The opencv_contrib
repo which contains extra modules for OpenCV, such as feature detection, local invariant descriptors (SIFT, SURF, etc.), text detection in natural images, line descriptors, and more.
$ cd ~ $ git clone https://github.com/Itseez/opencv_contrib $ cd opencv_contrib $ git checkout 3.0.0
Again, make sure that you checkout the same version for opencv_contrib
that you did for opencv
above, otherwise you could run into compilation errors.
Note: We don’t have to pull down the opencv_contrib
repo if we don’t want to. OpenCV will compile and install just fine without it. But if you compile OpenCV without opencv_contrib
, be warned that you’ll be missing out on some pretty important features, which will become very obvious, very fast, especially if you’re used to working with the 2.4.X version of OpenCV.
Step 8:
Let’s setup our OpenCV build by creating the build
directory:
$ cd ~/opencv $ mkdir build $ cd build
Where we’ll use CMake to configure our build:
$ cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local \ -D PYTHON2_PACKAGES_PATH=~/.virtualenvs/cv/lib/python2.7/site-packages \ -D PYTHON2_LIBRARY=/usr/local/Cellar/python/2.7.10/Frameworks/Python.framework/Versions/2.7/bin \ -D PYTHON2_INCLUDE_DIR=/usr/local/Frameworks/Python.framework/Headers \ -D INSTALL_C_EXAMPLES=ON -D INSTALL_PYTHON_EXAMPLES=ON \ -D BUILD_EXAMPLES=ON \ -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules ..
There are some very important options we are supplying to CMake here, so let’s break them down:
CMAKE_BUILD_TYPE
: This option indicates that we are building a release binary of OpenCV.CMAKE_INSTALL_PREFIX
: The base directory where OpenCV will be installed.PYTHON2_PACKAGES_PATH
: The explicit path to where oursite-packages
directory lives in ourcv
virtual environment.PYTHON2_LIBRARY
: Path to our Hombrew installation of Python.PYTHON2_INCLUDE_DIR
: The path to our Python header files for compilation.INSTALL_C_EXAMPLES
: Indicate that we want to install the C/C++ examples after compilation.INSTALL_PYTHON_EXAMPLES
: Indicate that we want to install the Python examples after complication.BUILD_EXAMPLES
: A flag that determines whether or not the included OpenCV examples will be compiled or not.OPENCV_EXTRA_MODULES_PATH
: This option is extremely important — here we supply the path to theopencv_contrib
repo that we pulled down earlier, indicating that OpenCV should compile the extra modules as well.
Update (3 January 2016): In order to build OpenCV 3.1.0
, you need to set -D INSTALL_C_EXAMPLES=OFF
(rather than ON
) in the cmake
command. There is a bug in the OpenCV v3.1.0 CMake build script that can cause errors if you leave this switch on. Once you set this switch to off, CMake should run without a problem.
Whew, that was a lot of options.
Trust me, it’s a lot easier installing OpenCV 3.0 on Ubuntu where these options are automatically determined via CMake for us.
But when using OSX you’ll need to explicitly define the PYTHON2_PACKAGES_PATH
, PYTHON2_LIBRARY
, and PYTHON2_INCLUDE_DIR
yourself. It’s a real pain, but if you don’t, your compile will fail.
Here’s an example of what my CMake output looks like:
Notice how the Python 2 Interpreter, Libraries, numpy version, and packages path have been correctly picked up.
You’ll also want to make sure that python2
is in the list of modules To be built, like this:
If it python2
is not in this list, and is in the Unavailable list, then you need to go back to the CMake step and ensure that you have correctly supplied your PYTHON2_PACKAGES_PATH
, PYTHON2_LIBRARY
, and PYTHON2_INCLUDE_DIR
.
Now that CMake has properly configured the build, we can compile OpenCV:
$ make -j4
Where the 4 can be replaced with however many cores you have available on your processor. Here’s an example of OpenCV compiling on my system:
And assuming that OpenCV compiled without error, you can now install it on your OSX system:
$ make install
If you get an error message related to permissions (although that really shouldn’t happen), you’ll need to run the install command as sudo
:
$ sudo make install
Step 9:
Assuming you’ve made it this far, let’s perform a sanity check and ensure OpenCV is installed:
$ cd ~/.virtualenvs/cv/lib/python2.7/site-packages/ $ ls -l cv2.so -rwxr-xr-x 1 adrian staff 2013052 Jun 5 15:20 cv2.so
Sure enough, we can see that OpenCV has been installed in our cv
virtual environment’s site-packages
directory!
As a quick note, you’ll be able to find the cv2.so
file (which is your OpenCV bindings) in your build/lib
directory as well.
Let’s verify our install by firing up a shell and importing OpenCV:
(cv)annalee:~ adrianrosebrock$ python Python 2.7.8 (default, Jul 31 2014, 15:41:09) [GCC 4.2.1 Compatible Apple LLVM 5.1 (clang-503.0.40)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import cv2 >>> cv2.__version__ '3.0.0'
Doesn’t that 3.0.0
look nice?
Congrats, you have now installed OpenCV 3.0 and Python 2.7+ on your OSX system!
Step 10:
After all this work, let’s give our OpenCV 3.0 install a test drive!
Most of my work in computer vision involves image search engines, or more formally, Content-based Image Retrieval. A critical step of CBIR is extracting features to quantify and abstractly represent the contents of an image.
OpenCV 3.0 has numerous updates and changes, but perhaps my personal favorite is an implementation of AKAZE features — Fast Explicit Diffusion for Accelerated Features in Nonlinear Scale Spaces by Alcantarilla et al.
Since Jurassic World was just released (and Jurassic Park is my favorite movie of all time), let’s explore how we can compute and extract AKAZE features from the following image:
Open up a new file, name it test_akaze.py
, and insert the following code:
# import the necessary packages from __future__ import print_function import cv2 # load the image and convert it to grayscale image = cv2.imread("jurassic_world.jpg") gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) cv2.imshow("Original", image) # initialize the AKAZE descriptor, then detect keypoints and extract # local invariant descriptors from the image detector = cv2.AKAZE_create() (kps, descs) = detector.detectAndCompute(gray, None) print("keypoints: {}, descriptors: {}".format(len(kps), descs.shape)) # draw the keypoints and show the output image cv2.drawKeypoints(image, kps, image, (0, 255, 0)) cv2.imshow("Output", image) cv2.waitKey(0)
And then execute it via:
$ python test_akaze.py keypoints: 762, descriptors: (762, 61)
Assuming you have download the jurassic_world.jpg
image and placed it in the same directory as your test_akaze.py
script, you should see the following output:
Notice how we have been able to detect keypoints and extract AKAZE features in our image!
Obviously we need to do a lot more work than this to build a useful project using AKAZE features — but this example demonstrates that (1) our OpenCV 3.0 install is working, and (2) we are able to use a unique OpenCV 3.0 feature using Python 2.7.
What's next? I recommend PyImageSearch University.
30+ total classes • 39h 44m video • Last updated: 12/2021
★★★★★ 4.84 (128 Ratings) • 3,000+ Students Enrolled
I strongly believe that if you had the right teacher you could master computer vision and deep learning.
Do you think learning computer vision and deep learning has to be time-consuming, overwhelming, and complicated? Or has to involve complex mathematics and equations? Or requires a degree in computer science?
That’s not the case.
All you need to master computer vision and deep learning is for someone to explain things to you in simple, intuitive terms. And that’s exactly what I do. My mission is to change education and how complex Artificial Intelligence topics are taught.
If you're serious about learning computer vision, your next stop should be PyImageSearch University, the most comprehensive computer vision, deep learning, and OpenCV course online today. Here you’ll learn how to successfully and confidently apply computer vision to your work, research, and projects. Join me in computer vision mastery.
Inside PyImageSearch University you'll find:
- ✓ 30+ courses on essential computer vision, deep learning, and OpenCV topics
- ✓ 30+ Certificates of Completion
- ✓ 39h 44m on-demand video
- ✓ Brand new courses released every month, ensuring you can keep up with state-of-the-art techniques
- ✓ Pre-configured Jupyter Notebooks in Google Colab
- ✓ Run all code examples in your web browser — works on Windows, macOS, and Linux (no dev environment configuration required!)
- ✓ Access to centralized code repos for all 500+ tutorials on PyImageSearch
- ✓ Easy one-click downloads for code, datasets, pre-trained models, etc.
- ✓ Access on mobile, laptop, desktop, etc.
Summary
OpenCV 3.0 is finally here! And to celebrate the OpenCV 3.0 release, we are going to performing an OpenCV 3.0 install-fest for both Python 2.7+ and Python 3+ on a variety of operating systems including OSX, Ubuntu, and the Raspberry Pi!
This article kicked-off the install fest by detailing how to setup and install OpenCV 3.0 and Python 2.7+ on the OSX operating system.
Next week, we’ll be moving over to Ubuntu and detailing the instructions to get OpenCV 3.0 and Python 2.7 installed on Ubuntu 14.04+ (hint: it’s much easier than OSX).
Anyway, I hope you enjoyed this post and found it useful!
Please consider subscribing to the PyImageSearch Newsletter by entering your email address in the form below — I’ll be sending out updates as new OpenCV 3.0 + Python install instructions are released!
Join the PyImageSearch Newsletter and Grab My FREE 17-page Resource Guide PDF
Enter your email address below to join the PyImageSearch Newsletter and download my FREE 17-page Resource Guide PDF on Computer Vision, OpenCV, and Deep Learning.