X-Git-Url: http://gitweb.michael.orlitzky.com/?a=blobdiff_plain;f=doc%2FREADME;h=d84b0044aff029028e700bf97e31f7d59ff295bb;hb=46d349ec527b05687303b49724d97a6e56e12423;hp=c62e6173d4a3a2d61977a0ceb5628e844ae979ef;hpb=bebe7214d77fd80ae2d0cc376846165e06eace93;p=spline3.git
diff --git a/doc/README b/doc/README
index c62e617..d84b004 100644
--- a/doc/README
+++ b/doc/README
@@ -1,36 +1,146 @@
-== Requirements
+1. What is it?
-The following Haskell packages are required to build the program and
-its documentation. Each of them may in turn have their own
-dependencies; you should probably just use a package manager to
-install them.
+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).
- * DocTest
- https://github.com/sol/doctest-haskell
+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.
- * hUnit
- http://hunit.sourceforge.net/
+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.
- * QuickCheck
- http://hackage.haskell.org/package/QuickCheck
+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.
- * Test Framework
- http://batterseapower.github.com/test-framework/
- * Test Framework DocTest
- http://hackage.haskell.org/package/test-framework-doctest
+2. Requirements
- * Test Framework hUnit
- http://hackage.haskell.org/package/test-framework-hunit
+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.
- * Test Framework QuickCheck 2
- http://hackage.haskell.org/package/test-framework-quickcheck2
- * Vector
- http://hackage.haskell.org/package/vector
+3. Input data
- * HsColour
- http://www.cs.york.ac.uk/fp/darcs/hscolour/
+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.
- * Haddock
- http://www.haskell.org/haddock/
+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