ENH: support 'use' action for selections in vtkWrite, ensightWrite (#926)

- have 'use' as the action appears more intuitive as the first entry
  instead of 'add'. Was previously also added to vtkCloud.

src/functionObjects/utilities/ensightWrite/ensightWrite.H

@@ -49,7 +49,7 @@ Description
         {
             box
             {
-                action  add;
+                action  use;
                 source  box;
                 box     (-0.1 -0.01 -0.1) (0.1 0.30 0.1);
             }
@@ -110,7 +110,7 @@ Description
 
 Note
     The region of interest is defined by the selection dictionary
-    as a set of actions (add,subtract,subset,invert).
+    as a set of actions (use,add,subtract,subset,invert).
     Omitting the selection dictionary is the same as specifying the
     conversion of all cells (in the selected regions).
     Omitting the patches entry is the same as specifying the conversion of all

src/functionObjects/utilities/ensightWrite/ensightWriteUpdate.C

@@ -35,6 +35,7 @@ namespace Foam
     // A limited selection of actions
     const Enum<topoSetSource::setAction> actionNames
     ({
+        { topoSetSource::NEW, "use" },
         { topoSetSource::ADD, "add" },
         { topoSetSource::SUBTRACT, "subtract" },
         { topoSetSource::SUBSET, "subset" },
@@ -73,7 +74,7 @@ bool Foam::functionObjects::ensightWrite::updateSubset
 
         const dictionary& dict = dEntry.dict();
 
-        const auto action = actionNames.get("action", dict);
+        auto action = actionNames.get("action", dict);
 
         // Handle manually
         if (action == topoSetSource::INVERT)
@@ -92,7 +93,17 @@ bool Foam::functionObjects::ensightWrite::updateSubset
 
         switch (action)
         {
+            case topoSetSource::NEW:  // "use"
             case topoSetSource::ADD:
+                if (topoSetSource::NEW == action)
+                {
+                    // NEW (use) = CLEAR + ADD  (ie, only use this selection)
+                    cellsToSelect.reset();
+                    action = topoSetSource::ADD;
+                }
+                source->applyToSet(action, cellsToSelect);
+                break;
+
             case topoSetSource::SUBTRACT:
                 source->applyToSet(action, cellsToSelect);
                 break;

src/functionObjects/utilities/vtkWrite/vtkWrite.H

@@ -49,7 +49,7 @@ Description
         {
             box
             {
-                action  add;
+                action  use;
                 source  box;
                 box     (-0.1 -0.01 -0.1) (0.1 0.30 0.1);
             }
@@ -112,7 +112,7 @@ Description
 
 Note
     The region of interest is defined by the selection dictionary
-    as a set of actions (add,subtract,subset,invert).
+    as a set of actions (use,add,subtract,subset,invert).
     Omitting the selection dictionary is the same as specifying the
     conversion of all cells (in the selected regions).
     Omitting the patches entry is the same as specifying the conversion of all

src/functionObjects/utilities/vtkWrite/vtkWriteUpdate.C

@@ -34,6 +34,7 @@ namespace Foam
     // A limited selection of actions
     const Enum<topoSetSource::setAction> actionNames
     ({
+        { topoSetSource::NEW, "use" },
         { topoSetSource::ADD, "add" },
         { topoSetSource::SUBTRACT, "subtract" },
         { topoSetSource::SUBSET, "subset" },
@@ -71,7 +72,7 @@ bool Foam::functionObjects::vtkWrite::updateSubset
 
         const dictionary& dict = dEntry.dict();
 
-        const auto action = actionNames.get("action", dict);
+        auto action = actionNames.get("action", dict);
 
         // Handle manually
         if (action == topoSetSource::INVERT)
@@ -90,7 +91,17 @@ bool Foam::functionObjects::vtkWrite::updateSubset
 
         switch (action)
         {
+            case topoSetSource::NEW:  // "use"
             case topoSetSource::ADD:
+                if (topoSetSource::NEW == action)
+                {
+                    // NEW (use) = CLEAR + ADD  (ie, only use this selection)
+                    cellsToSelect.reset();
+                    action = topoSetSource::ADD;
+                }
+                source->applyToSet(action, cellsToSelect);
+                break;
+
             case topoSetSource::SUBTRACT:
                 source->applyToSet(action, cellsToSelect);
                 break;

src/meshTools/sets/topoSetSource/topoSetSource.H

@@ -82,7 +82,7 @@ public:
         enum setAction
         {
             ADD,                //!< Add elements to the set
-            SUBTRACT,           //!< Remove elements from the set
+            SUBTRACT,           //!< Subtract elements from the set
             SUBSET,             //!< Subset with elements in the set
             INVERT,             //!< Invert the elements in the set
             CLEAR,              //!< Clear the set, possibly creating it

tutorials/incompressible/simpleFoam/windAroundBuildings/system/vtkWrite

@@ -51,7 +51,7 @@ subset
     {
         dome
         {
-            action  add;
+            action  use;
             source  sphere;
             origin  (125 100 0);
             radius  100;

tutorials/lagrangian/reactingParcelFoam/filter/system/vtkWrite

@@ -22,7 +22,7 @@ vtkWrite
     {
         inletRegion
         {
-            action  add;
+            action  use;
             source  zone;
             zones   (leftFluid);
         }