Updated constructors for mesh info classes to conform with other filters

The `CellMeasures` and `MeshQuality` filters had constructors that took the
metric that the filter should generate. However, this is different than the
iterface of the rest of the filters. To make the interface more consistent,
these filters now have a default (no argument) constructor, and the metric
to compute is selected via a method. This makes it more clear what is being
done.

In addition, the documentation for these two classes is updated.

docs/changelog/mesh-info-constructors.md

@@ -0,0 +1,10 @@
+# Constructors for mesh info classes updated to conform with other filters
+
+The `CellMeasures` and `MeshQuality` filters had constructors that took the
+metric that the filter should generate. However, this is different than the
+iterface of the rest of the filters. To make the interface more consistent,
+these filters now have a default (no argument) constructor, and the metric
+to compute is selected via a method. This makes it more clear what is being
+done.
+
+In addition, the documentation for these two classes is updated.

docs/users-guide/examples/VTKmQuickStart.cxx

@@ -58,8 +58,8 @@ int main(int argc, char* argv[])
   ////
   //// BEGIN-EXAMPLE VTKmQuickStartFilter
   ////
-  vtkm::filter::mesh_info::MeshQuality cellArea(
-    vtkm::filter::mesh_info::CellMetric::Area);
+  vtkm::filter::mesh_info::MeshQuality cellArea;
+  cellArea.SetMetric(vtkm::filter::mesh_info::CellMetric::Area);
   vtkm::cont::DataSet outData = cellArea.Execute(inData);
   ////
   //// END-EXAMPLE VTKmQuickStartFilter

examples/mesh_quality/MeshQuality.cxx

@@ -271,7 +271,8 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  vtkm::filter::mesh_info::MeshQuality filter(shapeMetric);
+  vtkm::filter::mesh_info::MeshQuality filter;
+  filter.SetMetric(shapeMetric);
   TestMetrics(outFileName, input, filter);
   return 0;
 }

vtkm/filter/contour/MIRFilter.cxx

@@ -77,8 +77,7 @@ VTKM_CONT vtkm::cont::DataSet MIRFilter::DoExecute(const vtkm::cont::DataSet& in
   const vtkm::cont::CoordinateSystem inputCoords =
     input.GetCoordinateSystem(this->GetActiveCoordinateSystemIndex());
   vtkm::cont::ArrayHandle<vtkm::FloatDefault> avgSizeTot;
-  vtkm::filter::mesh_info::CellMeasures getSize(
-    vtkm::filter::mesh_info::IntegrationType::AllMeasures);
+  vtkm::filter::mesh_info::CellMeasures getSize;
   getSize.SetCellMeasureName("size");
   vtkm::cont::ArrayCopyShallowIfPossible(getSize.Execute(input).GetCellField("size").GetData(),
                                          avgSizeTot);

vtkm/filter/mesh_info/CellMeasures.cxx

@@ -18,9 +18,17 @@ namespace filter
 {
 namespace mesh_info
 {
+
+//-----------------------------------------------------------------------------
+VTKM_CONT CellMeasures::CellMeasures()
+{
+  this->SetUseCoordinateSystemAsField(true);
+  this->SetCellMeasureName("measure");
+}
+
 //-----------------------------------------------------------------------------
 VTKM_CONT CellMeasures::CellMeasures(IntegrationType m)
-  : measure(m)
+  : Measure(m)
 {
   this->SetUseCoordinateSystemAsField(true);
   this->SetCellMeasureName("measure");
@@ -40,7 +48,7 @@ VTKM_CONT vtkm::cont::DataSet CellMeasures::DoExecute(const vtkm::cont::DataSet&
   vtkm::cont::ArrayHandle<vtkm::FloatDefault> outArray;
 
   auto resolveType = [&](const auto& concrete) {
-    this->Invoke(vtkm::worklet::CellMeasure{ this->measure }, cellset, concrete, outArray);
+    this->Invoke(vtkm::worklet::CellMeasure{ this->Measure }, cellset, concrete, outArray);
   };
   this->CastAndCallVecField<3>(field, resolveType);
 

vtkm/filter/mesh_info/CellMeasures.h

@@ -14,6 +14,8 @@
 #include <vtkm/filter/Filter.h>
 #include <vtkm/filter/mesh_info/vtkm_filter_mesh_info_export.h>
 
+#include <vtkm/Deprecated.h>
+
 namespace vtkm
 {
 namespace filter
@@ -22,12 +24,18 @@ namespace mesh_info
 {
 
 /// \brief Specifies over what types of mesh elements CellMeasures will operate.
+///
+/// The values of `IntegrationType` may be `|`-ed together to select multiple
 enum struct IntegrationType
 {
   None = 0x00,
+  /// @copydoc CellMeasures::SetMeasureToArcLength
   ArcLength = 0x01,
+  /// @copydoc CellMeasures::SetMeasureToArea
   Area = 0x02,
+  /// @copydoc CellMeasures::SetMeasureToVolume
   Volume = 0x04,
+  /// @copydoc CellMeasures::SetMeasureToAll
   AllMeasures = ArcLength | Area | Volume
 };
 
@@ -40,7 +48,7 @@ VTKM_EXEC_CONT inline IntegrationType operator|(IntegrationType left, Integratio
   return static_cast<IntegrationType>(static_cast<int>(left) | static_cast<int>(right));
 }
 
-/// \brief Compute the measure of each (3D) cell in a dataset.
+/// @brief Compute the size measure of each cell in a dataset.
 ///
 /// CellMeasures is a filter that generates a new cell data array (i.e., one value
 /// specified per cell) holding the signed measure of the cell
@@ -50,17 +58,56 @@ VTKM_EXEC_CONT inline IntegrationType operator|(IntegrationType left, Integratio
 class VTKM_FILTER_MESH_INFO_EXPORT CellMeasures : public vtkm::filter::Filter
 {
 public:
-  VTKM_CONT
-  explicit CellMeasures(IntegrationType);
+  VTKM_CONT CellMeasures();
 
-  /// Set/Get the name of the cell measure field. If not set, "measure" is used.
-  void SetCellMeasureName(const std::string& name) { this->SetOutputFieldName(name); }
-  const std::string& GetCellMeasureName() const { return this->GetOutputFieldName(); }
+  VTKM_DEPRECATED(2.2, "Use default constructor and `SetIntegrationType`.")
+  VTKM_CONT explicit CellMeasures(IntegrationType);
+
+  /// @brief Specify the type of integrations to support.
+  ///
+  /// This filter can support integrating the size of 1D elements (arclength measurements),
+  /// 2D elements (area measurements), and 3D elements (volume measurements). The measures to
+  /// perform are specified with a `vtkm::filter::mesh_info::IntegrationType`.
+  ///
+  /// By default, the size measure for all types of elements is performed.
+  VTKM_CONT void SetMeasure(vtkm::filter::mesh_info::IntegrationType measure)
+  {
+    this->Measure = measure;
+  }
+  /// @copydoc SetMeasure
+  VTKM_CONT vtkm::filter::mesh_info::IntegrationType GetMeasure() const { return this->Measure; }
+  /// @brief Compute the length of 1D elements.
+  VTKM_CONT void SetMeasureToArcLength()
+  {
+    this->SetMeasure(vtkm::filter::mesh_info::IntegrationType::ArcLength);
+  }
+  /// @brief Compute the area of 2D elements.
+  VTKM_CONT void SetMeasureToArea()
+  {
+    this->SetMeasure(vtkm::filter::mesh_info::IntegrationType::Area);
+  }
+  /// @brief Compute the volume of 3D elements.
+  VTKM_CONT void SetMeasureToVolume()
+  {
+    this->SetMeasure(vtkm::filter::mesh_info::IntegrationType::Volume);
+  }
+  /// @brief Compute the size of all types of elements.
+  VTKM_CONT void SetMeasureToAll()
+  {
+    this->SetMeasure(vtkm::filter::mesh_info::IntegrationType::AllMeasures);
+  }
+
+  /// @brief Specify the name of the field generated.
+  ///
+  /// If not set, `measure` is used.
+  VTKM_CONT void SetCellMeasureName(const std::string& name) { this->SetOutputFieldName(name); }
+  /// @copydoc SetCellMeasureName
+  VTKM_CONT const std::string& GetCellMeasureName() const { return this->GetOutputFieldName(); }
 
 private:
   VTKM_CONT vtkm::cont::DataSet DoExecute(const vtkm::cont::DataSet& input) override;
 
-  IntegrationType measure;
+  IntegrationType Measure = vtkm::filter::mesh_info::IntegrationType::AllMeasures;
 };
 } // namespace mesh_info
 } // namespace filter

vtkm/filter/mesh_info/MeshQuality.cxx

@@ -55,6 +55,7 @@ namespace
 //Names of the available cell metrics, for use in
 //the output dataset fields
 const std::map<CellMetric, std::string> MetricNames = {
+  { CellMetric::None, "-empty-metric-" },
   { CellMetric::Area, "area" },
   { CellMetric::AspectGamma, "aspectGamma" },
   { CellMetric::AspectRatio, "aspectRatio" },
@@ -80,6 +81,12 @@ const std::map<CellMetric, std::string> MetricNames = {
 };
 } // anonymous namespace
 
+VTKM_CONT MeshQuality::MeshQuality()
+{
+  this->SetUseCoordinateSystemAsField(true);
+  this->SetOutputFieldName(MetricNames.at(this->MyMetric));
+}
+
 VTKM_CONT MeshQuality::MeshQuality(CellMetric metric)
   : MyMetric(metric)
 {
@@ -87,6 +94,17 @@ VTKM_CONT MeshQuality::MeshQuality(CellMetric metric)
   this->SetOutputFieldName(MetricNames.at(this->MyMetric));
 }
 
+VTKM_CONT void MeshQuality::SetMetric(CellMetric metric)
+{
+  this->MyMetric = metric;
+  this->SetOutputFieldName(this->GetMetricName());
+}
+
+VTKM_CONT std::string MeshQuality::GetMetricName() const
+{
+  return MetricNames.at(this->MyMetric);
+}
+
 VTKM_CONT vtkm::cont::DataSet MeshQuality::DoExecute(const vtkm::cont::DataSet& input)
 {
   std::unique_ptr<vtkm::filter::Filter> implementation;

vtkm/filter/mesh_info/MeshQuality.h

@@ -24,6 +24,8 @@
 #include <vtkm/filter/Filter.h>
 #include <vtkm/filter/mesh_info/vtkm_filter_mesh_info_export.h>
 
+#include <vtkm/Deprecated.h>
+
 namespace vtkm
 {
 namespace filter
@@ -33,48 +35,83 @@ namespace mesh_info
 
 enum struct CellMetric
 {
+  /// @copydoc MeshQualityArea
   Area,
+  /// @copydoc MeshQualityAspectGamma
   AspectGamma,
+  /// @copydoc MeshQualityAspectRatio
   AspectRatio,
+  /// @copydoc MeshQualityCondition
   Condition,
+  /// @copydoc MeshQualityDiagonalRatio
   DiagonalRatio,
+  /// @copydoc MeshQualityDimension
   Dimension,
+  /// @copydoc MeshQualityJacobian
   Jacobian,
+  /// @copydoc MeshQualityMaxAngle
   MaxAngle,
+  /// @copydoc MeshQualityMaxDiagonal
   MaxDiagonal,
+  /// @copydoc MeshQualityMinAngle
   MinAngle,
+  /// @copydoc MeshQualityMinDiagonal
   MinDiagonal,
+  /// @copydoc MeshQualityOddy
   Oddy,
+  /// @copydoc MeshQualityRelativeSizeSquared
   RelativeSizeSquared,
+  /// @copydoc MeshQualityScaledJacobian
   ScaledJacobian,
+  /// @copydoc MeshQualityShape
   Shape,
+  /// @copydoc MeshQualityShapeAndSize
   ShapeAndSize,
+  /// @copydoc MeshQualityShear
   Shear,
+  /// @copydoc MeshQualitySkew
   Skew,
+  /// @copydoc MeshQualityStretch
   Stretch,
+  /// @copydoc MeshQualityTaper
   Taper,
+  /// @copydoc MeshQualityVolume
   Volume,
+  /// @copydoc MeshQualityWarpage
   Warpage,
   None
 };
 
-/** \brief Computes the quality of an unstructured cell-based mesh. The quality is defined in terms of the
-  * summary statistics (frequency, mean, variance, min, max) of metrics computed over the mesh
-  * cells. One of several different metrics can be specified for a given cell type, and the mesh
-  * can consist of one or more different cell types. The resulting mesh quality is stored as one
-  * or more new fields in the output dataset of this filter, with a separate field for each cell type.
-  * Each field contains the metric summary statistics for the cell type.
-  * Summary statists with all 0 values imply that the specified metric does not support the cell type.
-  */
+/// @brief Computes the quality of an unstructured cell-based mesh.
+///
+/// The quality is defined in terms of the summary statistics (frequency, mean, variance,
+/// min, max) of metrics computed over the mesh cells. One of several different metrics
+/// can be specified for a given cell type, and the mesh can consist of one or more different
+/// cell types. The resulting mesh quality is stored as one or more new fields in the output
+/// dataset of this filter, with a separate field for each cell type. Each field contains the
+/// metric summary statistics for the cell type. Summary statists with all 0 values imply
+/// that the specified metric does not support the cell type.
+///
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQuality : public vtkm::filter::Filter
 {
 public:
+  MeshQuality();
+
+  VTKM_DEPRECATED(2.2, "use default constructor and SetMetric().")
   VTKM_CONT explicit MeshQuality(CellMetric);
 
+  /// @brief Specify the metric to compute on the mesh.
+  VTKM_CONT void SetMetric(CellMetric metric);
+  /// @copydoc SetMetric
+  VTKM_CONT CellMetric GetMetric() const { return this->MyMetric; }
+
+  /// @brief Return a string describing the metric selected.
+  VTKM_CONT std::string GetMetricName() const;
+
 private:
   VTKM_CONT vtkm::cont::DataSet DoExecute(const vtkm::cont::DataSet& input) override;
 
-  CellMetric MyMetric;
+  CellMetric MyMetric = CellMetric::None;
 };
 } // namespace mesh_info
 } // namespace filter

vtkm/filter/mesh_info/MeshQualityArea.h

@@ -30,15 +30,18 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute the area of each cell.
+///
+/// This only produces values for triangles and quadrilaterals.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityArea : public vtkm::filter::Filter
 {
 public:
   MeshQualityArea();
 
-  /// \brief Computes the area of all polygonal cells and returns the total area.
+  /// @brief Computes the area of all polygonal cells and returns the total area.
   vtkm::Float64 ComputeTotalArea(const vtkm::cont::DataSet& input);
 
-  /// \brief Computes the average area of cells.
+  /// @brief Computes the average area of cells.
   ///
   /// This method first computes the total area of all cells and then divides that by the
   /// number of cells in the dataset.

vtkm/filter/mesh_info/MeshQualityAspectGamma.h

@@ -30,6 +30,13 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief For each cell, compute the normalized root-mean-square of the edge lengths.
+///
+/// This only produces values for tetrahedra.
+///
+/// The root-mean-square edge length is normalized to the volume such that the value is
+/// 1 for an equilateral tetrahedron. The acceptable range for good quality meshes is
+/// considered to be [1, 3]. The normal range of values is [1, FLOAT_MAX].
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityAspectGamma : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityAspectRatio.h

@@ -30,6 +30,13 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute for each cell the ratio of its longest edge to its circumradius.
+///
+/// This only produces values for triangles, quadrilaterals, tetrahedra, and hexahedra.
+///
+/// An acceptable range of this mesh for a good quality polygon is [1, 1.3], and the acceptable
+/// range for a good quality polyhedron is [1, 3]. Normal values for any cell type have
+/// the range [1, FLOAT_MAX].
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityAspectRatio : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityCondition.h

@@ -30,6 +30,12 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute for each cell the condition number of the weighted Jacobian matrix.
+///
+/// This only produces values for triangles, quadrilaterals, and tetrahedra.
+///
+/// The acceptable range of values for a good quality cell is [1, 1.3] for triangles,
+/// [1, 4] for quadrilaterals, and [1, 3] for tetrahedra.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityCondition : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityDiagonalRatio.h

@@ -30,6 +30,12 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute for each cell the ratio of the maximum diagonal to the minimum diagonal.
+///
+/// This only produces values for quadrilaterals and hexahedra.
+///
+/// An acceptable range for a good quality cell is [0.65, 1]. The normal range is [0, 1], but
+/// a degenerate cell with no size will have the value of infinity.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityDiagonalRatio : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityDimension.h

@@ -30,6 +30,9 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute for each cell a metric specifically designed for Sandia's Pronto code.
+///
+/// This only produces values for hexahedra.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityDimension : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityJacobian.h

@@ -30,6 +30,9 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute for each cell the minimum determinant of the Jacobian matrix, over corners and cell center.
+///
+/// This only produces values for quadrilaterals, tetrahedra, and hexahedra.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityJacobian : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityMaxAngle.h

@@ -30,6 +30,14 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Computes the maximum angle within each cell in degrees.
+///
+/// This only produces values for triangles and quadrilaterals.
+///
+/// For a good quality triangle, this value should be in the range [60, 90]. Poorer quality
+/// triangles can have a value as high as 180. For a good quality quadrilateral, this value
+/// should be in the range [90, 135]. Poorer quality quadrilaterals  can have a value as high
+/// as 360.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityMaxAngle : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityMaxDiagonal.h

@@ -30,6 +30,9 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Computes the maximum diagonal length within each cell in degrees.
+///
+/// This only produces values for hexahedra.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityMaxDiagonal : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityMinAngle.h

@@ -30,6 +30,14 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Computes the minimum angle within each cell in degrees.
+///
+/// This only produces values for triangles and quadrilaterals.
+///
+/// For a good quality triangle, this value should be in the range [30, 60]. Poorer quality
+/// triangles can have a value as low as 0. For a good quality quadrilateral, this value
+/// should be in the range [45, 90]. Poorer quality quadrilaterals  can have a value as low
+/// as 0.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityMinAngle : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityMinDiagonal.h

@@ -30,6 +30,9 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Computes the minimal diagonal length within each cell in degrees.
+///
+/// This only produces values for hexahedra.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityMinDiagonal : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityOddy.h

@@ -30,6 +30,12 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute for each cell the maximum deviation of a metric tensor from an identity matrix, over all corners and cell center.
+///
+/// This only produces values for quadrilaterals and hexahedra.
+///
+/// For a good quality quadrilateral or hexahedron, this value should be in the range
+/// [0, 0.5]. Poorer quality cells can have unboundedly larger values.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityOddy : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityRelativeSizeSquared.h

@@ -30,6 +30,19 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute for each cell the ratio of area or volume to the mesh average.
+///
+/// If S is the size of a cell and avgS is the average cell size in the mesh, then
+/// let R = S/avgS. R is "normalized" to be in the range [0, 1] by taking the minimum
+/// of R and 1/R. This value is then squared.
+///
+/// This only produces values for triangles, quadrilaterals, tetrahedra, and hexahedra.
+///
+/// For a good quality triangle, the relative sized squared should be in the range [0.25, 1].
+/// For a good quality quadrilateral, it should be in the range [0.3, 1].
+/// For a good quality tetrahedron, it should be in the range [0.3, 1].
+/// For a good quality hexahedron, it should be in the range [0.5, 1].
+/// Poorer quality cells can have a relative size squared as low as 0.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityRelativeSizeSquared : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityScaledJacobian.h

@@ -30,6 +30,24 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute for each cell a metric derived from the Jacobian matric with normalization involving edge length.
+///
+/// This only produces values for triangles, quadrilaterals, tetrahedra, and hexahedra.
+///
+/// For a triangle, an acceptable range for good quality is [0.5, 2*sqrt(3)/3]. The value for
+/// an equalateral triangle is 1. The normal range is [-2*sqrt(3)/3), 2*sqrt(3)/3], but
+/// malformed cells can have plus or minus the maximum float value.
+///
+/// For a quadrilateral, an acceptable range for good quality is [0.3, 1]. The unit square
+/// has a value of 1. The normal range as well as the full range is [-1, 1].
+///
+/// For a tetrahedron, an acceptable range for good quality is [0.5, sqrt(2)/2]. The value for
+/// a unit equalateral triangle is 1. The normal range of values is [-sqrt(2)/2, sqrt(2)/2], but
+/// malformed cells can have plus or minus the maximum float value.
+///
+/// For a hexahedron, an acceptable range for good quality is [0.5, 1]. The unit cube has
+/// a value of 1. The normal range is [ -1, 1 ], but malformed cells can have a maximum float
+/// value.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityScaledJacobian : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityShape.h

@@ -30,6 +30,17 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute a shape-based metric for each cell.
+///
+/// This metric is based on the condition number of the Jacobian matrix.
+///
+/// This only produces values for triangles, quadrilaterals, tetrahedra, and hexahedra.
+///
+/// For good quality triangles, the acceptable range is [0.25, 1]. Good quality quadrilaterals,
+/// tetrahedra, hexahedra are in the range [0.3, 1].  Poorer quality cells can have values
+/// as low as 0.
+///
+///
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityShape : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityShapeAndSize.h

@@ -30,6 +30,17 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute a metric for each cell based on the shape scaled by the cell size.
+///
+/// This filter multiplies the values of the shape metric by the relative size squared
+/// metric. See `vtkm::filter::mesh_info::MeshQualityShape` and
+/// `vtkm::filter::mesh_info::MeshQualityRelativeSizeSquared` for details on each of
+/// those metrics.
+///
+/// This only produces values for triangles, quadrilaterals, tetrahedra, and hexahedra.
+///
+/// For a good quality cell, this value will be in the range [0.2, 1]. Poorer quality
+/// cells can have values as low as 0.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityShapeAndSize : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityShear.h

@@ -30,6 +30,13 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute the shear of each cell.
+///
+/// The shear of a cell is computed by taking the minimum of the Jacobian at each corner
+/// divided by the length of the corner's adjacent edges.
+///
+/// This only produces values for quadrilaterals and hexahedra. Good quality cells will
+/// have values in the range [0.3, 1]. Poorer quality cells can have values as low as 0.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityShear : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualitySkew.h

@@ -30,6 +30,16 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute the skew of each cell.
+///
+/// The skew is computed as the dot product between unit vectors in the principal directions.
+/// (For 3D objects, the skew is taken as the maximum of all planes.)
+///
+/// This only produces values for quadrilaterals and hexahedra.
+///
+/// Good quality cells will have a skew in the range [0, 0.5]. A unit square or cube will
+/// have a skew of 0. Poor quality cells can have a skew up to 1 although a malformed cell
+/// might have its skew be infinite.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualitySkew : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityStretch.h

@@ -30,6 +30,14 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute the stretch of each cell.
+///
+/// The stretch of a cell is computed as the ratio of the minimum edge length to the maximum
+/// diagonal, normalized for the unit cube. A good quality cell will have a stretch in
+/// the range [0.25, 1]. Poorer quality cells can have a stretch as low as 0 although a malformed
+/// cell might return a strech of infinity.
+///
+/// This only produces values for quadrilaterals and hexahedra.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityStretch : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityTaper.h

@@ -30,6 +30,16 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute the taper of each cell.
+///
+/// The taper of a quadrilateral is computed as the maximum ratio of the cross-derivative
+/// with its shortest associated principal axis.
+///
+/// This only produces values for quadrilaterals and hexahedra.
+///
+/// A good quality quadrilateral will have a taper in the range of [0, 0.7]. A good quality
+/// hexahedron will have a taper in the range of [0, 0.5]. The unit square or cube will
+/// have a taper of 0. Poorer quality cells will have larger values (with no upper limit).
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityTaper : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityVolume.h

@@ -30,6 +30,9 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute the volume each cell.
+///
+/// This only produces values for tetrahedra, pyramids, wedges, and hexahedra.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityVolume : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/MeshQualityWarpage.h

@@ -30,6 +30,19 @@ namespace filter
 namespace mesh_info
 {
 
+/// @brief Compute the flatness of cells.
+///
+/// This only produces values for quadrilaterals. It is defined as the cosine of the minimum
+/// dihedral angle formed by the planes intersecting in diagonals (to the fourth power).
+///
+/// This metric will be 1 for a perfectly flat quadrilateral and be lower as the
+/// quadrilateral deviates from the plane. A good quality quadrilateral will have a
+/// value in the range [0.3, 1]. Poorer quality cells having lower values down to -1,
+/// although malformed cells might have an infinite value.
+///
+/// Note that the value of this filter is consistent with the equivalent metric in VisIt,
+/// and it differs from the implementation in the Verdict library. The Verdict library
+/// returns 1 - value.
 class VTKM_FILTER_MESH_INFO_EXPORT MeshQualityWarpage : public vtkm::filter::Filter
 {
 public:

vtkm/filter/mesh_info/testing/UnitTestCellMeasuresFilter.cxx

@@ -43,7 +43,8 @@ void TestCellMeasuresFilter(vtkm::cont::DataSet& dataset,
 {
   std::cout << "Testing CellMeasures Filter on " << msg << "\n";
 
-  vtkm::filter::mesh_info::CellMeasures vols{ type };
+  vtkm::filter::mesh_info::CellMeasures vols;
+  vols.SetMeasure(type);
   vtkm::cont::DataSet outputData = vols.Execute(dataset);
 
   VTKM_TEST_ASSERT(vols.GetCellMeasureName() == "measure");

vtkm/filter/mesh_info/testing/UnitTestMeshQualityFilter.cxx

@@ -355,7 +355,8 @@ int TestMeshQuality()
   for (size_t i = 0; i < numTests; i++)
   {
     printf("Testing metric %s\n", metricName[i].c_str());
-    vtkm::filter::mesh_info::MeshQuality filter(metrics[i]);
+    vtkm::filter::mesh_info::MeshQuality filter;
+    filter.SetMetric(metrics[i]);
     testFailed = TestMeshQualityFilter(inputs[i], expectedValues[i], metricName[i], filter);
     if (testFailed)
     {

vtkm/filter/mesh_info/worklet/cellmetrics/CellDiagonalRatioMetric.h

@@ -69,7 +69,7 @@ VTKM_EXEC inline OutType ComputeDiagonalRatio(const VecType& diagonals)
       maxLen = currLen;
   }
 
-  if (minLen <= OutType(0.0))
+  if (maxLen <= OutType(0.0))
     return vtkm::Infinity<OutType>();
 
   //Take square root because we only did magnitude squared before