Note: A small bug has been fixed in the sample project. Please see the README file in the sample directory for more information.

Project 4: Image Manipulation, Recursion, and Flood Fill

Due Date:

Midnight Sunday, April 16, 2000. Note that this means before 23:59:59 on Sunday evening. The standard late policy applies. Note that you have three weeks to complete this project.

Objectives

The objectives of this project are:

Background

Data Formats

Much of the time that you spend programming will be devoted to data formats. Data formats (such as protocols and file formats) describe the way one program can pass information on to another. If programs (and programmers) cannot agree on data formats, they cannot share information.

Images as Data

Everything that we manipulate with a computer has some sort of data format and pictures are no exception. Computer images are usually based on what is called a "raster" format; an image consists of a rectangular grid of independent "picture elements" (pixels) that each have separate properties (usually red, green and blue levels). That having been said, as a general rule, images consist of a width, a height, and a grid of pixels.

Images come in a vast array of formats ranging from very simple to exceedingly complex. Most often, one representation is chosen (or designed) instead of another because of the needs addressed in the application. For example, GIF and JPEG images are designed to be small so that file transfers take as little time as possible. They use a combination of limited color and other compression techniques to limit the size of the images on disk, often at the expense of image quality.

A much simpler format is a portable bitmap (PBM) file. The PBM files you will be using are plain ASCII text (so you can read them in an editor) and consist of:

  1. A "magic number" that identifies the file's contents as a PBM image. For all intents and purposes, it's a string that must be at the beginning of a PBM file.
  2. Some whitespace (" \t\n")
  3. The image width
  4. Some more whitespace
  5. The image height
  6. Some more whitespace
  7. A series of width * height '0's and '1's, possibly separated by whitespace.

Here is a sample PBM file:

P1 11 11 00000000000 00000000000 00001110000 00010001000 00100000100 00100000100 00100000100 00010001000 00001110000 00000000000 00000000000

In PBM files, each pixels can either be "on" or "off"; the zeroes represent while pixels and the ones represent black pixels.

This actually describes a subset of the real PBM format. You are only responsible for PBMs of the format described here for this project.

For more information, see the man page for PBM (man pbm) for details.

Tasks

You must write a simple image manipulation program. Before you panic with questions, see the sample run included below. Your program should behave like the sample program. All of your prompts and error messages should be the same as those in the sample program.

Your program should perform the following operations on PBM files:

  1. Load -

    The load command should prompt the user for a filename and then attempt to read that file into an image object. Your program should have the following behavior:

    1. File cannot be opened - Print an error and return to the main menu.
    2. File is not a PBM file (magic number is not "P1") - Print an error and return to the main menu.

    You may assume no other errors will occur during load.

  2. Save -

    The save command should prompt the user for a filename and write a valid PBM file to that filename. Your program should have the following behavior:

    1. File cannot be opened - Print an error and return to the main menu.

    You may assume no other errors will occur during save.

  3. Fill -

    The fill command should prompt the user for an x,y coordinate and recursively "color in" space inside the image starting at that point. The fill color will always be 1. When the fill hits a boundary it should stop moving outwards and continue filling inside the image. The algorithm you will be implementing is called a "flood fill" or a "seed fill" (since you give it a seed point and it fills the interior of the shape that contains that point.) A more intensive description of the flood fill process will come after the algorithm has been discussed in class. Your program should have the following behavior:

    1. x or y are outside the bounds of the image - Print an error and return to the main menu.

    You may assume that no other errors will occur during fill.

  4. Enlarge -

    The enlarge command should prompt the user for an x,y pair of scale factors and then enlarge the image by those factors. For example, a scale of 2 2 should make every single pixel in the starting image a 2x2 square of pixels in the final image. This doubles the size of the image in both x and y. A scale of 2 1 should make the final image twice as wide but the same height as the starting image. In this case, each starting pixel is a 2x1 rectangle of pixels in the final image.

    Your program must behave as follows:

    1. Both the x scale and the y scale must be greater than 0. If x or y is less than 1, print an error and return to the main menu.

  5. Draw -

    The draw command should draw a version of the image to the screen. The drawn representation of the image should be like those in the sample run:

    1. It should have a border drawn with: 1. a '+' at each corner. 2. a series of '-'s along the top and bottom edges. 3. a series of '|'s along the left and right edges. The border is outside of the image, so for a PBM that is 5x6, the area inside the border should be 5 characters across and 6 characters high.
    2. Pixels with value of 0 should be drawn as blanks. Pixels with a value of 1 should be drawn as '*'s.

    A draw command on an image that has not been loaded should print an error message.

  6. Exit -

    Your program should exit when the exit command is given.

Final Note

This is not an all encompassing list of the error conditions you may find while coding your project. When in doubt, make your program behave like the sample program. You will not lose points for correctness if your program's output is the same as the sample's.

A Sample Run

Here is an example of the output generated by the sample program. Script started on Mon Mar 27 20:00:23 2000 % ./proj4 Welcome to CMSC 202 Project 4! (l)oad, (s)ave, (e)nlarge, (f)ill, (d)raw, or e(x)it: d - You must load an image first. (l)oad, (s)ave, (e)nlarge, (f)ill, (d)raw, or e(x)it: l - Enter a file name: circle.pbm - Loaded image of size 11x11 (WxH) from "circle.pbm". (l)oad, (s)ave, (e)nlarge, (f)ill, (d)raw, or e(x)it: d +-----------+ | | | | | *** | | * * | | * * | | * * | | * * | | * * | | *** | | | | | +-----------+ (l)oad, (s)ave, (e)nlarge, (f)ill, (d)raw, or e(x)it: f - Enter fill coordinates (eg. "x y"): 10 10 - Filled 84 pixels. (l)oad, (s)ave, (e)nlarge, (f)ill, (d)raw, or e(x)it: d +-----------+ |***********| |***********| |***********| |**** ****| |*** ***| |*** ***| |*** ***| |**** ****| |***********| |***********| |***********| +-----------+ (l)oad, (s)ave, (e)nlarge, (f)ill, (d)raw, or e(x)it: e - Enter scale factors greater than zero(eg. "xs ys"): 2 1 - Image is now: 22x11 (WxH). (l)oad, (s)ave, (e)nlarge, (f)ill, (d)raw, or e(x)it: s - Enter a file name: filledcircle.pbm - File saved. (l)oad, (s)ave, (e)nlarge, (f)ill, (d)raw, or e(x)it: x % exit script done on Mon Mar 27 20:01:16 2000

The program used to generate the sample output is available in:

/afs/umbc.edu/users/j/k/jkukla1/pub/cs202/proj4 Sample input files are also provided.

Requirements

Your program must include an image class. You may choose to create other object types during the course of your development, but you are only required to use an image class.

Coding Standards

For this project you must follow the class coding standards. Remember, you must document your code as well as your headers. Comments should be on their own lines and should not share lines with actual code.

Using Code You Didn't Write

Claiming authorship of code that you didn't write is plagiarism and will be dealt with as academic dishonesty. You should not use code that you didn't write; it defeats the learning experience of the project. If you do use outside code on your project, you must site the source. If a significant portion of the project comes from an outside source, your grade may be reduced.

Testing Your Program

Remember, your program must compile and run using the CC compiler on the IRIX machines (umbc8/9). If your program does not compile or does not generate the correct output, you will not receive full credit for this project.

You should be able to adapt your makefile from a previous project to work for project 4. You should make sure that you have a makefile named either makefile or Makefile and that when you type make your program compiles to an executable called proj4. Failure to follow these simple directions will result in a reduced grade.

Grading

Now that you are designing your own classes, design will be one of the criteria for your project grade. The grade for this project will be broken down as follows: 50% Correctness This tests that your program behaves the same way that the sample does. 30% Design and Style You should follow the coding standards and make sure your coding style is consistent. In addition, your image class should handle only image operations; the menu is not part of the image. 20% Documentation Commenting inline as well as header files.

What to Turn In

You should submit your Makefile and any files needed to build your program.

Submitting Your Project

When you have finished and tested your project you can submit it electronically using submit. The project name for this assignment is proj4. As an example, to submit your Makefile, you would type: submit cs202 proj4 Makefile More complete documentation for submit and related commands can be found here.

Last modified: 27 March 2000