Project 4

Project description, v. 3 (old v. 2) (old v. 1)
Virtual trackball notes

A note on Transforms

The parser code has just (4/01) been updated with different interfaces for Transforms. Instead of having 3 subinterfaces (Scale, Translate, Rotate), there is one Transform interface with setter methods (setTranslate, setScale, setRotate, and setMatrix). Although the name of the methods is setX, the intended behavior is that a Transform should maintain a transformation matrix (initialized to identity) and multiply its current matrix by the appropriate transformation. Thus a new Transform which is called like this

 
setTranslate(-1,0,0); 
setScale (10,5,10); 
setTranslate(1,0,0)

would have the effect of translating, then scaling, then translating back. The same applies for the setRotate and setMatrix calls. The setRotate call takes an array of 4 doubles. The first 3 doubles represent an axis around which to rotate (unnormalized) and the fourth double is the angle to rotate in degrees (be careful if you're using the Vecmath AxisAngle4d, as this takes an angle in radians). The setMatrix call takes an array of 16 doubles and represents a transformation matrix in row-major order (the first 4 values are the first row, next 4 values are the second row, and so on).

Parsing

In this assignment, you will be reading in model files and displaying them in your modeler. These model files will be in XML. We are providing you with parser code to read in the XML and create your classes based on the file content. In order to use the parser, you need to do the following:

Download parser.jar
Look at the Java files in the cs418.parser.interfaces package. These are the interfaces your classes will have to implement in order to make use of the parser. For many of your classes, this will just mean adding "implements InterfaceFoo" after your class name. For some of your classes, you will need to rename some methods to match the name used in the interface. You will also need to create some new classes, for example, you will need a class that implements the Mesh interface. All of these classes are required to have a no-argument public constructor (e.g. public Mesh() { }). It is important to note that you're not allowed to modify the interfaces in the interfaces package. These interfaces define the file format used and if you modify them, your program will not be able to read in the files we will be using to grade your project. However, if you wish, you can extend these interfaces, in order to save and load data associated with any extra credit features you wish to add. Doing so involves creating a new interface that "extends" the old one, in the same way that classes "extend" each other. The new interface does not need to be in the cs418.parser.interfaces package.
Create a cs418.parser.Parser object
```
 Parser parser = new Parser(); 
```
Call the setImplementation method for each of your classes that implements an interface in the interfaces package:
```
parser.setImplementation(cs418.parser.interface.Mesh.class, OurMeshImplementation.class);
parser.setImplementation(cs418.parser.interface.Sphere.class, OurSphereImplementation.class);
parser.setImplementation(cs418.parser.interface.Phong.class, OurPhongImplementation.class);
...
```
You can, of course, have more reasonable names for your classes. You can even reuse the name Mesh, for example, as long as you are careful about fully qualifying the name in your code. The .class in the above method calls may be something you have not seen before. Every class and interface in Java has an implicit class field which is a Class object representing the class. The parser needs these class objects in order to be able to call the right constructors and appropriate accessor methods (an accessor method is a method with a name like setFoo or getFoo). Note: If you have extended one of the provided interfaces in order to load/save data associated with an extra credit feature, be sure to also call setImplementation on the new interface. For example, if we provide an interface A, and you extend it with interface B and implement interface B with class C, your code should look like this:
```
parser.setImplementation(A.class, C.class);
parser.setImplementation(B.class, C.class);
```
When the user selects a file to parse, call
```
Scene scene = (Scene)parser.parse(file);
```
Sometimes, the user will want to select multiple files to parse, because some of the files depend on objects defined in other files. In this case, call
```
List objects = parser.parse(files);
```
and look through the objects List for a Scene object (use the instanceof operator: if (obj instanceof Scene) { ... }). It is important that you make this call and not multiple calls with single files, since otherwise the parser cannot resolve name references that go from one file to another.
The object returned will be one of your implementation classes, so you can just render it as you have in previous assignments.
In addition, the parser also has print and save methods that you can use.

Some hints on parsing

You probably should not import the cs418.parser.interfaces classes. Doing so lets you use short names for those classes and if the names of the classes match the name of the interfaces (e.g. cs418.parser.interfaces.Shape and cs418.model.Shape), things could get confusing.
Be sure that all implementation classes have a default constructor.
Be careful about package access. If you don't have "public" or "private" in front of a method or class, that does not imply "public". It implies "package" which means it is public to those classes in the exact same package and private to everyone else. In particular, private to the parser class in the parser package, which means it can't construct or call methods on such a class. Some of the classes handed out for previous projects have default access.

Sample files

Here are some sample files you can use to test parsing:

test1.xml: A red sphere
test2.xml: 3 colored spheres
bunny.xml: The Stanford Bunny (70K triangles)
bunny_lowres.xml: A low-resolution Bunny (950 faces)
horse.xml: A horse (97K triangles)
happy-buddha.xml: The Happy Buddha (1.1M triangles)
happy-buddha_lowres.xml: A low-resolution Buddha (16K triangles)

The Bunny and Buddha models are courtesy of the Stanford Scanned Data Repository. The Horse model is courtesy of the Georgia Tech Large Geometric Models Archive.

Watch this location for additional test files to be posted.

Submission Instructions

The submission procedure is similar to that used for Project 1. However, this time there will be point penalties for not following the procedure.
Your project must have the following file structure:

cs418/*/*.java
cs418/*/*.class
cs418/Main.class

That is, a cs418 directory with subdirectories beneath it. Each java file must have a corresponding class file within the same directory. In addition, you must have a cs418.Main class. This is the class we will be calling in order to run your project. If you want, you can just have this class call your real main method somewhere else in your project (this is probably a good idea, since you will have different entry points into your project as the project evolves over the semester). You will create a submission.jar file as you did for the last project, by first changing into the directory above the cs418 subdirectory and executing

jar cvf submission.jar cs418

You will then submit this file using the web interface. You may submit multiple times, but only the last submission counts. We will be using the following command to run and grade your project:

java -cp submission.jar;gl4java.jar;vecmath.jar;parser.jar cs418.Main

Try running this at least a couple of hours before the submission deadline. If this does not start up your project, you will lose a significant number of points on your assignment. We will have gl4java.jar, vecmath.jar, and parser.jar, so there is no need to submit these. Also, the gl4java dll will be in our PATH.