

			     SIGGRAPH 99
			supplemental material

				 ---

		  Subdivision Schemes for Fluid Flow

				 ---

			    Henrik Weimer
		    http://www.cs.rice.edu/~henrik
				   
				 and
				   
			      Joe Warren
		   http://www.cs.rice.edu/~jwarren

				 ---



Hello!

This directory contains some supplementary material for our SIGGRAPH
paper. In particular you will find:
	-the different local subdivision masks for flow in 2 and 3D
	-an example program for flow subdivision in 3D
	-the interactive flow editor shown in the video tape
	-some example input for these subdividers

Enjoy.

	       ***************************************
 We can only provide you with versions that were compiled and tested
	   under IRIX 6.5. No other versions are available.
	       ***************************************

1. Interactive Flow Editor
--------------------------

We provided the interactive flow editor shown in the video
proceedings. The program is called flowfun and you should be able to
run it from the command line.

One thing is very crucial: flowfun reads the actual subdivision masks
from disk. Therefore, the directory named "masks" has to be in the
current working directory for flowfun to run.

The directory exampl2d contains some example flows that you can load
into the editor using the file menu.

The program should be pretty self explanatory once you have seen the
video tape for the paper. One thing is worth mentioning: In the fine
view (the right half of the window) you can add and drag streamlines
using the right button. All streamlines are erased using the center
button.

2. 3D Flow Subdivision
----------------------

The 3D flow subdivider takes a uniform 3D vector fields as input,
subdivides it some number of times and produces another 3D vector
field as its result.

The usage is fairly simple:

	flow in.flw out.flw numRounds

where in.flw is a 3D vector field in the file format described
below. out.flw is the result, in the same format. numRounds is an
integer denoting the number of rounds of subdivision you want applied
(better try small numbers first).

Again, the program flow reads the subdivision masks from disk. The
subdirectory masks contains these files and it has to reside inside
your current working directory. Right now, flow uses the masks of
support 9x9x9 but you should be able to simply rename the files in the
masks directory to have it use different ones.

Some example input files are provided in the directory example3d. For
a start you may want to give the following a try:

	flow exampl3d/bubbles.flw /tmp/bubbles1.flw 1


3. Displaying a 3D Flow Field
-----------------------------

You may find the application showflw useful: it displays vector fields
inside Geomview as a bunch of vectors in 3D. To be able to use
showflw, you have to install Geomview (see
http://www.geom.umn.edu/software/download/geomview.html) and the
program "togeomview" has to be in the search path.

Usage of showflw is pretty simple. There are two versions:

	showflw /tmp/bubbles1.flw
	showflw /tmp/bubbles1.flw a

where /tmp/bubbles1.flw is the filename of a flow field in the file
format described later (in particular output/input for the flow
subdividers from sections 1 and 2 of this document). The second
version (ending in the character a) displays arrow heads also.

We also provided a couple converter programs:

	flw2vct in.flw out.vct

	converts a flow file into VECT which is part of OOGL and can
	be displayed with Geomeview.

	flw2p3d in.flw outbase

	creates two files in a format suitable for FAST.

A1: File Format for Flow Fields
-------------------------------

The 3D vector fields are stored in simple text files of the following
format:

nx ny nz 3
v000x v000y v000z 
v001x v001y v001z
....

where nx, ny and nz are integers denoting the dimensions of the
field. The field has size nx times ny times nz. What follows are
nx*ny*nz triples of vector coordinates denoting the actual vectors in
the field. By convention, z is the fastest running index and x is the
slowest running index for the vectors in the field.

In this distribution, all flow files end in .flw. SOme examples can be 
found in the exampl2d and exampl3d directories.

A2: File Format for Subdivision Masks
-------------------------------------

The subdivision masks are stored in text files of the following
format:

nx ny nz
v000 v001 v002 ...

Where nx, ny and nz are integers denoting the dimensions of the
mask. What follows are the nx*ny*nz floating point number that
constitute the mask in the following order: z is the fastest running
index, x is the slowest running index.

One particular simplification has been incorporated: In equation (11)
of the paper the subdivision matrix mask is shown. We observe that the
diagonal entries of the subdivision matrix mask are very similar: The
(1,1) entry has the form d[y^2]d[y] whereas the (2,2) entry has the
form d[x^2]d[x]. Therefore, the finite approximation for the (1,1)
entry can be re-used as a finite approximation of the (2,2) entry: all
that needs to be done to get the (2,2) entry is to interchange the
roles of x and y. For this reason, we only compute and store the
subdivision mask for on diagonal entry (always the (1,1) or (1,1,1)
entry of the subdivision matrix mask). Names of these files are of the
form dNxNxN.msk of dNxN.msk where N is some integer describing the
mask size. For example d9x9x9.msk is a nine cubed approximation of the
diagonal entry in the matrix subdivision mask for 3D slow
flow. d9x9.msk is the corresponding mask of size nine squared for 2D
flow.

Similarly, only one entry needs to be computed and stored for the
off-diagonal entries in the mask. By convention we always keep the
(1,2) entry and all other masks can be derived by exchanging the roles
of x, y and z appropriately. Names for these files are of the form
odNxNxN.msk or odNxN.msk where N is again some cardinal denoting the
size of the mask.


A4: Disclaimer
--------------

Copyright 1999 Rice University, Henrik Weimer & Joe Warren

ALL RIGHTS RESERVED                                               
                                                                   
Permission to use this software for any purpose and  without  fee
is  hereby  granted,  provided  that  the  above copyright notice
appear in all copies and that both the copyright notice and  this
permission  notice  appear  in supporting documentation, and that
the name of  Rice  University  not  be  used  in  advertising  or
publicity  pertaining  to  distribution  of  the software without
specific, written prior permission.  You  may  not  redistribute,
modify the software in any way.

THE MATERIAL EMBODIED ON THIS SOFTWARE IS PROVIDED TO YOU "AS-IS" 
AND  WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, 
INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY  OR 
FITNESS  FOR  A  PARTICULAR  PURPOSE.   IN  NO  EVENT  SHALL RICE 
UNIVERSITY OR THE AUTHORS BE LIABLE TO YOU OR ANYONE ELSE FOR ANY 
DIRECT, SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF 
ANY  KIND,  OR  ANY   DAMAGES   WHATSOEVER,   INCLUDING   WITHOUT 
LIMITATION,  LOSS  OF PROFIT, LOSS OF USE, SAVINGS OR REVENUE, OR 
THE CLAIMS OF THIRD PARTIES, WHETHER OR NOT  RICE  UNIVERSITY  OR 
THE  AUTHOR  HAVE  BEEN  ADVISED OF THE POSSIBILITY OF SUCH LOSS, 
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, ARISING OUT OF  OR 
IN  CONNECTION  WITH  THE  POSSESSION, USE OR PERFORMANCE OF THIS 
SOFTWARE.   
