ENG 6 - Final Project
An Image Editing Application

• Final projects must be done with groups of two students. Although not recommended, students may work alone. Clearly write both names in the header comments of the main script file.

• Due Friday, June 3, 5pm uploaded to smartsite. Upload each script and function file separately (e.g., not in a single zip file) to either students' account, but not both. Each student must upload a plain text "README.txt" file which very briefly states:
  1. which parts you did,
  2. which parts your partner did (make SURE you get this clear with your partner and submit consistent reports),
  3. any parts that do not work (additional points will be deducted if we find things you did not find which shows adequate testing was not performed), and
  4. any special items such as extra credit functions.

• 1. Load new image
  Requests a filename and loads image.

  Implement as a function: pic = load_image(filename);

• 2. Crop image
  Submenu requests edge to be cropped (1. top, 2. left, 3. right, 4. bottom), and number of pixels to remove and does it.

  Implement as a function: pic_new = crop_image(pic,direction,pixels);

• 3. Scale image
  Submenu requests scale_zoom which has valid values from 0.50 - 2.00, where 0.50 would result in the new image having half the number of rows and columns and 2.00 would result in the new image having twice the number of rows and columns. Calculation of new pixels will in general require interpolation. This operation is sometimes called "resize" and the new image should look just like the old one but of a different size.

  Implement as a function: pic_new = scale_image(pic,scale_zoom);

• 4. Edit image
  For color images, a submenu requests one of the following: 1. red, 2. green, 3. blue, 4. all. For grayscale images, this submenu is skipped.

  The next submenu requests one of the following:

  • 1. Intensity adjust
    Submenu requests intensity_adj with valid values from 0.00 - 2.00 where:
    new_value = current_value * intensity_adj;
    new_value = new_value saturated to maximum of 1.00
    A value of intensity_adj=1.00 results in no change.

  • 2. Auto-intensity adjust
    Same as option #1 except that the scaling is automatically chosen such that the image's new max value is 1.00

  • 3. Contrast adjust
    Submenu requests contrast_adj with valid values from 0.10 - 10.00 where:
    mid_value = 0.50; % middle of valid pixel values
    new_value = (current_value - mid_value)*contrast_adj + mid_value;
    A value of contrast_adj =1.00 results in no change.

  • 4. Color bringout
    This option does not appear for grayscale images. If user previously selected "all" color and then selects this option, print an error message saying, "Error: red, green, or blue color must be selected." Otherwise, use this algorithm for each pixel:
    if pixel has more of the selected color than either of the other two colors: do nothing
    else: convert pixel to grayscale

• 5. Blur image
  Submenu requests direction to be blurred (1. left-right, 2. up-down, 3. all directions), and range of pixels to blur (valid range is 0-num_rows or 0-num_cols as appropriate).

  For example: 2 (up-down), 5 (pixels): pixel (x,y) new value = sum of pixels from ((x,y-5)...+...(x,y)...+...(x,y+5)) / 11.
  Pixels within 5 rows of the top and bottom of the image have the values summed and averaged over only the pixels that fall on the image.

  Implement as a function: pic_new = blur_image(pic,direction,pixels);

         
• 6. Convert color image to grayscale
  Shown on menu only when the current image is color.

• 7. Plot histograms
  Plot histograms with intensities showing the full range with at least 100 "bins". Plot in Figure 2. For color images, plot red, green, blue histograms as subplots above each other in a single figure. For grayscale images, plot a single histogram.

• 8. Undo
  Undo last editing command. Only one level of undo supported. Option is removed from menu if last command was "undo" or at beginning before any command has been run.

• 9. Repeat/Redo
  This command works in two ways. 1) If the last command was a supported command that makes sense to repeat (such as "blur" but not "load" or "save"), print "Repeat" on the menu, and Redo the last editing command if selected. Do not ask the user for input and just repeat the operation. 2) If the last command was "Undo," print "Redo" on the menu, and return the image to the state is was before "Undo" was executed, if selected.

• 10. Save current working image
  Requests filename and the image file type (jpeg, gif, png, tiff, bmp) in a string format. Program continues running after saving.

• 11. Play slideshow
  Shows slideshow by fading between jpeg images at a specified rate. Requests filename of a file with slideshow information: first line contains the number of images, the second line contains the number of seconds to show an image unfaded, the third line contains the number of seconds to fade images in and out, and the remaining lines contain filenames of images in the local directory.

  Images are loaded into an array structure "slides" and then played. Choose a rate to update image fades that looks good. Use the pause() command to control timing. Images of any size must work but all images in a slideshow will always be the same size. Here are the contents of an example file:
  

  5
  2
  3
  beach.jpeg
  hiking.jpeg
  skiing.jpeg
  biking.jpeg
  birthday.jpeg
  

• 12. Exit
  Quit program.

Some general project requirements

• The application is a matlab script which calls functions as needed.
  • Functions written to process images must be written in a way that they operate on all of the following pixel types: red, green, blue, grayscale.

• Menus and messages
  • Appropriate menu options and messages are printed whenever user input is needed, and are printed with fprintf() and input().
  • All menus and submenus must display brief help instructions.
  • Control returns to the main menu after execution of a function in a submenu (e.g., after performing an "auto-intensity adjust").
  • Options appear on main menu only when appropriate. For example, "Save" and editing commands appear only when a valid image exists. "Load" should appear always.

• Figure 1 must show the current state of the working image at all times. Execute "axis image" to keep the picture in proper perspective.

• All reasonable errorneous user inputs (text, letters, numbers, out of range numbers, etc.) must result in an appropriate error message and a chance for the user to try again.
  • Program must ask, "are you sure you want to lose current image?" if user tries to load or quit while working on an unsaved image.

• Images must be stored in the following structure after being loaded:
  
  pic.valid     % 0=no valid image in structure, 1=valid image is in structure
  pic.num_rows
  pic.num_cols
  pic.pixels
  pic.color     % 0=grayscale MxN, 1=color MxNx3

• Image editing must be done with only simple arithmetic operations such as +,-,*,/,sum(),sqrt() unless indicated otherwise. Using unallowed functions will result in a major loss of points. Check with a TA if you are unsure, but the final word is what is written on this web page.

• Because some calculations will result in pixel values out of the the range that the format can handle, follow the following procedure:
  • when loading images, convert pixel values to "double" and scale values to [0.0, 1.0] after consulting the appropriate max value for the file format that was read.
  • after any image processing, call a function normalize_image(image) which will bring the image back into the correct range [0.0, 1.0] by saturation if the range has been exceeded. Do not scale an image to fill the range as this is provided by other editing functions.
  • when saving images, scale the image appropriately according to what is required by the chosen file format.

• Write a function print_dot(row) which executes fprintf('.'); and also prints a "new line" every 50 lines. Call this function after processing each row to show progress. An image with 205 rows of pixels will cause the following pattern to be printed on the screen (one dot when each row is processed) when the image is processed:
  ..................................................
  ..................................................
  ..................................................
  ..................................................
  .....
  

Miscellaneous information

• Extra credit: A small amount of additional points will be given for significant enhancements beyond the requirements. Caution: changes to the requirements that reduce the programming effort will always result in a reduction of points. To be safe, check with your TA or the instructor during office hours or implement two versions. State clearly in the comments of your main script what extra things you have done. Ideas: additional image processing functions (simple ones like rotate, flip up/dn left/rt; or others like threshold and levels), sound with your slideshow, GUI menus, ken burns effect (matlab may be too slow to implement smoothly however), slideshow fade to black, etc.

• Basic functions like size(), length(), linspace(), str2num(), strcmp() are basic functions permitted anywhere.
  (However, I prefer you avoid linspace() and just write it yourself.)

• The intention of the suggested format: pic_new = SomeOperation(pic,...) is that pic is the "current" copy of the image, and pic_new is the "new" copy. At the appropriate time, the new image becomes the current one and the next editing cycle begins. As you can probably see, this method makes undo much simpler. Your application should work exactly like a typical image editing program where each edit is done in series to the current image.

• Here is a file for octave users which can be read with "load rose.mat" and will create a variable in their workspace called "pic" which is 240x384x3 of type uint8 and is the same format everyone else will start off with right after reading a file. This file was made from "pic=imread('rose.jpg);"

• Changes above not marked in green:
  • Although not essential, use "pic" for structure name instead of "image" to avoid confusion with the function image().

Grading rubric

• [5 pts] Basic menus and program flow such as going back to main menu after executing each command
• [2 pts] Load
• [2 pts] Crop
• [5 pts] Scale by 2 and by 1/2
  [Extra Credit +5] Scale by other factors
• [2 pts] Edit: intensity
  [2 pts] Edit: auto-intensity
  [2 pts] Edit: contrast
  [2 pts] Edit: color bringout
• [2 pts] Blur: up-down
  [2 pts] Blur: left-right
  [2 pts] Blur: all directions
• [2 pts] Convert color → grayscale
• [2 pts] Histograms: color
  [2 pts] Histograms: grayscale
• [2 pts] Undo
• [2 pts] Repeat
  [2 pts] Redo
• [2 pts] Save all formats except gif
  [Extra credit +2] Save gif
• [5 pts] Play slideshow
• Extra credit
  • Except for two cases above, extra credit is possible only if the remainder of the assignment is done (otherwise it would effectively be the same as the student changing the assignment).
  • 7 points (+15%) maximum. Talk to me if you see a project that is truly exceptional.

Todo:
 - get and post several test images
   - color, gray, super-simple for testing
 - "For matrices containing doubles, color intensities are on the range 
   [0.0, 1.0].  For uint8 and uint16 matrices, color intensities are on the 
   range [0, 255]."
 - generate special image format files for octave
 - verify imshow() is ok to use; it displays grayscale images scaled from 0-1