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 Tuesday, January 14, 2020.

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. The key libraries we are interested in are PIL, numpy, matplotlib, and scipy; they will be shipped with Enthought. Enthought can be installed on Windows, OSX, or Unix. The version we are using in this course is Python 2.7 and Enthought Canopy 2.1.9. You can find the download page here (https://assets.enthought.com/downloads/). Please make sure the Canopy version is 2.1.9 and the Python version is 2.7.

The installation should be straightforward. Please consult the installation guide (http://docs.enthought.com/canopy/quick-start.html) or attend a TA office hour if you have difficulty.

Note: Please check the Python and Canopy version if you are using a department machine. In general, we are not very strict about versioning; however, some starter code might break if you are using a different version. Most of them should be an easy fix, e.g., `print a` in Python 2 and `print(a)` in python 3.

2) Working with Python

Python v2.7.14 documentation (https://docs.python.org/release/2.7.14/) is the official documentation page for the version of Python we are using. It includes a helpful Python tutorial (http://docs.python.org/release/2.7.14/tutorial/index.html) for getting started. 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." The material in the Advanced Tutorial, "Classes/Objects" (and beyond) won't be needed in this course.

Additionally, you will be using numpy extensively and many lines of code in your assignments can be replaced with a few lines of numpy code. Please study a introduction tutorial on numpy (a href="https://docs.scipy.org/doc/numpy/user/quickstart.html). Fore more numpy materials, please visit this page (https://docs.scipy.org/doc/numpy/user/basics.html).

Some students might prefer watching tutorials as opposed to learning the documentation. You may find the Python and numpy tutorials on YouTube helpful.

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.