- Overview and Objectives
- The Basics: What is this thing anyway?
- Getting Started
- Grading Overview
- Historical notes
- The parts of the project
- Stage 1 (5 points) - some preliminary mechanics (due
Monday noon, Feb 4)
- Stage 2 (10 points) - signs of life checkpoint (due
Monday noon, Feb 11)
- Stage 3 (18 points) - theoretical background (due Monday
noon Feb 18)
- Stage 4 (67 points) - final project deliverable (due
Monday noon Feb 25)
- A Note on Efficiency
- The Picture Processing Functions
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.
than just dumping the whole project on you at once, we have a series of stages
to make sure you make steady progress:
- Stage 1 - some preliminary mechanics (due Monday noon, Feb 4)
- Stage 2 - signs of life checkpoint (due Monday noon, Feb 11)
- Stage 3 - theoretical background (due Monday noon Feb 18)
- Stage 4 - final project deliverable (due Monday noon Feb 25)
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).
language" is very simple:
- Each command is a single line
- Words on each line are separated by spaces (warning: this means that
spaces in filenames cannot be handled!)
- The first word on each line is a "verb" describing the command
- Each command interprets the rest of the words on the line as it wants to.
- The language should not be case sensitive.
- Variables in the language are single letters. In the example scripts we
give you, we will only use variables A-F.
- We will tell you some required commands (elsewhere), but you can add
additional ones. The required commands must work as specified (so you can run
the sample and testing scripts)
- A "#" represents a comment. Anything on a line following this character is
- Blank lines are OK.
- Your program should "garbage collect" - when a variable is over written,
the old contents should be deleted.
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
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
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
There are three
different types of commands that you will need to have implemented:
- Basic image management (reading, writing, making blank images, cropping,
fill, ...) - these should be easy, but are good practice for just working with
- Simple image processing (blur, darken, ...) - again, these should be easy,
but are good practice and important for making the program useful.
- Harder image operations (resize, composite, warp, impressionist paint,
...) - these are the real meat of the assignment. In a sense everything else
is just to work up to these.
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
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,
We also have
provided a C++ wrapper for LibTarga called
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.
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
Each student in class must turn
in their own projects (all parts).
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.
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
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):
command, among all the commends
you will need to finish
- a TGA image with a picture of yourself (send email to Chi Man if you want the
picture he took of you to start with). The image must be 200x300, and must
have an alpha channel. Some of the background should have alpha of zero, and
you should have alpha of one. Don't worry about making a clean cutout (unless
you want to). We're mainly concerned that you are able to find and use tools
for making test images. Check out the tutorial
on how to make these cutout images.
- finish the
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
You should turn
your program in into the P1-S1 directory in your handin folder
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
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).
building from the sample
solution (which is highly
recommended), all you need to do is write the
(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.
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:
- All code required to build your picture processor program. This includes
the source code and the project files (.sln and .vcproj) but not the binaries.
- Documentation. You will need to have documentation that explains the
commands that your program accepts, and discusses the methods that you
implemented. Specific things that need to be documented are listed in the
- Example images and scripts. You should turn in a set of up to 5 example
images named login-1.tga, login-2.tga, ... These images should be things that
show off what your program can do, and have "artistic merit." You should also
turn in an image where you use compositing to create a picture of yourself in
a place you've never been, or with a person you've never met. This image
should be named login-me.tga. (in all cases replace login with your cs login).
For each image you turn in, you should also turn in the script (name it with
.txt instead of .tga). You should also have a README-PICTURES.txt file that
explains how you made the pictures. We will be putting your result images on
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
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.
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
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.