Project 1 - A Picture Processing System (100 points)
The goal of this project is to give you experience writing programs that manipulate digital pictures. This project should make some of the theory we discuss in class (sampling, compositing, ...) more concrete, give you some experience with the pragmatic issues of image programming, and (potentially) give you a chance to learn about some topics we don't get time to discuss in class. And, we'll hopefully let you have some fun making pictures with your program.
The main part of the assignment will be to write a "picture processing" program that reads in a simple scripting language that tells it how to read, manipulate, and write images. The "meat" of this is to write the image manipulation functions. In fact, we'll give you sample code that takes care of most of the rest.
However, rather than just dumping the whole project on you at once, we have a series of stages to make sure you make steady progress:
We recommend that you read over the whole project before diving in to any part of it, although some parts of the description will be made available later. With a little planning, the work that you do in the earlier parts of the project will be useful on later parts.
The picture processor is a program that reads a sequence of commands, each describing a picture processing function. You can think of it as an interpreter for a very simple language. Your final program should take a single command line argument that is a name of the script file. For testing, we recommend that if your program is not given a command line argument that it takes commands from the standard input. (hint: to make an end-of-file to the standard input, hit CTRL-Z).
The "script language" is very simple:
Note that there is no (required) graphical user interface. The program reads and writes TGA files, and you can use some viewer program to look at the results.
Here is an example script:
read a p:/course/cs559-lizhang/public/TGAs/i1.tga blur a 3 write a i1-blurred.tga blank b 100 100 fill b 0 0 99 99 255 0 0 composite a over b 10 10 write b i1-framed.tga
This script reads a picture into variable A, blurs it, and then writes it out. It then creates a new blank image and puts it into variable B, fills the image with a red color, composites A over B (which changes B), and then writes out image B.
The language is very simple - we will provide example code to help you interpret it. The "meat" of the assignment is writing the image processing code that is executed by the commands.
There are three different types of commands that you will need to have implemented:
It is important to get the basic stuff right, since it gives the infrastructure for using the harder stuff. We'll give you example code that implements a lot of the basic stuff - you can either use it as a base for your project, or you can do everything from scratch. We'll also give you a demonstration project to play with so you can see what your project is supposed to do.
We'll give you an executable for an example solution so that you can try it out. We'll also provide a bunch of example scripts.
We'll actually give you a lot of example code to get started with.
The first thing you should do (if you haven't already) is figure out how to write programs using Visual Studio 2005 under windows. If you go to the main tutorials page, there are some guides there.
To read and write .tga files, we strongly recommend that you use our LibTarga library. The library is available here. If you don't use LibTarga, remember that we define the targa format to mean what LibTargadoes - if you use something that is inconsistent with LibTarga, its wrong.
We also have
provided a C++ wrapper for LibTarga called TargaImage.
We recommend that you use it. There is a tutorial on
getting started with it here,
and there is documentation for it here.
Since this is a pretty big project, we'll give you a large piece of our sample solution to use. Its designed such that you can use it, and just add new pieces to it. We've taken care of a lot of the boring parts (like parsing the scripting language). The sample solution is presented here.
You are not required to build off of the sample solution. However, it will probably save you a lot of time by starting with it.
This project has 4 parts and contributes 25% to your final grade.
What you turn in for earlier stages will also effect your grade for this project. Both directly (because it counts) and indirectly (because if you can't do the preliminary parts, you'll have problems later on).
The main part of the grading will be for you final project deliverable. We will have a demo session where you will demonstrate your program, we may test your program ourselves, and we will read over what you have handed in.
You will have a variety of options for what features to implement. In general, you will get a better grade for implementing more (and more challenging) features. However, it is more important to implement what you do correctly. It is better to do a correct and well-documented implementation of a basic assignment than to have a partially working and/or poorly documented implementation of more complex stuff.
You will not get points for re-implementing the functionality of the example code. Its probably best if you use it - it will save you a lot of time.
The generic principles for project grading are described here.
As part of the assignment you will need to turn in some example images made using your program. Your artistic skill in creating these will not be considered as part of your grade, however, we will give prizes for the most interesting images.
Every year in 559, we give an "image processing" assignment. The last time that we a script driven compositing system was in Fall of 2001, and students liked it - you can see a gallery of pictures students made here and an here (the latter gallery the challenge was to "make a picture of yourself in a place you've never been or with a person you've never met).
In the past few years, we asked students to simply implement 4 different image processing functions. This was boring. The old project was more fun, so we're bringing it back.
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 Storm computers in Room 1366 CS. 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.
Specific details on turning in each part will be described in the documentation for that part. Specific details on late policies will also be described for each part.
The purpose of this phase of the project is to make sure that you have gotten the mechanics issues dealt with, have gotten the necessary tools to write programs in the class, and have actually started working on things.
By the due date, you should turn in (that is copy to your handin directory P1-S1 - part of the goal here is to make sure that you can turn stuff in and that we have the directories made correctly):
We just want to make sure you have tried writing doing some programming on the PC, and that you can turn in things correctly so that we can rebuild it with no extras. You can look at the tutorials or even the Project Sample Code for advice on getting started.
You should turn your program in into the P1-S1 directory in your handin folder
How will this be graded? Your picture has 2 points and the the fill command has 3 points. While 5 points may not sound much, we suggest you take them seriously. Don't expect us to have much sympathy if 3 weeks into the project you need help getting the compiler to work. If you do turn things in a timely fashion, we'll check and make sure you've turned in the right files, etc.
The purpose of this phase is to make sure that you are actually started writing image processing code.
By the due date, you should turn in a program (or 2 programs if you prefer) that perform 2 image processing operations: desaturate and blur. The blur should be able to do (at least) a 3x3 and a 5x5 convolution with a blur kernel (like a BSpline), and desaturation should be able to desaturate the colors by 30% (or an arbitrary amount specified by the user, providing the user can input 30%). The program(s) should be able to read in a TGA image, apply an image processing operation, and write the result out. Desaturation is rdescribed under the command description for your final project.
You should turn in a version of the final picture processor that has the read, write, blur, and desaturate commands implemented (these are part of the final assignment).
If you're
building from the sample
solution (which is highly
recommended), all you need to do is write theblur and desaturate commands
(and turn things in correctly - you should turn in all of the project source,
including the code, solution, and project files we gave you.
You should turn your program in into the P1-S2 directory in your handin folder.
How will this be graded? - Each function contributes 5 points. We will look at your code to make sure that it seems to do what its supposed to. Basically, we need to be able to identify where in your code the important operations are happening. This will allow us to give you feedback on your code so you'll know how we're grading things later.
This written homework, including handin instructions, is available here.
This stage contributes 18 points.
This is where you turn in the whole final thing. Your handin must include:
This stage contributes 67 points. (All the commands have 80 points, 13 of which should have been finished in stage 1 and 2.)
On one hand, we'd like to tell you not to worry about how fast your programs are. We'd like you to focus on learning to do the image processing correctly. Learning to do it fast is another story. There's a famous quote that says "Premature optimization is the root of all evil" - that might be a little bit strong, but it makes the point.
On the other hand, if your program is so slow that you can't show that it works correctly, you have a different kind of problem. Because picture processing can require a lot of computation (and a lot of memory accesses), it can be slow if you're not careful.
So for this assignment: don't worry about efficiency too much. The Storm computers in Room 1366 CS are fast enough that unless you program in a really strange way, your programs will be "fast enough". If your program takes more than a few seconds on a "reasonably sized" image (less than 500 pixels on a side), then you should probably think about efficiency. Complex operations, such as impressionist painting, might take a bit longer.
For this assignment, you might decide that it is easier to do all of your computations in floating point. It certainly makes writing the image processing code easier, and on modern processors the floating point arithmetic is fast. It is possible to do this assignment in floating point and have it be fast enough. (one hint: converting between floating point and fixed point is sometimes slow, so avoid doing too many conversions).
The picture processing commands are detailed on another page.
Your program must provide all of the required commands. And during the demo, you'll have the opportunity to show us all of the cool ones you've added.