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