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.