CSCI 261 - Programming Concepts - A4 - Abstract Lists: Wavefront OBJ File Validator

→This assignment is due by Tuesday, March 29, 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: L4A, L4B, L4C, L4D, L4E, L4F ←

· 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, validate if it would correctly form a model, and print out the data that makes up the model.

The requirements for this assignment are more abstractly defined and the implementation is left to your choosing. However, you will need to defend the choices you made in your implementation.

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 p q r.

The face lines work in a very specific manner. As the file is read, all 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

The user needs to provide a filename to open for validation. The user can either specify this on the command line when running the program or after the program starts. Expected program execution is demonstrated below:

> ./A4
Enter the name of the file to open: triangle.obj
Opening file "triangle.obj"

> ./A4 triangle.obj
Opening file "triangle.obj"

> ./A4 triangle cube
Usage: ./A4 [filename]

Once you have a filename, validate that the file opened successfully. If it opened successfully, it's now time to start reading the file's contents.

Create three lists to store the comments, vertices, and faces respectively. It is to your choosing if you want to use an Array or a Linked List to implement the abstract list. Additionally, carefully consider the appropriate data type of each list.

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 list.
If it is v, then read the next three floating point values, create a Vertex, and store it in your vertices list.
If it is f, then read the next three integer values, create a Face, and store it in your faces list.

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:

> ./A4 triangle.obj
Opening file "triangle.obj"
File successfully opened!

Read in
	2 comments
	3 vertices
	1 faces

> ./A4 triangle2.oj
Opening file "triangle2.oj"
Could not open file, shutting down...

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

Functional Requirements

You cannot use the C++ STL vector for your list implementation
You cannot use the C++ STL list for your list implementation
You must create your own array or linked list implementation (you should leverage the work put into previous labs working with arrays and linked lists)

Part II: Validate the Faces

After our lists have been made, we now 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 list.

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:

> ./A4
Enter the name of the file to open: error.obj
Opening file "error.obj"
File successfully opened!

Read in
	5 comments
	3 vertices
	6 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
    Face 5 contains vertices out of range
    Face 6 contains vertices out of range
...File is invalid.

> ./A4 triangle.obj
Opening file "triangle.obj"
File successfully opened!

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 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:

> ./A4
Enter the name of the file to open: triangle.obj
Opening file "triangle.obj"
File successfully opened!

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.

Functional Requirements

Your program must be free from:
- Memory Leaks
- Dangling Pointers
- Null Pointer Exceptions
In other words, your program should run error free and clean up all memory that is used on the free store.
Your program should be cleanly structured, including appropriate use of:
- Functions
- structs or classes
- Separate files
- Comments
Your program cannot assume a smart user and must handle erroneous user input.

Best Practices To Follow

One clear and consistent coding style used (such as K&R, 1TBS, or Allman).
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.
Use const wherever possible. If your function takes a parameter and does not modify it, it should be const.
Don't leak memory. Every allocation using new needs to have a corresponding delete.
Don't use global variables. Instead, encapsulate it and design your interfaces effectively.

Hints

If you're having some trouble with this assignment, here are some pointers

Exit Interview

When completed, create a README.txt file and respond to the following questions:

Which data structure did you choose to implement? (Array or Linked List)
What challenges did your choice of data structure present when reading the file?
Does the data structure choice have any effect on the process of reading the file?
How did you build up your lists? Add one element at a time? Or create the full list and set each element one at a time?
What challenges did your choice of data structure present when validating the file?
Does the data structure choice have any effect on the process of validating the file?
What challenges did your choice of data structure present when printing data from the file?
Does the data structure choice have any effect on the process of printing data from the file?

Extra Credit 1: 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 two characters 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 list. 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 p/pt/pn q/qt/qn r/rt/rn.

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 list.
Each texture index refers to a valid position within the texture coordinate list.
Each normal index refers to a valid position within the vertex normal list.

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 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:

> ./A4
Enter the name of the file to open: texturedQuad.obj
Opening file "textureQuad.obj"
File successfully opened!

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)

Functional Requirements

Your program will need to handle the base test case for faces (f p q r) as well as the extra credit test case for faces (f p/pt/pn q/qt/qn r/rt/rn).

Extra Credit 2: Arrays & Linked Lists

For an additional challenge, give the user the choice of which implementation they want the program to use.

Based on the user's choice, you will need to use the corresponding data structure to store all the file data in.

After the user makes their choice, there is no obvious difference to the user that the backend implementation is different. The user will have the same experience working with both data structures.

> ./A4
Enter the name of the file to open: triangle.obj
Opening file "triangle.obj"
File successfully opened!

Which data structure do you wish to use?
    A) Array
    L) Linked List
Data Structure: A

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: 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!

> ./A4
Enter the name of the file to open: triangle.obj
Opening file "triangle.obj"
File successfully opened!

Which data structure do you wish to use?
    A) Array
    L) Linked List
Data Structure: L

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: 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!

Testing

The graders will build your program with the Makefile you provide to match your code structure.

The graders will test your program with the following executions:

./A4 triangle.obj
./A4 cube.obj
./A4 error.obj
./A4 private1.obj
./A4 private2.obj

Grading Rubric

Your submission will be graded according to the following rubric.

Points	Requirement Description
5	List implemented correctly.
3	File read correctly. (1 point per public test file)
3	File validated correctly. (1 point per public test file)
4.5	File data printed correctly. (0.5 point per file component per public test file)
7	Private test files generate correct results. (2 private tests)
2.5	All assignment code submitted with Makefile that matches submitted file structure.
10	The above items make up 25/35 points towards the assignment. The rest of the assignment grade is based on how well the best practices are followed: +10 Code is easily readable, follows best practices, well structured +8 Code is easy to follow, only a few small violations of best practices +6 No egregiously bad practices +4 Lots of violations of best practices +2 Little effort to follow best practices +0 No effort to follow best practices
+5	Assignment Extra Credit 1 completed
+3	Assignment Extra Credit 2 completed
30	All labs completed and submitted L4A, L4B, L4C, L4D, L4E, L4F
3	Free points since we added wrong :)
68	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 261: Assignment 4: A4 - Abstract Lists: Wavefront OBJ File Validator
 *
 * 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 A4 to generate a target executable named A4.
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 Set4
2. Inside Set4, create 7 sub-folders that are required for this Set. The name of each sub-folder is defined in that Set (e.g. L4A, L4B, L4C, L4D, L4E, L4F, and A4).
3. Copy your files into the subdirectories ofSet4 (steps 2-3), zip this Set4 folder (steps 4-5), and then submit the zipped file (steps 6-11) to Canvas.
4. For example, when you zip/submit Set4, there will be 7 sub-folders called L4A, L4B, L4C, L4D, L4E, L4F, and A4 inside the Set4 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 main.cpp, Makefile, README.txt, *.hpp, *.h, *.cpp.

STOP: Are you really sure you are viewing the correct assignment's folder?
Now, for A4, right click on main.cpp, Makefile, README.txt, *.hpp, *.h, *.cpp to copy the files. Then, return to the Set4/A4 folder and right click to paste the files. In other words, put a copy of your homework's main.cpp, Makefile, README.txt, *.hpp, *.h, *.cpp source code into the Set4/A4 folder.

Follow the same steps for each lab to put a copy of each lab's deliverable into the Set4/L4 folders. Do this process for Set4/L4A (main.cpp), Set4/L4B (linked_list_functions.cpp), Set4/L4C (Node.h, LinkedList.h), Set4/L4D (Node.h, LinkedList.h, LinkedList.cpp), Set4/L4E (Node.h, LinkedList.h, LinkedList.cpp, main.cpp), Set4/L4F (Node.hpp, LinkedList.hpp, main.cpp).

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