COMP 559 - Winter 2011 - Assignment 1
Mass-Spring Particle System

Since this is the first assignment, you'll need to spend a little bit of time to get set up. If you are not already using Java then download and install the latest Java SE JDK (careful not to select the JRE). I also recommend using Eclipse as a development environment. Note also that the specification of this assignment is long in that this first assignment. Future assignments will be much shorter and you will be expected to complete them with more autonomy.

New to Eclipse?

If you are familiar with Eclipse (i.e., you took COMP 557 last term), then you can probably skip this section. For those of you who are new, here is a few extra tips on using Eclipse and getting set up.

Eclipse uses a workspace to organize your projects. When you start eclipse for the first time, it will make you a workspace in some default location (probably your home directory), but you can switch workspaces with the file menu, and open any folder you want for your workspace. One nice way to organize this would be to create a workspaceComp559 folder in your home directory, then tell eclipse to open that workspace.

Once your workspace is open, add a new java project, give it a name like A1. The defaults for the project when you click next are probably fine, e.g., default JRE, separate folders for source and class files. Once it is created, you'll see a src folder for the source files and bin for the class files (note that you'll eventually need to create a directory called "stills" for when you're recording images to make a movie).

You'll want to put the provided code (see below) in src folder of your new project, and there are lots of ways to do this, but you need the directory structure to match the package structure!! An easy way is to copy the comp559 directory in the zip file and paste it into the src directory. Since everything lives in the package comp559 you need this folder (i.e., you can't just copy and paste the a1 folder into src). If you copy files into your project on the file system side, you'll need to tell Eclipse to refresh its view of the project (right click on the project and select refresh). So that summarizes the steps for "dumping the source code into a project". You'll have lots of errors at this point, but they all go away when you attach the jars as specified in the assignment.

Lastly a few tips on using eclipse when you're browsing the code. If you let your mouse hover over an identifier, variable or method, a window will pop up telling you what it is, and providing you with the javadoc. If you hold ctrl and click on an identifier, it will take you to its definition (e.g., the implementation of a method). This is a great way to explore code rapidly! Note the yellow forward and back buttons on the tool bar are useful for going back to where you were after control clicking an identifier.

Sample Code

Download the provided code from WebCT, and dump it into a new java project. The code makes use of mintools.jar, which is a collection of tools for quickly getting started with 2D and 3D graphics. There are three parts of this tools package:

• parameters contains boolean and double parameter classes for quickly setting values with swing interface controls.
• swing contains layout helpers and panels for quickly throwing together a Java swing interface.
• viewer contains some simple classes for 2D and 3D viewing, including a 3D trackball and camera controls. (note that for simplicity, this assignment is set up to be all 2D graphics).

The source for the tools is provided for your convenience, and you should not need to make changes. As for teh provided code, do not change any of the package names as this will interfere with marking.

More Jars and Native Libraries

The code uses three libraries: JOGL for OpenGL bindings, vecmath for classes useful for math with 2D (and 3D) vectors, and MTJ for matrix computations.

The vecmath package is available as part of Java3D. Instead of installing the full Java3D, download this copy of vecmath.jar. Compared to the latest version, I believe this version is only missing a few setter and getters in the matrix classes (nothing that you will miss, and marking problems will be avoided). Also, the source code (i.e., the javadoc) is in the jar, so if it isn't automatically attached, you'll want to follow the following process. First add the jar to your build path, then open up Reference Libraries in your project, right click on the jar to set properties, go to source code attachment, and tell it where to find the zip file. You might also want to browse the vecmath javadoc online to become more familiar with the available classes and methods.

There are many good packages out there for matrix computations, however, the provided code is set up to use Matrix Toolkits for Java, which is probably the most straightforward of available options. Find a link to the MTJ.jar in the downloads section. There is also a link for the source code, but I'm also providing you the zipped source locally (i.e., attach this for the javadoc). The important classes in MTJ for this assignment are the compressed row sparse matrix implementation, FlexCompRowMatrix and CompRowMatrix, along with non-sparse DenseVector objects. These classes have all the methods you might expect for adding and multiplication. You probably already noticed the link on the main page, but you can browse the javadoc online too.

The JOGL bindings project has moved and is now available at Project Kenai. From the main page you can find the necessary downloads from the archived builds link, but note that you do not want the JOGL2.0 beta builds as there are some small but significant changes to methods. Here is a direct link to the latest release build, JSR-231 1.1.1a. Be sure to download the appropriate files for your platform. If on windows, download

• jogl-1.1.1a-windows-i586.zip
• jogl-1.1.1a-src.zip (to have access to javadoc in Eclipse)
• jogl-1.1.1a-docs.zip (if you prefer reading javadoc in your browser)

To make your life more pleasant in Eclipse, you want to attach the source code to the jar for the javadoc, as described above.

Note that the .dll (or .so) that comes with the jar must be in your path. You can do this by opening the reference libraries in your project, right clicking to select properties, choose Native Library and enter the location of the .dll or .so file.

Note that the most noticable change to OpenGL function signatures under java is how functions with pointer arguments are mapped to two parameters under java (one for the array, one for the offset). See the note on Mapping of Pointer Arguments and Index Parameter for Arrays in the JSR 231 Specification Overview.

There will no OpenGL programing required in this assignment, but if there is something you would like to change, and you need either a quick introduction to or to brush up on OpenGL, then check out these links: The OpenGL Programming Guide (The Red Book) online version (or at Amazon), Jumping into JOGL, JOGL: A Beginner's Guide and Tutorial. Another popular resource is nehe.gamedev.net (see the NeHeGL JOGL link on the bottom left).

Creating Videos

Below you are asked to assemble a sequence of recorded frames that demonstrate the required features of your program. Everyone should use the xvid MPEG-4 / H.264 codec. Video creation is straightforward under windows using virtualdub. If you are using Linux or OSX, a good alternative is to use mencoder on the command line (you can do this on windows too). See the MPlayer page for downloads and more information, and you can probably make your video with a command line that looks something like the following:

mencoder -ovc xvid -xvidencopts bitrate=1800000:me_quality=6 -fps 24 -o out.avi mf://img

Alternatively, under windows, once you have both the codec and virtualdub installed, you can create an avi file from a sequence of png still frames using the following steps (you'll probably want to complete at least part of the assignment and then come back to these steps later).

1. In virtualdub, select "Open video file..." from the File menu and choose the first image in the sequence (i.e., img00000.png). This will automatically load the entire sequence
2. The loaded images probably do not have a width and height which are multiple of 16, so you'll need to add a filter. Under the Video menu, select "Filters...", click Add, select Resize and click OK.
3. In the window that opens, there should be an option for Codec-friendly sizing in the bottom right. Select "Multiples of 16" and click OK. Now back at the Filters, click OK to close it.
4. Now you need to set the codec. Choose "Compression..." under the video menu and choose the codec you installed (e.g., Xvid MPEG-4 Codec).
5. The default configuration of the codec should be fine, but I would prefer that you use maximum quality settings (i.e., adjust the quantization). It is unlikely that any of the files you are creating will be too large, but use your best judgment!
6. Now you can save the image sequence to an avi file. Select "Save as avi..." under the file menu and specify the file name, then wait for virtualdub to finish encoding the file (it might need a minute depending on the length of your video and the speed of your computer).

Note that there are also many other good ways to encode videos. Do whatever is easiest for you, but make sure that the result is high quality and uses the xvid codec.

The provided source code should help you get started quickly. It has an interface for creating points and dragging them around. The controls window lets to create a few different procedurally created test systems and lets you adjust parameters stuff as stiffness, damping, and step size. The main method lives in the A1App class, so this is the one you'll want to start when running your program. Note also the keyboard commands attached to the drawing canvas that let you start and stop the simulation, reset, and clear. There are also controls to help you save sequences of png files (you will need to create a directory called stills). The important parts of the program, however, are missing. They are labeled with TODO comments.

1. Spring Forces

   Finish implementing the code that computes spring deformation and viscous spring damping forces. See the Spring.java file and the comment the starts with "TODO". Refer to your class notes or the PBM notes on the Pixar site.

2. Derivs

   Implement the derivs function of particle system. Include gravity, viscous damping, spring forces, and spring damping. Note that getStaet and setState methods are already implemented for you, so unpack the provided state, compute the forces, from the accelerations compute the accelerations, and then fill out dydt.

3. Forward Euler

   Finish implementing the ForwardEuler class. Note that particleSystem.advanceTime calls the step method of the Integrator interface. Your other explicit numerical integration implementations will use the same interface.

4. Midpoint Method

   Implement a MidpointMethod class. Note that you'll probably need to allocate temporary arrays for intermediate results. Note that the number of particles will increase if you click to create them, so you'll probably want to do something smart, like grow the size of your arrays as needed.

5. Modified Midpoint Method

   Implement a ModifiedMidpointMethod class, using the 2/3 point stepping scheme discussed in class.

6. RK4 Method

   Implement a fourth order Runge-Kutta integration class.

7. Symplectic Euler

   Implementing a SymplecticEuler class. Note that you will need to make assumptions about how the state is packed in order to update the position components different from the velocity components (unfortunate as this breaks the abstraction). See the getState and setState methods of particleSystem for reference.

8. Backward Euler (2 marks)

   Implement a backward Euler step computation. Use MTJ to assemble the matrices as shown in class, and use the provided conjugate gradients implementation to solve the system. Note that the provided implementation uses a velocity filter (already implemented for you) to deal with pinned particles. Note that this velocity filter does not work correctly for walls.

9. Interesting Movie

   Finally record a sequence of something interesting or amusing. This could be something within the existing functionality of the specification and provided code, or some additional feature you add to your code (e.g., particles with other properties such as colours, different bouncyness properties). Be creative. Encode the video as described above. Keep your video short and to the point (i.e., at most a few MB).