main-project3
Project 3: Image Processing (due Wednesday, November 17th)
Note: we will give a slight extension for this project: Projects turned in on (or before) Friday, November 19th will be considered on time, and projects turned in on (or before) Sunday, November 21st will be considered late. Note that we may not be able to accept “very late” projects, and that the next programming assignment will be due on the 24th.
1.@ Overview
The goal of this project is to give you a chance to try your hand at doing some image processing.
Rather than thinking of this as a single big project, its probably less intimidating to think of this as 3 smaller assignments that all happen to be due on the same day.
For this assignment you will write three programs. Each will run from the command line, and take 2 file names as arguments (the input file and the output file name). Each program will take a TGA input file as input and write out a TGA file as output. While the programs are fully specified below, they are (roughly)
- Blur the image (convolve it)
- Resize the image (by resampling)
- Turn the image into an impressionist painting
The pieces are not equally hard, or equally weighted. Roughly, the weighting is 10% blur, 35% resize, 45% paint, and 10% for written questions. But this weighting is not rigid. If you do a particularly cool painting implementation, that can make up for other things.
The blur part is going to be graded “check/no-check” so its OK (in terms of your grade) to just do the very basic version. Think of it as a warm-up for the bigger pieces.
2.@ Basic Ground Rules
Each program should run from the command line and take a number of arguments. For all programs, the first argument is the name of the input file (including the “.tga” extension), the second is the name of the output file (including the “.tga” extension). Each program will take a different set of other arguments.
Note: you should still build your programs from the Visual Studio IDE (for example, by pressing “F7”). This build process created a “.exe” file that can be subsequently run from the command line.
You will hand in 3 seperate programs. There need to be three seperate “main” files, and 3 visual studio project files. You can put 3 projects into one solution file, or turn in 3 solution files. Just document what you’ve done.
Your programs should not crash - even if given invalid inputs. Detect errors before they turn into problems and fail gracefully and give error messages. We will test your program with invalid inputs.
Your program must build with no errors within Visual Studio. We recommend that your program builds with no warnings (this is good programming practice - even if a warning isn’t important, it can distract you from noticing important ones).
In some cases, programs may have optional arguments. Your program should have some reasonable defaults in the event the optional arguments aren’t specified.
The assignment is due on Wednesday November 17th. The standard project late policy applies. Note: we may allow you to turn in some examples after the fact, but generally, your program is due on the 17th.
3.@ Notes on Grading
We will look at each program, and then arrive at a combined grade.
For each program there are a number of “hardness levels.” You can do something simple, or do something harder. We’ll describe some of the options with each program, but there are so many things that people end up doing, its hard to predict them all.
In general, doing a basic version of a program (as defined for each program) that works well and meets all of the requirements (including documentation) will get you (roughly) a B. To get a better grade, you need to add some features (be sure to describe them in your documentation). However, it is often better to do something simple, but do it well, than it is to do something fancy and not do it well. If you say your program does something, and it doesn’t do it, that can be worse than not saying your program does it. (we’ll only check the things that you say that your program does)
You will be evaluated on:
- The correctness of your program, as evaluated by looking at the output of it.
- The set of features that you have implemented beyond the basic assignment.
- The quality of your code and documentation. (remember your readme).
- The answers that you turn in to the questions.
- Correctly following directions.
- Existence of examples. We will not grade you on artistic choices.
Note: we will not evaluate the efficiency of your program (within reasonable time). Concentrate on writing programs that get correct answers and are clean and readable code. If your program takes more than a few seconds to process a 600x400 image, then maybe there’s something wrong - but don’t worry about trying to get into a race with Photoshop.
4.@ Part 1 - Blur
The first program takes the input image and blurs it by convolving it with a filter kernel. Your program should take arguments:
blur input.tga output.tga R
where R is the “radius” of the blur.
Optionally, your program can take a second parameter that is a number (0 or greater) that specifies the type of blur.
blur input.tga output.tga R N
Remember, if your program can use a second parameter, it still should work if only 1 parameter is provided.
The output image should have the same size as the input.
The “Radius” of the blur is how many pixels on each side of the center the kernel is. So “R=1” would be a 3x3 blur.
For a very basic version of this part, your program can ignore R and just do a convolution with the 5x5 “box” kernel
1 1 1 1 1
1 1 1 1 1
1/25 1 1 1 1 1
1 1 1 1 1
1 1 1 1 1
(note: in terms of your grade, its OK to just do this very basic version)
A better version (i’d call this “basic”) would use R correctly, and apply an appropriately sized version of some filter kernel (like the box, or some of the others described in class).
The complete version work use N to choose between different kernel types. (Box, B-Spline, Gaussian, …) - we’ll describe some in class.
Your program should deal with image boundaries correctly. A basic version might simply clamp or zero outside the edges. Better versions would either use mirroring or kernel normalization (and maybe even give the option of switching between them).
As part of your documentation, you should explain the kernel that you used (all the options if you support them), as well as what boundary option you chose.
You must also turn in an input/output image pair. Make the input image no larger than 100x100 (since TGA images are uncompressed, and therefore big). If you support multiple kernel types, you can give multiple output files (just give 2 or 3). In your documentation, explain how we can tell that your program is doing what its supposed to be doing.
5.@ Part 2 - Resize
This program read in an image file and resamples it to have a different size.
resize input.tga output.tga x y
where x,y is the new size in pixels
Your program may take an optional argument that specifies what resampling kernel it uses. In your documentation, be sure to specify what kernel your program uses by default, as well as what the options are. The default should be one of the “best” kernels you support.
If you support multiple kernels, one of the kernels should be nearest-neighbor (the simplest thing to implement) so you can show how much better your “good” kernels are.
Remember: it is better to implement something simpler and get it to work correctly, than to get something complicated wrong. Implementing nearest neighbor in a simple way (having it just round the sampling position to the nearest pixel) is better than implementing something that incorrectly does pre-filtering / fancy interpolation.
You can see some hints on resizing in (2009 resize hints). Sample results for Downsampling and Upsizing have more hints and peeks into my code. The book has lots of hints on how to implement this as well.
Example Images: For downsampling, use t1.tga (which is used on the downsample page). Turn in downsampled versions of this image at 100x100, 150x75, and 300x400. (note: your results may be different than the ones I show on the page). Please name your files t1-100x100.tga, t1-150x75.tga, and t1-300x400.tga.
For upsampling, use the image pub:P1Samples/tiny.tga and resize it to 240x240 (a factor of 10 upsizing). Please name the result “tiny-240.tga”. If you want to give more than one result, you can name them “tiny-240-X.tga” (make X be meaningful). Be sure to explain in your documentation what the difference is. (don’t give more than 2 or 3)
Note: if your program doesn’t support multiple kernels, you can use some other program (the example solution, IrfanView, Photoshop, … - all have selectable kernels for resampling)the or just look at the results on the upsampling and downsampling page.
Questions to Answer:
- Which kernels did you implement?
- What kinds of images are you most likely to see the differences, and what would these differences look like?
- In what situations do the Catmul-Rom or Lanczos kernels give better results?
- For a black and white checkerboard, a nearest neighbor resampling will give as sharp (or maybe even sharper) result than anything else. Explain why this sharpness isn’t necessarily a good thing, and why the blurrier results you might get from a “better” filter (like a tent) are more “correct”.
6.@ Part 3: Impressionist Painting
Your program will take an input image and transform it into something that looks like an impressionist painting (with brush strokes). Your program must work with just 2 parameters (input and output file names), but can take optional parameters if you want (and you can decide what they are - just make sure they are documented).
So:
paint input.tga output.tga
should produce something reasonable.
For a discussion of impressionist painting, see this page on the 2007 web. If you want more ideas on fancier things to do, look at Aaron Hertzman’s tutorials which are here. For the very most basic version of this assignment, see the 2009 Hints.
Note: if your program needs to read in an auxiliary file, please make sure that the file is included as part of the handin, and that the executable can find it when its run from the command line in the build directory.
For some examples, check out a gallery from the 2009 class.
Example Images: You should turn in 3 or 4 result images. At least one of them should be one of these images: 3-Amsterdam.tga, 3-peppers.tga, 3-vail.tga. At least one of the examples should be an image of your own choosing.
Please name the result “3-username-picname.tga” (like “3-gleicher-vail.tga”).
Use the settings that you think make your program give the nicest results (if your program has options).
Questions: In your documentation, be sure to answer the following questions:
- What does your painting algorithm do? (How does it work - how does it choose where to put brush strokes? how does it decide what the brush strokes look like? how does it make the brush strokes?)
- What kinds of pictures does it tend to give nice results for?
- What kinds of pictures does it not give nice results for?
7.@ Mechanics
Each student in class must turn in their own projects (all parts).
Like all programming assignments in this class, your programs must build and run under Windows XP on the CSL computers. This means you should use Microsoft Visual Studio 2008.
The test images we supply, as well as the results you give us, must be in the TGA image file format. We will provide you with a C library for reading and writing this format (with a C++ wrapper). LibTarga is not perfect, but we define a “valid TGA image” to be a file that can be read by LibTarga.
You should include the source code to LibTarga in your handin so that each program is complete.
It should be the case that a grader can copy your handin folder to the local disk of a CSL computer, double click on the solution file in the folder, press build, and get an EXE file they can run. (in the debug or release directory). Your program should compile with no errors, and preferably no warnings.
You may use the sample code from the course web page and LibTarga. You should write all the real image processing code yourself.