Updates will be applied on October 27th between 12pm - 12:45pm EDT (UTC-0400). Gitlab may be slow during the maintenance window.

README.md 8.14 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
32
33
34
35
36
  + A practical [VTK-m Tutorial] based in what users want to accomplish with
    VTK-m:
      + Building VTK-m and using existing VTK-m data structures and filters.
      + Algorithm development with VTK-m.
      + Writing new VTK-m filters.

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

39
40
  + Doxygen-generated nightly reference documentation is available
    [online][VTK-m Doxygen].
41

42

43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
## 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]
60
61


62
63
64
65
66
## Dependencies ##

VTK-m Requires:

  + C++11 Compiler. VTK-m has been confirmed to work with the following
67
      + GCC 5.4+
Allison Vacanti's avatar
Allison Vacanti committed
68
      + Clang 5.0+
69
      + XCode 5.0+
70
      + MSVC 2015+
71
      + Intel 17.0.4+
72
  + [CMake](http://www.cmake.org/download/)
73
      + CMake 3.12+
74
      + CMake 3.13+ (for CUDA support)
75

76
77
Optional dependencies are:

78
  + CUDA Device Adapter
79
80
      + [Cuda Toolkit 9.2, >= 10.2](https://developer.nvidia.com/cuda-toolkit)
      + Note CUDA >= 10.2 is required on Windows
81
82
  + TBB Device Adapter
      + [TBB](https://www.threadingbuildingblocks.org/)
83
  + OpenMP Device Adapter
84
      + Requires a compiler that supports OpenMP >= 4.0.
85
86
87
88
89
90
  + 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
91
        not needed except for some optional tests.
92
93
  + Extension Binding
      + [GLEW](http://glew.sourceforge.net/)
94
95
96
97
  + On Screen Rendering
      + OpenGL Driver
      + Mesa Driver
  + On Screen Rendering Tests
98
99
      + [GLFW](http://www.glfw.org/)
      + [GLUT](http://freeglut.sourceforge.net/)
100
101
102
  + Headless Rendering
      + [OS Mesa](https://www.mesa3d.org/osmesa.html)
      + EGL Driver
103

104
VTK-m has been tested on the following configurations:c
105
  + On Linux
106
      + GCC 5.4.0, 5.4, 6.5, 7.4, 8.2, 9.2; Clang 5, 8; Intel 17.0.4; 19.0.0
107
      + CMake 3.12, 3.13, 3.16, 3.17
108
      + CUDA 9.2, 10.2, 11.0, 11.1 
109
110
111
      + TBB 4.4 U2, 2017 U7
  + On Windows
      + Visual Studio 2015, 2017
112
      + CMake 3.12, 3.17
113
      + CUDA 10.2
114
115
      + TBB 2017 U3, 2018 U2
  + On MacOS
116
      + AppleClang 9.1
117
      + CMake 3.12
118
      + TBB 2018
119

120

121
## Building ##
122

123
124
125
126
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].
127

128
129
130
131
132
133
134
The basic procedure for building VTK-m is to unpack the source, create a
build directory, run CMake in that build directory (pointing to the source)
and then build. Here are some example *nix commands for the process
(individual commands may vary).

```sh
$ tar xvzf ~/Downloads/vtk-m-v1.4.0.tar.gz
135
136
$ mkdir vtkm-build
$ cd vtkm-build
137
138
$ cmake-gui ../vtk-m-v1.4.0
$ cmake --build -j .              # Runs make (or other build program)
139
140
```

141
142
143
144
A more detailed description of building VTK-m is available in the [VTK-m
Users Guide].


145
## Example ##
146
147

The VTK-m source distribution includes a number of examples. The goal of the
148
VTK-m examples is to illustrate specific VTK-m concepts in a consistent and
149
150
151
152
153
154
155
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
Vicente Bolea's avatar
Vicente Bolea committed
156
157
158
159
#include <vtkm/Bounds.h>
#include <vtkm/Range.h>
#include <vtkm/cont/ColorTable.h>
#include <vtkm/filter/Contour.h>
160
#include <vtkm/io/VTKDataSetReader.h>
Vicente Bolea's avatar
Vicente Bolea committed
161
162
163
164
165
166
167
168
#include <vtkm/rendering/Actor.h>
#include <vtkm/rendering/Camera.h>
#include <vtkm/rendering/CanvasRayTracer.h>
#include <vtkm/rendering/Color.h>
#include <vtkm/rendering/MapperRayTracer.h>
#include <vtkm/rendering/Scene.h>
#include <vtkm/rendering/View3D.h>

169
vtkm::io::VTKDataSetReader reader("path/to/vtk_image_file.vtk");
170
171
vtkm::cont::DataSet inputData = reader.ReadDataSet();
std::string fieldName = "scalars";
172

173
174
175
vtkm::Range range;
inputData.GetPointField(fieldName).GetRange(&range);
vtkm::Float64 isovalue = range.Center();
176
177

// Create an isosurface filter
Li-Ta Lo's avatar
Li-Ta Lo committed
178
vtkm::filter::Contour filter;
179
filter.SetIsoValue(0, isovalue);
180
filter.SetActiveField(fieldName);
181
vtkm::cont::DataSet outputData = filter.Execute(inputData);
182
183
184
185
186
187
188

// compute the bounds and extends of the input data
vtkm::Bounds coordsBounds = inputData.GetCoordinateSystem().GetBounds();

// setup a camera and point it to towards the center of the input data
vtkm::rendering::Camera camera;
camera.ResetToBounds(coordsBounds);
189
vtkm::cont::ColorTable colorTable("inferno");
190
191
192
193
194
195
196
197
198
199
200
201
202
203

// 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.Paint();
204
view.SaveAs("demo_output.png");
205
206
```

Vicente Bolea's avatar
Vicente Bolea committed
207
208
209
210
211
212
213
214
215
216
217
218
219
A minimal CMakeLists.txt such as the following one can be used to build this
example.

```CMake
project(example)

set(VTKm_DIR "/somepath/lib/cmake/vtkm-XYZ")

find_package(VTKm REQUIRED)

add_executable(example example.cxx)
target_link_libraries(example vtkm_cont vtkm_rendering)
```
220

221
## License ##
222
223
224
225
226

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


227
228
229
230
231
[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/
232
[VTK-m Issue Tracker]:      https://gitlab.kitware.com/vtk/vtk-m/-/issues
233
[VTK-m Overview]:           http://m.vtk.org/images/2/29/VTKmVis2016.pptx
234
235
236
[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/
237
[VTK-m Tutorial]:           http://m.vtk.org/index.php/Tutorial
238
[CONTRIBUTING.md]:          CONTRIBUTING.md