CS 5643 Assignment #1: Position Based Fluids
Professor: Doug
James
Due date: Sunday, March 2, 2014 (midnight)
![From [Macklin and Muller 2013]](PBF.jpg)
In this first assignment, you will implement a particle-based fluid
simulator related to smoothed particle hydrodynamics (SPH).
Your implementation will be based on the recent "Position Based
Fluids" (PBF) approach described in [Macklin and Muller
2013]. You will extend a simple starter-code implementation to
support the basic PBF functionality, then extend it to produce a
nontrivial animation/simulation of your choosing.
Groups: Work on your own, or in a group of at most two
people. Additional work is expected from a group submission, such as
a more elaborate creative artifact or modeled phenomena. PhD
students are encouraged to work alone, and pursue a more challenging
creative artifact.
Starter Code (cs567.particles): This project has
starter code (available to registered students through CMS), primarily to support
basic OpenGL rendering and a simple Swing GUI. 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. In addition to Java, the starter
code also uses two other libraries that you need to install/get:
- 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:
- 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 here.
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 ParticleSystemBuildier.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 may want
to write a program to import these files to a better renderer
such as Mitsuba.
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.
Assignment Steps: The code provides some very basic
functionality for a particle system, but does not implement any
fluid-like forces, nor container boundary conditions to keep the
particles from flying away.
- 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.
After you get the basic simulator working, you should try something
unique to your submission:
- 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 code FrameExporter code snippet
shown here. However, for better offline rendering, I recommend
exporting to an offline renderer, such as Mitsuba. You can use
the particles to render an implicit surface directly, or extract
a mesh isosurface 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).
- More ideas for particle-based extensions can be found on
previous years' assignments.
Hand-in using CMS:
- 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.
Start early. Ask questions. Have
fun!!!
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 (or with your partner), 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.)
References:
- 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]