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
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
workspaceComp599 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 comp599 directory in the zip file and paste it into the
src directory. Since everything lives in the package comp599 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.
Download the provided code
and dump it into a
new java project. The code has two parts. The first part is the
comp599.a1 package which contains the template code for this
assignment. The second part is the comp599.tools package, which is
a set of tools for quickly getting started with 2D and 3D graphics.
There are three parts to the tools package:
- parameters contains boolean and double parameter
classes for quickly setting values with swing interface
- 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
You do not need to change anything in the tools package to
complete this assignment. The source for the tools is provided only
for your convenience, and you should
focus your attention on the a1 package. Do not
change any of the package names as this will interfere with
Jars and Native Libraries
The code uses two libraries: JOGL for OpenGL bindings, and
vecmath for classes useful for math with 2D (and 3D) vectors.
The vecmath package is available as part
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
javadoc online to become more familiar with the available classes
The JOGL bindings project has moved and is now available at
Kenai. From the main page you can find the necessary downloads from
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,
- 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 not be extensive OpenGL programing in this assignment,
but if you need either a quick introduction to or to brush up on
OpenGL, check out these links:
The OpenGL Programming Guide
(The Red Book) online version
A Beginner's Guide and Tutorial. Another popular resource
is nehe.gamedev.net (see the
NeHeGL JOGL link on the bottom left).
Below you are asked to assemble a sequence of recorded frames
that demonstrate the required features of your program. Everyone
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
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
- 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
- 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
- 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.
- 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).
- 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!
- 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
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. The
important parts of the program, however, are missing. Note also that
you will not be able to test much until you complete the first three
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. You can optionally add viscous damping too, but it
should be left at zero in your demonstration videos.
Create getState and setState methods to get and set phase
space state of the system in a flat array. Use these methods
to write a forward Euler numerical integration method using
the Integrator and Function interfaces
provided. See the "TODO" comments in ParticleSystem.java in
the updateParticles and derivs methods. Also see the "TODO"
comment in the ForwardEuler class in the numerical package.
To elaborate on this a bit, the step method in integrator needs
flat array containing the phase space state of the system. But the
state of the system is contained in member variables of all the
instances of the particles. As such, you'll want to write a method
such as getState(double y) in your particle system class to pack up
all the positions and velocities of the particles. The setState method
should obviously do the opposite, so you can take the double yout
array result from calling step. Of course, you'll also need to
allocate yourself arrays of the appropriate size so you can use these
methods, and so you can call step. 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. So,
what you want to do is, first check if you have arrays y and yout that
are of an appropriate size for the current number of particles. Then
pack the state of the particles using your getState method. Then call
the step method of the integrator. Then unpack the result into your
particles with your setState method.
Some of the example systems have particles with
a pinned property set to true. Add a method to filter the
state (and forces) so that these simple constraints work
nicely with your numerical integration methods (both forward
Euler, and those in step 5).
To elaborate on this slightly, if a particle is pinned (a bilateral
constraint), then each coordinate of the particle needs to remain
constant. It should also have zero velocity and it should not undergo
any acceleration. Your derivs function needs to make sure that the
velocity and acceleration are valid, otherwise strange things might
happen! Suppose you let forces produce accelerations, and you
integrate these to get velocities. You'll accumulate velocities for
the particle, which will try to make it move at each step, but you'll
set the position back to where it is supposed to be. But
that wrong velocity that the particle has will affect damping
forces on the particles to which it is attached by springs! Thus, it
is best to make sure that the whole state makes sense with respect to
Particle Wall Contact
Modify the method you made in the previous step to also keep
particles inside the window by projecting them to the closest
boundary. For a particle in contact with a wall, a velocity
away from the wall is OK, but a velocity toward the wall
should not be allowed (the same for forces).
Additional Numerical Integration Types
Create classes that implement the Integrator interface for the
midpoint method, the 2/3 point method, and the fourth-order
method. That is, add classes to the numerical package and use
them in your particle system. You should also implement
Euler method, but note that this will break the
abstraction of the Integrator interface slightly in that you
will need to know how the positions and velocities are packed
in the state array.
Add keyboard controls so that you can switch between integrators
by pressing 1 through 4 (have a look at the "TODO" comment at
the bottom of the A1App class which adds the KeyAdapter to the
When adjustSubsteps is true, you should automatically adjust
the number of sub-steps so that each step involves the same
amount of work (i.e., number of calls to compute derivatives).
That is, 4 for FE, 2 for midpoint, 2 for 2/3 point, 1 for RK4.
You might try to find scenarios for spring and damping
parameters where different methods will perform better given
the same computational cost.
Record a sequence of examples that demonstrate how these
different numerical methods perform. Specifically, with the
damping set to zero find a step size which demonstrates which
method performs best. Also demonstrate what happens and which
is best when the damping is not zero (you might want to do the
written question and think about regions of stability when doing
this question. Keep the time steps fixed. Encode the video as
described above. Please keep your video short (half a minute
should be plenty) and use the comment area to describe what
you are showing.
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, but don't spend too long on
anything as the assignment is quite long as it is. Encode the
video as described above. Keep your video short and to the
point (i.e., at most a few MB).
Consider a one dimensional system consisting of a single particle
with mass 1 kg attached to a rigid wall with a spring (100 N/m).
If the particle starts with zero velocity at a position 0.01
m from rest (x=0), what is the exact trajectory? What is the
frequency of the oscillation in Hertz?
Given what you know (from class) about the stability of the
different integrators used in the programming part of this
assignment, what would be a good choice of step size for each
integrator? Use your implementation to check that it matches
what you expect from the theory.
In the case of forward Euler and given a step size of 0.05 s, what
is the minimum amount of damping required to prevent the system
from blowing up?
Again, in the case of forward Euler and given a step size of
0.05 s, What is the maximum amount of damping that can be
used without the system blowing up? Use your implementation
to check that it matches what you expect from the theory.
Prepare a pdf file with your answer to these written questions
(scanned hand written document, or generated
with latex, openoffice, or otherwise) and submit it along with your
assignment via webCT.
Great! Submit your source code and two xvid encoded videos as a
zip file via webCT. Include a readme.txt file with any specific
comments. Also be sure to include a pdf with your written answer
(i.e., scans of handwritten work, or typeset). Your readme
should provide a list of people with which you discussed the
assignment, or state that you did discuss the assignment with