CSCI 261 - Programming Concepts - A5 - Wavefront OBJ File Validator

→This assignment is due by Tuesday, October 26, 2021 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: L5A, L5B, L5C ←
→ Do not forget to complete the APT for this set.←

· Instructions · Rubric · Submission ·

In Computer Graphics, it is very common to store a complex model in an external text file. The graphics program then reads and parses the text file to generate a rendered image of the model. Your task for this assignment is to read in a simplified Wavefront OBJ file and validate if it would correctly form a model.

Wavefront OBJ File Format

The actual Wavefront OBJ file format is quite complex, so we will be working with a simplified subset of its features. In the OBJ file, the first value on each line dictates what type of record the line is storing. The remaining format and interpretation of the line is determined by the first value. An example is below:

# this is a comment
# this makes a triangle
v 0.0 0.0 0.0
v 1.0 0.0 0.0
v 0.0 1.5 0.0
f 1 2 3

Our file can be made up of three different types of lines, outlined below:

COMMENT
A comment line begins with the character #. A string then follows on the remainder of the line.
The generic form of the line is: # string.
VERTEX
A vertex line begins with the character v. Three floating point values follow corresponding to the (x, y, z) location of the vertex in 3-Dimensional space.
The generic form of the line is: v x y z.
FACE
A face line begins with the character f. Three integer values follow corresponding to the vertices to connect to form a triangle.
The generic form of the line is: f v1 v2 v3.

The face lines work in a very specific manner. As the file is read, all of the vertices are stored in a list. The integer values specified for each face then correspond to the index within the vertex list to retrieve an individual vertex. IMPORTANT: the values provided for a face are 1-indexed. Meaning 1 corresponds to the first indexed vertex, 2 to the second, and so forth.

Part I: Read the File

Begin by creating a struct to represent a single vertex. Name it Vertex and have it contain three floating point values. Then create a struct to represent a face. Name it Face and have it contain three integer values.

Next, ask the user for the name of the file they wish to open. Validate that the file opened successfully. If it opened successfully, it's now time to start reading the file's contents. Create three vectors to store the comments, vertices, and faces respectively (carefully consider the appropriate data type of each vector).

Read the first character of the line and act accordingly:

If it is #, then read the remainder of the line in to a string and store it in your comments vector.
If it is v, then read the next three floating point values, create a Vertex, and store it in your vertices vector.
If it is f, then read the next three integer values, create a Face, and store it in your faces vector.

We can assume that the file will be well-formed. Meaning, the format of each line will match what we expect. There will not be any additional characters seen and there will not be any missing values on a line.

When done reading the file, print out a summary of how many comments, vertices, and faces were read in. An example is shown below:

Enter the name of the file to open: triangle.obj
Read in
	2 comments
	3 vertices
	1 faces

Two sample files to use for testing: cube.obj & triangle.obj.

Part II: Validate the Faces

Now we need to check each face to see if it is valid. A face is valid IFF:

The face is made up of unique indices.
Each index refers to a valid position within the vertex vector.

If ALL faces are valid, then print out the file is valid. If ANY faces are invalid, then print out that the file is invalid. Additionally, print which faces are invalid and why. An example is shown below:

Enter the name of the file to open: error.obj
Read in
	5 comments
	3 vertices
	4 faces
Validating faces...
	Face 2 has duplicate indices
	Face 3 contains vertices out of range
	Face 4 has duplicate indices
	Face 4 contains vertices out of range
File is invalid.

Enter the name of the file to open: triangle.obj
Read in
	2 comments
	3 vertices
	1 faces
Validating faces...
File is valid!

An additional sample files to use for testing: error.obj.

Part III: Inspect the File

If the file was invalid, then end the program. Otherwise, continually prompt the user with the following options:

Print comments: Print out all of the comments in the file
Print vertices: Print out the (x, y, z) coordinates of all vertices in the file
Print faces: For each vertex that makes up the face, print out the (x, y, z) coordinate
Quit: End the program

A full example is shown below:

Enter the name of the file to open: triangle.obj
Read in
	2 comments
	3 vertices
	1 faces
Validating faces...
File is valid!

What do you wish to do?
	1) Print comments
	2) Print vertices
	3) Print faces
	4) Quit
Choice: 1
Comment #1:  this is a comment
Comment #2:  this makes a triangle

What do you wish to do?
	1) Print comments
	2) Print vertices
	3) Print faces
	4) Quit
Choice: 2
Vertex #1: (0, 0, 0)
Vertex #2: (1, 0, 0)
Vertex #3: (0, 1.5, 0)

What do you wish to do?
	1) Print comments
	2) Print vertices
	3) Print faces
	4) Quit
Choice: 3
Face #1:	(0, 0, 0)	(1, 0, 0)	(0, 1.5, 0)

What do you wish to do?
	1) Print comments
	2) Print vertices
	3) Print faces
	4) Quit
Choice: 4
Goodbye!

In addition to the three provided public object files, your program will be tested against two additional private object files.

Extra Credit: Expanded Wavefront OBJ File Format

For an additional challenge, we'll support additional line types in the OBJ file. There are two new line types and a modified line type. The new line types are:

TEXTURE COORDINATE
A texture coordinate line begins with the characters vt. Two floating point values follow corresponding to the (s, t) location in 2-Dimensional texture space.
The generic form of the line is: vt s t.
VERTEX NORMAL
A vertex normal line begins with the characters vn. Three floating point values follow corresponding to the (x, y, z) direction of the vertex normal vector in 3-Dimensional space.
The generic form of the line is: vn x y z.

Take note that lines may no longer start with just a single character, but may start with a string now.

In addition to the two new lines, our face line now looks different:

FACE
A face line still begins with the character f. Three groups of integer values then follow to form each vertex. Each group has the following form: vertex/texture/normal, for instance 2/3/1. Each value is an integer representing the index in the corresponding vector. However, these integers are separated by slashes. You will need to read and split these values properly.
The generic form of the line is: f v1/t1/n1 v2/t2/n2 v3/t3/n3.

When validating, a face is valid IFF:

The face is made up of unique vertex indices.
Each vertex index refers to a valid position within the vertex vector.
Each texture index refers to a valid position within the texture coordinate vector.
Each normal index refers to a valid position within the vertex normal vector.

If the face is invalid, be sure to specify why. Lastly when giving the user the list of options to inspect the file, give additional options:

Print comments: Print out all of the comments in the file
Print vertices: Print out the (x, y, z) coordinates of all vertices in the file
Print texture coordinates: Print out the (s, t) coordinates of all texture coordinates in the file
Print vertex normals: Print out the (x, y, z) coordinates of all vertex normals in the file
Print faces: For each vertex that makes up the face, print out the full (x, y, z)/(s, t)/(x, y, z) coordinate
Quit: End the program

An additional sample files to use for testing: texturedQuad.obj. An abbreviated output is shown below:

Enter the name of the file to open: texturedQuad.obj
Read in
	6 comments
	4 vertices
	4 texCoords
	1 normals
	2 faces
Validating faces...
File is valid!

What do you wish to do?
	1) Print comments
	2) Print vertices
	3) Print texture coordinates
	4) Print vertex normals
	5) Print faces
	6) Quit
Choice: 5
Face #1:  (0, 0, 0)/(0, 0)/(0, 1, 0)    (10, 0, 0)/(1, 0)/(0, 1, 0)  (0, 0, 10)/(0, 1)/(0, 1, 0)
Face #2:  (10, 0, 10)/(1, 1)/(0, 1, 0)  (0, 0, 10)/(0, 1)/(0, 1, 0)  (10, 0, 0)/(1, 0)/(0, 1, 0)

Grading Rubric

Your submission will be graded according to the following rubric.

Points	Requirement Description
10	APT5 completed through AutoGrader.
6	All labs completed and submitted L5A, L5B, L5C
2	`struct`s created correctly.
1	User enters object filename and file opened properly.
4	File read properly.
3	Comments, Vertices, and Faces stored in `vector` properly (DO NOT use an array).
2	Faces validated correctly.
3	Comments, Vertices, and Faces printed properly.
2	Program I/O matches example flow.
3	Public test files generate correct results.
2	Private test files generate correct results.
+3	A5 Extra Credit: Additional line types supported.
2	(1) Comments used (2) Coding style followed (3) Appropriate variable names, constants, and data types used (4) Instructions followed
40	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. You can view these steps by watching the Windows / Mac video.

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 261: Assignment 5: A5 - Wavefront OBJ File Validator
 *
 * Author: XXXX (INSERT_NAME)
 * Skip Days Used: #
 * Skip Days Remaining: #
 * 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
- How many skip days you are applying to this assignment (if you are applying none, still enter zero)
- The number of skip days you have left for the remainder of the semester (keep track of how many you have used across all assignments)
- 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.
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 Set5
2. Inside Set5, create 4 sub-folders that are required for this Set. The name of each sub-folder is defined in that Set (e.g. L5A, L5B, L5C, and A5).
3. Copy your files into the subdirectories ofSet5 (steps 2-3), zip this Set5 folder (steps 4-5), and then submit the zipped file (steps 6-11) to Canvas.
4. For example, when you zip/submit Set5, there will be 4 sub-folders called L5A, L5B, L5C, and A5 inside the Set5 folder, and each of these sub-folders will have the associated files.
Using Windows Explorer (not to be confused with Internet Explorer), find the file named "main.cpp" located inside the folder for the particular lab or homework assignment you will submit.

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

Follow the same steps for L5A, to put a copy of your lab's main.cpp into the Set5/L5A folder. Repeat this process for Set5/L5B, Set5/L5C.

STOP: Are you sure your Set5 folder now has all your code to submit?
Now, right-click on the "Set5" 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 Set5 folder with sub-folders that each contain a main.cpp file in it?
After the previous step, you should now see a "Set5.zip" file.
Now visit the Canvas page for this course and click the "Assignments" button in the sidebar.
Find Set5, click on it, find the "Submit Assignment" area, and then click the "Choose File" button.
Find the "Set5.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 "Set5" folder and only the "Set5" 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.