Install OpenCV 4.0.1 from Source on MacOS with Anaconda Python 3.7 to Use SIFT and SURF

By default, OpenCV and opencv-python don’t include non-free algorithms like SIFT and SURF. Instead, we need to install it with contrib modules and from source. This tutorial combines PyImageSearch (Adrian Rosebrock)’s MacOS installation guide and Rob Williams’s Anaconda addendum. The difference is that we use Python 3.7, which is now the only option for Anaconda new installs.

0. Install MacOS Build Tools with Xcode (Adrian Rosebrock)

First of all, to build almost anything on any OS, one needs to install OS-specific tools. For MacOS, it’s through Xcode. Before anything else, you need to download Xcode from Apple. When the download finishes, open up Terminal and enter

sudo xcodebuild -license

This is to accept the user agreement for Xcode. You can either manually scroll all the way down or go straight to the bottom by hitting q. To accept, type “accept.”

After that, install things like make, gcc, and clang with

sudo xcode-select --install

1. Install Build Tools with Homebrew

The very first step is to install and upgrade Homebrew, a package manager (think apt in Ubuntu) for MacOS.

To install brew, here’s the current official instructions:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

After installation, it is customary to update Homebrew with

brew update

If you can’t get brew to work, you may need to include the path in your ~/.bash_profile by using

nano ~/.bash_profile # or vim ~/.bash_profile

and adding

# Homebrew
export PATH=/usr/local/bin:$PATH

to the bottom of the file. When you are done, do

source ~/.bash_profile

to apply the changes to the terminal, reinitialize it by

source ~/.bash_profile

2. Download OpenCV and OpenCV-Contrib 4.0.1 release source code

You can download Github project source codes under project/releases. For OpenCV and OpenCV-Contrib (important for SIFT and SURF features), it’s https://github.com/opencv/opencv/releases and https://github.com/opencv/opencv_contrib/releases. The current stable version is 4.0.1, and you can download either the .zip version or the .tar.gz version. I believe MacOS can unzip both with double clicking.

After unzipping them, rename the folders to opencv and opencv_contrib, respectively, stripping the version strings just to make things easier.

Then move both folders to your home folder. For example, if using Terminal,

mv ~/Downloads/opencv ~/
mv ~/Downloads/opencv_contrib ~/

3. Create a new Anaconda Environment for Using OpenCV

I’m one of those people who wants everything under the base Anaconda environment. However, when I build things from source, a lot of things can go wrong and mess that up. With a dedicated environment, however, it’s much easier to clean up. To create a new environment called “cv”, do

conda create --name cv python=3.7.2 numpy=1.16.2 # NEED NumPy
conda activate cv # or source activate cv

Then go to the opencv folder:

cd ~/opencv

4. Build Install Files with CMake and Make

Depending on your Anaconda installation, your Anaconda path may differ from mine. Most likely, you either have a single-user installation where the path is ~/anaconda3, or a global one with /anaconda3. To make it easier for you, let’s set that to a variable so you can change all of it in one line:

export CONDA_HOME=~/anaconda3 # if user. For global, /anaconda3
export CPLUS_INCLUDE_PATH=$CONDA_HOME/envs/cv/lib/python3.7
cmake -D CMAKE_BUILD_TYPE=RELEASE \
    -D CMAKE_INSTALL_PREFIX=/usr/local \
    -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \
    -D PYTHON3_LIBRARY=$CONDA_HOME/envs/cv/lib/libpython3.7m.dylib \
    -D PYTHON3_INCLUDE_DIR=$CONDA_HOME/envs/cv/include/python3.7m \
    -D PYTHON3_EXECUTABLE=$CONDA_HOME/envs/cv/bin/python \
    -D PYTHON3_PACKAGES_PATH=$CONDA_HOME/envs/cv/lib/python3.7/site-packages \
    -D BUILD_opencv_python2=OFF \
    -D BUILD_opencv_python3=ON \
    -D INSTALL_PYTHON_EXAMPLES=ON \
    -D INSTALL_C_EXAMPLES=OFF \
    -D OPENCV_ENABLE_NONFREE=ON \ # this enables SIFT, SURF, et al
    -D BUILD_EXAMPLES=ON .. # yes the dots are real

This outputs all the installation file targets. Then we actually build these files

make -j4 # the number 4 is the number of CPU cores. If you have
# 2 cores, you'd do make -j2. If you got that maxed-out iMac Pro,
# go nuts with make -j18.

5. Actually Install the Files

Now simply do

sudo make install

you should be all set! No need to create symlinks like Rob Williams suggests.

6. Test Our Installation

Vassar College library. Copyright unknown.

If we can run the nonfree SURF feature detection on an image, we can prove that we installed OpenCV correctly. First, let’s install matplotlib (plotting library) in our cv environment:

conda activate cv # or source activate cv
conda install matplotlib

Then, to avoid a pesky MacOS/matplotlib error that arises from using matplotlib in Terminal, we manually configure the matplotlib backend:

echo "backend: TkAgg" >> ~/.matplotlib/matplotlibrc

Then run this file in the cv environment:

# ~/Downloads/opencv_test.py
import cv2
import matplotlib.pyplot as plt
img_fname = 'vassar.jpg' # assuming this is where you 
# downloaded the above image
# load image
img = cv2.imread(img_fname)
if img is None:
  raise ValueError('{} is not a file'.format(img_fname))
# convert to grayscale
img_gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
# instantiate SURF
surf = cv2.xfeatures2d.SURF_create(7000)
# compute keypoints
keypoints = surf.detect(img_gray, None)
# plot keypoints
img_keypoints = cv2.drawKeypoints(img, keypoints, img, flags=cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS)
img_keypoints_rgb = cv2.cvtColor(img_keypoints, cv2.COLOR_BGR2RGB)
plt.imshow(img_keypoints_rgb)
plt.show()

After running it with

cd ~/Downloads
conda activate cv # or source activate cv
python opencv_test.py

, you should see something like this:

Result of running SURF on previous image

7. Conclusion

Does it work for you? Please let me know in the comments.