CPSC 120

Principles of Computer Science
Using Multimedia Design

Fall 2008

Lab 3: Introduction to Multimedia Programming in Python

Introduction

For the remainder of the course, we will be manipulating and creating multimedia (pictures, sounds, and movies) using the Python programming language. We will be using an implementation of Python called Jython, which is implemented on top of Java (hence the name Jython). To program in Python (or Jython) we will be using the Jython Environment for Students (JES) from Georgia Tech. In fact, we will be using a variant of JES called kJES, which was developed at Kalamazoo College. Note: kJES and JES are used interchangeably below.

In this lab, as well as in some of the upcoming labs, we will be manipulating pictures. A picture in a computer is represented using a 2-dimensional table of dots where each dot contains a different color. These dots are called pixels. By using enough pixels, the human viewer cannot tell that the picture is made up of a finite collection of colors. Each pixel in the picture, which contains a color, has a position within the picture. The upper lefthand corner of the picture is (1, 1). If the width of the picture is 100 and the height is 200, then the upper right hand corner is (100, 1), the lower left hand corner is (1, 200), and the lower right hand corner is (100, 200). We can use these x, y coordinates to access particular pixels within the picture.

As stated above, each pixel contains a color. A color in a computer is represented using the RGB color model. Each color contains a red component, green component, and a blue component, where each component is an integer from 0 to 255. Higher values are more intense and closer to white, while lower values are less intense and closer to black. For example, (r=0, g=0, b=0) is black, (r=255, g=255, b=255) is white, and (r=255, g=0, b=0) is bright red.

The kJES Program

In lab 1, you created a link to the kJES application and put it on your desktop (the icon looks like the picture on the right). You should click on this icon and run the program. You should eventually see the following window:

The top panel (the panel with a white background) in the window is called the Program Area. That's where you will write your programs (this panel is similar to Kate or any other editor). The bottom panel (the panel with a black background) in the window is called the Command Area or the Interactions Area. That's where you can execute Python commands, in order to experiment with Python and test your programs. In between the two panels are several buttons. The "Load Program" button allows you to load a program that you would like to use in the command area. You will need to use this button every time you open up a program file or make a modification to the program in your program area. The "Watcher" button allows you to open a debugger for testing your program and finding errors (i.e., bugs). We will not use the debugger in this lab and we will not use it often in this course. The "Stop" button allows you to stop a running program (being run from the command area) that is taking too long to finish. The bar beside the "Stop" button shows the status of a command executing in the command area. If it is empty then there is no command currently executing, otherwise, a command is still running.

At the bottom of the Window, there are also some useful text messages and buttons. On the left is a help or status message (at first it says "For help on a particular JES function, move the cursor over it"). Beside this message, there is an "Explain ..." button. If you put the cursor somewhere on a built-in JES function in your program, then click "Explain ...", you will see a third panel appear on the right called the Help Area. In this case, the Help Area will describe that particular function. You can also open the Help Area by clicking on "Help" in the top menu and selecting a particular topic or by clicking on "JES Functions" in the top menu and selecting a particular JES function. Below is an example of the kJES window with the Help Area open:

To get rid of the Help Area click on "Window Layout" in the top menu and select "Program Area + Interactions Area" (to make the Help Area appear you could select "Program Area + Interactions Area + Help"). In the bottom of the window on the far right, you will also see some text that indicates the current line and position of the cursor in the Program Area as well as the current user (which is not applicable for us).

The Program Area works in a similar way to other editors (Kate, Microsoft Word) except it is designed specifically for Python programming. You can cut, copy, and paste text via "Edit" in the top menu or using shortcut keys (click on "Edit" to find the shortcut keys). You can also switch between the Program Area and Command Area, go to a specific line, search for text, or set various options using the "Edit" menu at the top. You can create new Python files, open existing ones, save the currently open file, print the currently open file, load it (which is the same as using the "Load Program" button), or exit kJES using the "File" menu at the top.

The other menus at the top, which were not mentioned above, are "Watcher" and "MediaTools". As stated above, we will not use the Watcher debugger so you can ignore the "Watcher" menu. The "MediaTools" menu allows you to open up three tools for viewing pictures, sounds, and movies, respectively. These will all be helpful in later labs, but for this lab the only tool we will use is the Picture Tool (which is discussed later).

Take some time to explore JES. Try entering some commands into the Command Area (e.g., "3+2", "x=4*1"). Use the Help Area to find information about various topics or JES functions.

Working with Pictures in kJES

kJES has a lot of support for working with pictures (as well as sounds and movies) as we will see in the next couple of labs. For example, you can open an existing picture and store it in a variable via a few JES functions. The Python command pict = makePicture(pickAFile()) will open a picture and store it in the variable pict. pickAFile() is a function, which opens a graphical window and allows the user to select a file (in this case a picture). The file is returned as a string (e.g., "marc.jpg") and passed to the function makePicture. makePicture returns the picture, which is assigned to the variable pict. You can also create a new picture with the function makeEmptyPicture, which takes the width and height of the new picture. For example, pict = makeEmptyPicture(100, 50) creates a new, blank picture with width 100 and height 50.Once you store a picture into a variable, you can perform various operations on it. For example, you can display it in a new window with the function show (e.g., show(pict)). You can get the width or the height of the picture with the functions getWidth and getHeight, respectively (e.g., width = getWidth(pict)). You can duplicate a picture with the function duplicatePicture (e.g., copiedPict = duplicatePicture(pict)).

Copy a picture from the Internet (or somewhere else) to your desktop. The class pictures are available at http://math.hws.edu/mcorliss/teaching/fall08/cs120/pics. You may want to use a picture with a lower resolution (i.e., less pixels) since some picture editing commands in kJES can take a while with high resolution pictures. In the class pictures web page I have placed links to lower resolution versions of each picture. Once you have copied the picture to your desktop, use the Command Area to enter commands to assign that picture to a variable, print its width and height, and display it in a new window.

kJES also has an operation for cropping pictures. You can return a cropped picture using the function cropPicture. For example, croppedPict = cropPicture(pict, 72, 10, 70, 80) sets the variable croppedPict to the portion of the picture stored in pict, which starts at (72, 10), has a width of 70 and height of 80. The transformation below shows the effect of this function call. In the original picture on the left (note that the rectangle is to show cropping and is not a part of the picture), the area in the rectangle would be returned and the resulting picture would be assigned to croppedPict, which is shown on the right.

Use the cropPicture function to crop your picture that you opened above. Display the cropped picture to make sure that your function call worked properly.

kJES has many operations for modifying pictures. In the next lab, we will look at modifying individual pixels within the picture. In this lab, we will use some operations for modifying several pixels at a time. For example, there are functions for drawing figures onto the picture. For example, you can draw a rectangle outline on the picture with the function addRect. For example, addRect(pict, 10, 20, 100, 50) draws a black outline of a rectangle starting at (10, 20) with width 100 and height 50. In the picture above, which shows the effect of cropping, the rectangle in the picture on the left, was drawn using addRect. You can also set the color of the rectangle by supplying a color in the function call: addRect(pict, 10, 20, 100, 50, red). To draw a filled-in rectangle, you can use the function addRectFilled, which works like addRect. To draw ovals, you can use addOval and addOvalFilled, which work just like addRect and addRectFilled. There are also an addText and addLine functions for drawing lines (see the Help for information on how to use these functions).

When you modify a picture that is already displayed, the changes will not be automatically visible. You will have to close the picture window and then redisplay the picture via show. Alternatively, you can use the function repaint to apply any recent modifications (e.g., repaint(pict)).

Draw on your picture, using some of the fuctions discussed above (e.g., addRect). Display the modified picture to make sure that your function calls worked properly.

You can also copy one picture into another picture using the function copyInto. For example, copyInto(smallerPict, biggerPict, 50, 50) would copy smallerPict into biggerPict, placing the upper left corner of smallerPict at (50, 50).

Use copyInto to copy your cropped picture into the middle of the original picture, but at a different part of the picture. Display the modified picture to make sure that your function call worked properly.

After modifying a picture, you may want to save the picture to a file so that the modified picture is saved permanently. For instance, in the exercises below, you will need to save your modified pictures so that you can display them on your web page. The function for saving a picture to a file is writePictureTo (e.g., writePictureTo(pict, "new_picture.jpg")). Important: make sure you use a file name with the ".jpg" extension to ensure that the operating system treats that file as a (JPEG) picture. Note also that writePictureTo will either save the picture to your home folder or the last place where you opened or saved a picture. Alternatively, you could provide a complete path to the file (although it is long):

writePictureTo(pict, "/afs/.afs.hws.edu/home/mcorliss/Desktop/marc.jpg")

Save the picture you modified above using writePictureTo. You probably will want to save it to a new file rather than overwriting the original file.

Colors

In some of the examples above, colors were used such as red. red is a built-in color in kJES and there are several others including blue, white, green, etc. In addition, you can create colors using the RGB value. For example, the function makeColor creates a new color. It takes as a parameter the red amount, green amount, and blue amount. For example, color = makeColor(20, 30, 100) creates a new color with a red amount of 20, green amount of 30, and a blue amount of 100 and assigns it to the variable color. The variable color can be used in the same way as red, blue, etc (addRect(pict, 10, 20, 50, 75, color)).

To find non-standard colors, there is a function called pickAColor. For example, color = pickAColor() opens up a new window and allows the user to select arbitrary colors. There are three ways to select colors: using swatches, using the hue, saturation, and brightness (HSB), and using the RGB values. Once the user selects a color, the color is returned, and in this case, the color is assigned to the variable color.

Create an arbitrary color using pickAColor and assign it to a variable. Use this color, to draw on the picture you opened above.

Picture Tool

As mentioned earlier, kJES has a picture tool for viewing a picture and finding various characteristics of the picture. If you click on this tool from the "JES Functions" menu, it opens a new window for viewing a previously open picture (if no pictures were open yet, then this tool will not work). It can also be opened via the function openPictureTool. The Picture Tool window is shown below:

This tool will help you determine the x and y positions of various parts of the picture. For example, you can use the mouse to select a pixel and view the x and y positions. The color of that pixel is also displayed, which can be useful information. You can also select a pixel by entering an x value and a y value in the textfields at the top.

Use the Picture Tool to view the picture you opened in the earlier examples. Spend some time experimenting with this tool.

Python Programming

In this lab, you will start writing computer programs for the first time (an HTML page doesn't really count as a program). Python has strict rules about how you specify commands. For instance, it is case sensitive, meaning pict is not the same as Pict. The type of parameters (e.g., picture, integer, color, etc.) passed to a function must match the functions definition (for built-in functions check out the Help Area). When writing functions, commands that go within a function must be indented. Python also has other strict rules, which must be observed, so make sure you enter things precisely.

Below is an example program from class that can help you in writing your own programs. It contains a few mathematical and picture-related functions.

# A function that squares an integer => f(x) = x * x
# the value is a parameter and the squared value is returned
def square(x):
  # square x and return it
  sq = x * x
  return sq

# A function that cubes an integer => f(x) = x * x * x
# the value is a parameter and the cubed value is returned
def cube(x):
  # cube x and return it
  # uses square to square x and then multiplies by x to get cube
  cu = square(x) * x
  return cu

# A function that crops a picture of me (Marc)
# returns a picture of just my head
def crop():
  # open the picture -- the file is fixed
  file = "/Users/mcorliss/pics/marc.jpg"
  pict = makePicture(file)

  # crop the picture and return it
  croppedPict = cropPicture(pict, 71, 11, 75, 75)
  return croppedPict

# A function that doubles an input picture, side-by-side
# returns the doubled picture
def double(pict):
  # create blank canvas for doubled picture
  doublePict = makeEmptyPicture(getWidth(pict)*2, getHeight(pict))

  # copies picture to left half of blank canvas
  copyInto(pict, doublePict, 1, 1)

  # copies picture to right half of canvas
  copyInto(pict, doublePict, getWidth(pict)+1, 1)

  # returns doubled picture
  return doublePict

Good Programming Style

When programming, keep in mind that programs are written for people just as much as they are written for computers. It is important to make sure others (as well as you, after some time) can understand the program.

Any program that you turn in for this course should obey the rules of good programming style. You may lose points for poor style, even if your program works correctly. In particular, you should follow these style rules:

Put a comment at the beginning of the program file stating your name, the lab number, and any other relevant information.
Put a comment at the beginning of each function that explains what the function does and any assumptions it makes.
Use meaningful variable and function names which suggest the role of the variable and/or function in the program, while avoiding extremely long names. Single-letter names are rarely appropriate.
Use comments within functions for commands that are potentially complicated or hard to follow.

Exercises

Here are the exercises for this week's lab. They are due in lab next Friday (at the start of lab). You should write a function for each exercise below (except for the last exercise, which asks you to put your work on your cs120 web page) and put it in a single Python file called exercises.py within the lab03 folder within your cs120 folder on your desktop. Each function will modify a picture and return the modified picture. You will have to decide how to get the picture into the function. You can either pass the picture into the function as a parameter or open it within the function itself.

Make sure you comment all of your code as described above. This will be an important part of your grade. Important: make sure you provide a comment describing how the function should be called so that I can execute the function as you do.

Extra credit is possible for particularly nifty picture transformations.

Write a function called drawOnPicture that draws on a picture. For example, in the picture below, I drew glasses, a moustache, and a text bubble on a picture of myself:

You should use the functions addRect, addRectFilled, addOval, addOvalFilled, addLine, addText to do the drawing. Your drawing should be of something recognizable and not a bunch of random figures. In addition, you must make at least five calls to various drawing functions using three different functions. You should also use at least two different colors.
Write a function called splitPicture to split a picture in half and return just the left half of the picture. The picture must be a profile of a person (for example, the class picture of you) and it must be split at the middle of the nose, which most likely will not be the exact middle of the picture. Use the Picture Tool to determine where the picture must be split (i.e., the x position). Use cropPicture to perform the split. For example, here is the resulting picture after splitting a picture of me in half:
Write a function called createCollage to create a collage of several pictures. How you design the collage is up to you, but you must use at least four different pictures. Here is fairly simple collage of my two dogs (Zoe and Denver):

Note: your collage does not have to be structured exactly like mine (i.e., 2x2 table of pictures). You could have some overlap between the pictures. You could also use a different layout (e.g., 4 pictures centered around a middle picture). Feel free to experiment with a different design, although you should make sure you use at least 4 pictures.
In this exercise, you will put all the pictures that you created in the earlier exercises on your cs120 web page (cs120.html). For lab 2, you created a table to hold your course work. As mentioned in lab 2, each row of this table will contain a different picture (or sound or movie) transformation. Within each row, you should have a cell describing the transformation, a cell with the original picture (if applicable), and a cell with the edited picture. You should also make one starting row that states that these are for lab 3 (since you will augment this table with work from later labs). This page shows my version of this table. Your page should look similar. If you have trouble with this, look at the HTML code for my page by clicking on "View" in the browser and then selecting "View Source" (this might vary a little for different browsers, but there should still be some option for viewing the source HTML code).

Note: for each of the earlier exercises, you will need to use the writePictureTo function to save the changes that you make to each picture. These pictures will be used in the edited picture column. The original pictures will of course be used in the original picture column. Use the description column to describe the particular transformation. For the collage exercise, you do not need to include an original picture for the corresponding row since there were several pictures, but for the other exercises you should include the original picture. The description and edited picture should always be included for each exercise.

Again, look at my page for help on setting up and editing this table.