By far the easiest way to install the SimpleCV framework on Windows is by using the Windows Superpack. Clicking the latest stable release link from http://www.simplecv.org/download/ will download the Superpack from http://sourceforge.net. Simply download the Superpack and follow the instructions. In addition to the basic installation, it will also check for and download any missing dependencies. The following are the required dependencies:

The installation creates a SimpleCV program group under the Start menu. This includes a link to start the SimpleCV interactive Python shell and a link to access the program documentation. The majority of the examples in this book can be run using the SimpleCV shell. More details regarding the shell are covered in the SimpleCV shell section of this chapter.

The Mac installation follows a template similar to the Windows approach. From the SimpleCV download page, click the latest stable release link. It will go to SourceForge.net and begin downloading the installation Superpack. This package will handle the installation of the SimpleCV framework and its major dependencies. The list of dependencies is the same as it is for Windows:

Because the SimpleCV framework integrates with Python, the Superpack installs files in places other than the Applications directory. It will also install binary dependencies in /usr/local, and Python libraries in /Library/Python2.7.

The easiest way to work with the examples below is from the Python shell. Once the SimpleCV framework is installed, either click on the SimpleCV.command icon in the Applications folder or start iPython from a terminal window. To start a terminal window, go to the Applications folder, find the Utilities folder, and then click on Terminal to launch it. This will bring up a command prompt. At the command prompt, type python -m SimpleCV.__init__ to bring up the SimpleCV interactive Python shell. Most of the examples in this book can be run from the SimpleCV shell.

While the following instructions are for Ubuntu Linux, they should also work for other Debian-based Linux distributions. Installing SimpleCV for Ubuntu is done through a .deb package. From the SimpleCV download page, click the latest stable release link. This will download the package and handle the installation of all the required dependencies.

Note, however, that even recent distributions of Ubuntu may have an outdated version of OpenCV, one of the major dependencies for SimpleCV. If the installation throws errors with OpenCV, in a Terminal window enter:

$ sudo add-apt-repository ppa:gijzelaar/opencv2.3
$ sudo apt-get update

Once SimpleCV is installed, start the SimpleCV interactive Python shell by opening a command prompt and entering python -m SimpleCV.__init__. A majority of the examples in this book can be completed from the SimpleCV shell.

Some users may want to have the bleeding edge version of SimpleCV installed. SimpleCV is an open source framework, so the latest versions of the source code are freely available. The SimpleCV source code is available on GitHub. The repository can be cloned from [email protected]:ingenuitas/SimpleCV.git.

For a more complete description of using git and the open source site GitHub, see http://www.github.com/.

Once the source code is installed, go to the directory where it was downloaded. Then run the following command at the command prompt:

$ python setup.py install

Some readers may have had prior experience working with a shell on a Linux system, MS-DOS, or software like Matlab, SPSS, R, or Quake 3 Arena. Conceptually, the SimpleCV shell has many similarities. Whereas the operating system shells take text-based commands and pass them to the OS for execution, the SimpleCV shell takes Python commands and passes them to the Python interpreter for execution. The SimpleCVshell is based on iPython and automatically loads all of the SimpleCV framework libraries. As a result, it is a great tool for tinkering with the SimpleCV framework, exploring the API, looking up documentation, and generally testing snippets of code before deployment in a full application.

All of the functions available while programming are also available when working with the shell. However, writing code in the shell still has a slightly different “feel” compared with traditional approaches. The shell will interpret commands after they are typed. This is usually on a line-by-line basis, though certain blocks, such as loops, will only be executed after the full block is entered. This places certain practical limitations on the complexity of the code, but in turn, makes an ideal environment for testing code snippets.

Starting the SimpleCV shell varies depending on the operating system. In Windows, there is a SimpleCV link that is installed on the Desktop, or accessible from the SimpleCV folder under the Start menu. From a Mac or Linux machine, open a command prompt and enter simplecv to start the shell. After starting the shell, the window should look like Figure 2-1.

Figure 2-1. A screenshot of the SimpleCV shell

If the shell does not start with the SimpleCV command, it is also possible to start it manually. Either enter python -m SimpleCV.__init__, or python at the command prompt. Then enter the following:

>>> from SimpleCV import Shell
>>> Shell.main()

To quit the shell, simply type exit() and press Return or Enter.

Similar to the popular shells found on Linux and Mac systems, the SimpleCV shell supports tab completion. When typing the name of an object or function, press Tab and the shell will attempt to complete the name of the function. For example, if attempting to reference the getImage() function of a Camera object, first type getI and press Tab. The shell will complete the rest of the name of the function. In cases where multiple function names begin with the same letters, the shell will not be able to fully complete the function name. With a Camera object, get could be referring to getImage() or to getDepth(). In such cases, it is necessary to enter additional letters to eliminate the name ambiguity.

One of the most convenient features of the shell is the built-in help system. The help system can display the latest documentation for many objects. The documentation is organized by objects, but each object’s functions are also documented. For example, the documentation for Camera includes general information about the Camera class and its methods and inherited methods. To get help using the shell, simply type help object. For example, to get help on the Image object, enter:

>>> help Image

A slight variation on the above example is using the ? to get help on an object. In the code below, adding a question mark to the end of img will show help information about the image object. Since the SimpleCV shell imports all of the SimpleCV libraries, it is technically possible to skip the line: from SimpleCV import Image.

>>> img = Image('logo')
# The next two lines do the same thing
>>> img?
>>> ?img

The shell is also a convenient tool for frequently changing and testing blocks of code. In the shell, commands entered are immediately executed. Compare this to the traditional development cycle of writing and saving a block of code, compiling that code—or in the case of Python, waiting for the interpreter to start up—and then actually running the code to examine the results. This traditional process substantially slows any interactive designing and testing. For example, computer vision programming often involves tweaking various filters and thresholds to correctly identify the regions or objects of interest. Rather than going through many write-compile-execute cycles, it is substantially easier to simply test different configurations using the shell.

Consider the challenge of finding blobs. Blobs will be covered in greater depth later, but for the purposes of this example, assume that a blob is simply a region of lighter colored pixels surrounded by darker colored pixels. Letters written in white on a dark background are good examples of blobs. “Lighter” versus “darker” pixels are distinguished based on a threshold value. To ensure that the blobs are correctly identified, this threshold must be tweaked, usually through a process of trial and error.

Image objects have a function named findBlobs() that will search for the blobs. This function has a threshold option that represents its sensitivity. For instance, to find some blobs in the SimpleCV logo, try the following:

>>> img = Image('logo')
>>> blobs = img.findBlobs(255)
>>> print blobs

The shell will print None because no blobs will be found with the threshold argument set that high. To easily change this, simply tap the up arrow on the keyboard, cycling back through the command history to the line of code that says blobs = img.findBlobs(255). Now replace the 255 with 100, and press the enter key. Then hit the up arrow again until it shows the print blobs line. Hit enter again.

>>> blobs = img.findBlobs(100)
>>> print blobs

This time, the shell will output something like the following:

[SimpleCV.Features.Blob.Blob object at (35, 32) with area 385,
 SimpleCV.Features.Blob.Blob object at (32, 32) with area 1865]

This shows that with the lower threshold, the blobs were detected. Later chapters will cover fun blob tricks such as coloring them in and displaying them in a user-friendly fashion. For now, the point is to demonstrate how easy it is to rapidly tinker with the code using the SimpleCV Shell.

One feature of the SimpleCV Shell is that it also includes capabilities of the operating system’s shell. As a result, it is possible to navigate around the system without having everything located in the program directory. For example, you can download the images from this book from the SimpleCV website at http://www.simplecv.org/learn/. If the images used in this book are then stored in a folder named SimpleCV located in the home directory, then the paths to the example images used in this chapter would be: SimpleCVC:Usersyour_usernameSimpleCVChapter 2 on Windows SimpleCV/home/your_username/SimpleCV/Chapter 2 on Linux SimpleCV /Users/your_username/SimpleCV/Chapter 2 on Mac. There are also other advantages, such as being able to see what types of files are in a directory.

The next example shows how to find the image named ch1-test.png using the shell, and then load that image. First, locate the correct directory with the following commands:

>>> cd
>>> pwd

The two commands above should print out the location of the home directory, which is probably /home/your_username if working on a Linux system, /Users/your_username on a Mac system, and C:\Users\your_username on Windows. The example consists of two steps. First, by entering cd with nothing after it, the current directory is changed to the home directory. The cd command stands for “change directory”; when given a directory path, it moves you to that location. When no path is entered, it moves you to the home directory. The second command, pwd, stands for “print working directory.” It prints out the current location, which should be the home directory.

Assuming that the SimpleCV folder is located in the home directory, the camera-example.png image is loaded with the following command:

>>> img = Image('SimpleCV/Chapter 2/camera-example.png')

However, when working with a lot of images, it may be more convenient to be in the image directory instead. To go to the directory with the Chapter 2 images, and then output a list of all of the images, type:

>>> cd SimpleCV/Chapter 2
>>> ls

The result will be a directory listing of all the sample image files. Notice that this works just like using the cd and ls commands in a traditional Linux shell. Not surprisingly, common command options also work, such as ls -la to show the file details as well as all of the hidden files. This is a good way to look up a correct file name and prevent annoying “file not found” error messages. Once the directory and file names are correct, loading and displaying an image is done with the following commands:

>>> img = Image('camera-example.png')
>>> img.show()

A good first step when setting up a vision system is to view what the camera is capturing. To get live video feed from the camera, use the live() function. This is as simple as:

from SimpleCV import Camera

cam = Camera()
cam.live()

In addition to displaying live video feed, the live() function has two other very useful properties. The live feed makes it easy to find both the coordinates and the color of a pixel on the screen. This information will be useful in later chapters when cropping images by their coordinates or segmenting images based on color. Being able to click on the live feed to find the coordinates for cropping the image is a lot easier than a trial and error method of guessing what the coordinates or colors are and then tweaking the code based on the results.

To get the coordinates or color for a pixel, use the live() function as outlined in the example above. After the window showing the video feed appears, click the left mouse button on the image for the pixel of interest. The coordinates and color for the pixel at that location will then be displayed on the screen and also output to the shell. The coordinates will be in the (x, y) format, and the color will be displayed as an RGB triplet (R,G,B). An example is shown in Figure 2-4. The small text on the left of the image is displaying the coordinates and the RGB color values for where the left mouse button was clicked.

Figure 2-4. Demonstration of the live feed

This example operates like a camera with a timer: it takes a picture once per minute. It is a simple application that does nothing but save the images to disk. A more advanced version, though, could try to detect if there is any movement or look for changes in the objects. If left running indefinitely, it could quickly consume a great deal of disk space so a limit is included to only snap ten photos.

from SimpleCV import Camera, Image
import time

cam = Camera()

# Set the number of frames to capture
numFrames = 10

# Loop until we reach the limit set in numFrames
for x in range(0, numFrames):
    img = cam.getImage()  

    filepath = "image-" + str(x) + ".jpg"  
    img.save(filepath)  
    print "Saved image to: " + filepath

    time.sleep(60)

The next example is a simple photo booth application. After all, nothing says, “I’m an aspiring vision system developer” better than getting close with a friend or loved one and taking silly pictures. This application takes a continuous feed of images. When clicking the left mouse button on an image, it saves it to disk as photobooth0.jpg, photobooth1.jpg, and so on.

from SimpleCV import Camera, Display, Color
import time

# Initialize the camera
cam = Camera()

# Initialize the display
display = Display()

# Take an initial picture
img = cam.getImage()  

# Write a message on the image
img.drawText("Left click to save a photo.",
        color=Color().getRandom())  

# Show the image on the display
img.save(display)

time.sleep(5)  

counter = 0
while not display.isDone():
     # Update the display with the latest image
     img = cam.getImage() 

     img.save(display)

     if display.mouseLeft:
          # Save image to the current directory
          img.save("photobooth" + str(counter) + ".jpg")  

          img.drawText("Photo saved.", color=Color().getRandom()) 

          img.save(display)

          time.sleep(5)

          counter = counter + 1