CS 567 Assignment #1: Mass-Spring Particle Systems
Professor: Doug James

Due date: Fri, Feb 16 (before midnight).

Videos: Please submit videos (described below) that demonstrate the requested (and any additional) functionality of your system. Details on video generation are here.

In this first assignment you will experiment with particle systems, modifying a skeleton interactive program to add new behavior.

Starter Code (cs567.particles): This project has significant starter code, primarily to support OpenGL rendering and a simple Swing GUI. It is available here, with online Javadoc documentation here. In this assignment, you will modify this package as needed.

Software Dependencies:  The starter code will compile and run using JDK 1.5 or later. I recommend you get Sun's latest JDK6 here. In addition to Java the starter code also uses two other libraries:

• JOGL and OpenGL: The base program renders particle systems using JOGL (Java bindings for OpenGL) which you should download and install if it is not on your system. Although you can complete this assignment without writing any OpenGL, you can find more information on OpenGL or JOGL, some random introductory starting points are:
• OpenGL Programming Guide ("The Red Book"): An online version
  
• Jumping into JOGL
  
• JOGL: A Beginner's Guide and Tutorial
• Vecmath: 2D point and vector primitives are used from the Java3D vecmath library. You can download the full Java3D from here or here, or just the vecmath.jar library from here.
  

Assignments Steps: The starter code allows you to build particle systems, but you will quickly discover that some things are broken or just implemented poorly. Here are the steps you need to address:

1. Fill-in spring force implementations:  Three spring forces currently do nothing (SpringForce1Particle, SpringForce2Particle, SpringForceBending) and need to have their apply_force() function filled in.  The first two should use a damped Hookean spring (like in the Witkin course notes), whereas the second can use the bending force discussed in class (here is a simple derivation of bending force). Feel free to see if you can implement a non-zero rest angle for the bending force to support curly hair.  Once you do this, your "Create Spring" and "Create Hair" tasks should have more meaningful results.  Generate a video demonstrating a hair model with these force implementations.
   
2. Gravity and viscous damping forces: Currently gravity and viscous damping are "hacked" into ParticleSystem.advanceTime(), and conflate integration and physical modeling. Implement some global Force objects, GravitationalForce and ViscousDragForce, and add these to the ParticleSystem (immediately after its construction) to properly apply these forces to all particles. Generate a video demonstrating your gravity and viscous damping forces.
3. Numerical integration: The current forward Euler implementation is flakey, and doesn't support proper abstractions to enable easy swapping in/out of different integrators. Implement the get/setState() and derivEval() approach discussed in Witkin's course notes to provide support for both forward Euler and midpoint integrators. These particular integrators can be implementations of an Integrator interface, and you might add a GUI button to toggle between the two.
   
• Question: Keeping in mind it requires two function evaluations, is the midpoint integrator more efficient than forward Euler for stiff systems? For example, can you simulate stiffer hairs using midpoint for a fixed cost?  Generate a video comparing forward Euler and midpoint for the same step size (can you see a difference?)--you could switch between integrators mid-animation using a keyboard command.
  
4. Pin constraints were implemented using a post-step velocity and position projection in the hacky integrator. Implement a Constraint or filter class to make pin constraint projections play nicely with your new integrator.
   
5. Simple collision detection and response: The particles are currently not constrained to stay inside the unit computational cell. Implement a simple scheme to detect collisions with the four walls, and filter the post-step state to provide simple collision response. Use a restitution coefficient to attenuate normal velocity (defined in Constants.RESTITUTION_COEFF). Be careful how you update the particle velocity and position or you might find your particles interpenetrating the wall. Add a frictional drag force if you have time. Generate a video demonstrating collisions.
6. One Creative Artifact!: One of the best parts of computer animation is creative use of mathematics and computer programming. Particle systems are also very flexible. Use any free time you have to make a curious contraption, or otherwise show off any interesting functionality that you have. You can implement new building Task objects (in ParticleSystemBuilder.BuilderGUI) quite easily to make other components. If you would also like to submit a video showing some interesting behavior, you can record OpenGL screen captures using FRAPS, or other utilities--you can also dump frames using JOGL if you prefer. Generate a video demonstrating your creative artifact.
7. Make it easy to run your program: Finally, make it so that your program can be run. Ideally I should have implemented this as an applet, and used Java Webstart so that it would be easy to run/grade your assignments, and also display selected projects on the class webpage. 
   
• Optional: If you feel adventurous you can skip part 6 (creative artifact) in exchange for converting the program to a JOGL Applet, and running it using Java Webstart via the JOGLAppletLauncher. Similar examples are shown on the jogl-demos page. You will need to move the GUI panel into the applet, and modify the GLEventListener slightly.
  

On collaboration and academic integrity: You are allowed to collaborate on the assignments to the extent of formulating ideas as a group, and derivation of physical equations. However, you must conduct your programming and write up completely on your own, and understand what you are writing. Please also list the names of everyone that you discussed the assignment with.  (You are expected to maintain the utmost level of academic integrity in the course. Any violation of the code of academic integrity will be penalized severely.)

Hand-in using CMS: Please submit a short write-up (detailing what you did, your findings, and who you discussed the assignment with, etc.), as well as your Java implementation, and creative simulation artifacts, videos, etc. Submit videos in a compressed format.

Enjoy!!

Copyright Doug James, January 2007.