Add a preliminary README.

diff --git a/doc/README b/doc/README
new file mode 100644 (file)
index 0000000..d84b004
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,146 @@
+1. What is it?
+
+Spline3 is an implementation of the 3D interpolation scheme described
+in paper, "Local quasi-interpolation by cubic C^1 splines on type-6
+tetrahedral partitions" by Sorokina and Zeilfelder (this can be found
+in the 'references' folder).
+
+It takes volumetric data as input, and allows you "zoom in" on it,
+producing higher-resolution data as a result. We "fill in the gaps"
+through interpolation.
+
+The program is written in Haskell and is novel because the main
+algorithm is purely functional. Nowhere in the main algorithm are any
+state or global variables manipulated. This has a unique benefit: the
+program can parallelize itself. Because the algorithm is a "pure"
+function, the compiler knows that it's safe to partition the
+computation across all of the available processors.
+
+In fact, our results show close-to-perfect gains. In other words,
+running on two processors is essentially twice is fast as running on
+one.
+
+
+2. Requirements
+
+Spline3 is a Haskell program using the Cabal build system. The file
+spline3.cabal lists all dependencies and it is recommended that you
+use Cabal to build the project. For convenience, a makefile is
+provided to build the project.
+
+
+3. Input data
+
+The input data is "volumetric." Basically, they're pixels in
+space. The data used came from the Stanford Volume Data Archive at
+http://graphics.stanford.edu/data/voldata/. Still, this data needs to
+be preprocessed a little before spline3 will accept it.
+
+First, we download the tarball from the website:
+
+  $ wget -q http://graphics.stanford.edu/data/voldata/MRbrain.tar.gz
+
+Then, extract it and remove the tarball.
+
+  $ tar -xf MRbrain.tar.gz
+  $ rm MRbrain.tar.gz
+
+Now, we're left with 109 data files. We want to concatenate all of
+them together. Fortunately, they're named sequentially -- but not in
+alphabetical order. We can use a little shell magic to concatenate
+them in the right order:
+
+  $ rm -f mri.bin
+  $ for x in `seq 1 109`; do cat MRbrain.$x >> mri.bin; done;
+
+The result will be a file named "mri.bin" containing all 109
+layers. Other data from the website can be combined similarly.
+
+In all cases, you will need to supply a height, width, and depth to
+the program so that is knows the dimensions of its data. For the MRI
+data, this can be found on the website (although the program's
+defaults already assume you're using the MRI data):
+
+  109 slices of 256 x 256 pixels
+
+So, the correct program invocation would be,
+
+  $ spline3 --depth=109 --height=256 --width=256 <input> <output>
+
+The names for the dimensions are somewhat arbitrary. We deviate a
+little from the traditional x-y-z plane terminology; instead, the data
+can be thought of as a stack of 256x256 images. When you're looking at
+one of the images, the depth (third coordinate) would naturally be
+towards or away from you.
+
+
+4. Scaling
+
+The scale factor (default: 2) specifies how far you want to zoom in on
+the data. Higher values produce larger images, but take longer to
+compute. Only integral values (2, 3, 4, etc.) are supported. For
+example,
+
+  $ spline3 --slice=50 --scale=8 data/mri.bin out.bmp
+
+would produce an image 8x larger than the source slice.
+
+
+5. Two dimensions
+
+There are two modes that the program can run in. The first is
+two-dimensional. In two dimensions, the algorithm is not very
+impressive: similar results can be achieved with Photoshop. However,
+it's useful for testing the program.
+
+Since the input data is three-dimensional, we choose one "slice" of it
+to work on in 2D. If you pass the --slice flag to the program, it will
+cut that slice out of the input data and operate on it in 2D. For
+example,
+
+  $ ./spline3 --slice=50 data/mri.bin output.bmp
+
+In two dimensions, the program will output a bitmap as a result. This
+can be viewed in any image viewer.
+
+
+6. Three dimensions
+
+In 3D, things are a little trickier. The output format is the same as
+the input format, which means that you'll need to jump through some
+hoops to view it.
+
+First of all, to interpolate in 3D, just don't pass the --slice
+argument. An example, zooming in to the default of 2x:
+
+  $ ./spline3 data/mri.bin output.bin
+
+To view the volumetric data, you'll need to use Mayavi, obtainable
+from http://code.enthought.com/projects/mayavi/. A python script is
+provided for the MRI data: util/view-mri-data.py. To view the input
+data, for example, you would run,
+
+  $ util/view-mri-data.py data/mri.bin
+
+To view an output file (created previously),
+
+  $ util/view-mri-data.py output.bin
+
+Beware that this will consume a ton of memory!
+
+
+7. Results
+
+Several results in both 2D and 3D are located in the 'results'
+folder. Snapshots have been taken of the three-dimensional results for
+ease of viewing.
+
+
+8. Tests
+
+Foo
+
+
+9. How to report bugs
+
+Email them to me at michael@orlitzky.com.