GitHub - SCIInstitute/StructuredEikonal: CUDA implementation of FIM (Fast Iterative Method) for Eikonal equations on Structured Volumes (original) (raw)

GPUTUM: StructuredEikonal

GPUTUM: StructuredEikonal is a C++/CUDA library written to solve the Eikonal equation on structured meshes. It uses the fast iterative method (FIM) to solve efficiently, and uses GPU hardware.

The code was written by Won-Ki Jeong at the Scientific Computing and Imaging Institute, University of Utah, Salt Lake City, USA. The theory behind this code is published in the papers linked below. Table of Contents

Aknowledgements

**A Fast Iterative Method for Eikonal Equations**

**AUTHORS:**Won-Ki Jeong(b)
Ross T. Whitaker(a)

This library solves for the Eikional values for voxels within a volume.

Requirements

Building

Linux and OSX

In a terminal: ```c++ mkdir StructuredEikonal/build cd StructuredEikonal/build cmake ../src make ```

Windows

Open a Visual Studio (32 or 64 bit) Native Tools Command Prompt. Follow these commands: ```c++ mkdir C:\Path\To\StructuredEikonal\build cd C:\Path\To\StructuredEikonal\build cmake -G "NMake Makefiles" ..\src nmake ```

Note: For all platforms, you may need to specify your CUDA toolkit location (especially if you have multiple CUDA versions installed):

cmake -DCUDA_TOOLKIT_ROOT_DIR="~/NVIDIA/CUDA-7.5" ../src

(Assuming this is the location).

Note: If you have compile errors such as undefined reference: atomicAdd, it is likely you need to set your compute capability manually. CMake outputs whether compute capability was determined automatically, or if you need to set it manually. The default minimum compute capability is 2.0.

cmake -DCUDA_COMPUTE_CAPABILITY=20 ../src make

Running Examples

You will need to enable examples in your build to compile and run them.

cmake -DBUILD_EXAMPLES=ON ../src make

You will find the example binaries built in your build directory.

Run the examples in the build directory:

./Example1 -or- Example1.exe ...

Each example has a --help flag that prints options for that example.

Follow the example source code in src/example1.cu to learn how to use the library.

Depending on your device architecture, the default volume size may be too large. Make it smaller for Example1 with the option -s 128 or a smaller number if necessary. You can try this if you get a CUDA error when running the example.

Using the Library

A basic usage of the library links to the STRUCTURED_EIKONALlibrary during build and includes the headers needed, which are usually no more than:

#include <StructuredEikonal.h>

Then a program would setup the Eikonal parameters using theStructuredEikonal object object and callobject.solveEikonal() to generate the array of voxel values that represent the solution.

Here is a minimal usage example (in 3D).

#include <StructuredEikonal.h> #include int main(int argc, char *argv[]) { StructuredEikonal data(true); //Run the solver data.solveEikonal(); //now use the result data.writeNRRD("myfile.nrrd"); }

The following helper functions are available before running the solver:

void StructuredEikonal::setDims(size_t w, size_t h, size_t d); //set the volume dimensions void StructuredEikonal::setMapType(size_t t); //pre-generated speed functions (sphere or egg-carton) void StructuredEikonal::setItersPerBlock(size_t t); //set the iterations per block void StructuredEikonal::setSpeeds(std::vector<std::vector<std::vector > > speed); //set the voxel speeds void StructuredEikonal::setSeeds(std::vector<std::array<size_t, 3> > seeds); //set list of seed voxels

The following helper functions are available after running the solver:

void StructuredEikonal::writeNRRD(std::string filename); //write the result as a volume NRRD. std::vector< std::vector< std::vector > > getFinalResult(); //get the resulting volume voxel values.

You can also access the results and the mesh directly after running the solver:

std::vector<std::vector<std::vector > > StructuredEikonal::answer_;

Eikonal Options

class StructuredEikonalEikonal { bool verbose_; //option to set for runtime verbosity [Default false] size_t itersPerBlock_; //# of iters / block [Default 10] size_t width_; [Default 256] size_t height_; [Default 256] size_t depth_; [Default 256] size_t solverType_ ; //auto speed fuctions, 0=sphere, 1=eggcarton [Default 0] };

You will need to make sure your CMake/Makfile/Build setup knows where to point for the library and header files. See the examples and their CMakeLists.txt.

Testing

Testing has not yet been implemented.