Add `vtkm/Geometry.h` and test it.

This commit adds several geometric constructs to vtk-m
in the `vtkm/Geometry.h` header. They may be used from
both the execution and control environments.

We also add methods to perform projection and Gram-Schmidt
orthonormalization to `vtkm/VectorAnalysis.h`.

See `docs/changelog/geometry.md` included in this commit
for more information.

docs/changelog/geometry.md

+# New geometry classes and header.
+
+There are now some additional structures available both
+the control and execution environments for representing
+geometric entities (mostly of dimensions 2 and 3).
+These new structures are now in `vtkm/Geometry.h` and
+demonstrated/tested in `vtkm/testing/TestingGeometry.h`:
+
++ `Ray<CoordType, Dimension, IsTwoSided>`.
+  Instances of this struct represent a semi-infinite line
+  segment in a 2-D plane or in a 3-D space, depending on the
+  integer dimension specified as a template parameter.
+  Its state is the point at the start of the ray (`Origin`)
+  plus the ray's `Direction`, a unit-length vector.
+  If the third template parameter (IsTwoSided) is true, then
+  the ray serves as an infinite line. Otherwise, the ray will
+  only report intersections in its positive halfspace.
++ `LineSegment<CoordType, Dimension>`.
+  Instances of this struct represent a finite line segment
+  in a 2-D plane or in a 3-D space, depending on the integer
+  dimension specified as a template parameter.
+  Its state is the coordinates of its `Endpoints`.
++ `Plane<CoordType>`.
+  Instances of this struct represent a plane in 3-D.
+  Its state is the coordinates of a base point (`Origin`) and
+  a unit-length normal vector (`Normal`).
++ `Sphere<CoordType, Dimension>`.
+  Instances of this struct represent a *d*-dimensional sphere.
+  Its state is the coordinates of its center plus a radius.
+  It is also aliased with a `using` statment to `Circle<CoordType>`
+  for the specific case of 2-D.
+
+These structures provide useful queries and generally
+interact with one another.
+For instance, it is possible to intersect lines and planes
+and compute distances.
+
+For ease of use, there are also several `using` statements
+that alias these geometric structures to names that specialize
+them for a particular dimension or other template parameter.
+As an example, `Ray<CoordType, Dimension, true>` is aliased
+to `Line<CoordType, Dimension>` and `Ray<CoordType, 3, true>`
+is aliased to `Line3<CoordType>` and `Ray<FloatDefault, 3, true>`
+is aliased to `Line3d`.
+
+## Design patterns
+
+If you plan to add a new geometric entity type,
+please adopt these conventions:
+
++ Each geometric entity may be default-constructed.
+  The default constructor will initialize the state to some
+  valid unit-length entity, usually with some part of
+  its state at the origin of the coordinate system.
++ Entities may always be constructed by passing in values
+  for their internal state.
+  Alternate construction methods are declared as free functions
+  such as `make_CircleFrom3Points()`
++ Use template metaprogramming to make methods available
+  only when the template dimension gives them semantic meaning.
+  For example, a 2-D line segment's perpendicular bisector
+  is another line segment, but a 3-D line segment's perpendicular
+  line segment is a plane.
+  Note how this is accomplished and apply this pattern to
+  new geometric entities or new methods on existing entities.
++ Some entities may have invalid state.
+  If this is possible, the entity will have an `IsValid()` method.
+  For example, a sphere may be invalid because the user or some
+  construction technique specified a zero or negative radius.
++ When signed distance is semantically meaningful, provide it
+  in favor of or in addition to unsigned distance.
++ Accept a tolerance parameter when appropriate,
+  but provide a sensible default value.
+  You may want to perform exact arithmetic versions of tests,
+  but please provide fast, tolerance-based versions as well.

vtkm/CMakeLists.txt

@@ -35,6 +35,7 @@ set(headers
   CellShape.h
   CellTraits.h
   Flags.h
+  Geometry.h
   Hash.h
   ImplicitFunction.h
   ListTag.h
@@ -60,11 +61,20 @@ set(headers
   VecVariable.h
   VirtualObjectBase.h
   UnaryPredicates.h
-  )
+)
+
+set(template_sources
+  Geometry.hxx
+)
 
 vtkm_pyexpander_generated_file(Math.h)
 
-vtkm_declare_headers(${headers})
+vtkm_declare_headers(
+  ${headers}
+  ${template_sources}
+  EXCLUDE_FROM_TESTING
+    ${template_sources}
+)
 
 #-----------------------------------------------------------------------------
 #first add all the components vtkm that are shared between control and exec

vtkm/Math.h

@@ -1815,6 +1815,18 @@ static inline VTKM_EXEC_CONT T Min(const T& x, const T& y)
   return detail::Min(x, y, typename vtkm::TypeTraits<T>::DimensionalityTag());
 }
 
+/// Clamp \p x to the given range.
+///
+
+inline VTKM_EXEC_CONT vtkm::Float32 Clamp(vtkm::Float32 x, vtkm::Float32 lo, vtkm::Float32 hi)
+{
+  return x > lo ? (x < hi ? x : hi) : lo;
+}
+
+inline VTKM_EXEC_CONT vtkm::Float64 Clamp(vtkm::Float64 x, vtkm::Float64 lo, vtkm::Float64 hi)
+{
+  return x > lo ? (x < hi ? x : hi) : lo;
+}
 //-----------------------------------------------------------------------------
 
 //#ifdef VTKM_CUDA

vtkm/Math.h.in

@@ -637,6 +637,18 @@ static inline VTKM_EXEC_CONT T Min(const T& x, const T& y)
   return detail::Min(x, y, typename vtkm::TypeTraits<T>::DimensionalityTag());
 }
 
+/// Clamp \p x to the given range.
+///
+
+inline VTKM_EXEC_CONT vtkm::Float32 Clamp(vtkm::Float32 x, vtkm::Float32 lo, vtkm::Float32 hi)
+{
+  return x > lo ? (x < hi ? x : hi) : lo;
+}
+
+inline VTKM_EXEC_CONT vtkm::Float64 Clamp(vtkm::Float64 x, vtkm::Float64 lo, vtkm::Float64 hi)
+{
+  return x > lo ? (x < hi ? x : hi) : lo;
+}
 //-----------------------------------------------------------------------------
 
 //#ifdef VTKM_CUDA

vtkm/TypeListTag.h

@@ -92,6 +92,19 @@ struct TypeListTagFieldVec4
 {
 };
 
+/// A list containing common types for floating-point vectors. Specifically contains
+/// floating point vectors of size 2, 3, and 4 with floating point components.
+/// Scalars are not included.
+///
+struct TypeListTagFloatVec : vtkm::ListTagBase<vtkm::Vec<vtkm::Float32, 2>,
+                                               vtkm::Vec<vtkm::Float64, 2>,
+                                               vtkm::Vec<vtkm::Float32, 3>,
+                                               vtkm::Vec<vtkm::Float64, 3>,
+                                               vtkm::Vec<vtkm::Float32, 4>,
+                                               vtkm::Vec<vtkm::Float64, 4>>
+{
+};
+
 /// A list containing common types for values in fields. Specifically contains
 /// floating point scalars and vectors of size 2, 3, and 4 with floating point
 /// components.

vtkm/VectorAnalysis.h

@@ -208,6 +208,84 @@ TriangleNormal(const vtkm::Vec<T, 3>& a, const vtkm::Vec<T, 3>& b, const vtkm::V
   return vtkm::Cross(b - a, c - a);
 }
 
+//-----------------------------------------------------------------------------
+/// \brief Project a vector onto another vector.
+///
+/// This method computes the orthogonal projection of the vector v onto u;
+/// that is, it projects its first argument onto its second.
+///
+/// Note that if the vector \a u has zero length, the output
+/// vector will have all its entries equal to NaN.
+template <typename T, int N>
+VTKM_EXEC_CONT vtkm::Vec<T, N> Project(const vtkm::Vec<T, N>& v, const vtkm::Vec<T, N>& u)
+{
+  T uu = vtkm::Dot(u, u);
+  T uv = vtkm::Dot(u, v);
+  T factor = uv / uu;
+  vtkm::Vec<T, N> result = factor * u;
+  return result;
+}
+
+//-----------------------------------------------------------------------------
+/// \brief Project a vector onto another vector, returning only the projected distance.
+///
+/// This method computes the orthogonal projection of the vector v onto u;
+/// that is, it projects its first argument onto its second.
+///
+/// Note that if the vector \a u has zero length, the output will be NaN.
+template <typename T, int N>
+VTKM_EXEC_CONT T ProjectedDistance(const vtkm::Vec<T, N>& v, const vtkm::Vec<T, N>& u)
+{
+  T uu = vtkm::Dot(u, u);
+  T uv = vtkm::Dot(u, v);
+  T factor = uv / uu;
+  return factor;
+}
+
+//-----------------------------------------------------------------------------
+/// \brief Perform Gram-Schmidt orthonormalization for 3-D vectors.
+///
+/// See https://en.wikipedia.org/wiki/Gram%E2%80%93Schmidt_process for details.
+/// The first output vector will always be parallel to the first input vector.
+/// The remaining output vectors will be orthogonal and unit length and have
+/// the same handedness as their corresponding input vectors.
+///
+/// This method is geometric.
+/// It does not require a matrix solver.
+/// However, unlike the algebraic eigensolver techniques which do use matrix
+/// inversion, this method may return zero-length output vectors if some input
+/// vectors are collinear. The number of non-zero (to within the specified
+/// tolerance, \a tol ) output vectors is the return value.
+template <typename T, int N>
+VTKM_EXEC_CONT int Orthonormalize(const vtkm::Vec<vtkm::Vec<T, N>, N>& inputs,
+                                  vtkm::Vec<vtkm::Vec<T, N>, N>& outputs,
+                                  T tol = static_cast<T>(1e-6))
+{
+  int j = 0; // j is the number of non-zero-length, non-collinear inputs encountered.
+  vtkm::Vec<vtkm::Vec<T, N>, N> u;
+  for (int i = 0; i < N; ++i)
+  {
+    u[j] = inputs[i];
+    for (int k = 0; k < j; ++k)
+    {
+      u[j] -= vtkm::Project(inputs[i], u[k]);
+    }
+    T rmag = vtkm::RMagnitude(u[j]);
+    if (rmag * tol > 1.0)
+    {
+      // skip this vector, it is zero-length or collinear with others.
+      continue;
+    }
+    outputs[j] = rmag * u[j];
+    ++j;
+  }
+  for (int i = j; i < N; ++i)
+  {
+    outputs[j] = Vec<T, N>{ 0. };
+  }
+  return j;
+}
+
 } // namespace vtkm
 
 #endif //vtk_m_VectorAnalysis_h

vtkm/cont/cuda/testing/CMakeLists.txt

@@ -28,6 +28,7 @@ set(unit_tests
   UnitTestCudaDataSetExplicit.cu
   UnitTestCudaDataSetSingleType.cu
   UnitTestCudaDeviceAdapter.cu
+  UnitTestCudaGeometry.cu
   UnitTestCudaImplicitFunction.cu
   UnitTestCudaMath.cu
   UnitTestCudaShareUserProvidedManagedMemory.cu

vtkm/cont/cuda/testing/UnitTestCudaGeometry.cu

+//=============================================================================
+//
+//  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.
+//
+//  Copyright 2015 National Technology & Engineering Solutions of Sandia, LLC (NTESS).
+//  Copyright 2015 UT-Battelle, LLC.
+//  Copyright 2015 Los Alamos National Security.
+//
+//  Under the terms of Contract DE-NA0003525 with NTESS,
+//  the U.S. Government retains certain rights in this software.
+//  Under the terms of Contract DE-AC52-06NA25396 with Los Alamos National
+//  Laboratory (LANL), the U.S. Government retains certain rights in
+//  this software.
+//
+//=============================================================================
+
+// Make sure that the tested code is using the device adapter specified. This
+// is important in the long run so we don't, for example, use the CUDA device
+// for a part of an operation where the TBB device was specified.
+#define VTKM_DEVICE_ADAPTER VTKM_DEVICE_ADAPTER_ERROR
+
+#include <vtkm/cont/RuntimeDeviceTracker.h>
+#include <vtkm/cont/cuda/DeviceAdapterCuda.h>
+#include <vtkm/testing/TestingGeometry.h>
+
+int UnitTestCudaGeometry(int, char* [])
+{
+  auto tracker = vtkm::cont::GetGlobalRuntimeDeviceTracker();
+  tracker.ForceDevice(vtkm::cont::DeviceAdapterTagCuda{});
+  return vtkm::cont::testing::Testing::Run(
+    UnitTestGeometryNamespace::RunGeometryTests<vtkm::cont::DeviceAdapterTagCuda>);
+}

vtkm/cont/serial/testing/CMakeLists.txt

@@ -28,6 +28,7 @@ set(unit_tests
   UnitTestSerialDataSetExplicit.cxx
   UnitTestSerialDataSetSingleType.cxx
   UnitTestSerialDeviceAdapter.cxx
+  UnitTestSerialGeometry.cxx
   UnitTestSerialImplicitFunction.cxx
   UnitTestSerialPointLocatorUniformGrid.cxx
   UnitTestSerialVirtualObjectHandle.cxx

vtkm/cont/serial/testing/UnitTestSerialGeometry.cxx

+//=============================================================================
+//
+//  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.
+//
+//  Copyright 2015 National Technology & Engineering Solutions of Sandia, LLC (NTESS).
+//  Copyright 2015 UT-Battelle, LLC.
+//  Copyright 2015 Los Alamos National Security.
+//
+//  Under the terms of Contract DE-NA0003525 with NTESS,
+//  the U.S. Government retains certain rights in this software.
+//  Under the terms of Contract DE-AC52-06NA25396 with Los Alamos National
+//  Laboratory (LANL), the U.S. Government retains certain rights in
+//  this software.
+//
+//=============================================================================
+
+// Make sure that the tested code is using the device adapter specified. This
+// is important in the long run so we don't, for example, use the CUDA device
+// for a part of an operation where the TBB device was specified.
+#define VTKM_DEVICE_ADAPTER VTKM_DEVICE_ADAPTER_ERROR
+
+#include <vtkm/cont/RuntimeDeviceTracker.h>
+#include <vtkm/cont/serial/DeviceAdapterSerial.h>
+#include <vtkm/testing/TestingGeometry.h>
+
+int UnitTestSerialGeometry(int, char* [])
+{
+  auto tracker = vtkm::cont::GetGlobalRuntimeDeviceTracker();
+  tracker.ForceDevice(vtkm::cont::DeviceAdapterTagSerial{});
+  return vtkm::cont::testing::Testing::Run(
+    UnitTestGeometryNamespace::RunGeometryTests<vtkm::cont::DeviceAdapterTagSerial>);
+}

vtkm/testing/CMakeLists.txt

@@ -21,6 +21,7 @@
 set(headers
   Testing.h
   TestingMath.h
+  TestingGeometry.h
   OptionParser.h
   VecTraitsTests.h
   )

vtkm/testing/UnitTestVectorAnalysis.cxx

@@ -158,6 +158,21 @@ void TestCross(const vtkm::Vec<T, 3>& x, const vtkm::Vec<T, 3>& y)
                    "Triangle normal is not really normal.");
 }
 
+template <typename VectorBasisType>
+void TestOrthonormalize(const VectorBasisType& inputs, int expectedRank)
+{
+  VectorBasisType outputs;
+  int actualRank = vtkm::Orthonormalize(inputs, outputs);
+  std::cout << "Testing orthonormalize\n"
+            << "  Rank " << actualRank << " expected " << expectedRank << "\n"
+            << "  Basis vectors:\n";
+  for (int i = 0; i < actualRank; ++i)
+  {
+    std::cout << "    " << i << "  " << outputs[i] << "\n";
+  }
+  VTKM_TEST_ASSERT(test_equal(actualRank, expectedRank), "Orthonormalized rank is unexpected.");
+}
+
 struct TestLinearFunctor
 {
   template <typename T>
@@ -208,10 +223,43 @@ struct TestCrossFunctor
   }
 };
 
+struct TestVectorFunctor
+{
+  template <typename VectorType>
+  void operator()(const VectorType&) const
+  {
+    constexpr int NUM_COMPONENTS = VectorType::NUM_COMPONENTS;
+    using Traits = vtkm::VecTraits<VectorType>;
+    using ComponentType = typename Traits::ComponentType;
+    vtkm::Vec<VectorType, NUM_COMPONENTS> basis;
+    VectorType normalizedVector = VectorType(vtkm::RSqrt(ComponentType(NUM_COMPONENTS)));
+    VectorType zeroVector = VectorType(ComponentType(0));
+    // Test with a degenerate set of inputs:
+    basis[0] = zeroVector;
+    basis[1] = normalizedVector;
+    for (int ii = 2; ii < NUM_COMPONENTS; ++ii)
+    {
+      basis[ii] = zeroVector;
+    }
+    TestOrthonormalize(basis, 1);
+    // Now test with a valid set of inputs:
+    for (int ii = 0; ii < NUM_COMPONENTS; ++ii)
+    {
+      for (int jj = 0; jj < NUM_COMPONENTS; ++jj)
+      {
+        basis[ii][jj] =
+          ComponentType(jj == ii ? 1.0 : 0.0) + ComponentType(0.05) * ComponentType(jj);
+      }
+    }
+    TestOrthonormalize(basis, NUM_COMPONENTS);
+  }
+};
+
 void TestVectorAnalysis()
 {
   vtkm::testing::Testing::TryTypes(TestLinearFunctor(), vtkm::TypeListTagField());
   vtkm::testing::Testing::TryTypes(TestCrossFunctor(), vtkm::TypeListTagFieldVec3());
+  vtkm::testing::Testing::TryTypes(TestVectorFunctor(), vtkm::TypeListTagFloatVec());
 }
 
 } // anonymous namespace