From 28683930e3d6afd2a70a82e992ddc1db2e655a51 Mon Sep 17 00:00:00 2001 From: Kenneth Moreland Date: Wed, 16 Aug 2023 23:04:22 -0500 Subject: [PATCH] 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 | 10 +++ docs/users-guide/examples/VTKmQuickStart.cxx | 4 +- examples/mesh_quality/MeshQuality.cxx | 3 +- vtkm/filter/contour/MIRFilter.cxx | 3 +- vtkm/filter/mesh_info/CellMeasures.cxx | 12 +++- vtkm/filter/mesh_info/CellMeasures.h | 61 ++++++++++++++++--- vtkm/filter/mesh_info/MeshQuality.cxx | 18 ++++++ vtkm/filter/mesh_info/MeshQuality.h | 55 ++++++++++++++--- vtkm/filter/mesh_info/MeshQualityArea.h | 7 ++- .../filter/mesh_info/MeshQualityAspectGamma.h | 7 +++ .../filter/mesh_info/MeshQualityAspectRatio.h | 7 +++ vtkm/filter/mesh_info/MeshQualityCondition.h | 6 ++ .../mesh_info/MeshQualityDiagonalRatio.h | 6 ++ vtkm/filter/mesh_info/MeshQualityDimension.h | 3 + vtkm/filter/mesh_info/MeshQualityJacobian.h | 3 + vtkm/filter/mesh_info/MeshQualityMaxAngle.h | 8 +++ .../filter/mesh_info/MeshQualityMaxDiagonal.h | 3 + vtkm/filter/mesh_info/MeshQualityMinAngle.h | 8 +++ .../filter/mesh_info/MeshQualityMinDiagonal.h | 3 + vtkm/filter/mesh_info/MeshQualityOddy.h | 6 ++ .../MeshQualityRelativeSizeSquared.h | 13 ++++ .../mesh_info/MeshQualityScaledJacobian.h | 18 ++++++ vtkm/filter/mesh_info/MeshQualityShape.h | 11 ++++ .../mesh_info/MeshQualityShapeAndSize.h | 11 ++++ vtkm/filter/mesh_info/MeshQualityShear.h | 7 +++ vtkm/filter/mesh_info/MeshQualitySkew.h | 10 +++ vtkm/filter/mesh_info/MeshQualityStretch.h | 8 +++ vtkm/filter/mesh_info/MeshQualityTaper.h | 10 +++ vtkm/filter/mesh_info/MeshQualityVolume.h | 3 + vtkm/filter/mesh_info/MeshQualityWarpage.h | 13 ++++ .../testing/UnitTestCellMeasuresFilter.cxx | 3 +- .../testing/UnitTestMeshQualityFilter.cxx | 3 +- .../cellmetrics/CellDiagonalRatioMetric.h | 2 +- 33 files changed, 317 insertions(+), 28 deletions(-) create mode 100644 docs/changelog/mesh-info-constructors.md diff --git a/docs/changelog/mesh-info-constructors.md b/docs/changelog/mesh-info-constructors.md new file mode 100644 index 000000000..0859bf3ed --- /dev/null +++ b/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. diff --git a/docs/users-guide/examples/VTKmQuickStart.cxx b/docs/users-guide/examples/VTKmQuickStart.cxx index 78d7d168c..b775ae78f 100644 --- a/docs/users-guide/examples/VTKmQuickStart.cxx +++ b/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 diff --git a/examples/mesh_quality/MeshQuality.cxx b/examples/mesh_quality/MeshQuality.cxx index b58a78bc1..4dcec688f 100644 --- a/examples/mesh_quality/MeshQuality.cxx +++ b/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; } diff --git a/vtkm/filter/contour/MIRFilter.cxx b/vtkm/filter/contour/MIRFilter.cxx index 5817f8827..bc069ebbf 100644 --- a/vtkm/filter/contour/MIRFilter.cxx +++ b/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 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); diff --git a/vtkm/filter/mesh_info/CellMeasures.cxx b/vtkm/filter/mesh_info/CellMeasures.cxx index c16bd10f0..0cc36d478 100644 --- a/vtkm/filter/mesh_info/CellMeasures.cxx +++ b/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 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); diff --git a/vtkm/filter/mesh_info/CellMeasures.h b/vtkm/filter/mesh_info/CellMeasures.h index e2ae01ee1..3d75044e6 100644 --- a/vtkm/filter/mesh_info/CellMeasures.h +++ b/vtkm/filter/mesh_info/CellMeasures.h @@ -14,6 +14,8 @@ #include #include +#include + 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(static_cast(left) | static_cast(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 diff --git a/vtkm/filter/mesh_info/MeshQuality.cxx b/vtkm/filter/mesh_info/MeshQuality.cxx index 1c95760e8..6b10a1ca2 100644 --- a/vtkm/filter/mesh_info/MeshQuality.cxx +++ b/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 MetricNames = { + { CellMetric::None, "-empty-metric-" }, { CellMetric::Area, "area" }, { CellMetric::AspectGamma, "aspectGamma" }, { CellMetric::AspectRatio, "aspectRatio" }, @@ -80,6 +81,12 @@ const std::map 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 implementation; diff --git a/vtkm/filter/mesh_info/MeshQuality.h b/vtkm/filter/mesh_info/MeshQuality.h index cddb98b22..3faeb767f 100644 --- a/vtkm/filter/mesh_info/MeshQuality.h +++ b/vtkm/filter/mesh_info/MeshQuality.h @@ -24,6 +24,8 @@ #include #include +#include + 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 diff --git a/vtkm/filter/mesh_info/MeshQualityArea.h b/vtkm/filter/mesh_info/MeshQualityArea.h index 79799a714..fef980a50 100644 --- a/vtkm/filter/mesh_info/MeshQualityArea.h +++ b/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. diff --git a/vtkm/filter/mesh_info/MeshQualityAspectGamma.h b/vtkm/filter/mesh_info/MeshQualityAspectGamma.h index 672ef3c3c..5caf62d05 100644 --- a/vtkm/filter/mesh_info/MeshQualityAspectGamma.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityAspectRatio.h b/vtkm/filter/mesh_info/MeshQualityAspectRatio.h index 4645b5f6a..63856a8df 100644 --- a/vtkm/filter/mesh_info/MeshQualityAspectRatio.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityCondition.h b/vtkm/filter/mesh_info/MeshQualityCondition.h index 0d3f63e8f..477027c97 100644 --- a/vtkm/filter/mesh_info/MeshQualityCondition.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityDiagonalRatio.h b/vtkm/filter/mesh_info/MeshQualityDiagonalRatio.h index 052939e14..44fbd29e6 100644 --- a/vtkm/filter/mesh_info/MeshQualityDiagonalRatio.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityDimension.h b/vtkm/filter/mesh_info/MeshQualityDimension.h index c81cc3f83..274dd6edc 100644 --- a/vtkm/filter/mesh_info/MeshQualityDimension.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityJacobian.h b/vtkm/filter/mesh_info/MeshQualityJacobian.h index df27f4f31..5e06ad681 100644 --- a/vtkm/filter/mesh_info/MeshQualityJacobian.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityMaxAngle.h b/vtkm/filter/mesh_info/MeshQualityMaxAngle.h index ce2d80b27..50716abc7 100644 --- a/vtkm/filter/mesh_info/MeshQualityMaxAngle.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityMaxDiagonal.h b/vtkm/filter/mesh_info/MeshQualityMaxDiagonal.h index 695a7fac8..71ad746f5 100644 --- a/vtkm/filter/mesh_info/MeshQualityMaxDiagonal.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityMinAngle.h b/vtkm/filter/mesh_info/MeshQualityMinAngle.h index d0c1af6f5..c7e88d8ed 100644 --- a/vtkm/filter/mesh_info/MeshQualityMinAngle.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityMinDiagonal.h b/vtkm/filter/mesh_info/MeshQualityMinDiagonal.h index 08c05547f..f750729cb 100644 --- a/vtkm/filter/mesh_info/MeshQualityMinDiagonal.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityOddy.h b/vtkm/filter/mesh_info/MeshQualityOddy.h index 4794b9f4b..aad46e6db 100644 --- a/vtkm/filter/mesh_info/MeshQualityOddy.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityRelativeSizeSquared.h b/vtkm/filter/mesh_info/MeshQualityRelativeSizeSquared.h index c8dc53e36..6e8478bbe 100644 --- a/vtkm/filter/mesh_info/MeshQualityRelativeSizeSquared.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityScaledJacobian.h b/vtkm/filter/mesh_info/MeshQualityScaledJacobian.h index ab35ff208..15fccc251 100644 --- a/vtkm/filter/mesh_info/MeshQualityScaledJacobian.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityShape.h b/vtkm/filter/mesh_info/MeshQualityShape.h index 59da2f15f..34e3540f0 100644 --- a/vtkm/filter/mesh_info/MeshQualityShape.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityShapeAndSize.h b/vtkm/filter/mesh_info/MeshQualityShapeAndSize.h index f8cab7f23..b76baba4f 100644 --- a/vtkm/filter/mesh_info/MeshQualityShapeAndSize.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityShear.h b/vtkm/filter/mesh_info/MeshQualityShear.h index 4664d3fed..a276d64ec 100644 --- a/vtkm/filter/mesh_info/MeshQualityShear.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualitySkew.h b/vtkm/filter/mesh_info/MeshQualitySkew.h index beb3172f6..080d5b8e3 100644 --- a/vtkm/filter/mesh_info/MeshQualitySkew.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityStretch.h b/vtkm/filter/mesh_info/MeshQualityStretch.h index 7866dd453..74e8b5f1b 100644 --- a/vtkm/filter/mesh_info/MeshQualityStretch.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityTaper.h b/vtkm/filter/mesh_info/MeshQualityTaper.h index cfeece1c4..f273b7aec 100644 --- a/vtkm/filter/mesh_info/MeshQualityTaper.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityVolume.h b/vtkm/filter/mesh_info/MeshQualityVolume.h index 1b1d66aef..d0757f8ff 100644 --- a/vtkm/filter/mesh_info/MeshQualityVolume.h +++ b/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: diff --git a/vtkm/filter/mesh_info/MeshQualityWarpage.h b/vtkm/filter/mesh_info/MeshQualityWarpage.h index 7a6a5f198..58623b423 100644 --- a/vtkm/filter/mesh_info/MeshQualityWarpage.h +++ b/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: diff --git a/vtkm/filter/mesh_info/testing/UnitTestCellMeasuresFilter.cxx b/vtkm/filter/mesh_info/testing/UnitTestCellMeasuresFilter.cxx index 72dc22090..4eeb0950b 100644 --- a/vtkm/filter/mesh_info/testing/UnitTestCellMeasuresFilter.cxx +++ b/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"); diff --git a/vtkm/filter/mesh_info/testing/UnitTestMeshQualityFilter.cxx b/vtkm/filter/mesh_info/testing/UnitTestMeshQualityFilter.cxx index 89bb917ae..9570026ee 100644 --- a/vtkm/filter/mesh_info/testing/UnitTestMeshQualityFilter.cxx +++ b/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) { diff --git a/vtkm/filter/mesh_info/worklet/cellmetrics/CellDiagonalRatioMetric.h b/vtkm/filter/mesh_info/worklet/cellmetrics/CellDiagonalRatioMetric.h index 16ce305fe..9ce67b026 100644 --- a/vtkm/filter/mesh_info/worklet/cellmetrics/CellDiagonalRatioMetric.h +++ b/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(); //Take square root because we only did magnitude squared before