From CS559 Computer Graphics Fall 2007

Main: P1

This is a preliminary version - things are subject to change (but I expect the only things will be the additions of details that aren't here yet). Major modifications will be announced at the top (i.e. here).

Project 1 - A Picture Processing System

On this page... (hide)

  1. 1. Overview and Objectives
    1. 1.1 The Basics: What is this thing anyway?
    2. 1.2 Getting Started
    3. 1.3 Grading Overview
    4. 1.4 Historical notes
  2. 2. Mechanics
  3. 3. The parts of the project
    1. 3.1 Stage 1 - some preliminary mechanics (due Monday, Sept 17)
    2. 3.2 Stage 2 - signs of life checkpoint (due Monday, Sept 24)
    3. 3.3 Stage 3 - theoretical background (due Monday Oct 1)
    4. 3.4 Stage 4 - final project deliverable (due Monday Oct 8)
  4. 4. A Note on Efficiency
  5. 5. The Picture Processing Functions
  6. 6. Scoring

1.  Overview and Objectives

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, athough 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.

1.1  The Basics: What is this thing anyway?

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-gleicher/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
crop a 10 10 80 80
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, cuts A to a smaller size, composites it 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.

1.2  Getting Started

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 LibTarga does - 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.

1.3  Grading Overview

You will receive one overall grade for this project - the work in each stage will contribute to this.

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.

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

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.

1.4  Historical notes

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.

2.  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 Storm computers in B240 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.

3.  The parts of the project

3.1  Stage 1 - some preliminary mechanics (due Monday, Sept 17)

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 (Monday, Sept 17), you should turn in (that is copy to your handin directory P1-Stage1 - part of the goal here is to make sure that you can turn stuff in and that we have the directories made correctly):

How will this be graded? It won't - we're not even going to check. If you don't figure this stuff out, we'll find out soon enough. However, 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 (in a relatively timely fashion), we'll check and make sure you've turned in the right files, etc.

3.2  Stage 2 - signs of life checkpoint (due Monday, Sept 24)

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 can 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). Or you can write seperate programs that somehow pick what the input and output files are (see http://www.cs.wisc.edu/graphics/Courses/559-f2006/Assignments/P2 for an example).

If you're building from the sample solution (which is highly recommended), all you need to do is write the blur 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-Stage2 directory in your handin folder.

How will this be graded? - We won't actually test your program. These functions will be tested as part of your final project. However, 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.

3.3  Stage 3 - theoretical background (due Monday Oct 1)

This written homework, including handin instructions, is available here.

3.4  Stage 4 - final project deliverable (due Monday Oct 8)

This is where you turn in the whole final thing. Your handin must include:

There will be a stage 4 checklist that details what you need to turn in, and what you need to be sure that your program does.

4.  A Note on Efficiency

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

5.  The Picture Processing Functions

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.

6.  Scoring

Closer to the project due date (sometime during or before the week of Oct 1-5), we'll give you more precise information on how much the different commands are worth.

Retrieved from http://www.cs.wisc.edu/graphics/Courses/559-f2007/Main/P1
Page last modified on September 17, 2007, at 10:41 AM