Cleanup options for equivalence testing (#2115)

User facing naming changes for the functional equivalence API.
There are no logic changes.

Author: kwokcb

source/MaterialXCore/Element.cpp

@@ -396,14 +396,14 @@ bool Element::isEquivalent(ConstElementPtr rhs, const ElementEquivalenceOptions&
     StringVec rhsAttributeNames = rhs->getAttributeNames();
 
     // Filter out any attributes specified in the options.
-    const StringSet& skipAttributes = options.skipAttributes;
-    if (!skipAttributes.empty())
+    const StringSet& attributeExclusionList = options.attributeExclusionList;
+    if (!attributeExclusionList.empty())
     {
         attributeNames.erase(std::remove_if(attributeNames.begin(), attributeNames.end(),
-            [&skipAttributes](const string& attr) { return skipAttributes.find(attr) != skipAttributes.end(); }),
+            [&attributeExclusionList](const string& attr) { return attributeExclusionList.find(attr) != attributeExclusionList.end(); }),
             attributeNames.end());
         rhsAttributeNames.erase(std::remove_if(rhsAttributeNames.begin(), rhsAttributeNames.end(),
-            [&skipAttributes](const string& attr) { return skipAttributes.find(attr) != skipAttributes.end(); }),
+            [&attributeExclusionList](const string& attr) { return attributeExclusionList.find(attr) != attributeExclusionList.end(); }),
             rhsAttributeNames.end());
     }    
 
@@ -714,7 +714,7 @@ bool ValueElement::isAttributeEquivalent(ConstElementPtr rhs, const string& attr
 {    
     // Perform value comparisons
     bool performedValueComparison = false;
-    if (!options.skipValueComparisons)
+    if (options.performValueComparisons)
     {
         const StringSet uiAttributes = 
         {
@@ -724,7 +724,7 @@ bool ValueElement::isAttributeEquivalent(ConstElementPtr rhs, const string& attr
         };
 
         // Get precision and format options
-        ScopedFloatFormatting fmt(options.format, options.precision);
+        ScopedFloatFormatting fmt(options.floatFormat, options.floatPrecision);
 
         ConstValueElementPtr rhsValueElement = rhs->asA<ValueElement>();
 

source/MaterialXCore/Element.h

@@ -1389,34 +1389,33 @@ class MX_CORE_API ElementEquivalenceOptions
   public:
     ElementEquivalenceOptions()
     {
-        format = Value::getFloatFormat();
-        precision = Value::getFloatPrecision();
-        skipAttributes = {};
-        skipValueComparisons = false;
+        performValueComparisons = true;
+        floatFormat = Value::getFloatFormat();
+        floatPrecision = Value::getFloatPrecision();
+        attributeExclusionList = {};
     };
     ~ElementEquivalenceOptions() { }
 
-    /// Floating point format option for floating point value comparisons
-    Value::FloatFormat format;
+    /// Perform value comparisons as opposed to literal string comparisons.
+    /// Default is true.
+    bool performValueComparisons;
 
-    /// Floating point precision option for floating point value comparisons
-    int precision;
+    /// Floating point format to use for floating point value comparisons
+    Value::FloatFormat floatFormat;
 
-    /// Attribute filtering options. By default all attributes are considered.
-    /// Name, category attributes cannot be skipped.
+    /// Floating point precision to use for floating point value comparisons
+    int floatPrecision;
+
+    /// Specifies the set of attributes that should be excluded when performing a comparison. 
+    /// By default all attributes are considered. Name and category attributes cannot be excluded.
     /// 
-    /// For example UI attribute comparision be skipped by setting:
-    /// skipAttributes = { 
+    /// For example, to exclude UI and documentation attributes from consideration the follow may be set:
+    /// attributeExclusionList = {
     ///     ValueElement::UI_MIN_ATTRIBUTE, ValueElement::UI_MAX_ATTRIBUTE,
     ///     ValueElement::UI_SOFT_MIN_ATTRIBUTE, ValueElement::UI_SOFT_MAX_ATTRIBUTE,
     ///     ValueElement::UI_STEP_ATTRIBUTE, Element::XPOS_ATTRIBUTE, 
-    ///     Element::YPOS_ATTRIBUTE };
-    StringSet skipAttributes;
-
-    /// Do not perform any value comparisions. Instead perform exact string comparisons for attributes
-    /// Default is false. The operator==() method can be used instead as it always performs
-    /// a strict comparison. Default is false.
-    bool skipValueComparisons;
+    ///     Element::YPOS_ATTRIBUTE, Element::DOC_ATTRIBUTE };
+    StringSet attributeExclusionList;
 };
 
 /// @class ExceptionOrphanedElement

source/MaterialXTest/MaterialXCore/Document.cpp

@@ -217,27 +217,27 @@ TEST_CASE("Document equivalence", "[document]")
     mx::ElementEquivalenceOptions options;
     mx::ElementEquivalenceResultVec results;
 
-    // Check skipping all value compares
-    options.skipValueComparisons = true;
+    // Check that this fails when not performing value comparisons
+    options.performValueComparisons = false;
     bool equivalent = doc->isEquivalent(doc2, options, &results);
     REQUIRE(!equivalent);
 
     // Check attibute values 
-    options.skipValueComparisons = false;
+    options.performValueComparisons = true;
     results.clear();
     equivalent = doc->isEquivalent(doc2, options, &results);
     REQUIRE(equivalent);
 
     unsigned int currentPrecision = mx::Value::getFloatPrecision();
     // This will compare 0.012345608 versus: 1, 0.012345611 for input10
-    options.precision = 8;
+    options.floatPrecision = 8;
     equivalent = doc->isEquivalent(doc2, options);
     REQUIRE(!equivalent);
-    options.precision = currentPrecision;
+    options.floatPrecision = currentPrecision;
 
     // Check attribute filtering of inputs
     results.clear();
-    options.skipAttributes = { mx::ValueElement::UI_MIN_ATTRIBUTE, mx::ValueElement::UI_MAX_ATTRIBUTE };
+    options.attributeExclusionList = { mx::ValueElement::UI_MIN_ATTRIBUTE, mx::ValueElement::UI_MAX_ATTRIBUTE };
     for (mx::InputPtr floatInput : floatInputs)
     {
         floatInput->setAttribute(mx::ValueElement::UI_MIN_ATTRIBUTE, "0.9");

source/PyMaterialX/PyMaterialXCore/PyElement.cpp

@@ -224,10 +224,10 @@ void bindPyElement(py::module& mod)
         .def_readwrite("attributeName", &mx::ElementEquivalenceResult::attributeName);
 
     py::class_<mx::ElementEquivalenceOptions>(mod, "ElementEquivalenceOptions")
-        .def_readwrite("format", &mx::ElementEquivalenceOptions::format)
-        .def_readwrite("precision", &mx::ElementEquivalenceOptions::precision)
-        .def_readwrite("skipAttributes", &mx::ElementEquivalenceOptions::skipAttributes)
-        .def_readwrite("skipValueComparisons", &mx::ElementEquivalenceOptions::skipValueComparisons)
+        .def_readwrite("performValueComparisons", &mx::ElementEquivalenceOptions::performValueComparisons)
+        .def_readwrite("floatFormat", &mx::ElementEquivalenceOptions::floatFormat)
+        .def_readwrite("floatPrecision", &mx::ElementEquivalenceOptions::floatPrecision)
+        .def_readwrite("attributeExclusionList", &mx::ElementEquivalenceOptions::attributeExclusionList)
         .def(py::init<>());
 
     py::class_<mx::StringResolver, mx::StringResolverPtr>(mod, "StringResolver")