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

# You may include comments
model 1.0 0.0 0.0 45 1.0 10.0 10.0 10.0 cube.obj
model 0.0 1.0 0.0 90 1.0 0.0 0.0 0.0 ellelltri.obj
model 0.0 0.0 1.0 30 2.0 -10.0 -10.0 -10.0 cube.obj

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:

$./modeltoworld driver00.txt

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 a new *.obj file that is a clone of the corresponding .obj file with FOUR key differences:

  • 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 to a folder named driver00 located where your program is located.
  • The new file will have “_mw00” appended after the name and before “.obj”. Example: cube_mw00.obj
  • The order of vertices in this 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, e.g., 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, 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, ellelltri_mw00.obj, and cube_mw01.obj to the disk under a folder named driver00. Purpose behind this is to avoid clutter of output files in your source directory.

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.

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 elments 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.

Submission

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

    Your source files
    A makefile if appropriate
    README.txt file that explicitly tells us (1) how to compile your program and (2) how to execute it.

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.

Grading

Grading will be based upon 10 distinct tests with 10 driver files involving different combinations of models and transformations, out of which 3 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.

Addendum (Last update 8/30/18)

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

Addendum (Last update 9/07/18)

Here are the ideal outputs for three driver files that are provided to you. As a reminder, your program will be tested on seven more driver files that might contain unseen models.

Addendum (Last update 09/26/18)

Here are the test driver files and their outputs: test_drivers.tar and test_transformed_models.tar