0026798: Boolean operations: keep desired cells and boundaries in the result

The algorithm is based on the General Fuse algorithm (GFA). The result of
GFA is all split parts of the Arguments.

The purpose of this algorithm is to provide the result with the content of:
1. Cells (parts) defined by the user;
2. Internal boundaries defined by the user.

In other words the algorithm should provide the possibility for the user
to add or remove any part to (from) result and remove any internal boundaries
between parts.

Requirements for the Data:
All the requirements of GFA for the DATA are inherited in this algorithm.
Plus all the arguments should have the same dimension.

Results:
The result of the algorithm is compound containing selected parts of
the basic type (VERTEX, EDGE, FACE or SOLID). The default result
is empty compound. It is possible to add any split part to the result
by using the methods AddToRessult() and AddAllToResult().
It is also possible to remove any part from the result by using methods
RemoveFromResult() and RemoveAllFromResult().
The method RemoveAllFromResult() is also suitable for clearing the result.

To remove Internal boundaries it is necessary to set the same material to the
parts between which the boundaries should be removed and call the method
RemoveInternalBoundaries(). The material should not be equal to 0, as this is
default material value. The boundaries between parts with this value
will not be removed.
One part cannot be added with the different materials.
It is also possible to remove the boundaries during combining the result.
To do this it is necessary to set the material for parts (not equal to 0)
and set the flag bUpdate to TRUE.
BUT for the arguments of the types FACE or EDGE it is recommended
to remove the boundaries in the end when the result is completely built.
It will help to avoid self-intersections in the result.

It is possible to create typed Containers from the parts added to result by using
method MakeContainers(). The type of the containers will depend on the type of
the arguments: WIRES for EEDGE, SHELLS for FACES and COMPSOLIDS for SOLIDS.
The result will be compound containing containers.
Adding of the parts to such result will not update containers. The result
compound will contain the containers and new added parts (of basic type).
Removing of the parts from such result may affect some containers if the
the parts that should be removed is in container. In this case this container
will be rebuilt without that part.

History:
The algorithm supports history information. This information available through
the methods IsDeleted() and Modified(). In DRAW Test Harness it is available
through the same commands as for Boolean Operations (bmodified and bisdeleted).

Examples:
1. API
BOPAlgo_CellsBuilder aCBuilder;
BOPCol_ListOfShape aLS = ...; // arguments
/* parallel or single mode (the default value is FALSE)*/
Standard_Boolean bRunParallel = Standard_False;
/* fuzzy option (default value is 0)*/
Standard_Real aTol = 0.0;
//
aCBuilder.SetArguments(aLS);
aCBuilder.SetRunParallel(bRunParallel);
aCBuilder.SetFuzzyValue(aTol);
//
aCBuilder.Perform();
if (aCBuilder.ErrorStatus()) { // check error status
  return;
}
/* empty compound, as nothing has been added yet */
const TopoDS_Shape& aRes = aCBuilder.Shape();
/* all split parts */
const TopoDS_Shape& aRes = aCBuilder.GetAllParts();
//
BOPCol_ListOfShape aLSToTake = ...; // parts of these arguments will be taken into result
BOPCol_ListOfShape aLSToAvoid = ...; // parts of these arguments will not be taken into result
//
/* defines the material common for the cells, i.e.
   the boundaries between cells with the same material
   will be removed.
   By default it is set to 0. Thus, to remove some boundary
   the value of this variable should not be equal to 0 */
Standard_Integer iMaterial = ...;
/* defines whether to update the result right now or not */
Standard_Boolean bUpdate = ...;
// adding to result
aCBuilder.AddToResult(aLSToTake, aLSToAvoid, iMaterial, bUpdate);
aR = aCBuilder.Shape(); // the result
// removing of the boundaries
aCBuilder.RemoveInternalBoundaries();

// removing from result
aCBuilder.AddAllToResult();
aCBuilder.RemoveFromResult(aLSToTake, aLSToAvoid);
aR = aCBuilder.Shape(); // the result

2. DRAW Test Harness
psphere s1 15
psphere s2 15
psphere s3 15
ttranslate s1 0 0 10
ttranslate s2 20 0 10
ttranslate s3 10 0 0

bclearobjects; bcleartools
baddobjects s1 s2 s3
bfillds
# rx will contain all split parts
bcbuild rx
# add to result the part that is common for all three spheres
bcadd res s1 1 s2 1 s3 1 -m 1
# add to result the part that is common only for first and third shperes
bcadd res s1 1 s2 0 s3 1 -m 1
# remove internal boundaries
bcremoveint res

Added history support for Generated shapes (created in ShapeUpgrade_UnifySameDomain).

Methods AddToResult and RemoveFromResult have been documented in more details to clarify the procedure of adding and removing parts.

Adding external library to use ShapeUpgrade_UnifySameDomain.

Test-cases for issue #26798

src/BOPTest/BOPTest.cxx

@@ -42,6 +42,7 @@ void  BOPTest::AllCommands(Draw_Interpretor& theCommands)
   BOPTest::APICommands       (theCommands);
   BOPTest::OptionCommands    (theCommands);
   BOPTest::HistoryCommands   (theCommands);
+  BOPTest::CellsCommands     (theCommands);
 }
 //=======================================================================
 //function : Factory

src/BOPTest/BOPTest.hxx

@@ -55,6 +55,7 @@ public:
 
   Standard_EXPORT static void HistoryCommands  (Draw_Interpretor& aDI);
 
+  Standard_EXPORT static void CellsCommands  (Draw_Interpretor& aDI);
 
 
 protected:

src/BOPTest/BOPTest_CellsCommands.cxx

@@ -0,0 +1,333 @@
+// Created by: Eugeny MALTCHIKOV
+// Copyright (c) 2015 OPEN CASCADE SAS
+//
+// This file is part of Open CASCADE Technology software library.
+//
+// This library is free software; you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License version 2.1 as published
+// by the Free Software Foundation, with special exception defined in the file
+// OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
+// distribution for complete text of the license and disclaimer of any warranty.
+//
+// Alternatively, this file may be used under the terms of Open CASCADE
+// commercial license or contractual agreement.
+
+#include <BOPTest.hxx>
+#include <BOPTest_Objects.hxx>
+
+#include <Draw.hxx>
+#include <TopoDS_Shape.hxx>
+#include <DBRep.hxx>
+
+#include <BOPDS_DS.hxx>
+#include <BOPAlgo_PaveFiller.hxx>
+#include <BOPAlgo_CellsBuilder.hxx>
+
+
+static Standard_Integer bcbuild (Draw_Interpretor&, Standard_Integer, const char**);
+static Standard_Integer bcaddall (Draw_Interpretor&, Standard_Integer, const char**);
+static Standard_Integer bcremoveall (Draw_Interpretor&, Standard_Integer, const char**);
+static Standard_Integer bcadd (Draw_Interpretor&, Standard_Integer, const char**);
+static Standard_Integer bcremove (Draw_Interpretor&, Standard_Integer, const char**);
+static Standard_Integer bcremoveint (Draw_Interpretor&, Standard_Integer, const char**);
+static Standard_Integer bcmakecontainers (Draw_Interpretor&, Standard_Integer, const char**);
+
+//=======================================================================
+//function : CellsCommands
+//purpose  : 
+//=======================================================================
+void BOPTest::CellsCommands(Draw_Interpretor& theCommands)
+{
+  static Standard_Boolean done = Standard_False;
+  if (done) return;
+  done = Standard_True;
+  // Chapter's name
+  const char* g = "BOPTest commands";
+  // Commands
+  
+  theCommands.Add("bcbuild", "Cells builder. Use: bcbuild r",
+                  __FILE__, bcbuild, g);
+  theCommands.Add("bcaddall", "Add all parts to result. Use: bcaddall r [-m material [-u]]",
+                  __FILE__, bcaddall, g);
+  theCommands.Add("bcremoveall", "Remove all parts from result. Use: bcremoveall",
+                  __FILE__, bcremoveall, g);
+  theCommands.Add("bcadd", "Add parts to result. Use: bcadd r s1 (0,1) s2 (0,1) ... [-m material [-u]]",
+                  __FILE__, bcadd, g);
+  theCommands.Add("bcremove", "Remove parts from result. Use: bcremove r s1 (0,1) s2 (0,1) ...", 
+                  __FILE__, bcremove, g);
+  theCommands.Add("bcremoveint", "Remove internal boundaries. Use: bcremoveint r",
+                  __FILE__, bcremoveint, g);
+  theCommands.Add("bcmakecontainers", "Make containers from the parts added to result. Use: bcmakecontainers r",
+                  __FILE__, bcmakecontainers, g);
+}
+
+//=======================================================================
+//function : bcbuild
+//purpose  : 
+//=======================================================================
+Standard_Integer bcbuild(Draw_Interpretor& di,
+                         Standard_Integer n, 
+                         const char** a)
+{
+  if (n != 2) {
+    di << "Cells builder. Use: bcbuild r\n";
+    return 1;
+  }
+  //
+  BOPDS_PDS pDS = BOPTest_Objects::PDS();
+  if (!pDS) {
+    di << " prepare PaveFiller first\n";
+    return 1;
+  }
+  //
+  Standard_Boolean bRunParallel;
+  Standard_Integer iErr;
+  BOPCol_ListIteratorOfListOfShape aIt;
+  //
+  BOPAlgo_PaveFiller& aPF = BOPTest_Objects::PaveFiller();
+  //
+  BOPAlgo_CellsBuilder& aCBuilder = BOPTest_Objects::CellsBuilder();
+  aCBuilder.Clear();
+  //
+  BOPCol_ListOfShape& aLSObj = BOPTest_Objects::Shapes();
+  aIt.Initialize(aLSObj);
+  for (; aIt.More(); aIt.Next()) {
+    const TopoDS_Shape& aS = aIt.Value();
+    aCBuilder.AddArgument(aS);
+  }
+  //
+  BOPCol_ListOfShape& aLSTool = BOPTest_Objects::Tools();
+  aIt.Initialize(aLSTool);
+  for (; aIt.More(); aIt.Next()) {
+    const TopoDS_Shape& aS = aIt.Value();
+    aCBuilder.AddArgument(aS);
+  }
+  //
+  bRunParallel = BOPTest_Objects::RunParallel();
+  aCBuilder.SetRunParallel(bRunParallel);
+  //
+  aCBuilder.PerformWithFiller(aPF); 
+  iErr = aCBuilder.ErrorStatus();
+  if (iErr) {
+    di << "error: " << iErr << "\n";
+    return 1;
+  }
+  //
+  BOPTest_Objects::SetBuilder(&aCBuilder);
+  //
+  const TopoDS_Shape& aR = aCBuilder.GetAllParts();
+  if (aR.IsNull()) {
+    di << "no parts were built\n";
+    return 0;
+  }
+  //
+  DBRep::Set(a[1], aR);
+  return 0;
+}
+
+//=======================================================================
+//function : bcaddall
+//purpose  : 
+//=======================================================================
+Standard_Integer bcaddall(Draw_Interpretor& di,
+                          Standard_Integer n, 
+                          const char** a)
+{
+  if (n < 2 || n > 5) {
+    di << "Add all parts to result. Use: bcaddall r [-m material [-u]]\n";
+    return 1;
+  }
+  //
+  Standard_Integer iMaterial = 0;
+  Standard_Boolean bUpdate = Standard_False;
+  //
+  if (n > 3) {
+    if (!strcmp(a[2], "-m")) {
+      iMaterial = Draw::Atoi(a[3]);
+    }
+    //
+    if (n == 5) {
+      bUpdate = !strcmp(a[4], "-u");
+    }
+  }
+  //
+  BOPAlgo_CellsBuilder& aCBuilder = BOPTest_Objects::CellsBuilder();
+  //
+  aCBuilder.AddAllToResult(iMaterial, bUpdate);
+  //
+  const TopoDS_Shape& aR = aCBuilder.Shape();
+  //
+  DBRep::Set(a[1], aR);
+  return 0;
+}
+
+//=======================================================================
+//function : bcremoveall
+//purpose  : 
+//=======================================================================
+Standard_Integer bcremoveall(Draw_Interpretor& di,
+                             Standard_Integer n, 
+                             const char**)
+{
+  if (n != 1) {
+    di << "Remove all parts from result. Use: bcremoveall\n";
+    return 1;
+  }
+  //
+  BOPAlgo_CellsBuilder& aCBuilder = BOPTest_Objects::CellsBuilder();
+  //
+  aCBuilder.RemoveAllFromResult();
+  //
+  return 0;
+}
+
+//=======================================================================
+//function : bcadd
+//purpose  : 
+//=======================================================================
+Standard_Integer bcadd(Draw_Interpretor& di,
+                       Standard_Integer n, 
+                       const char** a)
+{
+  if (n < 4) {
+    di << "Add parts to result. Use: bcadd r s1 (0,1) s2 (0,1) ... [-m material [-u]]\n";
+    return 1;
+  }
+  //
+  BOPCol_ListOfShape aLSToTake, aLSToAvoid;
+  Standard_Integer i, iMaterial, iTake, n1;
+  Standard_Boolean bUpdate;
+  //
+  iMaterial = 0;
+  bUpdate = Standard_False;
+  n1 = n;
+  //
+  if (!strcmp(a[n-3], "-m")) {
+    iMaterial = Draw::Atoi(a[n-2]);
+    bUpdate = !strcmp(a[n-1], "-u");
+    n1 = n - 3;
+  }
+  else if (!strcmp(a[n-2], "-m")) {
+    iMaterial = Draw::Atoi(a[n-1]);
+    n1 = n - 2;
+  }
+  //
+  for (i = 2; i < n1; i += 2) {
+    const TopoDS_Shape& aS = DBRep::Get(a[i]);
+    if (aS.IsNull()) {
+      di << a[i] << " is a null shape\n";
+      continue;
+    }
+    iTake = Draw::Atoi(a[i+1]);
+    //
+    if (iTake) {
+      aLSToTake.Append(aS);
+    }
+    else {
+      aLSToAvoid.Append(aS);
+    }
+  }
+  //
+  if (aLSToTake.IsEmpty()) {
+    di << "No shapes from which to add the parts\n";
+    return 1;
+  }
+  //
+  BOPAlgo_CellsBuilder& aCBuilder = BOPTest_Objects::CellsBuilder();
+  aCBuilder.AddToResult(aLSToTake, aLSToAvoid, iMaterial, bUpdate);
+  //
+  const TopoDS_Shape& aR = aCBuilder.Shape();
+  //
+  DBRep::Set(a[1], aR);
+  return 0;
+}
+
+//=======================================================================
+//function : bcremove
+//purpose  : 
+//=======================================================================
+Standard_Integer bcremove(Draw_Interpretor& di,
+                          Standard_Integer n, 
+                          const char** a)
+{
+  if (n < 4 || ((n % 2) != 0)) {
+    di << "Remove parts from result. Use: bcremove r s1 (0,1) s2 (0,1) ...\n";
+    return 1;
+  }
+  //
+  BOPCol_ListOfShape aLSToTake, aLSToAvoid;
+  Standard_Integer i, iTake;
+  //
+  for (i = 2; i < n; i += 2) {
+    const TopoDS_Shape& aS = DBRep::Get(a[i]);
+    if (aS.IsNull()) {
+      di << a[i] << " is a null shape\n";
+      return 1;
+    }
+    iTake = Draw::Atoi(a[i+1]);
+    //
+    if (iTake) {
+      aLSToTake.Append(aS);
+    }
+    else {
+      aLSToAvoid.Append(aS);
+    }
+  }
+  //
+  if (aLSToTake.IsEmpty()) {
+    di << "No shapes from which to remove the parts\n";
+    return 1;
+  }
+  //
+  BOPAlgo_CellsBuilder& aCBuilder = BOPTest_Objects::CellsBuilder();
+  aCBuilder.RemoveFromResult(aLSToTake, aLSToAvoid);
+  //
+  const TopoDS_Shape& aR = aCBuilder.Shape();
+  //
+  DBRep::Set(a[1], aR);
+  return 0;
+}
+
+//=======================================================================
+//function : bcremoveint
+//purpose  : 
+//=======================================================================
+Standard_Integer bcremoveint(Draw_Interpretor& di,
+                             Standard_Integer n, 
+                             const char** a)
+{
+  if (n != 2) {
+    di << "Remove internal boundaries. Use: bcremoveint r\n";
+    return 1;
+  }
+  //
+  BOPAlgo_CellsBuilder& aCBuilder = BOPTest_Objects::CellsBuilder();
+  aCBuilder.RemoveInternalBoundaries();
+  //
+  const TopoDS_Shape& aR = aCBuilder.Shape();
+  //
+  DBRep::Set(a[1], aR);
+  return 0;
+}
+
+//=======================================================================
+//function : bcmakecontainers
+//purpose  : 
+//=======================================================================
+Standard_Integer bcmakecontainers(Draw_Interpretor& di,
+                                  Standard_Integer n, 
+                                  const char** a)
+{
+  if (n != 2) {
+    di << "Make containers from the parts added to result. Use: bcmakecontainers r\n";
+    return 1;
+  }
+  //
+  BOPAlgo_CellsBuilder& aCBuilder = BOPTest_Objects::CellsBuilder();
+  aCBuilder.MakeContainers();
+  //
+  const TopoDS_Shape& aR = aCBuilder.Shape();
+  //
+  DBRep::Set(a[1], aR);
+  return 0;
+}

src/BOPTest/BOPTest_Objects.cxx

@@ -18,6 +18,7 @@
 #include <BOPAlgo_PaveFiller.hxx>
 #include <BOPAlgo_Section.hxx>
 #include <BOPTest_Objects.hxx>
+#include <BOPAlgo_CellsBuilder.hxx>
 #include <NCollection_BaseAllocator.hxx>
 
 static Handle(NCollection_BaseAllocator)& Allocator1();
@@ -224,6 +225,15 @@ BOPAlgo_Section& BOPTest_Objects::Section()
   return sSection;
 }
 //=======================================================================
+//function : CellsBuilder
+//purpose  : 
+//=======================================================================
+BOPAlgo_CellsBuilder& BOPTest_Objects::CellsBuilder()
+{
+  static BOPAlgo_CellsBuilder sCBuilder(Allocator1());
+  return sCBuilder;
+}
+//=======================================================================
 //function : Shapes
 //purpose  : 
 //=======================================================================

src/BOPTest/BOPTest_Objects.hxx

@@ -24,6 +24,7 @@
 #include <BOPAlgo_PBuilder.hxx>
 #include <Standard_Boolean.hxx>
 #include <Standard_Real.hxx>
+#include <BOPAlgo_CellsBuilder.hxx>
 class BOPAlgo_PaveFiller;
 class BOPAlgo_Builder;
 class BOPAlgo_BOP;
@@ -52,6 +53,8 @@ public:
   
   Standard_EXPORT static BOPAlgo_Section& Section();
   
+  Standard_EXPORT static BOPAlgo_CellsBuilder& CellsBuilder();
+  
   Standard_EXPORT static BOPCol_ListOfShape& Shapes();
   
   Standard_EXPORT static BOPCol_ListOfShape& Tools();

src/BOPTest/FILES

@@ -12,4 +12,5 @@ BOPTest_Objects.hxx
 BOPTest_OptionCommands.cxx
 BOPTest_PartitionCommands.cxx
 BOPTest_TolerCommands.cxx
-BOPTest_HistoryCommands.cxx
+BOPTest_HistoryCommands.cxx
+BOPTest_CellsCommands.cxx