doc/README

   1 1. What is it?
   2
   3 Spline3 is an implementation of the 3D interpolation scheme described
   4 in paper, "Local quasi-interpolation by cubic C^1 splines on type-6
   5 tetrahedral partitions" by Sorokina and Zeilfelder (this can be found
   6 in the 'references' folder).
   7
   8 It takes volumetric data as input, and allows you "zoom in" on it,
   9 producing higher-resolution data as a result. We "fill in the gaps"
  10 through interpolation.
  11
  12 The program is written in Haskell and is novel because the main
  13 algorithm is purely functional. Nowhere in the main algorithm are any
  14 state or global variables manipulated. This has a unique benefit: the
  15 program can parallelize itself. Because the algorithm is a "pure"
  16 function, the compiler knows that it's safe to partition the
  17 computation across all of the available processors.
  18
  19 In fact, our results show close-to-perfect gains. In other words,
  20 running on two processors is essentially twice is fast as running on
  21 one.
  22
  23
  24 2. Requirements
  25
  26 Spline3 is a Haskell program using the Cabal build system. The file
  27 spline3.cabal lists all dependencies and it is recommended that you
  28 use Cabal to build the project. For convenience, a makefile is
  29 provided to build the project.
  30
  31
  32 3. Input data
  33
  34 The input data is "volumetric." Basically, they're pixels in
  35 space. The data used came from the Stanford Volume Data Archive at
  36 http://graphics.stanford.edu/data/voldata/. Still, this data needs to
  37 be preprocessed a little before spline3 will accept it.
  38
  39 First, we download the tarball from the website:
  40
  41   $ wget -q http://graphics.stanford.edu/data/voldata/MRbrain.tar.gz
  42
  43 Then, extract it and remove the tarball.
  44
  45   $ tar -xf MRbrain.tar.gz
  46   $ rm MRbrain.tar.gz
  47
  48 Now, we're left with 109 data files. We want to concatenate all of
  49 them together. Fortunately, they're named sequentially -- but not in
  50 alphabetical order. We can use a little shell magic to concatenate
  51 them in the right order:
  52
  53   $ rm -f mri.bin
  54   $ for x in `seq 1 109`; do cat MRbrain.$x >> mri.bin; done;
  55
  56 The result will be a file named "mri.bin" containing all 109
  57 layers. Other data from the website can be combined similarly.
  58
  59 In all cases, you will need to supply a height, width, and depth to
  60 the program so that is knows the dimensions of its data. For the MRI
  61 data, this can be found on the website (although the program's
  62 defaults already assume you're using the MRI data):
  63
  64   109 slices of 256 x 256 pixels
  65
  66 So, the correct program invocation would be,
  67
  68   $ spline3 --depth=109 --height=256 --width=256 <input> <output>
  69
  70 The names for the dimensions are somewhat arbitrary. We deviate a
  71 little from the traditional x-y-z plane terminology; instead, the data
  72 can be thought of as a stack of 256x256 images. When you're looking at
  73 one of the images, the depth (third coordinate) would naturally be
  74 towards or away from you.
  75
  76
  77 4. Scaling
  78
  79 The scale factor (default: 2) specifies how far you want to zoom in on
  80 the data. Higher values produce larger images, but take longer to
  81 compute. Only integral values (2, 3, 4, etc.) are supported. For
  82 example,
  83
  84   $ spline3 --slice=50 --scale=8 data/mri.bin out.bmp
  85
  86 would produce an image 8x larger than the source slice.
  87
  88
  89 5. Two dimensions
  90
  91 There are two modes that the program can run in. The first is
  92 two-dimensional. In two dimensions, the algorithm is not very
  93 impressive: similar results can be achieved with Photoshop. However,
  94 it's useful for testing the program.
  95
  96 Since the input data is three-dimensional, we choose one "slice" of it
  97 to work on in 2D. If you pass the --slice flag to the program, it will
  98 cut that slice out of the input data and operate on it in 2D. For
  99 example,
 100
 101   $ ./spline3 --slice=50 data/mri.bin output.bmp
 102
 103 In two dimensions, the program will output a bitmap as a result. This
 104 can be viewed in any image viewer.
 105
 106
 107 6. Three dimensions
 108
 109 In 3D, things are a little trickier. The output format is the same as
 110 the input format, which means that you'll need to jump through some
 111 hoops to view it.
 112
 113 First of all, to interpolate in 3D, just don't pass the --slice
 114 argument. An example, zooming in to the default of 2x:
 115
 116   $ ./spline3 data/mri.bin output.bin
 117
 118 To view the volumetric data, you'll need to use Mayavi, obtainable
 119 from http://code.enthought.com/projects/mayavi/. A python script is
 120 provided for the MRI data: util/view-mri-data.py. To view the input
 121 data, for example, you would run,
 122
 123   $ util/view-mri-data.py data/mri.bin
 124
 125 To view an output file (created previously),
 126
 127   $ util/view-mri-data.py output.bin
 128
 129 Beware that this will consume a ton of memory!
 130
 131
 132 7. Results
 133
 134 Several results in both 2D and 3D are located in the 'results'
 135 folder. Snapshots have been taken of the three-dimensional results for
 136 ease of viewing.
 137
 138
 139 8. Tests
 140
 141 Foo
 142
 143
 144 9. How to report bugs
 145
 146 Email them to me at michael@orlitzky.com.