CSCI 200 - Foundational Programming Concepts & Design - A2

→This assignment is due by Tuesday, September 27, 2022, 11:59 PM.←
→ As with all assignments, this must be an individual effort and cannot be pair programmed. Any debugging assistance must follow the course collaboration policy and be cited in the comment header block for the assignment.←
→ Do not forget to complete the following labs with this set: L2A, L2B ←
→ Do not forget to complete zyBooks Assignment 2 for this set.←

· Instructions · Rubric ·Submission ·

For this assignment you will do some simple image processing to create some pretty cool effects! In the process, we'll work with functions in a procedural manner.

Colors

Computers represent colors as a combination of three individual colors: red, green, and blue. These values correspond to an additive color space in which some combination of red and green creates yellow. If you wish to know more about the RGB color space, head over to Wikipedia.

We will read in the contents of an image file, manipulate the colors, and write out the contents for a new image file.

PPM Image Format

An image is an ordered arrangement of pixels. The pixels are arranged into a 2D grid with some number of rows and columns. Each pixel is made up of a combination of red, green, and blue as described above.

There are many formats that an image can be represented in. PPM (Portable Pix Map) is one of the simplest image formats and all the image information is stored in an ASCII text file.

A sample PPM file is shown below as viewed in a text editor:

P3
4 4
255
  0 0   0   100   0   0   0  0   0   255   0 255
  0 0   0     0 255 175   0  0   0     0   0   0
  0 0   0     0   0   0   0 15 175     0   0   0
255 0 255     0   0   0   0  0   0   255 255 255

The first value denotes the type of the PPM image (plain ASCII format) - this will always be the characters P3 for our examples.

The next two values denote the width and height of the image - these will always be integers.

The next value denotes the maximum value of each color - this will always be an integer.

After that there will be height*width*3 values which correspond to the R G B values of each pixel in the image. The values are presented going across a row and then down the image.

The above example corresponds to the following image when viewed in an image viewing program:

If you open the same PPM file in VS Code, then you will see the ASCII text representation of the image. You need to open the file in an image editor to view the rendered version (either Preview on Mac or you can upload a file here to view it in a web browser).

Two PPM images for you to use are provided: wallpaper.ppm & brick.ppm. Below is the wallpaper image.

Instructions

For this assignment, we will write a program to read in a PPM file, manipulate it, and then output a new PPM file. A starter code pack has been provided. Download and extract the source code. The source code package contains several items:

input/ - folder containing sample PPM images to read.
output/ - empty folder to generate results into.
solutions/ - folder containing the expected results for the public test cases. Compare your results against the expected output to verify proper execution.
main.cpp - expected program execution. You will not submit nor edit this file. Your solution will need to conform to the expected flow. More details about program execution are given below.
Makefile - used to build program.

The contents of main.cpp are shown below:

/* CSCI 200: Assignment 2: A2 - PPM Image Editor
 *
 * Author: Dr. Jeffrey Paone
 *
 * Starting template to read a PPM file and alter the image.
 *
 * DO NOT EDIT THIS FILE
 */

#include "ppm_functions.h"

#include <fstream>
#include <iostream>
using namespace std;

int main() {
    // prompt the user to select which PPM file to open
    const int MAX_FILE_CHOICES = print_file_options();
    const int FILE_TO_OPEN = get_user_input(MAX_FILE_CHOICES);

    // prompt the user to select which image processing technique to perform
    const int MAX_OPERATION_CHOICES = print_operation_options();
    const int OPERATION_TO_PERFORM = get_user_input(MAX_OPERATION_CHOICES);

    // open the associated input PPM and output PPM
    ifstream ppmIn;
    ofstream ppmOut;
    if( !open_files(ppmIn, ppmOut, FILE_TO_OPEN, OPERATION_TO_PERFORM) ) {
        cerr << "Error opening files" << endl;
        return -1;
    }

    // read image information from input PPM
    int width = 0, height = 0, maxValue = 0;
    if( !read_header_information(ppmIn, width, height, maxValue) ) {
        cerr << "Invalid PPM type" << endl;
        return -2;
    }

    // write image information to output PPM
    write_header_information(ppmOut, width, height, maxValue);

    // perform image processing technique
    read_and_write_modified_pixels(ppmIn, ppmOut, OPERATION_TO_PERFORM, width, height, maxValue);

    // close & release both the input and output PPMs
    ppmIn.close();
    ppmOut.close();

    // exit successfully
    return 0;
}

Our program now reads as a set of steps to perform. The steps are described below and then the function interface to implement these steps follow afterwards.

Program Flow

The execution follows as below.

Begin by prompting the user for which image they wish to open.

Which image to load?
  1. Brick
  2. Wallpaper
  3. Private
Enter 1, 2, or 3: 2

Then prompt the user for which operation they wish to perform.

Which process to apply?
  1. Grayscale
  2. Inversion
Enter 1, or 2: 2

For both prompting scenarios, continue to prompt the user for a valid value if they provide something other than 1, 2, or 3 (a different number or potentially a character).

Once we have two valid inputs, open the corresponding input and output files (output file names are described below, be sure to place the files in the output folder). If either file cannot be found, kindly alert the user and gracefully end the program. This should be testable if you select option 3.

Now we're ready to start reading in the file and read the data!

We'll need to read the first four values (two characters and three integers) to know the information about our image. Upon reading the image type, validate we are reading a P3 image (there do exist other types, such as P1, P2, P4, P5, P6, & P7 ). If we have anything other than P3, then alert the user the image is of the wrong type and gracefully end the program.

Continue reading the remainder of the header (width, height, max value). Once read, write the corresponding information to the output file.

Once we have the width and height of the image, we can create nested for loops to read all the pixel data. For each row and for each column, read the corresponding red, green, and blue values. Verify that you are reading in the correct values (use the debugger!).

Regardless of the user choice, we will write out a new PPM file in the format specified above. Details on each manipulation are given below. When you write out the individual pixel color values to the file, apply the appropriate conversion to the corresponding pixel.

Convert to Grayscale

Name the new image file basefilename_grayscale.ppm. For instance, if the user entered wallpaper.ppm then you would create a new file named wallpaper_grayscale.ppm.

To convert a color to grayscale, we want to average the three RGB values together and create a new pixel where all three values are equal to the average. However, we don't want to just do (R+G+B)/3 because this doesn't model how the colors appear in real life. Instead, we will use a weighted average. Use the following equation to compute the grayscale intensity to apply for an individual pixel:

gray = 0.2989 * red + 0.5870 * green + 0.1140 * blue

The wallpaper image converted to grayscale is shown below.

Invert the colors

Name the new image file basefilename_inverted.ppm. For instance, if the user entered wallpaper.ppm then you would create a new file named wallpaper_inverted.ppm.

When we invert a color, we need to find its complement (hey, nice color!). This is done by subtracting each color component from the max possible value.

The wallpaper image with inverted colors is shown below.

Code Structure & Functions

We will want to implement this program in a procedural style using functions. These functions will be declared in a separate ppm_functions.h file with their implementations defined in a corresponding ppm_functions.cpp file. Create, and use, the following functions:

- Name: print_file_options()
- Input: None
- Output: integer number of options available
- Description: Prints the options menu for which file to open and returns the number of files that can be opened.
- Name: print_operation_options()
- Input: None
- Output: integer number of options available
- Description: Prints the options menu for which file processing to perform and returns the number of options that can be performed.
- Name: get_user_input()
- Input: maximum allowable integer value
- Output: integer value chosen
- Description: Prompts the user to enter a value. Validates the entered value is (a) numeric (b) within the inclusive range of [1, maximum]. If both (a) and (b) are satisfied, returns the value entered by the user. If (a) fails, clears the error and continues to prompt the user for a valid value. If (b) fails, continues to prompt the user for a valid value. In any case, be sure to remove any trailing input the user may have inadvertently included. (See hints section for test cases.)
- Name: open_files()
- Input: an ifstream object to open, an ofstream object to open, an integer corresponding to the file to open, an integer corresponding to the operation to perform
- Output: true if both files successfully opened, false otherwise
- Description: Opens the corresponding files for reading and writing based on the file and operation chosen. Verifies that both files successfully opened, returning true if so. Otherwise, if either file failed to open, returns false. (Hint: this can be tested by trying to open the private test file which doesn't exist in the starter pack.)
- Name: read_header_information()
- Input: an ifstream object to read from, integers corresponding to the width, height, & max value in the image passed by reference
- Output: true if valid type, false otherwise
- Description: Reads the header block of the file (the first four values). Returns true if the PPM type is P3, false otherwise. Upon completion, the parameters corresponding to the width, height, & maximum value will correspond to the values read from the image.
- Name: write_header_information()
- Input: an ofstream object to write to, integers corresponding to the width, height, & max value in the image
- Output: None
- Description: Writes the header block of the file (the first four values).
- Name: read_and_write_modified_pixels()
- Input: an ifstream object to read from, an ofstream object to write to, integers corresponding to the operation to perform and width, height, & max value in the image
- Output: None
- Description: Reads all the pixel data from the input file. For each pixel read, writes to the output file the modified pixel value based on the selected operation.

Hints

A full example interaction is below:

Which image to load?
  1. Brick
  2. Wallpaper
  3. Private
Enter 1, 2, or 3: t
Invalid input.
Enter 1, 2, or 3: 4
Invalid input.
Enter 1, 2, or 3: 1 3
Which process to apply?
  1. Grayscale
  2. Inversion
Enter 1, or 2: -11
Invalid input.
Enter 1, or 2: 1
Opening brick.ppm file
Writing brick_grayscale.ppm file

You'll want to follow the high level pseudocode given below:

Prompt user to input file
Prompt user to operation
Open input file
Open output file
For each pixel
- Read existing pixel color
- Compute new pixel color
- Write new pixel color

Take note that the read/eval/print steps all take place within the loop (giving us our REPL). These steps also largely correlate to the functions we are writing. Implement and test your functions one at a time.

Due to the procedural style, your main.cpp is nothing more than creating a few variables and then calling the functions in the appropriate order. All the specifics and details are abstracted away to ppm_functions.cpp.

! Extra Credit !

One of the benefits of using functions can be seen by the ability to extend the functionality of our program. For extra credit, add a third image processing operation to apply. This can be a known operation (mirror, rotation, pixelating, edge detection, blurring, channel manipulation/selection/filtering) or a new custom operation you've defined (this must be a non-trivial operation, if unsure if your idea is sufficient - ask). In order to accomplish this new task, nothing needs to change with the flow of our program - just with the implementation of a couple of our functions.

Best Practices To Follow

One clear and consistent coding style used (such as K&R, 1TBS, or Allman).
Course naming scheme is followed for variable, function, class, and other identifiers. See the course style guide for more specifics.
Code is self-documenting. Variables sensibly named, function names descriptive of their purpose.
Keep your headers clean. Put the absolute minimum required in your headers for your interface to be used. Anything that can go in a source file should. Don't #include any system headers in your .h files that aren't absolutely required in that file specifically. Avoid using namespace in headers.
Implement the Big-3 as appropriate.
Use const wherever possible:
- If you declare a variable that is never modified, it should be const.
- If your function takes a parameter and does not modify it, it should be const.
- If a member function does not modify the callee, it should be const.
- If you are pointing at a value that does not change, it should point at a constant value (e.g. const T*).
- If the pointer itself is never modified, it should be a constant pointer (e.g. T* const).
Don't leak memory. Every allocation using new needs to have a corresponding delete.
Use appropriate inheritance access. Only expose necessary members to derived classes.
Use override and final wherever possible and/or appropriate on derived classes.
Don't use global variables unless absolutely necessary. Instead, encapsulate them and design your interfaces effectively. If there is no way around using a global variable, be prepared to defend and justify its usage.
Program flow uses structural blocks (conditionals/loops) effectively, appropriately, and efficiently.
Code compiles and links without any errors or warnings.
Program runs without any run time errors. Exceptions are properly caught, user input is validated appropriately, and program exits successfully.

Grading Rubric

Your submission will be graded according to the following rubric.

Points	Requirement Description
10	All labs completed and submitted L2A, L2B
28	Each function input/output correct as specified and performs correct task meeting the functional requirements.
4	Function files structured appropriately.
+4	A2 Extra Credit Completed
2	Public input test files generate correct results.
1	Private input test file generates correct results.
5	Best practices are followed: +5 Code is easily readable, follows best practices, well structured +4 Code is easy to follow, only a few small violations of best practices +3 No egregiously bad practices +2 Lots of violations of best practices +1 Little effort to follow best practices +0 No effort to follow best practices
50	Total Points

Submission

Always, always, ALWAYS update the header comments at the top of your main.cpp file. And if you ever get stuck, remember that there is LOTS of help available.

It is critical that you follow these steps when submitting homework.

If you do not follow these instructions, your assignment will receive a major deduction. Why all the fuss? Because we have several hundred of these assignments to grade, and we use computer tools to automate as much of the process as possible. If you deviate from these instructions, our grading tools will not work.

Submission Instructions

Here are step-by-step instructions for submitting your homework properly:

Make sure you have the appropriate comment header block at the top of every source code file for this set. The header block should include the following information at a minimum.
```
/* CSCI 200: Assignment 2: A2 - PPM Image Editor
 *
 * Author: XXXX (INSERT_NAME)
 * Resources used (Office Hours, Tutoring, Other Students, etc & in what capacity):
 *     // list here any outside assistance you used/received while following the
 *     // CS@Mines Collaboration Policy and the Mines Academic Code of Honor
 *
 * XXXXXXXX (MORE_COMPLETE_DESCRIPTION_HERE)
 */
```
Be sure to fill in the appropriate information, including:
- Assignment number
- Assignment title
- Your name
- If you received any type of assistance (office hours - whose, tutoring - when), then list where/what/who gave you the assistance and describe the assistance received
- A description of the assignment task and what the code in this file accomplishes.
Additionally, update the Makefile for A2 to generate a target executable named A2.
File and folder names are extremely important in this process. Please double-check carefully, to ensure things are named correctly.
1. The top-level folder of your project must be named Set2
2. Inside Set2, create 3 sub-folders that are required for this Set. The name of each sub-folder is defined in that Set (e.g. L2A, L2B, and A2).
3. Copy your files into the subdirectories ofSet2 (steps 2-3), zip this Set2 folder (steps 4-5), and then submit the zipped file (steps 6-11) to Canvas.
4. For example, when you zip/submit Set2, there will be 3 sub-folders called L2A, L2B, and A2 inside the Set2 folder, and each of these sub-folders will have the associated files.
Using Windows Explorer (not to be confused with Internet Explorer), find the files named ppm_functions.h, ppm_functions.cpp.

STOP: Are you really sure you are viewing the correct assignment's folder?
Now, for A2, right click on ppm_functions.h, ppm_functions.cpp to copy the files. Then, return to the Set2/A2 folder and right click to paste the files. In other words, put a copy of your homework's ppm_functions.h, ppm_functions.cpp source code into the Set2/A2 folder.

Follow the same steps for each lab to put a copy of each lab's deliverable into the Set2/L2 folders. Do this process for Set2/L2A (main.cpp, Makefile), Set2/L2B (coordinate_conversion.h, coordinate_conversion.cpp, main.cpp, Makefile).

STOP: Are you sure your Set2 folder now has all your code to submit?

The structure of the submission is as follows:
- Set2/
  - A2/
    - ppm_functions.h
    - ppm_functions.cpp
  - L2A/
    - main.cpp
    - Makefile
  - L2B/
    - coordinate_conversion.h
    - coordinate_conversion.cpp
    - main.cpp
    - Makefile
Now, right-click on the "Set2" folder.
1. In the pop-up menu that opens, move the mouse "Send to..." and expand the sub-menu.
2. In the sub-menu that opens, select "Compressed (zipped) folder".
STOP: Are you really sure you are zipping a Set2 folder with sub-folders that each contain a main.cpp file in it?
After the previous step, you should now see a "Set2.zip" file.
Now visit the Canvas page for this course and click the "Assignments" button in the sidebar.
Find Set2, click on it, find the "Submit Assignment" area, and then click the "Choose File" button.
Find the "Set2.zip" file created earlier and click the "Open" button.

STOP: Are you really sure you are selecting the right homework assignment? Are you double-sure?
WAIT! There's one more super-important step. Click on the blue "Submit Assignment" button to submit your homework.
No, really, make sure you click the "Submit Assignment" button to actually submit your homework. Clicking the "Choose File" button in the previous step kind of makes it feel like you're done, but you must click the Submit button as well! And you must allow the file time to upload before you turn off your computer!
Canvas should say "Submitted!". Click "Submission Details" and you can download the zip file you just submitted. In other words, verify you submitted what you think you submitted!

In summary, you must zip the "Set2" folder and only the "Set2" folder, this zip folder must have several sub-folders, you must name all these folders correctly, you must submit the correct zip file for this homework, and you must click the "Submit Assignment" button. Not doing these steps is like bringing your homework to class but forgetting to hand it in. No concessions will be made for incorrectly submitted work. If you incorrectly submit your homework, we will not be able to give you full credit. And that makes us unhappy.