This assignment is a self-directed study to introduce you to the basics of Python for computer vision. There is nothing to hand in and no marks will be given. You should aim to complete this assignment by Friday, January 11, 2019.

This assignment and all subsequent assignments use libraries contained in the Enthought Python Distribution (EPD). Submitted assignments must work based on, and only on, specified libraries included in Enthought.

The Enthought Python Distribution is available in the undergraduate unix labs. Here, we also provide information on how to obtain and install the Enthought Python distribution on your personal machine.

The Assignment

1) Python Distribution

On an undergraduate lab machine: To start the Python distribution from a unix shell, do the following:

	    
        # start Python
        python
	    
    

Note: “>>>” is the Python shell prompt (and you're ready to go).

On your personal machine: Enthought installs both Python and a collection of programming libraries for scientific and mathematical work. It can be installed for Windows, OSX, or Unix. It's free to students but you will need to provide your university email account as proof of enrollment. Enthought will then email you a link to their install files. You can request an academic licence here. Note: Students have reported that using an alumni.ubc.ca email address does not work automatically in that Enthought requests a follow up to prove that the person really is a UBC student. Using your course ugrad.cs.ubc.ca email address should work without problem.

Installation generally is quite simple. But, if you have problems consult Enthought's quick start installation guide.

Note: Enthought's current distribution, Canopy, is newer than the distribution installed in the undergraduate labs. Please post to Piazza if you encounter compatibility issues. In general, nothing we will do in this class should be too demending and should work with any distribution of Python.

2) Working with Python

Python v2.7.14 documentation is the official documentation page for the version of Python we are using. It includes a helpful Python tutorial for getting started. This table lists all of the packages and tools included in the Python Distribution repository. The key modules we are interested in are PIL, numpy, matplotlib, and scipy.

This Python Quick Guide is suggested as appropriate for someone in a 400-level Computer Science course who is not otherwise familiar with Python. For CPSC 425, you will need to know how to perform flow control and mathematical operations, how to create functions, how Python handles scoping through indentation, and file reading/writing. Follow the Python Quick Guide (or equivalent) and make sure you are comfortable with everything in the Basic Tutorial up to (but not including) “Exceptions.” Material in the Advanced Tutorial, “Classes/Objects” (and beyond) won't be needed in this course.

Also note that you can access Enthought Training On-demand with your free academic license. They have great (and short) video lectures to get you up to speed with Python.

3) Specific Examples

First download this test image, peacock.png (Image credit: Tristram Southey).

Since the version of Python were are using is an interpreted language, you can either just start Python at the command line and work from there or work from your favourite text editor and run the Python code. In future you will need to submit your code but not for this assignment.

        
        # import the packages we need for this assignment
        from PIL import Image
        import numpy as np

        # open the test image
        # Note: If you didn't launch Python from the same directory where you saved
        #       the file, peacock.png, you'll need to provide the full path name as
        #       the argument to Image.open
        im = Image.open('peacock.png')

        # display relevant Image class attributes: dimensions (width, height),
        # pixel format and file format
        print im.size, im.mode, im.format

        # Note: PIL does not have a built-in image display tool.  Instead, principally
        # for debugging, there's a show method which saves an image to a temporary file
        # on disk and calls a platform dependent external display utility
        # (the default being "xv" on unix, and the "Paint" program on Windows).

        # display the image
        im.show()

        # if this does not work on your system, try the imshow function from
        # matplotlib's pyplot module by uncommenting the next three lines
        #import matplotlib.pyplot as plt
        #plt.imshow(im)
        #plt.show()

        # convert the image to a black and white "luminance" greyscale image
        im = im.convert('L')

        # select a 100x100 sub region (containing the peacock's head)
        im2 = im.crop((475,130,575,230))

        # save the selected region
        im2.save('peacock_head.png','PNG')

        # PIL and numpy use different internal representations
        # convert the image to a numpy array (for subsequent processing)
        im2_array = np.asarray(im2)

        # compute the average intensity
        average = np.mean(im2_array)

        # Note: we need to make a copy to change the values of an array created using
        # np.asarray
        im3_array = im2_array.copy()

        # add 50 to each pixel value (clipping above at 255, the maximum uint8 value)
        # Note: indentation matters
        for x in range(0,100):
            for y in range(0,100):
                im3_array[y,x] = min(im3_array[y,x] + 50, 255)

        # convert the result back to a PIL image and save
        im3 = Image.fromarray(im3_array)
        im3.save('peacock_head_bright.png','PNG')

        # again make a copy of the (original) 100x100 sub-region
        im4_array = im2_array.copy()

        # this time, reduce the intensity of each pixel by half
        # Note: this converts the array to a float array
        im4_array = im4_array * 0.5

        # convert the array back to a unit8 array so we can write to a file
        im4_array = im4_array.astype('uint8')

        # convert the numpy array back to a PIL image and save
        im4 = Image.fromarray(im4_array)
        im4.save('peacock_head_dark.png','PNG')

        # let's generate our own image, a simple gradient test pattern
        # make a 1-D array of length 256 with the values 0 - 255
        grad = np.arange(0,256)

        # repeat this 1-D array 256 times to create a 256x256 2-D array
        grad = np.tile(grad,[256,1])

        # convert to uint8 and then to a PIL image and save
        im5 = Image.fromarray(grad.astype('uint8'))
        im5.save('gradient.png','PNG')
        
    

Deliverables

There is nothing to hand in for this assignment and no marks will be given. The objective is for you to get the Enthought Python Distribution (EPD) up and running on the platform of your choice, sufficient to run the above examples. The specific examples chosen demonstrate basic functionality needed in future assignments. Thus, it is to your benefit also to try to understand what is happening at each step in each example.