CS 151: Project 5

Project 5:
Cover Photos

Assigned: Wed Mar 05 2014
Due: 11:59:59 PM on Tue Mar 11 2014
Team Size: 1
Language: Python

Lab:

Lists as Information Collections

Tasks

Download two or more of the following images. Right click on the link and select 'Save As...'.
You may want to make the images smaller while testing. On the lab machines, the command to shrink an image by half is:

$ convert myImage.jpg -scale 50% mySmallImage.ppm

If you are interested in using ImageMagick on your own machine, you can download it at the ImageMagick homepage.
On your personal volume, make a folder for project 5. Then copy over the graphics and display packages from project 4.
Copy your filter.py file from your project 4 directory into your project 5 directory.
Now we're going to add alpha blending to the putPixmap function in your filter.py file. This is a modification of your existing function. The new algorithm is given below. Each comment is a line of python code.
```
def putPixmap( destination, source, x, y, alpha ):
    # for each row i
        # for each column j
            # assign to (r1, g1, b1) the rgb values from source location (j, i)
            # assign to (r2, g2, b2) the rgb values from destination location (j + x, i + y)
            # assign to newRed the alpha blend of r1 and r2
            # assign to newGreen the alpha blend of g1 and g2
            # assign to newBlue the alpha blend of b1 and b2
            # set destination pixel (j+x, i+y) to (newRed, newGreen, newBlue)
```
If you have two colors, (r1, g1, b1) and (r2, g2, b2), then the alpha blend of the two colors is given by:

(newRed, newGreen, newBlue) = (r1*alpha + (1.0-alpha)*r2, g1*alpha + (1.0-alpha)*g2, b1*alpha + (1.0-alpha)*b2)

When you are finished, download the file testpixmap.py and run it. As the usage statement indicates, it wants the names of two ppm images. When the program is finished, look at the image tpixmap.ppm.

On the lab machines, use the program xv to look at ppm images.
$ xv tpixmap.ppm

Type 'q' in the image window to make the program quit.

Note that in a terminal you can put a process into the background by adding the & symbol after the command. So if you type
$ xv tpixmap.ppm &

you can still use the terminal and the xv program will run in the background. If you type return or enter in the xv window it will re-read the image from the file, so you don't have to quit xv while you are experimenting with an image.
The goal of the project this week is to enable you to easily blend together multiple images, with various effects, into a collage. Rather than hard code all the collage positions, however, we want to put the essential information defining a collage into a list. Then we can write a general function that takes in all of that information and generates the correct collage image. To change the collage, we then just change the information defining the collage, not the code.
What is the essential information that defines a collage?

What is a data structure we can use to hold a mixture of information?

First, we should identify the essential information for a single image, since a collage is just a collection of single images.
- Filename of the image
- X offset in the collage
- Y offset in the collage
- Effect for the image
- Alpha blend value
- The Pixmap object (after being read in)
To store the information for a single image, we can use a list. To store the information for all of the images, we can use a list of lists. Consider the assignment below, which creates a list that defines a collage with two images.
```
    collageList = [ 
        [ 'maine1.ppm', 0, 0, 'rbswap', 0.8, False, None ],
        [ 'maine5.ppm', 200, 150, 'original', 0.8, False, None ] 
        ]
```
Create a new file called collage.py. Given the collage list structure we developed above, write a function that reads in all of the images in the collage and stores them in the collage list.
```
# reads in the files in the collage and stores the pixmaps in the list
def readImages( clist ):
    # for each item in clist
        # assign to the variable filename the first element in item
        # assign to the variable src, the pixmap returned by reading filename
        # assign to the last element of item, src
```
Test the readImages function by creating a test function in collage.py that makes the above collageList variable, calls readImages, and then prints out the names and sizes of each image.

Given the collage list structure we developed, write a function that calculates how big the program needs to make the background Pixmap to hold the collage.

def getImageSize( clist ):
    # assign to the variable rows, 0
    # assign to the variable cols, 0
    # for each item in clist
        # assign to x0 the x offset information in item
        # assign to y0 the y offset information in item
        # assign to src the Pixmap reference (last element in item)
        # assign to dx the offset x0 plus the width of src
        # if dx is greater than cols
            # assign to cols, dx
        # assign to dy the offset y0 plus the height of src
        # if dy is greater than rows
            # assign to rows, dy
    # return a tuple with rows and cols in it

Test out your getImageSize function using the simple collage list above, after reading in the images using your readImages function. The answer should be 600 wide (cols) and 450 high (rows)

Now that you have practice working with the collage information lists, you should be able to write a generic buildCollage program that creates a collage from the information in the list.

Assignment:

The purpose of this project is to make a program that processes a list defining a collage and builds the resulting image. The collage list information can specify if the program should apply an effect and/or an alpha blend to each image.

Tasks

For this assignment you're going to create a couple of new functions. One, buildCollage, should go in your collage.py file and will process the collage list information and build the output image. The other, putPixmapNoBlue, should go in your filter.py file and will be identical to putPixmap, except that it will not transfer blue screen pixels into the destination image.

In your collage.py file, create a function buildCollage, as given below. Each comment is a line of python code in the final function. The indentation of the comments should match the code.

def buildCollage( clist ):
    # assign to (rows, cols) the result of calling getImageSize with clist
    # assign to dst the result of calling graphics.Pixmap with cols and rows
    # for each item in clist
        # assign to filename the first element in item 
        # assign to x0 the second element in item
        # assign to y0 the third element in item
        # assign to operator the fourth element in item
        # assign to alpha the fifth element in item
	# assign to noBlue the sixth element in item
        # assign to src the last element in item (index -1)

        # use a set of if/elif statements to apply the correct
        # operator to the image (this is several lines of code)

        # call putPixmap to put src into dst at location x0, y0 with blend alpha

    # return dst

You can use testbuildcollage.py to test your buildCollage function. The test function assumes that your build collage knows what to do with the operator strings 'rbswap' and 'original', as we went over in lab.

In your filter.py file, create a function putPixmapNoBlue that has the same arguments and does the same thing as putPixmap, but does not copy the src pixel into the destination image if the src pixel is part of the blue screen.
Edit your buildCollage program so that it uses the sixth element in the collage information list, stored in the noBlue variable, to determine whether to call putPixmap or putPixmapNoBlue as the last step in the main for loop.
Make a new python file (e.g. mycollage.py) that contains a single main function. Be sure to put a call to the main function behind a test on __name__.
```
if __name__ == "__main__":
    main()
```
The main function should create a collage information list, call readImages, call buildCollage, then write the image to a file. You can use the testbuildcollage.py file as an example. Your collage should use at least four different source images.

The collage should include at least five different sub-images. Some of these can be copies of one of the source images with different effects. The collage should use at least 3 effects, at least one alpha blend, and at least one blue-screen image where the blue pixels are not copied into the collage.

Required image 1 is your first collage.
Make a new python file, coverphoto.py, that takes in at least one image filename from the command line. It should build a collage appropriate for a Facebook cover photo and write it out to a file.
The collage should be about three times as wide as it is tall and have at least three sub-images. You can control the height and width of the collage by appropriate selection and placement of your images, or you can fix the relative height and width and change putPixmap to safetly handle images that go outside the image boundaries. You can choose random effects for the three images or pick specific effects. The collage should use at least two effects.
Required image 2 is your cover photo collage.

Extensions

Create some new image effects you didn't implement in the last lab.
Make some additional programs that generate collages with specific geometric arrangements and that take their list of image files from the command line.
Add additional options to the collage information list, like whether to mirror the image or not, in addition to the other options.
Create a collage dynamically based on how many images are given on the command line.
Figure out how to call the proper effect function on each image without using an if/elif control structure. (Ok, this is kind of esoteric, but it's a cool feature of python.)
Uber-extension: put the collage information in a text file. Have your program read the text file (given as a command-line argument), parse the information, and build the collage.

Writeup and Hand-In

Before handing in your code, double check that it is well-styled:

All variable names and function names use either camelCase or snake_case.
All files and functions have docstrings.
Comments are added to explain complicated code blocks.
All variable and function names are appropriately descriptive.
Functions are defined before any other code is added at the top level of each file.
In a file with any functions defined, top level code is wrapped so that it won't execute if that file is imported by another.

Make a new wiki page for your assignment. Put the label cs151s14project5 on the page. Each of you needs to make your own writeup.

In addition to making the wiki page writeup, put the python files you wrote on the Academics server in your private handin directory.

Colby Wiki

In general, your writeup should follow the outline below.

A brief summary of the task, in your own words. This should be no more than a few sentences. Give the reader context and identify the key purpose of the assignment.
A description of your solution to the tasks, including any images you created. (Make sure your images are appropriately sized to fit onto the wiki page.) This should be a description of the form and functionality of your final code. You may want to incorporate code snippets in your description to point out relevant features. Note any unique computational solutions you developed.
A description of any extensions you undertook, including images demonstrating those extensions. If you added any modules, functions, or other design components, note their structure and the algorithms you used.
A brief description (1-3 sentences) of what you learned.
A list of people you worked with, including students who took the course in previous semesters, TAs, and professors. Include in this list anyone whose code you may have seen. If you didn't work with anyone, please say so.
Don't forget to label your writeup so that it is easy for others to find. For this lab, use cs151s14project5