A Slightly More Advanced Assembly Exercise

Exercise 1: Converting a Color Image (PPM) to Grayscale (PGM)

For this exercise, you will first write a MIPS assembly program to convert a color image (in PPM format) to grayscale (PGM format). A C version of the program (ex1.c) is provided; study it carefully and then convert it line-by-line to MIPS assembly.

PPM and PGM File Formats

For this exercise, we will use the ASCII file formats of type PPM (color) and PGM (grayscale). For a detailed description of these file formats, please see the Wikipedia entry on Netpbm format. A short description is given below.

The format of a PPM or PGM file is as follows:

• A PPM or PGM file begins with an identifier on the first line (called "magic number"). A magic number of "P3" means this file is an ASCII PPM file; "P2" means it is an ASCII PGM file.
• There may be an optional comment line following this, starting with "#". To make this assignment a little easier, the input files given to you will not have this optional comment line (or any other comment lines anywhere else in the input).
• Next, there are two numbers, the first indicating the number of columns, and the second the number of rows in the image.
• Next, there is a max value (PPM_MAX), which indicates the maximum value any pixel component (R, G, B, or gray value) may have. This value may be any positive integer, although values of 15 and 255 are quite typical.
• Finally, there are color or gray values for all the column * row pixels. The values are ordered by rows from top to bottom, i.e., row 1 first, then row 2, etc., and within each row, the pixels are listed left to right.
  • For a PPM image, each pixel value is listed as the values of its three components, Red, Green and Blue.
  • For a PGM image, each pixel value is a single gray value.
• A whitespace (i.e., typically a space or newline character) must separate these integers. Other than that, the file is allowed to have any number of values on each line. For example, it is possible that the file has a single pixel value (R, G and B, separated by spaces) on a single line. Or, the file may have a single pixel color component per line (i.e., R on one line, G on the next, then B, then the next pixel, etc.). Or, one line in the file may have color values for multiple pixels, e.g., the RGB values for an entire row of pixels may be listed on a single line (as in the Wikipedia examples). But, we will put some restrictions on this format to simplify reading/writing these files.

Additional Formatting Specifications for This Exercise: Since the MIPS input/output routines (syscalls) available in MARS are somewhat limited, we will put further restrictions on the format of PPM/PGM files as follows:

• The files will not have any comments in them (so, no need to look for "#").
• Each line will only have one number on it. This means that the number of columns and the number of rows in the image will appear on separate (consecutive) lines. Also, the three color components of a pixel (R, G and B values) will appear on three separate lines.
• Please refer to the samples provided for any other formatting questions.

PPM and PGM Viewers

There are a number of free/open-source viewers available for displaying PPM/PGM image files, including:

• Windows/Mac: GIMP (GNU Image Manipulation Program), available from http://www.gimp.org. You can also look into IrfanView, AyeView (fee trial), and ToyViewer (for Mac). I would recommend GIMP.
• Mac: Depending on your OS version, you may be able to look at these files simply using "quick look", by selecting them and then pressing the space bar.
• Linux: I would recommend GIMP again, but many X Windows distributions already include a lighter-weight tool called XV.

C Program

The C version of the program is provided (ex1.c). It reads a PPM image (on its standard input, i.e., keyboard), and outputs its corresponding PGM image (on its standard output, i.e., console). Keep in mind the following:

• The max value for each color component can be specified to be any number 1 or greater. For this exercise, this number could be from 1 to 255 for the input PPM images.
• We will use a better formula to convert RGB to gray values than the simple averaging we used in Lab 6. It turns out that the human eye has different sensitivities to red, green and blue colors, so the color values must be weighted different for a more accurate conversion to gray: (R*30% + G*59% + B*11%)
• The max value for the gray values for the output must be 255. Thus, if the input PPM image has a max color component value of 15, then all of the values must be scaled appropriately. In particular, if the red, green and blue values of the pixel colors in the PPM image is R, G and B, respectively, and the max value is specified to be PPM_MAX, then the corresponding gray value in the output PGM image must be computed exactly as follows:

  
                  Gray_Value = ((R*30 + G*59 + B*11) * 255) / (100 * PPM_MAX)
  

  Your assembly code must compute the gray value exactly as described by the last expression above, and exactly in the order indicated by the parentheses. The division is a truncated integer division (i.e., no rounding, throw away remainder); therefore, for best accuracy, all of the multiply operations are performed first, and division last.
• The magic number of the output image must be "P2" since it is an ASCII PGM file.
• You can compile and run the C program and test it by typing (or cutting-and-pasting) sample inputs onto the console, and looking at the console output. For the larger examples, use input/output redirection:

  
                  ex1 < ex1in1.ppm > ex1result1.pgm
                  Copy the PGM output to your laptop and view it in GIMP
                  The PGM output is the grayscale version of the PPM input
  

Assembly Program

Write an equivalent MIPS assembly program that implements the same conversion from PPM to PGM images. The best strategy would be to convert your C code (pretty much line-by-line) into its assembly equivalent. A starter file is provided (ex1.asm). Be sure to follow the structure outlined in the starter file. Specifically, your code must have the three procedures specified: main, iterate_through_pix, and rgb_to_gray.

TIP: Your program does not (in fact, should not) need to store the entire image in an array. Simply read RGB values of a pixel, and output its gray value, and repeat over the entire image. There is no need at all to create an array to store all the pixel values.

Run your program in MARS and verify that it is working correctly. You can run your program in MARS and test it by typing (or cutting-and-pasting) sample inputs onto the console, and looking at the console output. The first input file (ex1in1.ppm) is small enough for you to type it into the MARS console. For the larger examples, you will need to run it in command-line mode and use input/output redirection.

If you are developing your code on a Mac/Linux machine, you can use the following command on your computer within a terminal window without logging onto classroom.cs.unc.edu (replace /path/to with the actual path to Mars, e.g., /Users/yourid/Desktop/Mars/Mars4_5.jar):

% java -jar /path/to/Mars4_5.jar nc mc CompactDataAtZero ex1.asm < ex1in1.ppm > ex1result1.pgm

If you are using a Windows machine (or even Mac/Linux), you can login onto classroom.cs.unc.edu, copy your work there, and then run the following command:

% java -jar /home/montek/comp411/bin/Mars4_5.jar nc mc CompactDataAtZero ex1.asm < ex1in1.ppm > ex1result1.pgm

The PGM output should look like a grayscale version of the PPM input. Make sure the PGM output has the same overall brightness as the input; otherwise check PPM_MAX

(For more information on running MARS in command-line mode, please see http://courses.missouristate.edu/kenvollmar/mars/help/MarsHelpCommand.html.)

Name the file containing your assembly program ex1.asm, and test it on sample inputs provided. First view the output file using GIMP. If it looks good, then you may check it against the sample output provided using the diff command.

Exercise 2: Cropping a PGM image

For this exercise, you will a program in C first and then in assembly to crop a grayscale image (in PGM format). No templates are provided; you may want to follow the general structure/style of your programs of Exercise 1. The program will read four integers from the standard input, one per line as follows:

                x1
                x2
                y1
                y2
    

These numbers represent the coordinates of the bounding box with which to crop the image. That is, the top-left corner will be (x1, y1), and the bottom right corner will be (x2, y2). You can assume that x2 >= x1 and y2 >= y1, and that the values will be within the bounds of the actual image (so no error checking needed). The cropped image will include all the columns from x1 to x2 (inclusive), and all the rows from y1 to y2 (inclusive). The numbering starts with the top-left corner of the image at (0,0).

The input will consist of the four integers as above, followed by the contents of the PGM file but without the "P2" line at the top (to make things easier) (see description in Exercise 1). The output should be the contents of the cropped grayscale image, in PGM format, just as in Exercise 1.

TIP: Once again, your program does not (in fact, should not) need to store the entire image in an array. Cropping simply can be done by reading one pixel at a time, deciding whether it belongs in the cropped image or not (based on its row and column number), and then printing it on the output if it belongs in the image. There is no need at all to create an array to store all the pixel values.

Name your C program ex2.c and the assembly ex2.asm.

The first sample input (ex2in1) is small enough for you type into the terminal or MARS console. For the larger examples, you will need to run your program in command-line mode and use input/output redirection, as follows:

% ex2 < ex2in1 > ex2result1.pgm

And the assembly program as follows:

% java -jar /home/montek/comp411/bin/Mars4_5.jar nc mc CompactDataAtZero ex2.asm < ex2in1 > ex2result1.pgm

Please do view all output files using GIMP (or one of the other tools suggested above). If it looks good, then you may check it against the sample output provided using the diff command.

Test Inputs, Due Date and Submission Procedure

Sample inputs and corresponding outputs are provided under /home/montek/comp411/samples/lab7. You should try running your program on the sample input files provided, and make sure the program's output is identical to that in the sample output files.

Your assignment must be submitted electronically by 11:59pm on Friday, November 3.

First copy the files ex1.asm, ex2.c and ex2.asm to the CS Dept server (classroom.cs.unc.edu) under the appropriate folder in your home directory (e.g., comp411lab/lab7). Then, run the self-checking and submit scripts:

% cd ~/comp411lab/lab7
% /home/montek/comp411/bin/selfchecklab7
% /home/montek/comp411/bin/submitlab7

In case of any problems, please contact the instructor or the TAs.