diff --git a/tutorial/README.md b/tutorial/README.md index 154cf94b1..37d29710d 100644 --- a/tutorial/README.md +++ b/tutorial/README.md @@ -1,9 +1,104 @@ -# vtk-m-tutorial -The repository containts code samples for the tutorial of the [VTK-m code library](http://m.vtk.org). -Other tutorial material is avaialble on the [VTK-m tutorial](https://m.vtk.org/tutorial) +# VTK-m Tutorial -# Organization -The tutorial is divided into 3 sections based on what users want to accomplish with VTK-m: -1. Using VTK-m -2. Algorithm development with VTK-m -3. Advanced development with VTK-m +This page contains materials and instructions for the VTK-m tutorial. +[Slides] are available, and the instructions for getting the example source +code exercises are below. + +Developers interested in VTK-m should also consult _[The VTK-m User's +Guide]_, which contains a quick start guide along with detailed +documentation of most of VTK-m's features. + +Further information is available at https://m.vtk.org. + +## Downloading VTK-m + +The tutorial materials are maintained as part of the VTK-m code repository +to help keep the examples up to date. Thus, getting, compiling, and running +the tutorial examples is all part of VTK-m itself. + +There are two options for getting the VTK-m source code. You could either +download a tarball for a release or you can clone the source code directly +from the [VTK-m git repository]. + +### Downloading a VTK-m Release Tarball + +Souce code archives for every VTK-m release are posted on the [VTK-m +releases page] in multiple archive formats. Simply download an archive for +the desired version of VTK-m and extract the contents from that archive. + +### Cloning the VTK-m Git Repository + +Developers familiar with git might find it easier to simply clone the [VTK-m +git repository]. The latest VTK-m release is always on the `release` branch +and can be cloned as so. + +```sh +git clone --branch release https://gitlab.kitware.com/vtk/vtk-m.git +``` + +If you are feeling more daring, you can simply clone the main branch with +the latest developments. + +```sh +git clone https://gitlab.kitware.com/vtk/vtk-m.git +``` + +## Building VTK-m and the Tutorial Examples + +To build VTK-m, you will need at a minimum CMake and, of course, a C++ +compiler. The [VTK-m dependencies list] has details on required and +optional packages. + +When configuring the build with CMake, turn on the `VTKm_ENABLE_TUTORIALS` +option. There are lots of other options available including the ability to +compile for many different types of devices. But if this is your first +experience with VTK-m, it might be best to start with a simple build. + +Here is a list of minimal commands to download and build VTK-m. + +```sh +git clone --branch release https://gitlab.kitware.com/vtk/vtk-m.git +mkdir vtk-m-build +cd vtk-m-build +cmake ../vtk-m -DVTKm_ENABLE_TUTORIALS=ON +make -j8 +``` + +The first line above downloads VTK-m using git. You can choose to download +a release as described [above](#downloading-a-vtk-m-release-tarball). Note +that if you do so, the source code will be placed in a directory named +something like `vtk-m-vX.X.X` rather than the `vtk-m` directory you get by +default when cloning VTK-m. + +## Examples + +The tutorial contains several examples that can be built and edited. Each +example is described in detail in the [slides]. Here is a brief description +of each one, listed from most basic to increasing complexity. + +* **io.cxx** A bare minimum example of loading a `DataSet` object from a + data file and then writing it out again. +* **contour.cxx** A basic example of running a filter that extracts + isosurfaces from a data set. +* **contour_two_fields.cxx** A simple extension of contour.cxx that selects + two of the input fields to be passed to the output. +* **two_filters.cxx** Further extends the contour.cxx example by running a + sequence of 2 filters. The first extracts the isosurfaces and the second + clips the surface by a second fields. +* **rendering.cxx** Demonstrates how to render data in VTK-m. +* **error_handling.cxx** Demonstrates catching exceptions to react to + errors in VTK-m execution. +* **logging.cxx** Uses VTK-m's logging mechanism to write additional + information to the program output. +* **mag_grad.cxx** The implementation of a simple VTK-m filter which + happens to take the magnitude of a vector. +* **point_to_cell.cxx** A slightly more complicated filter that averages + the values of a point field for each cell. +* **extract_edges.cxx** A fully featured example of a nontrivial filter + that extracts topological features from a mesh. + +[slides]: https://www.dropbox.com/s/4pp4xf1jlvlt4th/VTKm_Tutorial_VIS22.pptx?dl=0 +[The VTK-m User's Guide]: https://gitlab.kitware.com/vtk/vtk-m-user-guide/-/wikis/home +[VTK-m git repository]: https://gitlab.kitware.com/vtk/vtk-m +[VTK-m releases page]: https://gitlab.kitware.com/vtk/vtk-m/-/releases +[VTK-m dependencies list]: https://gitlab.kitware.com/vtk/vtk-m#dependencies diff --git a/tutorial/logging.cxx b/tutorial/logging.cxx index f5f1e29b8..2381c5b93 100644 --- a/tutorial/logging.cxx +++ b/tutorial/logging.cxx @@ -11,6 +11,8 @@ #include #include +// Note that to see all of the logging output generated by this example, run +// the program with the --vtkm-log-level=1 argument. int main(int argc, char** argv) { diff --git a/tutorial/mag_grad_generalized.cxx b/tutorial/mag_grad_generalized.cxx deleted file mode 100644 index 5aea2ec47..000000000 --- a/tutorial/mag_grad_generalized.cxx +++ /dev/null @@ -1,103 +0,0 @@ -//============================================================================ -// Copyright (c) Kitware, Inc. -// All rights reserved. -// See LICENSE.txt for details. -// -// This software is distributed WITHOUT ANY WARRANTY; without even -// the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR -// PURPOSE. See the above copyright notice for more information. -//============================================================================ -#include -#include - -#include -#include -#include -#include - -#include -#include - -#include - -#include - -namespace vtkm -{ -namespace worklet -{ - -struct Magnitude : public vtkm::worklet::WorkletMapField -{ - using ControlSignature = void(FieldIn inputVectors, FieldOut outputMagnitudes); - - template - VTKM_EXEC void operator()(const vtkm::Vec& inVector, T& outMagnitude) const - { - outMagnitude = vtkm::Magnitude(inVector); - } -}; - -} // namespace worklet -} // namespace vtkm - -#include - -namespace vtkm -{ -namespace filter -{ - -class FieldMagnitude : public vtkm::filter::FilterField -{ -public: - using SupportedTypes = vtkm::TypeListTagVecCommon; - - template - VTKM_CONT cont::DataSet DoExecute(const vtkm::cont::DataSet& inDataSet, - const ArrayHandleType& inField, - const vtkm::filter::FieldMetadata& fieldMetadata, - vtkm::filter::PolicyBase) - { - VTKM_IS_ARRAY_HANDLE(ArrayHandleType); - - using ValueType = typename ArrayHandleType::ValueType; - using ComponentType = decltype(ValueType{}[0]); //component type of vector - - vtkm::cont::ArrayHandle outField; - this->Invoke(vtkm::worklet::Magnitude{}, inField, outField); - - std::string outFieldName = this->GetOutputFieldName(); - if (outFieldName == "") - { - outFieldName = fieldMetadata.GetName() + "_magnitude"; - } - - return vtkm::filter::CreateResult(inDataSet, outField, outFieldName, fieldMetadata); - } -}; - -} // namespace filter -} // namespace vtkm - -int main(int argc, char** argv) -{ - auto opts = vtkm::cont::InitializeOptions::DefaultAnyDevice; - vtkm::cont::InitializeResult config = vtkm::cont::Initialize(argc, argv, opts); - - vtkm::io::VTKDataSetReader reader("data/kitchen.vtk"); - vtkm::cont::DataSet ds_from_file = reader.ReadDataSet(); - - vtkm::filter::vector_analysis::Gradient grad; - grad.SetActiveField("c1"); - vtkm::cont::DataSet ds_from_grad = grad.Execute(ds_from_file); - - vtkm::filter::FieldMagnitude mag; - mag.SetActiveField("Gradients"); - vtkm::cont::DataSet mag_grad = mag.Execute(ds_from_grad); - - vtkm::io::VTKDataSetWriter writer("out_mag_grad.vtk"); - writer.WriteDataSet(mag_grad); - - return 0; -}