CS 5643 Assignment #1: Position Based Fluids

• JOGL and OpenGL: The base program renders particle systems using JOGL (Java bindings for OpenGL). You should download and install the appropriate version 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
  
• JOGL tutorials
• Vecmath: 2D point and vector primitives are used from the Java3D vecmath library. You can download the full Java3D from here, but you just need the vecmath.jar library (from here).
• Installation: To compile/run Java will need the jars {gluegen-rt.jar, jogl-all.jar, vecmath.jar}. To run the program make sure that the directory containing the JOGL binaries is in your PATH (or -Djava.library.path=./dlls/). For example, in Windows you will need to have {gluegen-rt.dll, jogl.dll, jogl_awt.dll, jogl_cg.dll} accessible.
• Detailed instructions on setting up JOGL that may be helpful are on the JOGL webpage.

Starter code tips:

Search for 'TODO's to find places in the code where you should implement better functionality. Some of these aren't essential to the program, but may make your life easier; these are marked as 'optional'.

Most of the action happens in ParticleSystemBuilder.java . This includes setup, GUI interactions, and timestepping. If you want to change something about the way the application runs, this is the first place to look.

By default, the simulation will perform several time steps per frame. Use the '-' and '=' keys to adjust the number of steps per frame as the program is running. Once you have implemented a better integrator (in ParticleSystem.java), you might choose to step once per frame, as fluid calculations can be very slow.

You can save the result of your simulation by pressing 'e' as the simulation runs. This creates a new FrameExporter (defined as a subclass of ParticleSystemBuilder) which will write the positions of each particle to a file every frame. You can use the provided python script (makeMitsubaFile.py) to import these files into Mitsuba to generate higher quality renderings. The default rendering format is simply diffuse particles, with hard shadows as shown here:

Within ParticleSystemBuilder, there is an abstract Task class that you may implement to add various GUI modes (e.g. adding particles, moving particles around, selecting particles and printing various stats about their current state, etc.) A simple CreateParticleTask has been included as an example. Switch between Tasks by adding new buttons in BuilderGUI.

Do I have to use the starter code? Can I program in C++? etc.: The starter code is provided to make your job easier, however you are not required to use it. Feel free to implement your assignment in any language or programming environment that you want (C++, processing, python, etc.). However you are still expected to implement the assignment steps listed below, and answer the questions. You may not use extensive libraries for particle systems or simulation since you are expected to implement the functionality from scratch (that's the point and the fun of it). However, please feel free to use any third-party graphics or 3D rendering software that you want.

• Getting started: Start by familiarizing yourself with the starter code, and modifying it to support the position-based time-stepping scheme described in the PBF paper.
• Visual debugging: The simple OpenGL renderer provided allows each particle to be rendered with its own color. Modify the code so that you can easily set each particle's color. Use the colors to help you debug each stage of your pipeline by displaying relevant quantities, e.g., particle neighbors or particles in collision. Try changing the color of the particles to display simulation state, such as density or velocity, or more artistic things, such as foam.
• Handling collisions: To keep the particles from leaving the container, you need to implement position-based collision response with the computational cell boundaries. The basic functionality of the assignment is to simulate fluid in a rectangular box of fixed size. For now, modify the inner position-correction iteration so that the particle position are kept from leaving the box when bouncing around under the influence of gravity.
• Finding particle neighbors: Each fluid particle i will need to know a list of neighbors N_i in order to compute interactions (pressure, viscosity, etc.). To get started quickly, you can just loop over all particles to find ones that are close enough (e.g., at distance r < h), but since this is an O(N^2) computation it will quickly become impractical for even a few hundred particles.  To accelerate neighbor finding, you can use a spatial acceleration structure, such as a uniform subdivision with cubic cell widths chosen based on the particle diameter. By storing a list of particles in each nonempty [i,j,k] grid cell, you can easily find nearby particles. The simplest approach for a fixed computational cell of widths (Nx,Ny,Nz) is to build a List[i,j,k] structure, e.g., where nonnull entries have particles. However, you could also use a sparse hashmap to support larger domains, or to allow particles to undergo unbounded motion. Document your design choices.
• XSPH viscosity: As your first particle-particle interaction, try implementing the simple velocity-based XSPH viscosity filter. You should observe more dissipative behavior. Note that this non-gradient based kernel makes use of the poly6 kernel.
• Position-based density constraints: Next implement the the position-based relaxation of particle positions to approximate each particle's density constraint. Iterate over the particles to estimate their lambda values, then iterative over the particles to estimate the position corrections, then update the positions. Note that you will need to adjust the positive-valued epsilon parameter to avoid problems when particles have insufficient neighbors. Make sure that your iterations play nice with the rigid boundary conditions by performing collision detection and response with the corrected particle positions.
• "Surface tension" correction: To approximate the effects of surface tension and avoid particle clumping, implement the surface-tension "s_{corr}" correction described in the PBF paper. Compare the results you get before/after implementing this correction by comparing a single frame of the animation at a specific time.
• Vorticity confinement (VC) should be implemented to avoid excessive energy loss. See the class notes for implementation details, and the video for a demonstration of the resulting effect. You will need to tweak the strength of the VC force for best visual results.
  

• Better rendering: The starter code support interactive OpenGL rendering, however you will want something better to make compelling animations. For starters, you can dump frames from your viewer to build an offline movie for technical illustrations. You can use the Mitsuba importer for better offline rendering. You can use the particles to render an implicit surface directly, or extract a mesh iso-surface using marching cubes (or marching tetrahedra) appropriately.
• More interesting scenes: Dropping water in a box is only so much fun. Try implementing more complex rigid environments, such as rigid objects (like a bunny) placed in the box. You will need to collide particles with the mesh geometry to keep them outside, or you can rasterize the geometry and normals to approximate boundaries. You could also try modeling a 3D terrain using a height field, H(x,y), and have water pour over it, e.g., to simulate a waterfall, or the Cascadilla Creek gorge :)
• Implement rigid-body obstacles to have objects pushed around by the fluid, or float on the surface. The simplest thing to do is to just model rigid spheres as big particles without rotational degrees of freedom; collisions could be handled by having them (a) bounce off the cell boundaries, (b) bounce off each other, and (c) collide with the tiny fluid particles.
• Interactivity: The current simulator is offline, but interaction is way more fun. Using low-resolution simulations, you can interact with the fluid. Try pushing on the fluid with forces, or moving obstacles (such as a sphere) through the fluid, or making the fluid respond to movement of the box (e.g., simulated by changing the gravitational acceleration).
• I already did Position-based Fluids... should I just re-type it?!?  No!  Come and speak to me about a new project extension. For instance, you could try implementing a better surface rendering scheme [Yu and Turk 2013], or adding a nicer foam effect to the surface [Ihmsen et al. 2012]. Let's talk.
  

• A brief written document (in txt or PDF) that details what you did, your findings, and who you discussed the assignment with, etc.  
  
• Include comparisons or analysis/results demonstrating the behavior of your implementation.
• Citation: 
  
• Include the names of everyone that you discussed the assignment with.
• Include citations of external resources (books, webpages, etc.) that you used in your R&D.
  
• Documented software implementation derived from the Java starter code, or based on an analogous framework in another language, e.g., C++.
• Your creative simulation artifacts, videos, images, etc.   
• We will run your software to evaluate your implementation, and/or ask you to provide a demo. However including videos that demonstrate the requested features, and interesting behavior are strongly encouraged.
  
• If you are working with a partner, be sure to form a two-person group, and submit your zip file as a group.
• Regarding requests for extensions because "I have another deadline on that day" or "I think I may have to use the bathroom at midnight": Please start early, and budget your time to do the many things you need to do. The deadline is not when you do your work, it's when you should be done by.
  

• Liu, G. Gui-Rong, and M. B. Liu. Smoothed particle hydrodynamics: a meshfree particle method. World Scientific, 2003.    
  
• Matthias Müller, David Charypar, Markus Gross, Particle-based fluid simulation for interactive applications, 2003 ACM SIGGRAPH / Eurographics Symposium on Computer Animation (SCA 2003), August 2003, pp. 154-159.  [Video]
• Wikipedia
• Takahiro Harada, Seiichi Koshizuka, Yoichiro Kawaguchi, Smoothed Particle Hydrodynamics on GPUs, Computer Graphics International, pp. 63-70, 2007.
• B. Solenthaler, R. Pajarola, Predictive-Corrective Incompressible SPH, ACM Transactions on Graphics, 28(3), July 2009, pp. 40:1-40:6. [PDF] [YouTube Video]
• Miles Macklin and Matthias Müller. Position Based Fluids. ACM Trans. Graph. 32, 4, Article 104 (July 2013), 12 pages. (other videos)
• Bridson, R., Fedkiw, R., and Muller-Fischer, M. 2006. Fluid simulation: SIGGRAPH 2006 course notes, In ACM SIGGRAPH 2006 Courses (Boston, Massachusetts, July 30 - August 03, 2006). SIGGRAPH '06. ACM Press, New York, NY, 1-87.  [Slides, Notes] [SPH pages (pp. 83-86)]
• Robert Bridson, Fluid Simulation for Computer Graphics, A K Peters, 2008. [Book format]