559-2009 | Main / Project2

10/21/2009 Some little things that people noticed:

some of the machines in the example code spawn the rocks in a way that they are covered up. if you create a rock from the dump truck, you need to move the truck out of the way to see it.
there is no way to know if a machine can spawn a rock or not (from the user interface). i'll add that for next year
there is an issue that if you use a scale transform, it messes up the normals. basically, the normals get transformed along with the object in a way that is different than the object itself (see section 6.2.2 of Shirley and Marschner - that describes it in a wierd way). so, if your code uses the scale transform, lighting can get messed up since it relies on the normals not being scaled (the cube code gets this wrong, so the cube changes color when it gets bigger). If you have this problem and can't fix it, just explain it in your documentation.

10/19/2009 - A clarification: When I refer to "camera control code" I am refering to the thing that spins the world around in "world" view mode. What you need to provide are the routines for driver's view/machine view that are methods that only need to set up transformations (as documented). Check out the example machine's lookAtMe method for an example.

Looking at the ExampleMachine::lookAtMe method will be really helpful in learning how to set up cameras. Notice how it first sets up the projection matrix (the transform from frustum to screen coordinates) and then sets up the camera transform. For reasons you will learn about soon, the projection matrix goes on a seperate matrix stack than the viewing and other transformations (we'll explain this in class on Wednesday) - but the book probably does a good job.

10/8/2009 - The original zip file was missing files. The new zip file (dated Oct8) should work. The link below is fixed, or just click here

10/8/2009 - A warning on the ZIP file: The Utilities directory contains a lot of stuff you won't need for this project. For example, you should delete the "glee" files (.c/.h) since they are big, and not used for this project. We'll use them in the future. Also, you can safely ignore/delete the "CVS" directory (which is only useful to me).

CS559 Construction Site Project

On this page... (hide)

1. Introduction
1. 1.1 Objectives
2. Construction Equipment
1. 2.1 If you really don't like construction...
3. The Construction Site (and code framework)
4. What machines need to be able to do
5. Assignment requirements
6. Caveats on the Code
7. What you will turn in
8. What we will give you
9. Deadlines
10. A Closing Note

Project Due: Wednesday, October 21st - (projects late policy)

1. Introduction

As you've noticed, there's a lot of construction around the CS building. First WID, now Union South.

Watching construction - especially with heavy equipment - is pretty fun. Wanting to watch big construction machines work seems to be genetic (as a father of a 3 year old, I can confirm this). Although some people might lose their fascination with construction equipment as they grow up, many of us have been surprised how fun (distracting?) it is to watch what's going on.

Unfortunately, when the Union South construction is complete, there will be no more sides of the CS building to have construction projects! (yes, in the past few years, there has been construction on all sides of the building). We need to have some way to remember all those machines and what they did, since we won't have any to look at. (note: The more obvious solution, take pictures/video of the construction, is being done. But making using of these images is for a different class.)

So, your mission in this assignment is to make a 3D simulation of some construction equipment. Fortunately, many types of construction equipment are great examples of hierarchical transformations (articulated figures), so this will be a great opportunity to practice this critical part of the graphics class.

1.1 Objectives

Understanding the "real" goals of this assignment will help you realize what is (and isn't important):

To practice designing things with hierarchical transformations, and using hierarchical transformations.
To experience trying to make things out of polygons, including getting the normals right.
To get some practice working inside of someone else's interactive system.

This last part is of some degree of importance: we will provide you with a bunch of code to make a 3D user interface, so you can focus your energy on making construction equipment. If you don't use our code, this assignment will be a lot more work. You may not like our code, but think of it as practice for the real world, where you are often forced to make use of an existing code.

Note that many of the things we're discussing later in this class are not part of the assignment. For example:

We're not doing curve and surface models (yet) - so you'll model everything with polygons. (yes, they will look blocky)
We're not doing texture mapping (yet) - so you won't be able to put fancy colorings (like words and logos) onto the construction equipment.
We're not doing physical simulation - so you won't have to model how the dirt is moved around by the various machines.

2. Construction Equipment

Here are some of the kinds of equipment I've seen at work at the WID and Union South sites:

Tower Crane
Truck Crane
Telescoping Truck Crane
Excavator
Mini-Loader
Fork-Lift
Fork-Lift Crane
Bulldozer
Front-End Loader
Dump Truck
Cement Mixer
Back-hoe
Z-Fold Concrete Boom Pump (check out the animated demo, or this huge one 70z)

If you notice, for each of these, the main function consists of a number of pieces that move with rotation/translation with respect to one another. Many involve just rotation (e.g. excavator, bulldozer, dump truck), others have some translation involved (cranes).

The main portion of this assignment is to make a few of these pieces of construction equipment. You need to make them such that each of the main pieces is separate so you can change the "parameters" of the transformations and make the machine move.

For example, consider the dump truck. Like all pieces of equipment it has 3 parameters that are its position in the work (x,y on the ground plane, and theta - its orientation on the ground plane). But it also has another parameter - the angle of the "dump".

That main thing you do for this assignment is to create the functions that implement the various pieces of construction equipment (including drawing them).

2.1 If you really don't like construction...

In the event that your inner 3 year old isn't excited by this, there are other "machines" that can also be modeled / simulated as a number of pieces moving relative to one another. Many amusement park rides (ferris wheels, merry-go-rounds, tilt-a-whirls, ...) fall into this category, and if you want, you can make some of those. Note that "track rides" (like roller coasters) are quite a different thing, and will be the subject of another assignment.

We want to let you be creative in what you choose to model, but remember, our goal here is to have you learn about modeling with transformation hierarchies. So having something that moves in a "creative" way, is only valuable if it moves in the way its supposed to. (not "i meant for it to do that"), and its modeled as a hierarchy of transformations.

Also, not all of the things construction equipment can do (like place rocks) make sense for other things. Make sure you have enough equipment to show off the features.

3. The Construction Site (and code framework)

The pieces of construction equipment need a construction site to work in. More practically, this is the program that puts up a window, provides lighting and a camera UI, provides an interface to each piece of equipment, etc.

We will provide you with an (admittedly simple) framework for doing the project. It will define an "abstract base class" for "Machines" (pieces of construction equipment). Your main task for this project is to define subclasses for different types of machines. You'll also need to edit the setup portion of the program to have it put the Machines into the construction site.

The example code is intentionally very simple. You can clean it up, provide a spiffier interface, add features, etc. You can even re-write it from scratch if you're really ambitious (warning: this will be a lot of work, and you'll need to make sure you provide all the functionality). However, this is not the focus of the assignment. The main thing your grade is based on is how well you implement the various machines.

4. What machines need to be able to do

To work in the simulation, machines need to:

Set themselves up in a way that allows the framework code to work with them. (this involves a constructor that sets a number of variables)
Draw themselves (given their parameters)
Set the viewpoint to provide a nice view of the machine
Set the viewpoint to look out the driver's seat (note: not all things can do this)
Determine where the "end-effector" of the machine is. For example, the bucket of an excavator, or the gripper of a crane. (this doesn't make sense for all pieces of equipment). This will be used to "place rocks".

At a minimum, a machine needs to do 1-3. 4 and 5 only make sense for some machines (those that drive and those that can pick things up). You'll need to make at least one machine that does everything (an excavator, or a boom pump).

There is a virtual base class for Machine that provides methods for each of these. To make a new kind of machine, all you need to do create a subclass of Machine and override the appropriate methods. You'll also need to modify the main function of the program in order to put an instance of the machine into the construction site, so we can see it work.

A Caveat on setting the view in general...
Be sure to clear and set both transformation stacks. Look at the ExampleMachine for an example.

A Caveat on Driver's view:
If you put the viewpoint inside of the machine, you might be looking at the walls of it! You might consider setting the near clipping plane so that the machine can see outside, or to move the position in front of the windshield.

A Caveat on Lighting:
The sample code uses lighting. This means that you need to set normal vectors properly. Alternatively, you can turn off lighting and color each polygon seperately.

A Caveat on Controls:
The simple UI (sliders for all the parameters) isn't so convenient. It lets you change the parameter values, but its limited to (at most) 10 parameters, and isn't so useful for making coordinated changes to sliders (changing more than one thing at once). It was designed to be general, and easy to implement, not necessarily easy to use. Improving the UI is something you might want to consider doing.

A Caveat on Computing the Position of the End-Effector:
It is tempting to have OpenGL do the matrix multiplies for you, and read the resulting matrix back with glGetMatrix (or whatever it is called these days). It turns out that this is tricky (since GL's internal matrices can have other stuff in them. So, we explicitly disallow using glGet (or equivalent) or pipeline feedback to compute end effector positions. These are actually more pain than they are worth, anyway.

5. Assignment requirements

At a minimum you must:

Create at least 3 new types of machines that support the minimum functionality
At least one of them must be an excavator or z-fold boom pump, which has (at least) the following parameters: X,Z, (Theta - orientation of the base), Spin (rotation of the upper part), arm lift angle, "elbow" angle, and bucket angle. The excavator page will tell you more about excavators. The excavator must support the driver's view and compute the end effector position.

The sample executable meets this requirement. With an amazingly small amount of code.

To go beyond the minimums you can:

Make more than 3 different types of machines. The best is if you show off different types of articulations.
Make the machines geometry be nicer. (yes, you can make things out of cubes, but hopefully things will be nicer - unless you try for a "realistic lego look")
Add extra functioning things to the geometry (like the hydraulic pistons on the excavator).
Do something creative that we haven't thought of. (Note: you should probably ask before spending a lot of time on something. For this assignment, things should focus on the goals of the assignment - we'll have time later to explore topics like appearance and texture, curved surfaces, ...). Some things you might want to add (like nicer interfaces for driving and animation) will require are a little tricky given how the framework is created.
Improve the UI - unfortunately, this will require making changes to the framework code. But, if you want to try to implement better ways to control the machines than sliders, let us know, and we'll help you figure out how to adapt the framework code.

Note: it is more important to have machines with the correct behavior than it is to have them look really nice. If you really want to write a model loader (or find one on the web and incorporate it into your program), and either model things yourself or find models on the web, that's fine (providing you give proper attribution). However, its a lot of work, and you still will need to figure out how to have the models have the pieces move correctly (which can be harder than making things from scratch). If you have no idea what a model loader is, don't worry about it.

Appearance does matter. Its a secondary concern (after behavior), but having nice shapes is important. Having decent normal vectors (so lighting shows up correctly) is also

6. Caveats on the Code

The framework code that you will be using is somewhat simple. It was designed for a minimum of dependencies on other things, and to make it as easy as possible to do the basic aspects of the assignment. This means some unusual design choices were made (for example, there is no 3D point class or math library used), and the interface is a bit overly-simplified.

The framework code may evolve over the course of the project. We might fix bugs, or add interface improvements. We will provide updated code as its available. To make it easier to get updates, we recommend:

Most of your work should be in seperate files (defining new classes), except for a few lines added to the main function
If you find a bug in the framework code, tell us so we can update it for everyone
If you make changes/improvements to the framework code, make sure its clearly marked. This is important for you (so you can move these changes to new versions), but also it will be useful for us (so we can incorporate improvements for future projects).
Avoid making changes to the existing code that aren't essential. For example, if you don't like the style of the code, or the way that a particular thing is done, don't make a change that doesn't improve the functionality. (basically, if it isn't broken, don't fix it)

The camera control code was given in previous years, you can find the sample code discussed on 2007 Sample Code Page. You might also want to look at last year's Tutorials for examples of how OpenGL and FlTk work together.

Don't expect to figure out how the camera code works: it's based on some tricky concepts (such as quaternions) inside. Hopefully all the internals are hidden from you.

When I refer to "camera control code" I am refering to the thing that spins the world around in "world" view mode. What you need to provide are the routines for driver's view/machine view that are methods that only need to set up transformations (as documented). Check out the example machine's lookAtMe method for an example.

The one thing you probably do want to know about the camera: use the right mouse button. If you hold the ALT key, you'll pan instead of rotate. It only looks for the ALT key when you first press the mouse button.

7. What you will turn in

You will need to turn in everything that is required to build your project (including the framework code). This includes the visual studio solution and project files. As usual, do not turn in binary files or debugger information.

Be sure to turn in a README file that describes your project. It should list all of the changes you've made to the example code.

In the README, be sure to:

List all the machines you added, including a list of the parameters they have.
List any other changes you made to the code. (besides adding the new machines to main)

Also, include screen shots (in .png or .jpg format) that include pictures of each type of machine you've created.

8. What we will give you

We will provide you with the framework code. Download this zip file - this version is dated October 5th.

There is a sample executable that meets the minimum requirements. It has an excavator, a (very simple) dump truck, and a crane. We may provide another executable with more machines to play with

9. Deadlines

The project is due on Wednesday, October 21st.

Late projects will be accepted according to the course late policy. (A late project may be turned in until Friday, October 23th, and a very late project until sometime around the following week).

10. A Closing Note

Last year, several (at least 4) former 559 students have found out about this project (makes you wonder why former students look at the web page from a class they took 1-2 years ago), and commented to me that they thought it sounded fun. That's the idea.

Hopefully, this is a fun way for you to experiment with coordinate systems. The minimum requirements are quite simple, but hopefully people will be creative and make cool stuff!

Last year, we saw some pretty cool things.