0028508: Make the CellsBuilder algorithm to work with multi-dimensional arguments

1. The CellsBuilder algorithm has been extended to work with multi-dimensional arguments.
It has become possible not only simulate Boolean expressions, but also perform non-supported
Boolean operations, like cutting face from solid, or fusing face with edge.

2. Test cases with multi-dimensional input shapes have been created.

3. Documentation has been updated.

dox/user_guides/boolean_operations/boolean_operations.md

@@ -2099,7 +2099,216 @@ Creating compartments on a ship defined by hull shell and a set of planes. The s
 </tr>
 </table>
 
-@section occt_algorithms_10	Algorithm Limitations 
+@section occt_algorithms_10c_Cells Cells Builder algorithm
+
+The Cells Builder algorithm has been designed as an extension of the General Fuse algorithm. The result of General Fuse algorithm is all split parts of the arguments. The Cells Builder algorithm provides means to specify uniquely any split part of the arguments, which are called Cells, to be taken or avoided in the result.
+The possibility of selecting any Cell allows combining any possible result and gives the Cells Builder algorithm a very wide application - from building the result of any Boolean operation to building the result of any application-specific operation.
+The algorithm builds the Cells only once, and then just reuses these Cells for combining the result. This gives the algorithm the performance advantage over the Booleans which are always rebuilding the splits to obtain the desirable result.
+Thus, the Cells Builder algorithm can be especially useful for simulating Boolean expressions - sequence of Boolean operations on the same arguments. Instead of performing many Boolean operations it allows getting the final result in a single operation.
+Usage of the Cells Builder will also be beneficial if you need to obtain a few results of different Boolean operations on the same arguments - Cut and Common for example.
+
+The Cells Builder algorithm also provides the possibility to remove any internal boundaries between splits of the same type, i.e. fuse any same-dimensional parts added into result and keep any other separate.
+It is implemented through the Cells material approach - to remove boundary between two Cells, both of these Cells should be assigned with the same material ID.
+But, if the same material ID has been assigned to the Cells of different dimension, the removal of the internal boundaries for that material will not be performed. Currently, such case is considered as limitation for the algorithm.
+
+The algorithm can also create containers from the connected Cells added into result - WIRES from Edges, SHELLS from Faces and COMPSOLIDS from Solids.
+
+@subsection occt_algorithms_10c_Cells_1 Usage
+
+The algorithm has been implemented in the *BOPAlgo_CellsBuilder* class.
+
+Cells Builder is a General Fuse based algorithm. Thus all the options of the General Fuse algorithm, such as parallel processing mode, fuzzy mode, safe processing mode, gluing mode and history support are also available in this algorithm.
+
+The requirements for the input shapes are the same as for General Fuse - each argument should be valid in terms of *BRepCheck_Analyzer* and *BOPAlgo_ArgumentAnalyzer*.
+
+The result of the algorithm is compound containing selected parts of the basic type (VERTEX, EDGE, FACE or SOLID). The default result is an empty compound.
+It is possible to add any Cell 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.
+
+Definition of the Cells that should be added/removed to/from the result is performed by the definition of the input shapes from which the parts should be taken (ShapesToTake) and shapes which parts should be avoided (ShapesToAvoid).
+To be taken into result the part must be IN for all shapes from ShapesToTake and must be OUT of all shapes from ShapesToAvoid.
+
+To remove Internal boundaries it is necessary to set the same material to the Cells 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 ID. The boundaries between Cells with this material ID will not be removed. The same Cell 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.
+If the same material ID has been set for the parts of different dimension, the removal of internal boundaries for this material will not be performed.
+
+It is possible to create typed Containers from the parts added into result by using method MakeContainers(). The type of the containers will depend on the type of the input shapes: WIRES for EDGE, SHELLS for FACES and COMPSOLIDS for SOLIDS. The result will be compound containing containers.
+
+#### API usage
+Here is the example of the usage of the algorithm on the API level:
+~~~~
+BOPAlgo_CellsBuilder aCBuilder;
+BOPCol_ListOfShape aLS = …; // arguments
+Standard_Boolean bRunParallel = Standard_False; /* parallel or single mode (the default value is FALSE)*/
+Standard_Real aTol = 0.0; /* fuzzy option (default value is 0)*/
+Standard_Boolean bSafeMode = Standard_False; /* protect or not the arguments from modification*/
+BOPAlgo_Glue aGlue = BOPAlgo_GlueOff; /* Glue option to speed up intersection of the arguments*/
+//
+aCBuilder.SetArguments(aLS);
+aCBuilder.SetRunParallel(bRunParallel);
+aCBuilder.SetFuzzyValue(aTol);
+aCBuilder.SetNonDestructive(bSafeMode);
+aCBuilder.SetGlue(aGlue);
+//
+aCBuilder.Perform(); // build splits of all arguments (GF)
+if (aCBuilder.ErrorStatus()) { // check error status
+  return;
+}
+//
+// collecting of the cells into result
+const TopoDS_Shape& anEmptyRes = aCBuilder.Shape(); // empty result, as nothing has been added yet 
+const TopoDS_Shape& anAllCells = aCBuilder.GetAllParts(); //all split parts 
+//
+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
+//
+Standard_Integer iMaterial = 1; // defines the material for the cells
+Standard_Boolean bUpdate = Standard_False; // defines whether to update the result right now or not
+// adding to result
+aCBuilder.AddToResult(aLSToTake, aLSToAvoid, iMaterial, bUpdate);
+aCBuilder.RemoveInternalBoundaries(); // removing of the boundaries
+TopoDS_Shape aResult = aCBuilder.Shape(); // the result
+// removing from result
+aCBuilder.AddAllToResult();
+aCBuilder.RemoveFromResult(aLSToTake, aLSToAvoid);
+aResult = aCBuilder.Shape(); // the result
+~~~~
+
+#### DRAW usage
+
+The following set of new commands has been implemented to run the algorithm in DRAW Test Harness:
+~~~~
+bcbuild          : Initialization of the Cells Builder. Use: bcbuild r
+bcadd            : Add parts to result. Use: bcadd r s1 (0,1) s2 (0,1) ... [-m material [-u]]
+bcaddall         : Add all parts to result. Use: bcaddall r [-m material [-u]]
+bcremove         : Remove parts from result. Use: bcremove r s1 (0,1) s2 (0,1) ...
+bcremoveall      : Remove all parts from result. Use: bcremoveall
+bcremoveint      : Remove internal boundaries. Use: bcremoveint r
+bcmakecontainers : Make containers from the parts added to result. Use: bcmakecontainers r
+~~~~
+
+Here is the example of the usage of the algorithm on the DRAW level:
+~~~~
+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 spheres
+bcadd res s1 1 s2 0 s3 1 -m 1
+# remove internal boundaries
+bcremoveint res
+~~~~
+
+@subsection occt_algorithms_10c_Cells_2 Examples
+
+The following simple example illustrates the possibilities of the algorithm - cylinder and a sphere intersected by a plane:
+~~~~
+pcylinder c 10 30 
+psphere s 15
+ttranslate s 0 0 30
+plane p 0 0 20 1 0 0
+mkface f p -25 30 -17 17
+~~~~
+
+@figure{/user_guides/boolean_operations/images/cells_algorithm_001.png, "Arguments"} 
+
+~~~~
+bclearobjects
+bcleartools
+baddobjects c s f
+bfillds
+bcbuild r
+~~~~
+
+#### 1. Common for all arguments
+
+~~~~
+bcremoveall
+bcadd res c 1 s 1 f 1
+~~~~
+
+@figure{/user_guides/boolean_operations/images/cells_algorithm_002.png, "The result of COMMON operation"} 
+
+#### 2. Common between cylinder and face
+
+~~~~
+bcremoveall
+bcadd res f 1 c 1
+~~~~
+
+@figure{/user_guides/boolean_operations/images/cells_algorithm_003.png, "The result of COMMON operation between cylinder and face"} 
+
+#### 3. Common between cylinder and sphere
+
+~~~~
+bcremoveall
+bcadd res c 1 s 1
+~~~~
+
+@figure{/user_guides/boolean_operations/images/cells_algorithm_004.png, "The result of COMMON operation between cylinder and sphere"} 
+
+#### 4. Fuse of cylinder and sphere
+
+~~~~
+bcremoveall
+bcadd res c 1 -m 1
+bcadd res s 1 -m 1
+bcremoveint res
+~~~~
+
+@figure{/user_guides/boolean_operations/images/cells_algorithm_005.png, "The result of FUSE operation between cylinder and sphere"} 
+
+#### 5. Parts of the face inside solids - FUSE(COMMON(f, c), COMMON(f, s))
+
+~~~~
+bcremoveall
+bcadd res f 1 s 1 -m 1
+bcadd res f 1 c 1 -m 1
+~~~~
+
+@figure{/user_guides/boolean_operations/images/cells_algorithm_006_1.png, "Parts of the face inside solids"} 
+
+~~~~
+bcremoveint res
+~~~~
+
+@figure{/user_guides/boolean_operations/images/cells_algorithm_006_2.png, "Unified parts of the face inside solids"} 
+
+#### 6. Part of the face outside solids
+
+~~~~
+bcremoveall
+bcadd res f 1 c 0 s 0
+~~~~
+
+@figure{/user_guides/boolean_operations/images/cells_algorithm_007.png, "Part of the face outside solids"} 
+
+#### 7. Fuse operation (impossible using standard Boolean Fuse operation)
+
+~~~~
+bcremoveall
+bcadd res c 1 -m 1
+bcadd res s 1 -m 1
+bcadd res f 1 c 0 s 0
+bcremoveint res
+~~~~
+
+@figure{/user_guides/boolean_operations/images/cells_algorithm_008.png, "Fuse operation"} 
+
+
+These examples may last forever. To define any new operation, it is just necessary to define which Cells should be taken and which should be avoided.
+
+
+@section occt_algorithms_10	Algorithms Limitations 
 
 The chapter describes the problems that are considered as Algorithm limitations. In most cases an Algorithm failure is caused by a combination of various factors, such as self-interfered arguments, inappropriate or ungrounded values of the argument tolerances, adverse mutual position of the arguments, tangency, etc.
 
@@ -2396,7 +2605,7 @@ This example stresses not only the validity, but also the performance issue. The
 
 @subsection occt_algorithms_11a_2 Gluing Operation
 
-The Gluing operation is the option of the Basic Operations, such as General Fuse, Partition, Boolean, Section, Maker Volume operations.
+The Gluing operation is the option of the Basic Operations, such as General Fuse, Partition, Boolean, Section, Maker Volume and Cells building operations.
 It has been designed to speed up the computation of the interferences among arguments of the operations on special cases, in which the arguments may be overlapping but do not have real intersections between their sub-shapes.
 
 This option cannot be used on the shapes having real intersections, like intersection vertex between edges, or intersection vertex between edge and a face or intersection line between faces:
@@ -2460,14 +2669,14 @@ Performance improvement in this case is also about 70 percent.
 
 @subsection occt_algorithms_11a_3 Safe processing mode
 
-The safe processing mode is the advanced option in Boolean Operation component. This mode can be applied to all Basic operations such as General Fuse, Partition, Boolean, Section, Maker Volume.
+The safe processing mode is the advanced option in Boolean Operation component. This mode can be applied to all Basic operations such as General Fuse, Partition, Boolean, Section, Maker Volume, Cells building.
 This option allows keeping the input arguments untouched. In other words, switching this option on prevents the input arguments from any modification such as tolerance increase, addition of the P-Curves on edges etc.
 
 The option might be very useful for implementation of the Undo/Redo mechanism in the applications and allows performing the operation many times without changing the inputs.
 
 By default the safe processing option is switched off for the algorithms. Enabling this option might slightly decrease the performance of the operation, because instead of the modification of some entitiy it will be necessary to create the copy of this entitiy and modify it. But this degradation should be very small because the copying is performed only in case of necessity.
 
-The option is also availible in the Intersection algorithm - *BOPAlgo_PaveFiller*. Thus, if it is necessary to perform several different operations on the same arguemnts, it is possible to enable the safe processing mode in PaveFiller and prepare it only once and then use it in operations. It is enough to set the option to PaveFiller only and all algorithms taking this PaveFiller will also work in safe mode.
+The option is also available in the Intersection algorithm - *BOPAlgo_PaveFiller*. Thus, if it is necessary to perform several different operations on the same arguments, it is possible to enable the safe processing mode in PaveFiller and prepare it only once and then use it in operations. It is enough to set the option to PaveFiller only and all algorithms taking this PaveFiller will also work in safe mode.
 
 @subsubsection occt_algorithms_11a_3_1 Usage
 

src/BOPAlgo/BOPAlgo_CellsBuilder.hxx

@@ -18,6 +18,7 @@
 
 #include <Standard_DefineAlloc.hxx>
 #include <Standard_Handle.hxx>
+#include <Standard_OStream.hxx>
 
 #include <TopoDS_Shape.hxx>
 
@@ -32,128 +33,146 @@
 #include <BOPCol_DataMapOfShapeShape.hxx>
 
 //!
-//! 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.
-//! 
+//! The algorithm is based on the General Fuse algorithm (GFA). The result of
+//! GFA is all split parts of the Arguments.<br>
+//!
+//! The purpose of this algorithm is to provide the result with the content of:<br>
+//! 1. Cells (parts) defined by the user;<br>
+//! 2. Internal boundaries defined by the user.<br>
+//!
 //! 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.
+//! between parts.<br>
 //!
-//! Results:
-//! The result of the algorithm is compound containing selected parts of 
-//! the basic type (VERTEX, EDGE, FACE or SOLID). The default result
+//! Requirements for the Data:<br>
+//! All the requirements of GFA for the DATA are inherited in this algorithm -
+//! The arguments could be of any type (dimension) and should be valid in terms of
+//! BRepCheck_Analyzer and BOPAlgo_ArgumentAnalyzer.<br>
+//!
+//! Results:<br>
+//! The result of the algorithm is compound containing selected parts of
+//! the basic types (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 
+//! 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.
+//! The method RemoveAllFromResult() is also suitable for clearing the result.<br>
 //!
-//! 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 
+//! 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
+//! and set the flag bUpdate to TRUE.
+//! 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 will help to avoid self-intersections in the result.<br>
+//! Note, that if the result contains the parts with same material but of different
+//! dimension the boundaries between such parts will not be removed. Currently,
+//! the removal of the internal boundaries between multi-dimensional shapes is not supported.<br>
 //!
 //! 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 
+//! 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 
+//! 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 
+//! Removing of the parts from such result may affect some containers if
 //! the parts that should be removed is in container. In this case this container
-//! will be rebuilt without that part.
+//! will be rebuilt without that part.<br>
 //!
-//! History:
+//! History:<br>
 //! The algorithm supports history information for basic types of the shapes -
-//! VERTEX, EDGE, FACE. 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, bgenerated and bisdeleted).
+//! VERTEX, EDGE, FACE. This information available through the methods
+//! IsDeleted() and Modified().<br>
+//! In DRAW Test Harness it is available through the same
+//! commands as for Boolean Operations (bmodified, bgenerated and bisdeleted).<br>
 //! There could be Generated shapes only after removing of the internal boundaries
-//! between faces and edges, i.e. after using ShapeUpgrade_UnifySameDomain tool.
-//! 
-//! 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
-//! //
+//! between faces and edges, i.e. after using ShapeUpgrade_UnifySameDomain tool.<br>
+//!
+//! The algorithm can return the following Error Statuses:<br>
+//! - 0 - in case of success;<br>
+//! - Error status acquired in the General Fuse algorithm.<br>
+//! The Error status can be checked with ErrorStatus() method.
+//! If the Error status is not equal to zero, the result cannot be trustworthy.<br>
+//!
+//! The algorithm can return the following Warning Statuses:<br>
+//! - 0 - no warnings occurred;<br>
+//! - Warning status acquired in the General Fuse algorithm;<br>
+//! - One of the warnings from BOPAlgo_CellsBuilder_WarningStatusEnum.<br>
+//! The Warning status can be checked with WarningStatus() method or
+//! printed with the DumpWarnings() method. If the Warning status is not equal
+//! to zero, the result may be not as expected.<br>
+//!
+//! Examples:<br>
+//! 1. API<br>
+//! BOPAlgo_CellsBuilder aCBuilder;<br>
+//! BOPCol_ListOfShape aLS = ...; // arguments<br>
+//! /* parallel or single mode (the default value is FALSE)*/<br>
+//! Standard_Boolean bRunParallel = Standard_False;<br>
+//! /* fuzzy option (default value is 0)*/<br>
+//! Standard_Real aTol = 0.0;<br>
+//! //<br>
+//! aCBuilder.SetArguments(aLS);<br>
+//! aCBuilder.SetRunParallel(bRunParallel);<br>
+//! aCBuilder.SetFuzzyValue(aTol);<br>
+//! //<br>
+//! aCBuilder.Perform();<br>
+//! if (aCBuilder.ErrorStatus()) { // check error status<br>
+//!   return;<br>
+//! }<br>
+//! /* empty compound, as nothing has been added yet */<br>
+//! const TopoDS_Shape& aRes = aCBuilder.Shape();<br>
+//! /* all split parts */<br>
+//! const TopoDS_Shape& aRes = aCBuilder.GetAllParts();<br>
+//! //<br>
+//! BOPCol_ListOfShape aLSToTake = ...; // parts of these arguments will be taken into result<br>
+//! BOPCol_ListOfShape aLSToAvoid = ...; // parts of these arguments will not be taken into result<br>
+//! //<br>
 //! /* 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
+//!    will be removed.<br>
+//!    By default it is set to 0. Thus, to remove some boundary
+//!    the value of this variable should not be equal to 0 */<br>
+//! Standard_Integer iMaterial = ...;<br>
+//! /* defines whether to update the result right now or not */<br>
+//! Standard_Boolean bUpdate = ...;<br>
+//! // adding to result<br>
+//! aCBuilder.AddToResult(aLSToTake, aLSToAvoid, iMaterial, bUpdate);<br>
+//! aR = aCBuilder.Shape(); // the result<br>
+//! // removing of the boundaries (should be called only if bUpdate is false)<br>
+//! aCBuilder.RemoveInternalBoundaries();<br>
+//! //<br>
+//! // removing from result<br>
+//! aCBuilder.AddAllToResult();<br>
+//! aCBuilder.RemoveFromResult(aLSToTake, aLSToAvoid);<br>
+//! aR = aCBuilder.Shape(); // the result<br>
+//! <br>
+//!
+//! 2. DRAW Test Harness<br>
+//! psphere s1 15<br>
+//! psphere s2 15<br>
+//! psphere s3 15<br>
+//! ttranslate s1 0 0 10<br>
+//! ttranslate s2 20 0 10<br>
+//! ttranslate s3 10 0 0<br>
+//! \# adding arguments<br>
+//! bclearobjects; bcleartools<br>
+//! baddobjects s1 s2 s3<br>
+//! \# intersection<br>
+//! bfillds<br>
+//! \# rx will contain all split parts<br>
+//! bcbuild rx<br>
+//! \# add to result the part that is common for all three spheres<br>
+//! bcadd res s1 1 s2 1 s3 1 -m 1<br>
+//! \# add to result the part that is common only for first and third spheres<br>
+//! bcadd res s1 1 s2 0 s3 1 -m 1<br>
+//! \# remove internal boundaries<br>
+//! bcremoveint res<br>
 //!
-
-
 class BOPAlgo_CellsBuilder : public BOPAlgo_Builder
 {
  public:
@@ -169,33 +188,33 @@ class BOPAlgo_CellsBuilder : public BOPAlgo_Builder
   //! Redefined method Clear - clears the contents.
   Standard_EXPORT virtual void Clear() Standard_OVERRIDE;
 
-  //! Adding the parts to result.
-  //! The parts are defined by two lists of shapes.
-  //! <theLSToTake> defines the arguments which parts should be taken into result;
-  //! <theLSToAvoid> defines the arguments which parts should not be taken into result;
+  //! Adding the parts to result.<br>
+  //! The parts are defined by two lists of shapes:<br>
+  //! <theLSToTake> defines the arguments which parts should be taken into result;<br>
+  //! <theLSToAvoid> defines the arguments which parts should not be taken into result;<br>
   //! To be taken into result the part must be IN for all shapes from the list
-  //! <theLSToTake> and must be OUT of all shapes from the list <theLSToAvoid>. 
+  //! <theLSToTake> and must be OUT of all shapes from the list <theLSToAvoid>.<br>
   //! 
-  //! To remove internal boundaries between any cells in the result 
-  //! <theMaterial> variable should be used. The boundaries between 
-  //! cells with the same material will be removed. Default value is 0. 
-  //! Thus, to remove any boundary the value of this variable should not be equal to 0.
-  //! <theUpdate> parameter defines whether to remove boundaries now or not
+  //! To remove internal boundaries between any cells in the result
+  //! <theMaterial> variable should be used. The boundaries between
+  //! cells with the same material will be removed. Default value is 0.<br>
+  //! Thus, to remove any boundary the value of this variable should not be equal to 0.<br>
+  //! <theUpdate> parameter defines whether to remove boundaries now or not.
   Standard_EXPORT void AddToResult(const BOPCol_ListOfShape& theLSToTake,
                                    const BOPCol_ListOfShape& theLSToAvoid,
                                    const Standard_Integer theMaterial = 0,
                                    const Standard_Boolean theUpdate = Standard_False);
 
-  //! Add all split parts to result
-  //! <theMaterial> defines the removal of internal boundaries;
+  //! Add all split parts to result.<br>
+  //! <theMaterial> defines the removal of internal boundaries;<br>
   //! <theUpdate> parameter defines whether to remove boundaries now or not.
   Standard_EXPORT void AddAllToResult(const Standard_Integer theMaterial = 0,
                                       const Standard_Boolean theUpdate = Standard_False);
 
-  //! Removing the parts from result.
-  //! The parts are defined by two lists of shapes.
-  //! <theLSToTake> defines the arguments which parts should be removed from result;
-  //! <theLSToAvoid> defines the arguments which parts should not be removed from result.
+  //! Removing the parts from result.<br>
+  //! The parts are defined by two lists of shapes:<br>
+  //! <theLSToTake> defines the arguments which parts should be removed from result;<br>
+  //! <theLSToAvoid> defines the arguments which parts should not be removed from result.<br>
   //! To be removed from the result the part must be IN for all shapes from the list
   //! <theLSToTake> and must be OUT of all shapes from the list <theLSToAvoid>.
   Standard_EXPORT void RemoveFromResult(const BOPCol_ListOfShape& theLSToTake,
@@ -204,7 +223,11 @@ class BOPAlgo_CellsBuilder : public BOPAlgo_Builder
   //! Remove all parts from result.
   Standard_EXPORT void RemoveAllFromResult();
 
-  //! Removes internal boundaries between cells with the same material.
+  //! Removes internal boundaries between cells with the same material.<br>
+  //! If the result contains the cells with same material but of different dimension
+  //! the removal of internal boundaries between these cells will not be performed.<br>
+  //! In case of some errors during the removal the method will set the appropriate warning status -
+  //! see the WarningStatusEnum enumeration.
   Standard_EXPORT void RemoveInternalBoundaries();
 
   //! Get all split parts.
@@ -218,24 +241,34 @@ class BOPAlgo_CellsBuilder : public BOPAlgo_Builder
   
   //! Returns true if the shape theS has been deleted.
   Standard_EXPORT virtual Standard_Boolean IsDeleted (const TopoDS_Shape& theS) Standard_OVERRIDE;
-  
+
+  //! Define possible warning statuses of the CellsBuilder algorithm:<br>
+  //! - RemovalOfIBForMDimShapes - The result contains multi-dimensional shapes with the same
+  //!                              material. Removal of internal boundaries has not been performed.<br>
+  //! - RemovalOfIBForSolidsFailed - Removal of internal boundaries among Solids has failed.<br>
+  //! - RemovalOfIBForFacesFailed  - Removal of internal boundaries among Faces has failed.<br>
+  //! - RemovalOfIBForEdgesFailed  - Removal of internal boundaries among Edges has failed.<br>
+  enum WarningStatusEnum
+  {
+    RemovalOfIBForMDimShapes = 2,
+    RemovalOfIBForSolidsFailed = 4,
+    RemovalOfIBForFacesFailed = 8,
+    RemovalOfIBForEdgesFailed = 16
+  };
+
+  //! Dumps the warning status
+  Standard_EXPORT virtual void DumpWarnings(Standard_OStream& theOS) const;
+
  protected:
 
-  //! Redefined method Prepare - no need to prepare history 
+   //! Redefined method Prepare - no need to prepare history
   //! information on the default result as it is empty compound.
   Standard_EXPORT virtual void Prepare() Standard_OVERRIDE;
 
-  //! Redefined method CheckData() - additional check for the arguments 
-  //! to be of the same dimension.
-  Standard_EXPORT virtual void CheckData() Standard_OVERRIDE;
-
-  //! Redefined method PerformInternal1 - makes all split parts, 
+  //! Redefined method PerformInternal1 - makes all split parts,
   //! nullifies the result <myShape>, and index all parts.
   Standard_EXPORT virtual void PerformInternal1 (const BOPAlgo_PaveFiller& thePF) Standard_OVERRIDE;
 
-  //! Saves all split parts in myAllParts.
-  Standard_EXPORT void TakeAllParts();
-
   //! Indexes the parts for quick access to the arguments.
   Standard_EXPORT void IndexParts();
 
@@ -244,12 +277,12 @@ class BOPAlgo_CellsBuilder : public BOPAlgo_Builder
                                  const BOPCol_ListOfShape& theLSToAvoid,
                                  BOPCol_ListOfShape& theParts);
 
-  //! Removes internal boundaries between cells with the same material.
-  Standard_EXPORT Standard_Integer RemoveInternals(const BOPCol_ListOfShape& theLS,
+  //! Removes internal boundaries between cells with the same material.<br>
+  //! Returns TRUE if any internal boundaries have been removed.
+  Standard_EXPORT Standard_Boolean RemoveInternals(const BOPCol_ListOfShape& theLS,
                                                    BOPCol_ListOfShape& theLSNew);
 
   // fields
-  TopAbs_ShapeEnum myType;
   TopoDS_Shape myAllParts;
   BOPCol_IndexedDataMapOfShapeListOfShape myIndex;
   BOPCol_DataMapOfIntegerListOfShape myMaterials;

src/BOPTest/BOPTest_CellsCommands.cxx

@@ -137,7 +137,7 @@ Standard_Integer bcbuild(Draw_Interpretor& di,
 //purpose  : 
 //=======================================================================
 Standard_Integer bcaddall(Draw_Interpretor& di,
-                          Standard_Integer n, 
+                          Standard_Integer n,
                           const char** a)
 {
   if (n < 2 || n > 5) {
@@ -162,6 +162,10 @@ Standard_Integer bcaddall(Draw_Interpretor& di,
   //
   aCBuilder.AddAllToResult(iMaterial, bUpdate);
   //
+  Standard_SStream aSStream;
+  aCBuilder.DumpWarnings(aSStream);
+  di << aSStream;
+  //
   const TopoDS_Shape& aR = aCBuilder.Shape();
   //
   DBRep::Set(a[1], aR);
@@ -243,6 +247,10 @@ Standard_Integer bcadd(Draw_Interpretor& di,
   BOPAlgo_CellsBuilder& aCBuilder = BOPTest_Objects::CellsBuilder();
   aCBuilder.AddToResult(aLSToTake, aLSToAvoid, iMaterial, bUpdate);
   //
+  Standard_SStream aSStream;
+  aCBuilder.DumpWarnings(aSStream);
+  di << aSStream;
+  //
   const TopoDS_Shape& aR = aCBuilder.Shape();
   //
   DBRep::Set(a[1], aR);
@@ -311,6 +319,10 @@ Standard_Integer bcremoveint(Draw_Interpretor& di,
   BOPAlgo_CellsBuilder& aCBuilder = BOPTest_Objects::CellsBuilder();
   aCBuilder.RemoveInternalBoundaries();
   //
+  Standard_SStream aSStream;
+  aCBuilder.DumpWarnings(aSStream);
+  di << aSStream;
+  //
   const TopoDS_Shape& aR = aCBuilder.Shape();
   //
   DBRep::Set(a[1], aR);

tests/boolean/cells_test/J1

@@ -0,0 +1,49 @@
+puts "========"
+puts "OCC28528"
+puts "========"
+puts ""
+#######################################################################
+# Make the CellsBuilder algorithm to work with multi-dimensional arguments
+#######################################################################
+
+puts "Arguments: solid and a face"
+
+box b 10 10 10
+plane p 5 5 5 1 0 0
+mkface f p -10 10 -10 10
+
+bclearobjects
+bcleartools
+baddobjects b f
+bfillds
+bcbuild r
+
+puts "Results"
+
+puts "All split shapes"
+bcaddall result
+checknbshapes result -solid 2 -m "Number of SOLIDs in the result containing all splits"
+checknbshapes result -face 12 -m "Number of FACEs in the result containing all splits"
+checkprops result -v 1000 -s 1200
+
+puts "Cut solid from face"
+bcremoveall
+bcadd result f 1 b 0
+checknbshapes result -face 1 -m "Number of FACEs in the result of CUT(f, b) operation"
+
+puts "Cut face from solid"
+bcremoveall
+bcadd result b 1 f 0
+checknbshapes result -solid 2 -m "Number of SOLIDs in the result of CUT(b, f) operation"
+
+puts "Common between face and solid"
+bcremoveall
+bcadd result b 1 f 1
+checknbshapes result -face 1 -m "Number of FACEs in the result of COMMON(b, f) operation"
+
+puts "Fuse operation between face and solid"
+bcremoveall
+bcadd result b 1 -m 1 -u
+bcadd result f 1 b 0
+checknbshapes result -solid 1 -m "Number of SOLIDs in the result of FUSE(b, f) operation"
+checknbshapes result -face 11 -m "Number of FACEs in the result of FUSE(b, f) operation"

tests/boolean/cells_test/J2

@@ -0,0 +1,51 @@
+puts "========"
+puts "OCC28528"
+puts "========"
+puts ""
+#######################################################################
+# Make the CellsBuilder algorithm to work with multi-dimensional arguments
+#######################################################################
+
+puts "Arguments: solid and a face"
+
+box b 10 10 10
+plane p 5 5 5 1 0 0
+mkface f p 0 10 0 10
+
+bclearobjects
+bcleartools
+baddobjects b f
+bfillds
+bcbuild r
+
+puts "Results"
+
+puts "All split shapes"
+bcaddall result
+checknbshapes result -solid 1 -m "Number of SOLIDs in the result containing all splits"
+checknbshapes result -face 8 -m "Number of FACEs in the result containing all splits"
+checkprops result -v 1000 -s 725
+
+puts "Cut solid from face"
+bcremoveall
+bcadd result f 1 b 0
+checknbshapes result -face 1 -m "Number of FACEs in the result of CUT(f, b) operation"
+
+puts "Cut face from solid"
+bcremoveall
+bcadd result b 1 f 0
+checknbshapes result -solid 1 -m "Number of SOLIDs in the result of CUT(b, f) operation"
+checknbshapes result -face 7 -m "Number of FACEs in the result of CUT(b, f) operation"
+
+puts "Common between face and solid"
+bcremoveall
+bcadd result b 1 f 1
+checknbshapes result -face 1 -m "Number of FACEs in the result of COMMON(b, f) operation"
+
+puts "Fuse operation between face and solid"
+bcremoveall
+bcadd result b 1 -m 1 -u
+checknbshapes result -face 7 -m "Number of faces in unified split of solid"
+bcadd result f 1 b 0
+checknbshapes result -solid 1 -m "Number of SOLIDs in the result of FUSE(b, f) operation"
+checknbshapes result -face 8 -m "Number of FACEs in the result of FUSE(b, f) operation"

tests/boolean/cells_test/J3

@@ -0,0 +1,120 @@
+puts "========"
+puts "OCC28528"
+puts "========"
+puts ""
+#######################################################################
+# Make the CellsBuilder algorithm to work with multi-dimensional arguments
+#######################################################################
+
+puts "Arguments: three interfering boxes cut by a plane"
+box b1 10 10 10
+box b2 7 0 0 10 10 10
+box b3 5 0 5 10 10 10
+plane p 5 5 5 0 1 0
+mkface f p -20 20 -20 20
+
+bclearobjects
+bcleartools
+baddobjects b1 b2 b3
+baddtools f
+bfillds
+bcbuild r
+
+puts "Results"
+
+puts "All split shapes"
+bcaddall result
+checknbshapes result -solid 14 -m "Number of SOLIDs in the result containing all splits"
+checknbshapes result -face 66 -m "Number of FACEs in the result containing all splits"
+checkprops result -v 2200 -s 4120
+
+puts "Splits of solids"
+bcremove result f 1
+checknbshapes result -solid 14 -m "Number of SOLIDs in the result containing only splits of solids"
+checknbshapes result -face 65 -m "Number of FACEs in the result containing only splits of solids"
+checkprops result -v 2200 -s 2520
+
+puts "Splits of the face"
+bcremoveall
+bcadd result f 1
+checknbshapes result -face 8 -m "Number of FACEs in the result containing only splits of the face"
+checkprops result -s 1600
+
+puts "Cut solids from face"
+bcremoveall
+bcadd result f 1 b1 0 b2 0 b3 0
+checknbshapes result -face 1 -m "Number of FACEs in the result of CUT(face, solids) operation"
+checkprops result -s 1380
+
+puts "Splits of only one solid"
+bcremoveall
+bcadd result b1 1
+checknbshapes result -solid 8 -m "Number of FACEs in the result containing only the splits of first solid"
+checkprops result -v 1000
+
+
+puts "Making containers"
+
+puts "Make SHELL and COMPSOLID from all splits parts"
+bcremoveall
+bcaddall result
+bcmakecontainers result
+explode result
+if {![regexp "SHELL" [whatis result_1]]} {puts "Error: Shell is not created"}
+checknbshapes result_1 -face 8 -m "Number of FACEs in the SHELL built from all splits of face"
+if {![regexp "COMPSOLID" [whatis result_2]]} {puts "Error: COMPSOLID is not created"}
+checknbshapes result_2 -solid 14 -m "Number of SOLIDs in the COMPSOLID built from splits of all solids"
+
+puts "Remove splits of the first solid from the COMPSOLID"
+bcremove result b1 1
+explode result
+if {![regexp "SHELL" [whatis result_1]]} {puts "Error: Shell has been destroyed"}
+if {![regexp "COMPSOLID" [whatis result_2]]} {puts "Error: COMPSOLID has been destroyed"}
+checknbshapes result_2 -solid 6 -m "Number of SOLIDs in the COMPSOLID built from splits of two solids not included in the first solid"
+
+puts "Remove splits of face included into first solid from the shell"
+bcremove result f 1 b1 1
+explode result 
+if {![regexp "SHELL" [whatis result_1]]} {puts "Error: Shell has been destroyed"}
+checknbshapes result_1 -face 4 -m "Number of FACEs in the SHELL built from splits of face not included into the first solid"
+if {![regexp "COMPSOLID" [whatis result_2]]} {puts "Error: COMPSOLID has been destroyed"}
+
+puts "Destroy the shell completely by removing all splits of the face from the result"
+bcremove result f 1
+if {[regexp "_2" [explode result]]} {puts "Error: Shell has not been destroyed"}
+if {![regexp "COMPSOLID" [whatis result_1]]} {puts "Error: COMPSOLID has been destroyed"}
+
+
+puts "Removing internal boundaries"
+
+puts "Remove internal boundaries in the result of COMMON operation between first two solids"
+bcremoveall
+bcadd result b1 1 b2 1 -m 1 -u
+checknbshapes result -solid 1 -m "Number of SOLIDs in the result of COMMON(b1, b2) operation"
+
+puts "Remove internal boundaries in the result of COMMON operation between first solid and face"
+bcremoveall
+bcadd result b1 1 f 1 -m 1 -u
+checknbshapes result -face 1 -m "Number of FACEs in the result of COMMON(b1, f) operation"
+
+
+puts "Make Fuse operation between two solids and face"
+bcremoveall
+bcadd result b1 1 -m 1
+bcadd result b3 1 -m 1
+bcadd result f 1 b1 0 b3 0 -m 2
+bcmakecontainers result
+bcremoveint result
+set expl [explode result]
+if {![regexp "result_1 result_2" $expl]} {puts "Error: The unification did not work"}
+if {[regexp "result_3" $expl]} {puts "Error: The unification did not work"}
+
+if {![regexp "SOLID" [whatis result_1]]} {puts "Error: The solids have not been fused"}
+if {![regexp "FACE" [whatis result_2]]} {puts "Error: The faces have not been unified"}
+
+puts "Fuse splits of solids with different material for each solid"
+bcremoveall
+bcadd result b1 1 -m 1 -u
+bcadd result b2 1 -m 2 -u
+bcadd result b3 1 -m 3 -u
+checknbshapes result -solid 3 -m "Number of shapes in the result of Unification of splits of each solid"

tests/boolean/cells_test/J4

@@ -0,0 +1,49 @@
+puts "========"
+puts "OCC28528"
+puts "========"
+puts ""
+#######################################################################
+# Make the CellsBuilder algorithm to work with multi-dimensional arguments
+#######################################################################
+
+puts "Arguments: solid and an edge"
+
+psphere s 10
+line l 0 0 0 0 1 0
+mkedge e l -15 15
+
+bclearobjects
+bcleartools
+baddobjects s e
+bfillds
+bcbuild r
+
+puts "Results"
+
+puts "All split shapes"
+bcaddall result
+checknbshapes result -solid 1 -m "Number of SOLIDs in the result containing all splits"
+checknbshapes result -edge 6 -m "Number of EDGEs in the result containing all splits"
+checkprops result -v 4188.79 -l 112.832
+
+puts "Cut solid from edge"
+bcremoveall
+bcadd result e 1 s 0
+checknbshapes result -edge 2 -m "Number of EDGEs in the result of CUT(e, s) operation"
+
+puts "Cut edge from solid"
+bcremoveall
+bcadd result s 1 e 0
+checknbshapes result -solid 1 -m "Number of SOLIDs in the result of CUT(s, e) operation"
+
+puts "Common between edge and solid"
+bcremoveall
+bcadd result s 1 e 1
+checknbshapes result -edge 1 -m "Number of EDGEs in the result of COMMON(s, e) operation"
+
+puts "Fuse operation between edge and solid"
+bcremoveall
+bcadd result s 1 -m 1 -u
+bcadd result e 1 s 0
+checknbshapes result -solid 1 -m "Number of SOLIDs in the result of FUSE(s, e) operation"
+checknbshapes result -edge 6 -m "Number of EDGEs in the result of FUSE(s, e) operation"

tests/boolean/cells_test/J5

@@ -0,0 +1,50 @@
+puts "========"
+puts "OCC28528"
+puts "========"
+puts ""
+#######################################################################
+# Make the CellsBuilder algorithm to work with multi-dimensional arguments
+#######################################################################
+
+puts "Arguments: face and an edge"
+
+cylinder c 0 0 0 0 0 1 10
+mkface f c 0 2*pi -20 20
+viso l c 0
+mkedge e l
+
+bclearobjects
+bcleartools
+baddobjects f e
+bfillds
+bcbuild r
+
+puts "Results"
+
+puts "All split shapes"
+bcaddall result
+checknbshapes result -face 2 -m "Number of FACEs in the result containing all splits"
+checknbshapes result -edge 5 -m "Number of EDGEs in the result containing all splits"
+checkprops result -s 2513.27 -l 394.159
+
+puts "Cut face from edge"
+bcremoveall
+bcadd result e 1 f 0
+checknbshapes result -edge 0 -m "Number of EDGEs in the result of CUT(e, f) operation"
+
+puts "Cut edge from face"
+bcremoveall
+bcadd result f 1 e 0
+checknbshapes result -face 2 -m "Number of FACE in the result of CUT(f, e) operation"
+
+puts "Common between face and edge"
+bcremoveall
+bcadd result f 1 e 1
+checknbshapes result -edge 1 -m "Number of EDGEs in the result of COMMON(f, e) operation"
+
+puts "Fuse operation between face and edge"
+bcremoveall
+bcadd result f 1
+bcadd result e 1 s 0
+checknbshapes result -face 2 -m "Number of FACEs in the result of FUSE(f, e) operation"
+checknbshapes result -edge 5 -m "Number of EDGEs in the result of FUSE(f, e) operation"

tests/boolean/cells_test/J6

@@ -0,0 +1,50 @@
+puts "========"
+puts "OCC28528"
+puts "========"
+puts ""
+#######################################################################
+# Make the CellsBuilder algorithm to work with multi-dimensional arguments
+#######################################################################
+
+puts "Arguments: face and an edge"
+
+cylinder c 0 0 0 0 0 1 10
+mkface f c 0 2*pi -20 20
+uiso l c pi
+mkedge e l -25 25
+
+bclearobjects
+bcleartools
+baddobjects f e
+bfillds
+bcbuild r
+
+puts "Results"
+
+puts "All split shapes"
+bcaddall result
+checknbshapes result -face 2 -m "Number of FACEs in the result containing all splits"
+checknbshapes result -edge 8 -m "Number of EDGEs in the result containing all splits"
+checkprops result -s 2513.27 -l 335.664
+
+puts "Cut face from edge"
+bcremoveall
+bcadd result e 1 f 0
+checknbshapes result -edge 2 -m "Number of EDGEs in the result of CUT(e, f) operation"
+
+puts "Cut edge from face"
+bcremoveall
+bcadd result f 1 e 0
+checknbshapes result -face 2 -m "Number of FACE in the result of CUT(f, e) operation"
+
+puts "Common between face and edge"
+bcremoveall
+bcadd result f 1 e 1
+checknbshapes result -edge 1 -m "Number of EDGEs in the result of COMMON(f, e) operation"
+
+puts "Fuse operation between face and edge"
+bcremoveall
+bcadd result f 1
+bcadd result e 1 s 0
+checknbshapes result -face 2 -m "Number of FACEs in the result of FUSE(f, e) operation"
+checknbshapes result -edge 8 -m "Number of EDGEs in the result of FUSE(f, e) operation"