Software Design and Implementation

---

L3: Image PPM files

You may work alone or with a pair partner for this. If you work with a partner, be sure to follow good "pair-programming" practices.

---

Screen Pixels

In this assignment, we will be working with classes as well as PPM images. 

You will need to install a program to view PPM images on a Windows machine. I recommend installing Irfanview.

A pixel is  the smallest addressable element in an image. The word pixel is based on a contraction of pix ("pictures") and el (for "element").  We will work with some very small images like: .  Using the zoom feature of Irfanview we can see the pixels of the same image to the right where zoomed in you can see it is 8 pixels wide and 10 pixels tall. 

We recommend that you uncheck the use resample settings in Irfanview as follows:

Image Colors

Images displayed on a screen use light for the display.  Any three colors (or frequencies) of light that produce white light when combined with full intensity are called primary colors of light. The most commonly used set of primary colors of light is the set Red (R), Green (G), and Blue (B).  Using a term borrowed from neuroscience, each color is typically called a color channel.

Below you will find a widget for your exploration of color channels.  Try various RGB color channel values between 0 and 255.

The PPM Image Format

PPM stands for "Portable Pixel Map." PPM files are an image format which is easy to view as text (using Notepad, for instance.) They are also easy to work with in code. But, because they are completely uncompressed, the files become large quickly. Most modern image formats use some kind of compression to make their size reasonable while preserving the image appearance. However PPMs do still serve a purpose--one modern use for PPM is an intermediate format when converting images from one type to another.

We will be using the "plain" PPM-P3 format. Here an example plain PPM-P3 of the image shown above:

P3
# Created by Dr. Jan Pearce
8 10
255
140 140 140 120 120 120 100 100 100 80 80 80 60 60 60 40 40 40 20 20 20 0 0 0
120 120 120 63 72 204 63 72 204 63 72 204 63 72 204 252 252 255 255 255 255 15 15 15
105 105 105 255 255 255 63 72 204 255 255 255 63 72 204 255 255 255 255 255 255 30 30 30
90 90 90 255 255 255 63 72 204 63 72 204 63 72 204 255 255 255 255 255 255 45 45 45
75 75 75 255 255 255 63 72 204 255 255 255 63 72 204 63 72 204 63 72 204 60 60 60
60 60 60 63 72 204 63 72 204 63 72 204 63 72 204 255 255 255 63 72 204 75 75 75
45 45 45 255 255 255 255 255 255 63 72 204 255 255 255 254 254 254 255 255 255 90 90 90
30 30 30 255 255 255 255 255 255 63 72 204 255 255 255 255 255 255 63 72 204 105 105 105
15 15 15 252 252 253 255 255 255 63 72 204 63 72 204 63 72 204 63 72 204 120 120 120
0 0 0 20 20 20 40 40 40 60 60 60 80 80 80 100 100 100 120 120 120 140 140 140 

Irfanview will allow you to convert your own images to PPM so you can practice with your own pictures, but keep in mind that you will need to make them small or the resulting PPM will be very large!

Image Header

You can think of the image as having two parts, a header and a body. The header consists of the following entries:
P3
# Created by Dr. Jan Pearce
8 10
255
     
P3 is a "magic number". It indicates what type of PPM file it is. P3 indicates full color with ASCII encoding. For this assignment it will always be P3.
A comment line is typical after the magic number.
Next comes the width or number of columns and the height or number of rows in the image (8 x 10).
Finally, we have the maximum color intensity of 255 which is a common value for the magic number.
The way you see the header presented is how it should be spaced out.

Image Body

The image body contains the actual color information. Each pixel of the image is a tiny, colored rectangle whose color is determined by how much Red (R), Green (G), and Blue (B) are present in that order. So, 63 72 204 is the first color of the image, which is the instructor's version of Berea blue. Other pixels in the image are 255 255 255, which is white, and 0 0 0 which is black. By varying the levels of the RGB values you can come up with any color.

Note that color values must be separated by a space, but after that additional white space is ignored by the image viewer. In the sample ppm above we used line breaks to format the image so that it is easy for a human to understand.

Here is a color widget in case you are interested in experimenting:
http://yuilibrary.com/yui/docs/color/rgb-slider.html.

We have created a class which can be used to manipulate and display PPM-P3 images. This is a larger class than we have seen before so the CRC card is larger too, but like functional decomposition, class decomposition makes it easier to focus on a single method at a time.

CRC Card for the PPM class

Class name: PPM Class Methods: Class Collaborations (other classes, etc): __init__() initializer/constructor for the class, opening a provided PPM-P3 file and setting all member attributes. PPM_makeoutputfiles() given self.inasciifile, sets self.ascii and creates both ascii and binary files for output PPM_partition() Given input parameter strng, the string to partition and ch, the character to use as the delimiter returns a triple with all characters before the delimiter, the delimiter itself if present and all of the characters after the delimiter (if any). PPM_clean() removes all single line comments, whitespace, and newline characters present in the input parameter string strng. PPM_load() takes string input parameter inasciifile as the name of the ASCII PPM-P3 (non-binary) file to load. PPM_makepixellist() creates self.pixellist, a nested list of rows of [red, green, blue] pixels from input color_list which contains an unnested list of strings. PPM_updatefrompixellist() updates image object data and related files from input pixellist PPM_convert2bin() converts PPM-P3 to PPM-P6 using self.pixellist. PPM_set_title() setter for title of display window. PPM_make_red( ) colorizes current image to red by using self.pixellist. TODO FIX ME: PPM_greyscale() 'changes the picture into a grey scale image. TODO FIX ME: PPM_flip_horizontal() flips image horizontally. TODO FIX ME: PPM_rotateclockwise() rotates image clockwise. TODO FIX ME: write at least two additional PPM class methods PPM_set_up() is a helper function which must be called at the beginning of any program which uses the PPM class, but it is not a part of the class. PPM_render() is a helper function which renders all PPM images. It is not part of the class. PPM_Exception is a Python class which enables meaningful error messages on exceptions. Class Data: Class Collaborations (other classes, etc): self.root # provided master Tkinter instance created using helper function PPM_set_up() self.inasciifile # string which represents filename is used only for reading the provided PPM-P3 as input self.outasciifile # string of filename of human readable modifications to the PPM file self.outbinfile  # string of binary ppm filename needed for viewing self.title  # used for the title of the display window self.magic # ppm file type is often called the "magic number." It needs to be P3 to be readable self.comment # creates a comment for the PPM file self.width # image width in pixels self.height # image height in pixels self.colormax # should be set to 255 self.ascii  # will store the color intensities in P3 format self.pixellist # will store nested list containing pixel colors self.image # reference to image window self.label  #  used to place image in window                                 global tkintertoggle  is needed as global to ensure a single Tkinter instance which is needed to render images.

---

The instructions

We have created a ppm.py module which contains the PPM class and works with PPM images.  Download all of the following files and put them into a single folder named yourusername(s)-L3:

• ppm.py
• yourusername-L3-ppm.py: If you are working with a partner, rename this file as yourusername(s)-L3-ppm.py
• default.ppm
• bc-sign.ppm
• bc-flowers.ppm

You will be extending the PPM class and also testing your extension.

Hint: Be careful to remember that making copies of a data structure which is a list of rows which are lists which is a list of color pixels (i.e., a list of lists of lists) will require you to make deep copies.

The user will specify the name of the image file. The file needs to be a text file in PPM format as described in the discussion above.

Add the following methods into the PPM class:

• PPM_greyscale(self) ''' changes the picture into a grey scale image.'''
# This is done by averaging the values of all three color numbers for a pixel, the red, green and blue.
# then replacing them all by that average truncated to an integer.
# So if the three colors were 10, 40 and 200, the average would be 83.333333333333
# And, all three numbers would become 83, after truncating to an integer.
• PPM_flip_horizontal(self) ''' flips the picture horizontally.'''
# After this, the pixel that is on the far right end of the row ends up on the far left of the row and vice versa.
# Be sure to remember to preserve RGB order.
• PPM_rotate_clockwise(self) ''' rotates the image clockwise 90 degrees.'''
# This one is a bit tricky because you have to make a DEEP copy which is sideways.

• at least two additional methods.  Consider such ideas as negative, add a frame, turn sepia, colorize, add noise, extreme contrast, soft blur, or other functions which appeal to you.  Be sure to explain these in the docstring.

The last part of the program is to add a menu to your main() so that the user can decide which of these effects will be applied to their image. Here is an example of user interaction (Yours will likely differ from this!):

Then the program should indicate which actions occurred, and display one or more images with these actions taken.

Requirements:

• Be sure to include an appropriate docstring for each of your methods and to add informative comments in both files.
• Be sure to modify the standard header at the top of your program with name, username, assignment number, purpose and acknowledgements.
• The highest level of the program (i.e., no indenting) must only contain the following:
• the header
• any import statements
• function definitions
• a call to the main() function
• Note that for all labs in addition to writing the program, you must also do a short lab write-up. At the end of this write-up, include the revised CRC card for the PPM class.

When you are finished writing and testing your program, put all of your code in a folder named yourusername(s)-L3.  Inside the folder, include your source code, yourusername(s)-L3-ppm.py, your lab write-up, and the modified file ppm.py. You may optionally include additional PPM-P3 images if you want to. Submit your zipped folder to the L3 link on Moodle.

_{Note: The idea for this assignment came from: http://nifty.stanford.edu/2012/guerin-image-editor/image_editor.html However, you must use the provided class, so going to this site will not help with the lab.}