forked from lanl/PISTON
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
113 lines (83 loc) · 8.2 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
PISTON: A Portable Cross-Platform Data-Parallel Visualization and Analysis Library
Authors: Li-Ta Lo, Chris Sewell, and Jim Ahrens
Version 0.3
Copyright Notice:
Copyright (c) 2011, Los Alamos National Security, LLC
All rights reserved.
Copyright 2011. Los Alamos National Security, LLC. This software was produced under U.S. Government contract DE-AC52-06NA25396
for Los Alamos National Laboratory (LANL), which is operated by Los Alamos National Security, LLC for the U.S. Department of
Energy. The U.S. Government has rights to use, reproduce, and distribute this software.
NEITHER THE GOVERNMENT NOR LOS ALAMOS NATIONAL SECURITY, LLC MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LIABILITY
FOR THE USE OF THIS SOFTWARE.
If software is modified to produce derivative works, such modified software should be clearly marked, so as not to confuse it
with the version available from LANL.
Additionally, redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
· Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
· Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
· Neither the name of Los Alamos National Security, LLC, Los Alamos National Laboratory, LANL, the U.S. Government, nor the
names of its contributors may be used to endorse or promote products derived from this software without specific prior
written permission.
THIS SOFTWARE IS PROVIDED BY LOS ALAMOS NATIONAL SECURITY, LLC AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL LOS ALAMOS NATIONAL SECURITY, LLC OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.
Instructions for Use:
This project uses CMake. Create a build directory, pointing to this directory as the root of the source directory.
Dependencies include QT4 development, GLUT development, and Xmu development. To run the CUDA backend, an installation of NVIDIA's
CUDA toolkit (including the thrust include files) is required, and the location of this installation may be provided in the CMake
configuration. To run the demos that load files, VTK must also be installed.
Note that the CUDA backend used by this project uses NVIDIA's nvcc compiler, which is not compatible with gcc 4.5 and higher. If
your gcc version is 4.5 or newer, and you want to run the CUDA backend, you will also need to install an older version of gcc and
point to this version, either by changing environment variable paths or editing the compiler-bindir in the nvcc.profile file.
If you do not have the nvcc compiler or CUDA toolkit, you can still build the OpenMP examples. Set the USE_CUDA CMake variable to OFF.
You will then need to provide a directory for Thrust in the THRUST_DIR CMake variable, which you may download independently of CUDA
at the Thrust website (http://code.google.com/p/thrust/).
If you do not have VTK, you can still build the examples in the examples directory (but not the file-loading demos in the demos
directory). Set the BUILD_DEMO CMake variable to OFF.
A directory for data files may also be specified in CMake. Some sample data files are available in a separate gzip available for
download on the PISTON webpage, or you may use your own files in vti format. Only structured grids (vtkImageData) are currently
supported.
Filters for the currently implemented PISTON operators (isosurface and cut surfaces using marching_cube.h and thresholding
using threshold_geometry.h) are located in the piston subdirectory, along with data structures for input data and other
utilities.
This distribution includes example applications that run using the CUDA and OpenMP backends provided by the thrust
library. We have also developed a prototype OpenCL backend for the isosurface and cut surface operators, but that is not
included in this distribution as it is still in development. Thus, the GPU applications will only run on NVIDIA graphics cards.
The OpenMP backend provided in NVIDIA's thrust library includes only a serial rather than a parallel implementation of the
scan algorithm, which is used by PISTON's operators. Thus, in order to improve PISTON's OpenMP performance, replace the scan.inl
file in thrust/detail/device/omp with the scan.inl file provided in this directory.
The examples subdirectory includes several simple applications illustrating PISTON operators. The tangleGPU/tangleOMP example
generates an isosurface on an implicitly-defined field, mimicking the marching cubes example that is part of NVIDIA's GPU Computing
SDK. The cutplaneGPU/cutplaneOMP example generates a cut plane through this tangle field. The thresholdGPU/thresholdOMP example
applies the thresholding operator to an implicitly-defined sphere field. The tangleGPU, cutplaneGPU, and thresholdGPU examples use
the CUDA interop extension to render the computation results directly on the graphics card, but this may be disabled by setting the
ENABLE_INTEROP CMake variable to OFF.
The demoGPU and demoOMP applications allow the user to specify an input file at the command-line, apply either the
isosurface, cut surface, or threshold operator to it, rotate and zoom the view, and scroll through the isovalues, cut surface
positions, or threshold ranges using a QT user interface. The demoGPU and demoOMP applications compile from the same exact code,
the only difference being a compiler switch indicating whether thrust will compile to the CUDA or OpenMP backend. When these
applications are run, the first command-line parameter is the file name (within the data directory specified in CMake, or an
absolute path) for the data set to use. The second command-line parameter specifies which operator to use: 1=isosurface, 2=cut
plane, 3=threshold. If omitted, the default is isosurface (1). Optional third and fourth command-line parameters allows the user
to specify the range for the isovalues or thresholds. If these parameters are omitted, it defaults to using the minimum and maximum
values in the file. Thresholds are generated in the range [minValue, curValue], where curValue is determined by the position of the
slider in the GUI and ranges between minValue and maxValue. The number of processors used by OpenMP in demoOMP can be
controlled by setting the OMP_NUM_THREADS environment variable. The demoGPU application uses the interop extension by default,
but can be run without this by setting ENABLE_INTEROP to false in CMake.
You may either use your own data sets, or download sample data sets available as a separate tar.gz on the PISTON web page. Note that
some of these data sets may require more memory than is available on some graphics cards, so, if you get a std::bad_alloc error when
running demoGPU, try using one of the smaller data sets.
Here are some sample execution commands using the provided data sets:
% Apply the isosurface operator to the HighResOceanTemp.vti file within the isovalue range 0.0 to 32.0, running with CUDA, using low-res data set
./demoGPU LowResOceanTemp.vti 1 0.0 32.0
% Apply the isosurface operator to the HighResOceanTemp.vti file within the isovalue range 0.0 to 32.0, running with CUDA, using high-res data set
./demoGPU HighResOceanTemp.vti 1 0.0 32.0
% Apply the cut plane operator to the OceanTemp.vti file within the isovalue range 0.0 to 32.0, running with OpenMP
./demoOMP OceanTemp.vti 2 0.0 32.0
% Apply the threshold operator to the NorthPacificEddies.vti file within the threshold range -0.25 up to -0.25 to -0.04, running with CUDA
./demoGPU NorthPacificEddies.vti 3 -0.25 -0.04