README.md 7.32 KB
Newer Older
1
# VTK-m #
2

3 4 5 6 7 8
VTK-m is a toolkit of scientific visualization algorithms for emerging
processor architectures. VTK-m supports the fine-grained concurrency for
data analysis and visualization algorithms required to drive extreme scale
computing by providing abstract models for data and execution that can be
applied to a variety of algorithms across many different processor
architectures.
9

10
You can find out more about the design of VTK-m on the [VTK-m Wiki].
11 12


13
## Learning Resources ##
14

15 16 17
  + A high-level overview is given in the IEEE Vis talk "[VTK-m:
    Accelerating the Visualization Toolkit for Massively Threaded
    Architectures][VTK-m Overview]."
18

19 20 21 22 23 24 25 26 27 28 29
  + The [VTK-m Users Guide] provides extensive documentation. It is broken
    into multiple parts for learning and references at multiple different
    levels.
      + "Part 1: Getting Started" provides the introductory instruction for
        building VTK-m and using its high-level features.
      + "Part 2: Using VTK-m" covers the core fundamental components of
        VTK-m including data model, worklets, and filters.
      + "Part 3: Developing with VTK-m" covers how to develop new worklets
        and filters.
      + "Part 4: Advanced Development" covers topics such as new worklet
        types and custom device adapters.
30

31
  + Community discussion takes place on the [VTK-m users email list].
32

33 34
  + Doxygen-generated nightly reference documentation is available
    [online][VTK-m Doxygen].
35

36

37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
## Contributing ##

There are many ways to contribute to [VTK-m], with varying levels of
effort.

  + Ask a question on the [VTK-m users email list].

  + Submit new or add to discussions of a feature requests or bugs on the
    [VTK-m Issue Tracker].

  + Submit a Pull Request to improve [VTK-m]
      + See [CONTRIBUTING.md] for detailed instructions on how to create a
        Pull Request.
      + See the [VTK-m Coding Conventions] that must be followed for
        contributed code.

  + Submit an Issue or Pull Request for the [VTK-m Users Guide]
54 55


56 57 58 59 60 61 62 63
## Dependencies ##

VTK-m Requires:

  + C++11 Compiler. VTK-m has been confirmed to work with the following
      + GCC 4.8+
      + Clang 3.3+
      + XCode 5.0+
64
      + MSVC 2015+
65 66
  + [CMake](http://www.cmake.org/download/)
      + CMake 3.3+ (for any build)
67
      + CMake 3.9+ (for CUDA build or OpenMP build)
68
      + CMake 3.11+ (for Visual Studio generator)
69

70 71
Optional dependencies are:

72
  + CUDA Device Adapter
73
      + [Cuda Toolkit 7.5+](https://developer.nvidia.com/cuda-toolkit)
74 75
  + TBB Device Adapter
      + [TBB](https://www.threadingbuildingblocks.org/)
76
  + OpenMP Device Adapter
77
      + Requires a compiler that supports OpenMP >= 4.0.
78 79 80 81 82 83
  + OpenGL Rendering
      + The rendering module contains multiple rendering implementations
        including standalone rendering code. The rendering module also
        includes (optionally built) OpenGL rendering classes.
      + The OpenGL rendering classes require that you have a extension
        binding library and one rendering library. A windowing library is
84
        not needed except for some optional tests.
85 86
  + Extension Binding
      + [GLEW](http://glew.sourceforge.net/)
87 88 89 90
  + On Screen Rendering
      + OpenGL Driver
      + Mesa Driver
  + On Screen Rendering Tests
91 92
      + [GLFW](http://www.glfw.org/)
      + [GLUT](http://freeglut.sourceforge.net/)
93 94 95
  + Headless Rendering
      + [OS Mesa](https://www.mesa3d.org/osmesa.html)
      + EGL Driver
96

97 98 99 100 101 102 103 104 105 106 107 108 109 110 111
VTK-m has been tested on the following configurations:
  + On Linux 
      + GCC 4.8.5, 5.4.0, 6.4.0, Clang 3.8.0
      + CMake 3.9.2, 3.9.3, 3.10.3
      + CUDA 8.0.61, 9.1.85
      + TBB 4.4 U2, 2017 U7
  + On Windows
      + Visual Studio 2015, 2017
      + CMake 3.3, 3.11.1
      + CUDA 9.1.85
      + TBB 2017 U3, 2018 U2
  + On MacOS
      + AppleClang 6.0
      + TBB 2017 U6

112

113
## Building ##
114

115 116 117 118
VTK-m supports all majors platforms (Windows, Linux, OSX), and uses CMake
to generate all the build rules for the project. The VTK-m source code is
available from the [VTK-m download page] or by directly cloning the [VTK-m
git repository].
119 120 121 122 123 124 125 126 127 128

```
$ git clone https://gitlab.kitware.com/vtk/vtk-m.git
$ mkdir vtkm-build
$ cd vtkm-build
$ cmake-gui ../vtk-m
$ make -j<N>
$ make test
```

129 130 131 132
A more detailed description of building VTK-m is available in the [VTK-m
Users Guide].


133 134 135 136 137 138 139 140 141 142 143 144
## Example##

The VTK-m source distribution includes a number of examples. The goal of the
VTK-m examples is to illustrate specific VTK-m concepts in a consistent and 
simple format. However, these examples only cover a small part of the
capabilities of VTK-m.

Below is a simple example of using VTK-m to load a VTK image file, run the
Marching Cubes algorithm on it, and render the results to an image:

```cpp
vtkm::io::reader::VTKDataSetReader reader("path/to/vtk_image_file");
145 146
vtkm::cont::DataSet inputData = reader.ReadDataSet();
std::string fieldName = "scalars";
147

148 149 150
vtkm::Range range;
inputData.GetPointField(fieldName).GetRange(&range);
vtkm::Float64 isovalue = range.Center();
151 152 153 154

// Create an isosurface filter
vtkm::filter::MarchingCubes filter;
filter.SetIsoValue(0, isovalue);
155
filter.SetActiveField(fieldName);
156
vtkm::cont::DataSet outputData = filter.Execute(inputData);
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174

// compute the bounds and extends of the input data
vtkm::Bounds coordsBounds = inputData.GetCoordinateSystem().GetBounds();
vtkm::Vec<vtkm::Float64,3> totalExtent( coordsBounds.X.Length(),
                                        coordsBounds.Y.Length(),
                                        coordsBounds.Z.Length() );
vtkm::Float64 mag = vtkm::Magnitude(totalExtent);
vtkm::Normalize(totalExtent);

// setup a camera and point it to towards the center of the input data
vtkm::rendering::Camera camera;
camera.ResetToBounds(coordsBounds);

camera.SetLookAt(totalExtent*(mag * .5f));
camera.SetViewUp(vtkm::make_Vec(0.f, 1.f, 0.f));
camera.SetClippingRange(1.f, 100.f);
camera.SetFieldOfView(60.f);
camera.SetPosition(totalExtent*(mag * 2.f));
175
vtkm::cont::ColorTable colorTable("inferno");
176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194

// Create a mapper, canvas and view that will be used to render the scene
vtkm::rendering::Scene scene;
vtkm::rendering::MapperRayTracer mapper;
vtkm::rendering::CanvasRayTracer canvas(512, 512);
vtkm::rendering::Color bg(0.2f, 0.2f, 0.2f, 1.0f);

// Render an image of the output isosurface
scene.AddActor(vtkm::rendering::Actor(outputData.GetCellSet(),
                                      outputData.GetCoordinateSystem(),
                                      outputData.GetField(fieldName),
                                      colorTable));
vtkm::rendering::View3D view(scene, mapper, canvas, camera, bg);
view.Initialize();
view.Paint();
view.SaveAs("demo_output.pnm");
```


195
## License ##
196 197 198 199 200

VTK-m is distributed under the OSI-approved BSD 3-clause License.
See [LICENSE.txt](LICENSE.txt) for details.


201 202 203 204 205 206 207 208 209 210 211
[VTK-m]:                    https://gitlab.kitware.com/vtk/vtk-m/
[VTK-m Coding Conventions]: docs/CodingConventions.md
[VTK-m Doxygen]:            http://m.vtk.org/documentation/
[VTK-m download page]:      http://m.vtk.org/index.php/VTK-m_Releases
[VTK-m git repository]:     https://gitlab.kitware.com/vtk/vtk-m/
[VTK-m Issue Tracker]:      https://gitlab.kitware.com/vtk/vtk-m/issues
[VTK-m Overview]:           http://m.vtk.org/images/2/29/VTKmVis2016.pptx 
[VTK-m Users Guide]:        http://m.vtk.org/images/c/c8/VTKmUsersGuide.pdf
[VTK-m users email list]:   http://vtk.org/mailman/listinfo/vtkm
[VTK-m Wiki]:               http://m.vtk.org/
[CONTRIBUTING.md]:          CONTRIBUTING.md