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

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