→This assignment is due by Tuesday, June 07, 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
←
· 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 so long as it matches the functional requirements & matches the expected I/O.
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 characterv
. 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 characterf
. 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 linked lists to store the comments, vertices, and faces respectively. 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 list (or any STL container) for your list implementation
- You must create your own linked list implementation (you should leverage the work put into previous labs working with 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 corresponding (x, y, z) coordinates
- 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
- Your program should be cleanly structured, including appropriate use of:
- Functions
- structs and/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 correspondingdelete
. - 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
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 charactersvt
. 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 charactersvn
. 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 characterf
. Three groups of integer values then follow to form each vertex. Each group has the following form:vertex/texture/normal
, for instance2/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
).
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:
./A0 triangle.obj
./A0 cube.obj
./A0 error.obj
./A0 private1.obj
./A0 private2.obj
Grading Rubric
Your submission will be graded according to the following rubric.
Points | Requirement Description |
6 | OBJ data stored in Linked Lists as appropriate. |
3 | File read correctly. (1 point per public test file) |
3 | File validated correctly. (1 point per public test file) |
9 | File data printed correctly. (1 point per file component per public test file) |
6 | Private test files generate correct results. (2 private tests) |
1 | Code and corresponding Makefile submitted properly |
10 | The above items make up 28/38 points towards the assignment. The rest of the assignment grade is based on how well the best practices are followed:
|
+5 | Assignment Extra Credit 1 completed |
10 | All labs completed and submitted L4A, L4B |
48 | Total Points |
→This assignment is due by Tuesday, June 07, 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
←
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.
Be sure to fill in the appropriate information, including:/* 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) */- 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 theMakefile
for A4 to generate a target executable namedA4
.
- File and folder names are extremely important in this process.
Please double-check carefully, to ensure things are named correctly.
- The top-level folder of your project must be named
Set4
- Inside
Set4
, create 3 sub-folders that are required for this Set. The name of each sub-folder is defined in that Set (e.g.L4A
,L4B
, andA4
). - Copy your files into the subdirectories of
Set4
(steps 2-3), zip thisSet4
folder (steps 4-5), and then submit the zipped file (steps 6-11) to Canvas. - For example, when you zip/submit
Set4
, there will be 3 sub-folders calledL4A
,L4B
, andA4
inside theSet4
folder, and each of these sub-folders will have the associated files.
- The top-level folder of your project must be named
- Using Windows Explorer (not to be confused with Internet Explorer), find the files
named
main.cpp, Makefile, *.h, *.cpp
.
STOP: Are you really sure you are viewing the correct assignment's folder? - Now, for A4, right click on
main.cpp, Makefile, *.h, *.cpp
to copy the files. Then, return to theSet4/A4
folder and right click to paste the files. In other words, put a copy of your homework'smain.cpp, Makefile, *.h, *.cpp
source code into theSet4/A4
folder.
Follow the same steps for each lab to put a copy of each lab's deliverable into theSet4/L4
folders. Do this process forSet4/L4A
(linked_list_functions.cpp
),Set4/L4B
(LinkedList.h, LinkedList.cpp
).
STOP: Are you sure yourSet4
folder now has all your code to submit?
- Now, right-click on the
"Set4"
folder.- In the pop-up menu that opens, move the mouse
"Send to..."
and expand the sub-menu. - In the sub-menu that opens, select
"Compressed (zipped) folder"
.
STOP: Are you really sure you are zipping aSet4
folder with sub-folders that each contain amain.cpp
file in it?
- In the pop-up menu that opens, move the mouse
- 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.
→This assignment is due by Tuesday, June 07, 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
←