IC210: Project 1

Introduction: Green Screen

Almost certainly, you're familiar with green screening, where a plain green background is replaced with some other image. The most common example is weather maps on the news - you'll never see a weather person wearing green clothes, or they would disappear.

In this project, we're going to do some green screening, combining a background from one picture with a foreground from another.

For example, consider a picture of Bill the Goat (on the left below). He deserves to be someplace nice. So, for every pixel that is green, we'll replace it with the corresponding pixel from the image in the middle below, giving us the image on the right below.


foreground picture	background picture	combined picture

Honor

The course policy and the instructions it references, most pertinently COMPSCIDEPTINST 1531.1C, spell out what kinds of assistance are permissible for programming projects. The instructor can give explicit permission for things that would otherwise not be allowed.

For this project, you have explicit permission

to get help from your instructor or from current IC210 MGSP leaders (any assistance must be documented though), and
to use general purpose C++ resources online (though such use must be documented). Resources that might specifically address this project are not allowed.

With the instructions referenced in the course policy and the explicit permissions above, what you get is summarized as:

You cannot provide help to any IC210 students on this project.
In no circumstancel may you copy code and submit it as your own work. That is the definition of plagiarism.
For projects, you may not look at other people's project code nor may you show your own code to others.
You can not look at online resources for help that is specific to the functionality required of your project.

Warning: Do not even vaguely talk about the contents of the project with your colleagues.

If you have questions about any of these rules, email your instructor and ask about it.

Submitting Your Work

Code submission: Submit your code with the command
~/bin/submit -c=IC210 -p=proj01 *.cpp
Cover sheet submission: Fill out the coversheet and submit it in class (see the deadlines above).

Deadlines

Code submission:
- Parts 1 and 2: Due 0800 on Monday, Sep 23.
  You must pass all test cases in the submission server for Parts 1 and 2.
- The full project: Due 2359 on Wednesday, Oct 2.
Coversheet submission:
- Bring it to class on Thursday, Oct 3.

Early bonus and late penalty

For Part 1
- 5% penalty for any late submissions.
For the final project:
- 1 day early: 5% bonus
- 1 day late: 10% penalty
- 2 or more days late: 100% penalty
If you submit your coversheet late: 2% penalty

Grading

70% of your grade will be based on functionality (i.e., whether your program works as specified), mostly based on the test cases that you see when you submit, but perhaps also extra test cases according to the specifications of the project. The code you submit must work if you expect to earn a passing grade.

30% of your grade will be based on coding style, which includes:

Readability: You should use good spacing and proper indentation, and avoid long lines longer than 80 characters.
Documentation: Use meaningful variable names and write helpful comments to make it obvious what your code is doing.
Organization: Use your tools wisely! Do not use unnecessary conditions or loops. This is about the "art" of programming, beyond just "getting it to work".

Calculation

All of this is factored into your maximum score based on which part you have completed. So for example:

Suppose that you complete up to part 4. So, your work would be scored up to 85 points.
Suppose that your code works perfectly. So, you earn the full functionality score (i.e., 70%).
Suppose that you get 22% (out of 30%) for the coding style.
Suppose that you turn in the final project 24 hours early.

Then, your final grade would be grade would be 85*(0.70+0.22)*1.05 = 82.11.

Tips for success

Start early! Because programming is such a creative progress, it's notoriously difficult to predict how long ANY programming project will take you to complete. If you start early, the worst that can happen is you finish early and get to relax.
Work deliberately, stopping frequently to recompile and test what you have so far. This is the best way to catch problems early and easily.
Start small. Don't go for the big example right away. Instead, use a smaller debugging example that you can follow completely, so that you can check your work.
Writing good documentation, variable names, etc., as you go along is always easier than trying to add it in at the end.

Part 1: Understanding ppm image format (30/100)

Project files

Download proj01files.tgz. Extract the project files by running following the command in the terminal:

tar -xvf proj01files.tgz

Understanding PPM format

In this project, to manipulate the pixels of images easily, we're going to use a horribly space-inefficient image file format called "plain PPM."

The project files contain a bunch of PPM files that you can use. For example, open bg.ppm in a text editor (i.e., vi, emacs, or atom), you'll see something that looks like this:

P3 6 5 255 0 255 0 255 0 0 0 255 0 255 0 0 0 255 0 255 0 0 255 0 0 255 0 0 255 0 0 255 0 0 255 0 0 255 0 0 0 255 0 0 255 0 0 255 0 0 255 0 0 255 0 0 255 0 0 0 255 0 0 255 0 0 255 0 0 255 0 0 255 0 0 255 255 255 0 255 255 0 255 255 0 255 255 0 255 255 0 255 255 0

file_header = P3 width=6 height=5 largest_possible_value=255 6 pixels: (r 0, g 255, b 0) ... 6 pixels: (r 255, g 0, b 0) ... 6 pixels: (r 0, g 255, b 0) ... 6 pixels: (r 0, g 0, b 255) ... 6 pixels: (r 255, g 255, b 0) ...

The P3 is the "magic number" or file header, which tells the computer what the format is (remember this from SY110?).
6 is the width of the image in pixels, and 5 is the height of the image in pixels.
255 is the largest possible value of all the trailing numbers.
The remainder describe the red, green, and blue values of each pixel in turn.
- The first three numbers after the max value are 0 255 0, meaning no red, the strongest possible green, and no blue.
- The second pixel is (255, 0, 0), and so on.

Every PPM file must be in this format.

Viewing a PPM image

To view a PPM image on your Linux machine, use the command:

eog mule.ppm

Of course, you can specify any other ppm file instead of mule.ppm

Your task: readppm.cpp

Write a program in a file called readppm.cpp. The program should first prompt the user for the filename of an existing PPM image. Then, it should print out the contents of the image as shown on the right. In particular, for each pixel, your program should provide its row and column position in the image.

An example run (with user input colored in red):

~$ ./readppm
Input file: bg.ppm
P3
width = 6, height = 5
max value = 255
*** row 0 ***
row 0, col 0: r0 g255 b0
row 0, col 1: r255 g0 b0
row 0, col 2: r0 g255 b0
row 0, col 3: r255 g0 b0
row 0, col 4: r0 g255 b0
row 0, col 5: r255 g0 b0
*** row 1 ***
row 1, col 0: r255 g0 b0
row 1, col 1: r255 g0 b0
row 1, col 2: r255 g0 b0
row 1, col 3: r255 g0 b0
row 1, col 4: r255 g0 b0
row 1, col 5: r255 g0 b0
*** row 2 ***
row 2, col 0: r0 g255 b0
row 2, col 1: r0 g255 b0
row 2, col 2: r0 g255 b0
row 2, col 3: r0 g255 b0
row 2, col 4: r0 g255 b0
row 2, col 5: r0 g255 b0
*** row 3 ***
row 3, col 0: r0 g0 b255
row 3, col 1: r0 g0 b255
row 3, col 2: r0 g0 b255
row 3, col 3: r0 g0 b255
row 3, col 4: r0 g0 b255
row 3, col 5: r0 g0 b255
*** row 4 ***
row 4, col 0: r255 g255 b0
row 4, col 1: r255 g255 b0
row 4, col 2: r255 g255 b0
row 4, col 3: r255 g255 b0
row 4, col 4: r255 g255 b0
row 4, col 5: r255 g255 b0

Part 2: Grayscale an image (50/100)

To get used to the PPM format more, let's make an image grayscale (black and white).

Write a program in a file called gray.cpp:

It prompts the user first for the filename of an existing PPM image, then for the filename the user would like his grayscale version to be called.
The program then creates the new image, which is the gray version of the one read in.

Tip: To find the gray value of a pixel, take the r, g, and b values, average them (to an integer with fractions truncated), and set all three values to that number. So, the gray version of (5, 100, 16) would be (40, 40, 40).

As an example, running this program on our picture of flowers gives us a picture on the right.

Note: If the input file to be read in does not exist, the program should print an error message and gracefully exit. Example runs of the program are shown here (with user input colored in red):

~$ ./gray
Input file: bg.ppm
Output file: graybg.ppm
Image saved to graybg.ppm

~$ ./gray
Input file: flowers.ppm
Output file: grayflowers.ppm
Image saved to grayflowers.ppm

~$ ./gray
Input file: nonexisting.ppm
Output file: output.ppm
Error: Input file not found

Checking if your output is correct

The correct output ppm files for bg.ppm and folowers.ppm are provided in proj01files.tgz. In particular:

The output ppm file graybg.ppm from your code should be the same as test_graybg.ppm in proj01files.tgz.
Likewise, you can check your output grayflowers.ppm against the provided file test_grayflowers.ppm.

Do as follows in order to check the correctness of your code:

Change the permission of the script to be executable (also found in proj01files.tgz):
```
~/$ chmod 700 diff.sh
```
Make sure that your readppm compiles and works correctly (the script diff.sh uses your readppm).
```
~/$ g++ readppm.cpp -o readppm
```

Use the script to see if your output file is the same as the corresponding test data.

~/$ ./diff.sh graybg.ppm test_graybg.ppm
~/$ ./diff.sh grayflowers.ppm test_grayflowers.ppm

Part 3: Combine images (70/100)

In this part, we'll do the part described in the introduction. In particular:

Consider, for example, a picture of Bill the Goat (on the left below).
For every pixel that is green, we'll replace it with the corresponding pixel from the background image (in the middle below).
The combined output image is shown on the right below.

Example runs of the program (with user input red):

~$ ./green
Foreground file: fg.ppm
Background file: bg.ppm
Output file: fgbg.ppm
Image saved to fgbg.ppm

~$ ./green
Foreground file: bill.ppm
Background file: flowers.ppm
Output file: billflowers.ppm
Image saved to billflowers.ppm

~$ ./green
Foreground file: fg.ppm
Background file: flowers.ppm
Output file: fgflowers.ppm
Error: Images have different sizes

~$ ./green
Foreground file: bill.ppm
Background file: nonexisting.ppm
Output file: billflowers.ppm
Error: Input file not found

Your program should be in a file called green.cpp.

Your program should prompt the user

first for the foreground image (our picture of Bill, with the green),
then the background image (the flowered hillside), and
finally the filename of the produced, combined image.

Your program should work for any two images that are the same size as each other. If the foreground and background images are not the same size, your program should output an error message.

If one of the two files to be read in don't exist, the program should print an error message and gracefully exit.

Note: A one-pixel wide green border around your foreground subject is fine.

Checking your output with test vectors

Use the script to see if your output file is the same as the test data.

 ./diff.sh fgbg.ppm test_fgbg.ppm

 ./diff.sh billflowers.ppm test_billflowers.ppm

Part 4: Move down the foreground image (85/100)

The problem with our program so far is that it only accepts pictures that are the same size. What if we want Bill somewhere other than in the middle of the picture? Some pictures in the tarball you downloaded are cropped (i.e., fgc.ppm, billc.ppm, bbillc.ppm, and mulec.ppm), so we should be able to put them anywhere in a picture that is at least as big as they are.

Write a program in a file called rowshift.cpp that prompts the user for:

a foreground image, a background image, a row shift, and the output image

Example pictures illustrating how the row shift works:

row shift=0

row shift=100

Example runs of the program (with user input red):

~$ ./rowshift
Foreground file: fgc.ppm
Background file: bg.ppm
Row shift: 1
Output file: fb_1.ppm
Image saved to fb_1.ppm

~$ ./rowshift
Foreground file: billc.ppm
Background file: flowers.ppm
Row shift: 100
Output file: bf_100.ppm
Image saved to bf_100.ppm

~$ ./rowshift
Foreground file: billc.ppm
Background file: nonexisting.ppm
Row shift: 100
Output file: bf_100.ppm
Error: Input file not found

~$ ./rowshift
Foreground file: billc.ppm
Background file: flowers.ppm
Row shift: 1200
Output file: bf_1200.ppm
Error: The foreground goes past the background

Read carefully (if necessary many times)

Let rs be a row shift.

For the first rs rows, no green screening should be performed (do you see why?). In particular:
- Only the background figure pixels should be read and stored into the output figure.
- To reiterate, the foreground figure pixels should not be read here, yet!!
For the next fg_height rows, the program should perform the green screening.
- Be careful about the pixels represented with the red dot (labeled ???) on the right, though. Like the first rs rows above, the program should not perform green screening in those regions.

If the given row shift is so large that the foreground image would extend past the background image, an error message should be given, and no output image created. In addition, if one of the two images input does not exist, the program should print an error message and gracefully exit.

Checking your output

First, check if your program runs correctly for the first example test case. Your program should create fb_1.ppm (recall: rowshift = 1) that should be analyzed by readppm as follows.

You have to clearly understand why fb_1.ppm should look as follows.
Focus on the first three columns of rows 1 and 2 in the background and output file.

~/$ ./readppm
Input file: fgc.ppm
P3
width = 3, height = 2
max value = 255
*** row 0 ***
row 0, col 0: r0 g255 b0
row 0, col 1: r0 g255 b0
row 0, col 2: r127 g127 b127
*** row 1 ***
row 1, col 0: r127 g127 b127
row 1, col 1: r127 g127 b127
row 1, col 2: r0 g255 b0

~/$ ./readppm
Input file: bg.ppm
P3
width = 6, height = 5
max value = 255
*** row 0 ***
row 0, col 0: r0 g255 b0
row 0, col 1: r255 g0 b0
row 0, col 2: r0 g255 b0
row 0, col 3: r255 g0 b0
row 0, col 4: r0 g255 b0
row 0, col 5: r255 g0 b0
*** row 1 ***
row 1, col 0: r255 g0 b0
row 1, col 1: r255 g0 b0
row 1, col 2: r255 g0 b0
row 1, col 3: r255 g0 b0
row 1, col 4: r255 g0 b0
row 1, col 5: r255 g0 b0
*** row 2 ***
row 2, col 0: r0 g255 b0
row 2, col 1: r0 g255 b0
row 2, col 2: r0 g255 b0
row 2, col 3: r0 g255 b0
row 2, col 4: r0 g255 b0
row 2, col 5: r0 g255 b0
*** row 3 ***
row 3, col 0: r0 g0 b255
row 3, col 1: r0 g0 b255
row 3, col 2: r0 g0 b255
row 3, col 3: r0 g0 b255
row 3, col 4: r0 g0 b255
row 3, col 5: r0 g0 b255
*** row 4 ***
row 4, col 0: r255 g255 b0
row 4, col 1: r255 g255 b0
row 4, col 2: r255 g255 b0
row 4, col 3: r255 g255 b0
row 4, col 4: r255 g255 b0
row 4, col 5: r255 g255 b0

~/$ ./readppm
Input file: fb_1.ppm
P3
width = 6, height = 5
max value = 255
*** row 0 ***
row 0, col 0: r0 g255 b0
row 0, col 1: r255 g0 b0
row 0, col 2: r0 g255 b0
row 0, col 3: r255 g0 b0
row 0, col 4: r0 g255 b0
row 0, col 5: r255 g0 b0
*** row 1 ***
row 1, col 0: r255 g0 b0
row 1, col 1: r255 g0 b0
row 1, col 2: r127 g127 b127
row 1, col 3: r255 g0 b0
row 1, col 4: r255 g0 b0
row 1, col 5: r255 g0 b0
*** row 2 ***
row 2, col 0: r127 g127 b127
row 2, col 1: r127 g127 b127
row 2, col 2: r0 g255 b0
row 2, col 3: r0 g255 b0
row 2, col 4: r0 g255 b0
row 2, col 5: r0 g255 b0
*** row 3 ***
row 3, col 0: r0 g0 b255
row 3, col 1: r0 g0 b255
row 3, col 2: r0 g0 b255
row 3, col 3: r0 g0 b255
row 3, col 4: r0 g0 b255
row 3, col 5: r0 g0 b255
*** row 4 ***
row 4, col 0: r255 g255 b0
row 4, col 1: r255 g255 b0
row 4, col 2: r255 g255 b0
row 4, col 3: r255 g255 b0
row 4, col 4: r255 g255 b0
row 4, col 5: r255 g255 b0

Checking your output with the test vectors

Use the script to see if your output file is the same as the test data.

 ./diff.sh fb_1.ppm test_fb_1.ppm

 ./diff.sh bf_100.ppm test_bf_100.ppm

Part 5: Fully offset foreground image (100/100)

Example runs of the program (with user input red):

~$ ./shift
Foreground file: fgc.ppm
Background file: bg.ppm
Row shift: 1
Column shift: 2
Output file: fb_1_2.ppm
Image saved to fb_1_2.ppm

Foreground file: billc.ppm
Background file: flowers.ppm
Row shift: 100
Column shift: 400
Output file: bf_100_400.ppm
Image saved to bf_100_400.ppm

~$ ./shift
Foreground file: billc.ppm
Background file: nonexisting.ppm
Row shift: 100
Column shift: 200
Output file: bf_100_200.ppm
Error: Input file not found

~$ ./shift
Foreground file: billc.ppm
Background file: flowers.ppm
Row shift: 0
Column shift: 1200
Output file: bf_0_1200.ppm
Error: The foreground goes past the background

Write a program in a file called shift.cpp that prompts the user for:

a foreground image, a background image, a row shift, a column shift, and the output image

Example pictures illustrating how the row shift and column shift work:

row shift=0, column shift=0

row shift=0, column shift=450

row shift=100, column shift=0

Tips

As with the previous part, you need to be careful about when not to perform green screening.

If the given row shift or column shift is so large that the foreground image would extend past the background image, an error message should be given, and no output image created. In addition, if one of the two images input does not exist, the program should print an error message and gracefully exit.

Checking your output with test vectors

Use the script to see if your output file is the same as the test data.

 ./diff.sh fb_1_2.ppm test_fb_1_2.ppm

 ./diff.sh bf_100_400.ppm test_bf_100_400.ppm