From a74e394637d73a1fce837458a699713d8edef821 Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Wed, 22 Aug 2012 17:00:23 -0400 Subject: [PATCH] Add a preliminary README. --- doc/README | 146 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 doc/README diff --git a/doc/README b/doc/README new file mode 100644 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 + +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. -- 2.44.2