Quick Start 1

From pyvision

I find that the easiest way to learn a new library is to try some simple examples. The following examples will introduce some of the basics elements of pyvision.

Edge Finding (QS1)

This first example processes a set of images using the OpenCV canny edge detector. This example will show how to load images from files process the images with a PyVision interface to the canny function, and save the results. The code for this example can be found in src/samples/QS1EdgeFinding.py. The full code listing is shown here:

import pyvision as pv
from pyvision.edge.canny import canny  # An interface to the OpenCV Canny.

'''
This code is from part 1 of the PyVision Quick Start Guide.
'''
if __name__ == '__main__':
    # (1) Load an image from a file.
    im = pv.Image(pv.__path__[0]+"/data/nonface/NONFACE_16.jpg")
    
    # (2) Rescale the image
    im = pv.AffineScale(0.5,(320,240)).transformImage(im)
    
    # (3) Run the canny function to locate the edges.
    edge_im1 = canny(im)
    
    # (4) Run the canny function with different defaults.
    edge_im2 = canny(im,threshold1=100,threshold2=250)
    
    # (5) Save the results to a log.
    ilog = pv.ImageLog("../..")
    ilog.log(im,label="Source")    
    ilog.log(edge_im1,label="Canny1")
    ilog.log(edge_im2,label="Canny2")
    
    # (6) Display the results.
    ilog.show()

First, we need to load some classes and functions from the pyvision library. In this example we are loading the Image class, a class for generating affine transformations, the canny function, and the ImageLog class. These will each be explained shortly.

Images

In step (1) the Image class is used to load in an image. In this case it is one of the default testing images that is included with pyvision. The Image constructor accepts filenames as an argument and will then load that file from the disk as a PIL image. The Image constructor will also accept other python image objects. For example, if you pass a numpy matrix, PIL image, or an OpenCV image to the constructor it will crate a pyvision image based on that data.

# (1) Load an image from a file.
im = pv.Image(pv.__path__[0]+"/data/nonface/NONFACE_16.jpg")

Affine Transform

In step (2) the image is scaled by half. This step was included primarily to produce smaller images for this tutorial. However this is a good time to introduce affine transformations. The Affine class is able to transform images and points two and from different coordinate systems. This class becomes especially valuable when dealing with images and points at multiple resolutions. In this case the transformation is a simple scale operation. Typically the Affine factory functions take parameters that define the transformation, and the size of the new image. The scaled image can be seen here.

# (2) Rescale the image
im = pv.AffineScale(0.5,(320,240)).transformImage(im)

Step 2: Scaled starting image.

Canny and OpenCV

Next, canny edge detection is run on the image. This function highlights edges in the image. For the purpose of this tutorial we will try to find the outlines of the snails. As you can see, the output of the edge detector is finding too many lines.

# (3) Run the canny function to locate the edges.
edge_im1 = canny(im)

Step 3: Canny with default thresholds

The canny function is just a wrapper around the OpenCV python interface. The source code is shown here. At the beginning of the function the image class converts the image data into an OpenCV compatible image. The Image class is often used as an intermediate format to translate between all of the libraries that PyVision interfaces with. After produceing the OpenCV compatible image, OpenCV functions are used to compute the canny edge detector. The result is passed to the Image constructor to produces a PyVision compatible image and is returned.

def canny(im,threshold1=40.0,threshold2=100.0,aperture_size=3):
    '''
    void cvCanny( const CvArr* image, CvArr* edges, double threshold1,
              double threshold2, int aperture_size=3 );
    '''
    cvim = im.asOpenCV()
    edges = opencv.cvCreateImage( opencv.cvGetSize(cvim), 8, 1 );

    if cvim.nChannels == 3:
        gray = opencv.cvCreateImage( opencv.cvGetSize(cvim), 8, 1 );
        opencv.cvCvtColor( cvim, gray, opencv.CV_BGR2GRAY );
    else:
        gray = cvim

    opencv.cvCanny(gray,edges,threshold1,threshold2,aperture_size)
    
    return Image(edges)

The canny function uses default parameters. To produce better edge detection for the image, those parameters can be tuned. Here the canny thresholds have been altered to produce good edges.

# (4) Run the canny function with different defaults.
edge_im2 = canny(im,threshold1=100,threshold2=250)

Step 4: Canny with tuned thresholds.

ImageLog

Finally, the results need to be saved. The ImageLog class is used to organize and save results. Creating the ImageLog automatically produces a folder on disk that is labeled with the date and time the log was started. By default this will go in the "tmp" directory, however, here we have created that directory two levels up (../..). The log() method will save each image to this folder. The show() method is a convenance function that opens all the MacOS X Preview application. On other platforms you may have to open these images manually.