From: Michael Orlitzky Date: Fri, 24 Aug 2012 19:07:50 +0000 (-0400) Subject: Remove the plain text README now that the webpage works. X-Git-Tag: 0.0.1~31 X-Git-Url: https://gitweb.michael.orlitzky.com/?a=commitdiff_plain;h=f8f564994e86b06a1e549ab81e689a111a7f8035;p=spline3.git Remove the plain text README now that the webpage works. --- diff --git a/doc/README b/doc/README index d84b004..a68f492 100644 --- a/doc/README +++ b/doc/README @@ -1,146 +1,4 @@ -1. What is it? +Unfortunately, there's too much content in this README for me to +maintain two versions. Please see the canonical REAME at, -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. + http://michael.orlitzky.com/code/spline3.php