Imaging Programming Assignments

In the past, this has been a whole “image manipulation project”, but we’ve shrunk it down a bit. So it might be better to think of it as three (or two for reasons you might see) programming assignments that 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)

1. Resize the image (by resampling)
2. Linear warp the image
3. Turn the image into an impressionist painting

1.@ 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.

We will have you hand in 3 seperate programs - as three totally independent handins. Each one should have all required parts (a readme file, sample outputs (see below), solution file, …).

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.

The assignment is due on Tuesday, September 30th. Wednesday October 1st (extra day because of the computer issues). The standard project late policy applies.

2.@ Some Notes on Grading

Each program will be graded seperately. However, we will treat the entire assignment (all 3 programs) as 1 in terms of the late policy. (If one is late, they all are late, but it only counts as 1 late assignment).

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 (except for the resize program). 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.

3.@ Part 1: Resize

The first program takes an image as input and resamples it to a different size. You program should take commands as:

    resize input.tga output.tga F XN XD YN YD

where F, XN, XD, YN and YD are integers. F specified the filter type, (XN,XD) specifies the amount of scaling in the X direction, (YN,YD) specifies the amount of scaling in the Y direction.

Note that we give you the scaling as a fraction (N for numerator, D for denominator). Your program might just turn this into a floating point number, or make use of the fractional form. A naive way to implement resize is to first scale up by N, then scale down by D.

Your program should interpret F as follows:

• F = 0 means do point sampling (and box filters / pixel replication)
• F = 1… means do better re-sampling

Even if you implement fancy re-sampling, you must implement point sampling/pixel replication as well. If you implement fancy sampling, you might want to have different levels of fanciness, for example, to try out different types of filters. Being able to try different filters / interpolation methods so you can compare the results is a good way to show that things are right (hint hint).

In your documentation, make explicitly clear which features you have implemented, and what filters/interpolation you use. You should explain how you determine the parameters of the filters based on the inputs.

The basic version of this assignment would be to implement point sampling. For this program, that will get you a BC if you do it well. If you want a better grade, you need to implement some of the following features:

• Proper pre-filtering (with good filters) so when you reduce the size of an image, things look OK.
• Proper interpolation (with good filters) so when you enlarge the size of an image, things look better.
• Adapting the filter size/sampling pattern so you don’t need to first scale up then scale down.
• Being able to choose various forms of filters (cubic, …)

More specific grading information will be provided closer to the due date.

Remember: it is better to implement something simpler and get it to work correctly, than to get something complicated wrong.

Example Images: closer to the due date, we will provide a set of test images, and a set of parameters to try. Check back to find out what you should turn in. In the example image directory (p:/course/cs559-gleicher/public/2008ImagingTests) there are 3 sample images (1-1, 1-2, 1-3) for this part. Turn in the following:

• 1-1-1.tga - image 1-1, scaled by 3 in the horizontal direction and 3 in the vertical direction using the best filtering your program implements (parameters: N 3 1 3 1)
• 1-2-1.tga - image 1-2, scaled by 1 in the horizontal and 2 in the vertical (using your best filtering)
• 1-2-2.tga - image 1-2, scaled by .5 in the horizontal and 1 in the vertical (using your best filtering)
• 1-2-3.tga - image 1-2, scaled by 3/4 in the horizontal and 5/4 in the vertical (using your best filtering)
• 1-3-0.tga - image 1-3, scaled by 1/2 in both directions, using the most basic (point sampling - no filtering)
• 1-3-1.tga - image 1-3, scaled by 1/2 in both directions, using the best filtering

_Questions:_In your readme file, please answer the following questions:

1. What filters does your implementation provide?
2. Describe an image on which your “best” filter gives a “better” result than the simplest one (in terms of how you think the result looks). Describe an image where the simplest one looks better.

4.@ Part 2: Linear Warp

Your program will transform the input by applying a linear warp. (Note: resizing is a special case of this, although you probably want to implement it seperately).

A linear warp transforms each pixel in the source image (x,y) to a destination location (x’,y’) as:

    x' = a * x + b * y + e
    y' = c * x + d * y + f

Your program should take arguments as follows:

    linear input.tga output.tga F SX SY A B C D E F

Where F SX and SY are integers (F=Filter type, (SX,SY) is the size of the resulting image). A,B,C,D,E,F are floating point numbers (giving the values in the equation above). For the purposes of this assignment (0,0) is the upper left pixel of the image.

   a b e
   c d f
   0 0 1

You should assume that locations outside the source image are black. For example, given a 200x200 image on the left, and the following command that rotates and scales, you’ll get something like the image below right.

    linearwarp t0.tga t1.tga 0 100 100 .25 -.25 .25 .25 50 0

Notice that the source is 200x200, the result is 100x100, and I’ve used point sampling.

To see more examples, check the ProgramImagingSamples page.

Warning: notice that the values specified are the FORWARD warp. See the hints below. If you can’t figure out how to deal with forward warps, you can interpret the parameters as the inverse warp, but there will be a penalty for this.

As with resize, F=0 should be point sampling (and you must implement this). F>0 should be some better resampling options. Notice that for this part, pre-filtering for down-sampling is a bit trickier.

The basic version of this program does point sampling, and uses a “reverse warp” to make sure that no pixels are missed. (instead, you can do a forward warp, and use some technique to make sure no pixels are missed, but this is much harder).

Some features to add:

• Interpolation
• Pre-filtering
• Determining a good value for the pre-filter such that things aren’t blurred too much.

The basic version of this assignment does point sampling, and will earn a B.

Be sure to document the warping method you use, and how you do the sampling/pre-filtering.

Example Images: closer to the due date, we will provide a set of test images, and a set of parameters to try. Check back to find out what you should turn in. In the example image directory (p:/course/cs559-gleicher/public/2008ImagingTests) there are 2 test images for this part 2-1 and 2-2. For all the images you turn in for this part, just include the outputs, and use the best filtering you can.

2-1 is the same sample image as shown in ProgramImagingSamples (its called t0 there). Turn in the same 6 tests that are shown there (note: the first test is shown with the ski image). Name the output files 2-1-X.tga (where the X is the number of the trial:

    linearwarp 2-1.tga 2-1-1.tga N 200 200 .8 -.8 .8 .8 100 -50
    linearwarp 2-1.tga 2-1-2.tga N 100 100 1 0 0 1 0 0
    linearwarp 2-1.tga 2-1-3.tga N 100 100 .25 -.25 .25 .25 50 0
    linearwarp 2-1.tga 2-1-4.tga N 100 100 .25 .25 0 .5 0 0
    linearwarp 2-1.tga 2-1-5.tga N 200 200 .707 -.707 .707 .707 0 0
    linearwarp 2-1.tga 2-1-6.tga N 200 200 2 0 0 -2 -100 300

Replace N with the number for your best filter.

2-2 is a similar image to one of the resizing images. Hand in an image 2-2-1.tga made with the following parameters:

    linearwarp2 2-2.tga 2-2-1.tga N 256 256 1 0 .5 1 0 0

_Questions:_Answer the following questions in your README file:

1. Describe the algorithm that you used for performing the image warp.
2. Describe the filters that your algorithm implements (or the filtering that happens when your algorithm works).

5.@ 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 last year’s web.

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.

Example Images: you should turn in (at least) 2 examples. Close to the due date we will provide you with a test image (turn in the results of running your program on it). In the example image directory (p:/course/cs559-gleicher/public/2008ImagingTests) there are 3 test images for this part (3-1, 3-2, 3.3 - the third has a “big version”). You can pick any one of these three (or four, if you count the big version). You can turn in two if you’d like.

For your second example, pick some image that you really like the results on (not too big), and provide both the input image and the output image. If you have 1-2 other examples you really like, you can turn them in too.

Use the settings that you think make your program give the nicest results (if your program has options).

Questions: In your README file for this part, be sure to answer the following questions:

1. 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?)
2. What kinds of pictures does it tend to give nice results for?
3. What kinds of pictures does it not give nice results for?

6.@ Questions

For each program, we will provide a list of questions for you to answer in your documentation. These will be coming soon.

7.@ Mechanics

Each student in class must turn in their own projects (all parts).

Like all programming assignments (see the policy) in this class, your programs must build and run under Windows XP on the CSL computers. This means you should use Microsoft Visual Studio 2005.

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).

You may choose a different library for reading and writing the TGA images. However, you will be responsible for reading the sample images we provide (and providing images we can read). 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.

8.@ Some Hints

In previous years, we had students implement bunches of simple operations (like cropping), which weren’t very interesting and took a lot of time. However, implementing simple operations is good practice for implementing harder stuff later. So, we recommend trying to implement convolution (for blurring) before trying to take on something like painting.

Try getting the simple versions of all parts to work correctly before adding fancy features to anything.

We will provide simple sample solutions (executables only) so you can get a rough idea of what the programs do. They will only implement the basic functionality.

The linear warp is an affine transform. It can be written as a matrix equation:

    x' = ax + by + e       [ x' ]   [ a b e ] [ x ]
    y' = cx + dy + f       [ y' ] = [ c d f ] [ y ]
                           [ 1  ]   [ 0 0 1 ] [ 1 ]

So you can find the inverse of the affine transformation by inverting the matrix. 3x3 matrices have simple, closed form inverses that become really simple when the bottom row has zeros in it.