CS 226: Data Structures, Program #4 (Project 2)

Turtle Flood

Assigned: Wednesday, October 20, 2004
Due: Monday, November 1, 2004, 11:59 pm (GRADED!!)

(Reminder: Please do not look at each other's source code except for any designated project partner. We will be actively looking for programs that are "too similar", and I do not wish to find any.)

Overview

So far, your turtle has been limited to mere line drawing. Now you will add the ability to fill in arbitrarily-shaped areas of your image. This process is often referred to as flood filling. You will accomplish this by applying your knowledge of breadth-first graph traversal.

Command Descriptions

For this assignment, you will be implementing the fill command:

fill   <solid|rainbow>

The fill command initiates a flood fill starting from the turtle's current position in the image. If we think of the current color of the pixel at the turtle location as the background color, the flood fill algorithm should modify the color of all pixels which share the same background color and form a connected region of the image. Choosing solid as a parameter should color all the pixels in that region with the current turtle color (i.e. the foreground color). Using rainbow mode will color pixels according to their traversal order, as explained later.

Classes

FillCommand

You should implement a FillCommand class which implements the TurtleCommand interface for your new command (similar to all the other commands supported by your TurtleCommander program).

Implementation

You may choose to create additional new classes as well. For this assignment, I will be leaving more of the design up to you, so you are free to specify the interfaces to these classes as you see fit (for example, my implementation includes a class called ImageGraph, but yours need not).

Unlike the graphs we studied in class, the vertices and edges of this graph have a somewhat implicit specification. Each pixel of your image is a vertex with four edges coming out of it. These edges connect each pixel vertex to its neighboring pixel vertex (vertically and horizontally only, not diagonally). Thus your graph is fully specified by knowing the dimensions of the image.

The useful data stored with each vertex is its color. When you create your image using createImage( ), cast it to a BufferedImage, which allows you to access individual pixels. You can then use the methods BufferedImage.getRGB( ), BufferedImage.setRGB( ), and Color.getRGB to manipulate the colors of individual pixels.

The flood filling algorithm should procede as a classic breadth-first graph traversal (Note: recursive depth-first search overflows the Java call stack rather quickly, and I have been unsuccessfull at extending the stack size using Java's command-line parameters. If you find a way to get a stack depth of more than a few thousand under Windows, let me know how). The image is a highly cyclic graph, so of course you need to ensure that you only visit each vertex once. Furthermore, you should not traverse portions of the graph which do not initially contain the background color, so only a single connected region of the given background color will be traversed and recolored.

For the rainbow fill mode, you should use the method Color.HSVtoRGB( ) to generate the RGB colors. Keep the saturation and value (brightness) parameters set to 1.0, while varying the hue parameter between 0.0 and 1.0. The purpose of this fill mode, besides being pretty, is to visualize the traversal depths of the pixels in your fill region. You should set the hue according to the depth in the breadth-first traversal tree, allowing for 50 different hues in the range 0.0-1.0.In fact, 0.0 and 1.0 map to the same hue (using just the fractional part of the number), so depths 0, 50, 100, etc. should map to hue 0.0, and depths 49, 99, and 149 should map to hue 49.0/50.0. Thus, an appropriate formula would be hue = (depth % 50) / 50.0.  Feel free to experiment with other saturations and values if you want to explore the meaning of that color space, but set them to 1.0 for the final implementation of the assigned fill command. Also, feel free to experiment with and add additional color modes if you like.

Create Some Cool Drawings

Now that you have filling commands, get to making some more pretty and creative pictures.  Submit one or more of your most creative drawings as text command sets (don't include captured image files, which could take lots of storage space). If you implemented any additional coloring modes, tell us about them in the README file and give us a text file that demonstrates it.

I have posted a new sample command file and the corresponding sample image using this new fill command. As always, of  course, you should design some test cases of your own to verify that the traversal and associated depths operate the way you expect them to.

Restrictions

You may use the java.io, java.lang, java.awt, and javax.swing class libraries. In general, you may not use classes from the java.util library unless you receive permission to do so for some particular class. Standard exceptions to this rule are StringTokenizer and the Random (which may be useful for testing some of your programs and does not jeopardize the goals of the class).

Submission - Read  this Carefully

Your submission should include a set of .java files, a README.txt file with any information you want to tell the grader about running your program (even though this one is ungraded), and some text files with your best test cases and pictures. If you are working with a designated project partner, you should specify the submission ids of the team members (you only need to submit the program under a single person's submission id). Your main program class should be called TurtleCommander, and it should be compilable using "javac TurtleCommander.java" and runnable with the command "java TurtleCommander". You should submit your program as a single .zip (zip archive) file. This file should have no directory structure in it -- just the actual files, so extracting them should result in all your original files placed in the current directory.

To submit, you should follow these steps:
  1. Create the .zip file for submission
  2. Make a new, empty directory
  3. Copy the submission file to the new directory
  4. Extract all the files from your submission file into the new directory
  5. Verify that you can compile and run the program on your test cases in the new directory
  6. Go to the submissions page
  7. Submit the .zip file, making sure that the file appears in the directory listing displayed in the browser after submission (the file size listed could be slightly different on the recipient SunOS machine from that of a Windows  OS machine, but they should be very similar)
  8. Also in the submissions page, View the submission to be certain that the file is there (you should see basically the same directory listing you saw at the end of step 7).
If anything goes wrong with steps 7 or 8, try repeating them (resubmitting your file overwrites any previous submission and time stamp). If you cannot successfully submit your assignment, immediately send e-mail to the professor and the head TA explaining the problem (with all details so we can hopefully fix it) and including the submission file as an e-mail (MIME) attachment. It is your responsibility to verify that the assignment is received. If we do not have an assignment or record of its submission, it will receive zero points.

Grading

Your Project 2 will be graded according to the criteria such as:
Compiling and running
Proper execution on a number of our test cases (with valid and invalid inputs)
Overall implementation correctness
Comments, style, and readability (informative,  but not extraneous comments are appreciated)
Effort/creativity of created pictures
If a project does not compile, you can expect to receive very few points, if any. This should encourage you to take care in your submission process.

Final Words of Encouragement

This program should be less time consuming than the first project. However, it assumes that you have a working Project 1 to start from. You do not absolutely need a working undo/redo, but all the other commands need to work to demonstrate this project properly. If your Project 1 is not working, please see me, the TA, or the CA to get it cleaned up and operating properly as soon as possible!!  Good luck, and have fun!
Home
  October 20, 2004