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 this assignment you will begin the process of implementing what will grow into a scene specification file that ultimately will enable you to generate complete renderings of multiple objects based upon scene specifications. For this assignment you will write the portion of this file handling capability which establishes the 3D transformation that is then applied to an object model being read from a *.OBJ file. The transformation may consist of zero or more combinations of rotation, translation and non-uniform scaling. The rotations will be specified using the axis-angle format. For the sake of debugging and grading this assignment your code will write back out the transformed object models and will also write the actual transformation matrices to a separate deubbgin log file.

Driver File Format

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

# You may include comments
trans clear
trans move 10.0 10.0 0.0
trans rota 1.0 0.0 0.0 45
trans scale 1.0 1.0 1.0
load cube.obj
save cube_new_01.obj

Notice there are three basic commmands, trans , load and save . The load and save commands read a .OBJ model into your program's internal representation and then back out respectively. The trans command is used to establish a 3D transformation that is applied to all models read using the load command. There are four modifiers defind for the trans trans command.

  • trans clear Erase whatever transformation may have been defined before and resets the transformaion matrix to the (4x4) identity matrix.
  • trans move tx ty tz Translate by the amounts indicated. Being more precise, create a 4x4 transformation matrix T that translates by the amounts indicated. Now, assuming the transformation matrix prior to exectuing this command is M pre-multiply by the translation so that M = T * M
  • trans rota wx wy wz thetaRotate as specified by the axis-angle rotation specification. Being more precise, construct a 4x4 rotation matrix R to carry out a rotation of theta degrees about the axis specified by wx, wy, wz. Keep in mind the axis as specified need not be unit length. Finally, the order of operations again is defined by a pre-multiplication: M = R * M
  • trans scale sx sy sz Apply non-uniform scaling as defined. Being more precise, create the 4x4 scaling matrix with sx, sy, sz entered in the first three elements of the diagonal. Then, as before, use pre-multiplication to modify the transformation matrix: M = S * M

This format is very flexible allowing essentially arbitrary combinations of rotation, translation and scale. Keep in mind that the transformation matrix M always exists and is always applied to a model when the load command is invoked. Your code should set M to be the identity matrix upon initializaiton. Also, pay careful attention to the order-of-application as it must follow from the definitions provided above. Put simply, tranformation are applied to object vertices in the order the transformations appear listed in the driver file.

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:

$./render driver00.txt

Note that your program must be run from the command line as shown.

Your program will read the driver file and create in-memory versions of the objects loaded. As described above, the models will be transformed according to the 3D transformation specified as they are loaded into whatever internal format you design. Your program will also write back out the tranformed model when a save command is encountered in the command file.

Here in one zip bundle are a several driver files with associated sample output.

Please use these to guide and test your developing code for Project 1. Rest assured for grading we will test you code on additional cases. Also, please expect updates to these examples in the coming days. These will be provided in order to give you more cases for study and testing.

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:

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. Also provide the best email if we have compilation questions.

If you are using C++, your executable should be named 'render' exactly as shown above in Task section. If your are using java, the main executable class should be named 'Render'. 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.