Motivation

Polygonal models exist for lots and lots of objects. To make a coherent scene, however, you need to be able to read and write models to disk, along with applying manipulations to them. For example, translating, rotating, and scaling them. In this assignment you will take existing polygonal models (in .OBJ format) and apply some 3D transformations to them. In particular, you will be using Axis-Angle Rotation specifications to rotate the model about a given axis, followed by scaling it uniformly along three axes, followed by a translation along three axes. A 'driver' (scene file) - read as an argument by your program - will contain pairs of 3D transformations and object model names to be transformed.

Driver File Format

Here is an example of a driver file (driver00.txt):

The general format is as follows: model wx wy wz theta scale tx ty tz model.obj . The keyword model identifies that the line is a description model and its transform. The triplet wx wy wz represents the axis about which to rotate followed by theta in degrees representing the angle by which to rotate (thus Axis-Angle format). Next, the scale is a uniform scaling factor to shrink or grow a model. Next, the triplet tx ty tz defines a model-to-world translation. Finally, model.obj is the model file on which you will be applying the defined 3D transformation.

Note that the axis of rotation may not be unit length (normalized). Also, the order of transformation is rotate, scale, and then translate. Moreover, there could be multiple model lines in a driver file. This ‘driver’ file will grow over the course of the semester to include camera information, lighting information, and other models such as spheres.

OBJ Format

We will be using WaveFront OBJ model format throughout this course. Details on this format will be covered in the class.

Task

You will write a program that takes a single command line argument: the driver file name. A C++ example is:

Your program will read the driver file and create in-memory versions of the objects mentioned in the driver file. Then, the program will apply corresponding 3D transformations to the objects. Finally, it will write back to disk two things for each object: a new *.obj file that is the result of the transformation and a *.txt file containing the transformation matrix, the inverse transformation matrix, and two values described below. The structure of those files is as follows:

• Your program must write the outputs to a folder named after driver file. Example: if driver file is named as driver00.txt then your program writes the new (transformed) .obj files and the .txt files to a folder named driver00 located where your program is located.
• The new .obj file will have “_mw00” appended after the name and before “.obj”. Example: cube_mw00.obj. The .txt file will have "_transform_mw00" appended after the name and before ".txt". Example: cube_transform_mw00.txt.
• The order of vertices in the new *_mw00.obj file will be the same as it was in the original *.obj file. Also, any line in the original file starting with ‘vn’ should NOT be written into the new file.
• The same file, for example cube.obj, may be read twice with different model to world 3D transformation. If this happens, then the file names must become [root_name]_mw00.obj, [root_name]_mw01.obj and [root_name]_transform_mw00.txt, [root_name]_transform_mw01.txt, etc. The order reflects the order in the ‘driver’ file. Example: in case of driver00.txt described above, your program should write cube_mw00.obj, cube_transform_mw00.txt, ellelltri_mw00.obj, ellelltri_transform_mw00.txt, cube_mw01.obj, and cube_transform_mw01.txt to the disk under a folder named driver00.
• The .txt transformation files should contain the values in the homogeneous transformation matrix. For an axis-angle rotation matrix, R, a uniform scaling matrix S, and a translation matrix T, this transformation matrix, M is the product M = TSR as discussed in class. In the file, this should have elements in the same row separated by spaces and rows separated by line breaks. For example, a simple transformation matrix may look like
  2 0 0 -0.004
0 0 -2 0
0 2 0 1012.232
0 0 0 1
  Each number in this matrix should be printed with up to three decimal places of precision.
• The .txt file should also contain the inverse transformation matrix, M^-1, in the same format.
• The .txt file should also contain the sum of absolute translations from the original vertices to the transformed vertices. For example, a vertex that starts at 1 1 1 and is transformed to the new position 1.996 -2 3.2 has an absolute translation of
  |1 - 1.996| + |1 - (-2)| + |1 - 3.2| = 6.196
  Calculate this for each vertex and print the sum in the .txt file. This number should be printed with up to ten decimal places of precision.
• The .txt file should also contain the sum of absolute translations obtained by transforming the original vertices to the transformed vertices, then using the calculated inverse transform to return to the original coordinate system. This number should be printed with up to ten decimal places of precision.
• An example .txt file is available at example.txt
• Please follow the format of the example exactly, including the lines beginning with #.

Here are three driver files and some models that your program will input. Extract the individual files into your source code directory. Your program will be tested for seven more driver files that might contain unseen models.

• models.tar

• drivers.tar

• driver00.tar (Solution for driver00 posted 9/8/2019)

Hints

You will quickly discover this assignment is asking you to start learning about 3D models and also 3D transformations, in particular axis-angle rotation. Given the ordering of topics in lecture, start with code that only reads vertices and transforms vertices without worrying about the rest of the modeling. Truth be told, there is not much more to understand for this assignment. That said, in the first week of work you may ignore the other elements in the file and simply transform the vertices. Once that is working, go back and make sure your code writes out a complete 3D model and that you understand the rest of the OBJ model file.

You are going to be rendering these models in the future. Therefore, the best software practice would be to build a model object class that includes not only vertices but faces, and to make sure that your input is robust.

Here is a non-exhaustive list of linear algebra libraries that students used previously:

• Eigen
• GLM
• Apache Commons Math library

Submission

Submit a tar file via the CANVAS assignment page that includes:

If you are using C++, your executable should be named 'modeltoworld' exactly as shown above in Task section. If your are using java, the main executable class should be named 'Modeltoworld'. Notice the change in case for the first letter between C++ and Java.

The GTA will have a script to unpack your tar file, compile your program, and then test it on some of the models you have been given along with other models. Note that your tar file should not contain executable or compiled files, just source files. Also, it should not contain the driver and model files.
All tests will be run on machines in the CS120. Please verify that your code compiles and runs properly on those machines.

Grading

Grading will be based upon 10 distinct tests with 10 driver files involving different combinations of models and transformations, out of which three are given to you.

Reminder

There is no “late period”. The program is due when it is due. All work you submit must be your own. You may not copy code from colleagues or the web or anywhere else. Cheating will not be tolerated, and will be handled in accordance with university and department policy.

Update Oct. 15 2019 - hidden drivers

So that you can check your work driver03.txt through driver09.txt, their associated models, and their solutions are available at solutions.tar