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