-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 <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.
+ http://michael.orlitzky.com/code/spline3.php
projects / spline3.git / commitdiff