0030145: Modeling Algorithms - Boolean Operations on open solids
[occt.git] / src / BOPAlgo / BOPAlgo_Builder.hxx
1 // Created by: Peter KURNEV
2 // Copyright (c) 2010-2014 OPEN CASCADE SAS
3 // Copyright (c) 2007-2010 CEA/DEN, EDF R&D, OPEN CASCADE
4 // Copyright (c) 2003-2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN, CEDRAT,
5 //                         EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
6 //
7 // This file is part of Open CASCADE Technology software library.
8 //
9 // This library is free software; you can redistribute it and/or modify it under
10 // the terms of the GNU Lesser General Public License version 2.1 as published
11 // by the Free Software Foundation, with special exception defined in the file
12 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
13 // distribution for complete text of the license and disclaimer of any warranty.
14 //
15 // Alternatively, this file may be used under the terms of Open CASCADE
16 // commercial license or contractual agreement.
17
18 #ifndef _BOPAlgo_Builder_HeaderFile
19 #define _BOPAlgo_Builder_HeaderFile
20
21 #include <Standard.hxx>
22 #include <Standard_DefineAlloc.hxx>
23 #include <Standard_Handle.hxx>
24
25 #include <BOPAlgo_PPaveFiller.hxx>
26 #include <BOPAlgo_BuilderShape.hxx>
27 #include <BOPAlgo_GlueEnum.hxx>
28 #include <BOPAlgo_Operation.hxx>
29 #include <BOPDS_PDS.hxx>
30 #include <NCollection_BaseAllocator.hxx>
31 #include <Standard_Integer.hxx>
32 #include <Standard_Real.hxx>
33 #include <TopTools_DataMapOfShapeListOfShape.hxx>
34 #include <TopTools_DataMapOfShapeShape.hxx>
35 #include <TopTools_ListOfShape.hxx>
36 #include <TopTools_MapOfShape.hxx>
37 #include <Standard_Boolean.hxx>
38 #include <TopAbs_ShapeEnum.hxx>
39 class IntTools_Context;
40 class TopoDS_Shape;
41 class BOPAlgo_PaveFiller;
42 class TopoDS_Solid;
43
44 //!
45 //! The class is a General Fuse algorithm - base algorithm for the
46 //! algorithms in the Boolean Component. Its main purpose is to build
47 //! the split parts of the argument shapes from which the result of
48 //! the operations is combined.<br>
49 //! The result of the General Fuse algorithm itself is a compound
50 //! containing all split parts of the arguments. <br>
51 //!
52 //! Additionally to the options of the base classes, the algorithm has
53 //! the following options:<br>
54 //! - *Safe processing mode* - allows to avoid modification of the input
55 //!                            shapes during the operation (by default it is off);<br>
56 //! - *Gluing options* - allows to speed up the calculation of the intersections
57 //!                      on the special cases, in which some sub-shapes are coinciding.<br>
58 //! - *Disabling the check for inverted solids* - Disables/Enables the check of the input solids
59 //!                          for inverted status (holes in the space). The default value is TRUE,
60 //!                          i.e. the check is performed. Setting this flag to FALSE for inverted solids,
61 //!                          most likely will lead to incorrect results.
62 //!
63 //! The algorithm returns the following warnings:
64 //! - *BOPAlgo_AlertUnableToOrientTheShape* - in case the check on the orientation of the split shape
65 //!                                           to match the orientation of the original shape has failed.
66 //!
67 //! The algorithm returns the following Error statuses:
68 //! - *BOPAlgo_AlertTooFewArguments* - in case there are no enough arguments to perform the operation;
69 //! - *BOPAlgo_AlertNoFiller* - in case the intersection tool has not been created;
70 //! - *BOPAlgo_AlertIntersectionFailed* - in case the intersection of the arguments has failed;
71 //! - *BOPAlgo_AlertBuilderFailed* - in case building splits of arguments has failed with some unexpected error.
72 //!
73 class BOPAlgo_Builder  : public BOPAlgo_BuilderShape
74 {
75 public:
76
77   DEFINE_STANDARD_ALLOC
78
79   //! Empty constructor.
80   Standard_EXPORT BOPAlgo_Builder();
81   Standard_EXPORT virtual ~BOPAlgo_Builder();
82
83   Standard_EXPORT BOPAlgo_Builder(const Handle(NCollection_BaseAllocator)& theAllocator);
84
85   //! Clears the content of the algorithm.
86   Standard_EXPORT virtual void Clear() Standard_OVERRIDE;
87
88   //! Returns the PaveFiller, algorithm for sub-shapes intersection.
89   BOPAlgo_PPaveFiller PPaveFiller()
90   {
91     return myPaveFiller;
92   }
93
94   //! Returns the Data Structure, holder of intersection information.
95   BOPDS_PDS PDS()
96   {
97     return myDS;
98   }
99
100   //! Returns the Context, tool for cashing heavy algorithms.
101   Handle(IntTools_Context) Context() const
102   {
103     return myContext;
104   }
105
106
107 public: //! @name Arguments
108
109   //! Adds the argument to the operation.
110   Standard_EXPORT virtual void AddArgument (const TopoDS_Shape& theShape);
111
112   //! Sets the list of arguments for the operation.
113   Standard_EXPORT virtual void SetArguments (const TopTools_ListOfShape& theLS);
114
115   //! Returns the list of arguments.
116   const TopTools_ListOfShape& Arguments() const
117   {
118     return myArguments;
119   }
120
121 public: //! @name Options
122
123   //! Sets the flag that defines the mode of treatment.
124   //! In non-destructive mode the argument shapes are not modified. Instead
125   //! a copy of a sub-shape is created in the result if it is needed to be updated.
126   //! This flag is taken into account if internal PaveFiller is used only.
127   //! In the case of calling PerformWithFiller the corresponding flag of that PaveFiller
128   //! is in force.
129   void SetNonDestructive(const Standard_Boolean theFlag)
130   {
131     myNonDestructive = theFlag;
132   }
133
134   //! Returns the flag that defines the mode of treatment.
135   //! In non-destructive mode the argument shapes are not modified. Instead
136   //! a copy of a sub-shape is created in the result if it is needed to be updated.
137   Standard_Boolean NonDestructive() const
138   {
139     return myNonDestructive;
140   }
141
142   //! Sets the glue option for the algorithm
143   void SetGlue(const BOPAlgo_GlueEnum theGlue)
144   {
145     myGlue = theGlue;
146   }
147
148   //! Returns the glue option of the algorithm
149   BOPAlgo_GlueEnum Glue() const
150   {
151     return myGlue;
152   }
153
154   //! Enables/Disables the check of the input solids for inverted status
155   void SetCheckInverted(const Standard_Boolean theCheck)
156   {
157     myCheckInverted = theCheck;
158   }
159
160   //! Returns the flag defining whether the check for input solids on inverted status
161   //! should be performed or not.
162   Standard_Boolean CheckInverted() const
163   {
164     return myCheckInverted;
165   }
166
167
168 public: //! @name Performing the operation
169
170   //! Performs the operation.
171   //! The intersection will be performed also.
172   Standard_EXPORT virtual void Perform() Standard_OVERRIDE;
173
174   //! Performs the operation with the prepared filler.
175   //! The intersection will not be performed in this case.
176   Standard_EXPORT virtual void PerformWithFiller (const BOPAlgo_PaveFiller& theFiller);
177
178
179 public: //! @name BOPs on open solids
180
181   //! Builds the result shape according to the given states for the objects
182   //! and tools. These states can be unambiguously converted into the Boolean operation type.
183   //! Thus, it performs the Boolean operation on the given groups of shapes.
184   //!
185   //! The result is built basing on the result of Builder operation (GF or any other).
186   //! The only condition for the Builder is that the splits of faces should be created
187   //! and classified relatively solids.
188   //!
189   //! The method uses classification approach for choosing the faces which will
190   //! participate in building the result shape:
191   //! - All faces from each group having the given state for the opposite group
192   //!   will be taken into result.
193   //!
194   //! Such approach shows better results (in comparison with BOPAlgo_BuilderSolid approach)
195   //! when working with open solids. However, the result may not be always
196   //! correct on such data (at least, not as expected) as the correct classification
197   //! of the faces relatively open solids is not always possible and may vary
198   //! depending on the chosen classification point on the face.
199   //!
200   //! History is not created for the solids in this method.
201   //!
202   //! To avoid pollution of the report of Builder algorithm, there is a possibility to pass
203   //! the different report to collect the alerts of the method only. But, if the new report
204   //! is not given, the Builder report will be used.
205   //! So, even if Builder passed without any errors, but some error has been stored into its report
206   //! in this method, for the following calls the Builder report must be cleared.
207   //!
208   //! The method may set the following errors:
209   //! - BOPAlgo_AlertBuilderFailed - Building operation has not been performed yet or failed;
210   //! - BOPAlgo_AlertBOPNotSet - invalid BOP type is given (COMMON/FUSE/CUT/CUT21 are supported);
211   //! - BOPAlgo_AlertTooFewArguments - arguments are not given;
212   //! - BOPAlgo_AlertUnknownShape - the shape is unknown for the operation.
213   //!
214   //! Parameters:
215   //! @param theObjects   - The group of Objects for BOP;
216   //! @param theObjState  - State for objects faces to pass into result;
217   //! @param theTools     - The group of Tools for BOP;
218   //! @param theObjState  - State for tools faces to pass into result;
219   //! @param theReport    - The alternative report to avoid pollution of the main one.
220   Standard_EXPORT virtual void BuildBOP(const TopTools_ListOfShape& theObjects,
221                                         const TopAbs_State          theObjState,
222                                         const TopTools_ListOfShape& theTools,
223                                         const TopAbs_State          theToolsState,
224                                         Handle(Message_Report)      theReport = NULL);
225
226   //! Builds the result of Boolean operation of given type
227   //! basing on the result of Builder operation (GF or any other).
228   //!
229   //! The method converts the given type of operation into the states
230   //! for the objects and tools required for their face to pass into result
231   //! and performs the call to the same method, but with states instead
232   //! of operation type.
233   //!
234   //! The conversion looks as follows:
235   //! - COMMON is built from the faces of objects located IN any of the tools
236   //!          and vice versa.
237   //! - FUSE   is built from the faces OUT of all given shapes;
238   //! - CUT    is built from the faces of the objects OUT of the tools and
239   //!          faces of the tools located IN solids of the objects.
240   //!
241   //! @param theObjects   - The group of Objects for BOP;
242   //! @param theTools     - The group of Tools for BOP;
243   //! @param theOperation - The BOP type;
244   //! @param theReport    - The alternative report to avoid pollution of the global one.
245   void BuildBOP(const TopTools_ListOfShape& theObjects,
246                 const TopTools_ListOfShape& theTools,
247                 const BOPAlgo_Operation     theOperation,
248                 Handle(Message_Report)      theReport = NULL)
249   {
250     TopAbs_State anObjState, aToolsState;
251     switch (theOperation)
252     {
253       case BOPAlgo_COMMON:
254       {
255         anObjState  = TopAbs_IN;
256         aToolsState = TopAbs_IN;
257         break;
258       }
259       case BOPAlgo_FUSE:
260       {
261         anObjState  = TopAbs_OUT;
262         aToolsState = TopAbs_OUT;
263         break;
264       }
265       case BOPAlgo_CUT:
266       {
267         anObjState  = TopAbs_OUT;
268         aToolsState = TopAbs_IN;
269         break;
270       }
271       case BOPAlgo_CUT21:
272       {
273         anObjState  = TopAbs_IN;
274         aToolsState = TopAbs_OUT;
275         break;
276       }
277       default:
278       {
279         anObjState  = TopAbs_UNKNOWN;
280         aToolsState = TopAbs_UNKNOWN;
281         break;
282       }
283     }
284     BuildBOP(theObjects, anObjState, theTools, aToolsState, theReport);
285   }
286
287 protected: //! @name History methods
288
289   //! Prepare information for history support.
290   Standard_EXPORT void PrepareHistory();
291
292   //! Prepare history information for the input shapes taking into account possible
293   //! operation-specific modifications.
294   //! For instance, in the CellsBuilder operation, additionally to splitting input shapes
295   //! the splits of the shapes (or the shapes themselves) may be unified during removal of internal
296   //! boundaries. In this case each split should be linked to the unified shape.
297   //!
298   //! To have correct history information, the method should be redefined in each operation
299   //! where such additional modification is possible. The input shape <theS> should be the one from arguments,
300   //! and the returning list should contain all final elements to which the input shape has evolved,
301   //! including those not contained in the result shape.
302   //!
303   //! The method returns pointer to the list of modified elements.
304   //! NULL pointer means that the shape has not been modified at all.
305   //!
306   //! The General Fuse operation does not perform any other modification than splitting the input
307   //! shapes basing on their intersection information. This information is contained in myImages map.
308   //! Thus, here the method returns only splits (if any) contained in this map.
309   Standard_EXPORT virtual const TopTools_ListOfShape* LocModified(const TopoDS_Shape& theS);
310
311   //! Returns the list of shapes generated from the shape theS.
312   //! Similarly to *LocModified* must be redefined for specific operations,
313   //! obtaining Generated elements differently.
314   Standard_EXPORT virtual const TopTools_ListOfShape& LocGenerated(const TopoDS_Shape& theS);
315
316 public: //! @name Images/Origins
317
318   //! Returns the map of images.
319   const TopTools_DataMapOfShapeListOfShape& Images() const
320   {
321     return myImages;
322   }
323
324   //! Returns the map of origins.
325   const TopTools_DataMapOfShapeListOfShape& Origins() const
326   {
327     return myOrigins;
328   }
329
330   //! Returns the map of Same Domain (SD) shapes - coinciding shapes
331   //! from different arguments.
332   const TopTools_DataMapOfShapeShape& ShapesSD() const
333   {
334     return myShapesSD;
335   }
336
337
338 protected: //! @name Methods for building the result
339
340   //! Performs the building of the result.
341   //! The method calls the PerfromInternal1() method surrounded by a try-catch block.
342   Standard_EXPORT virtual void PerformInternal (const BOPAlgo_PaveFiller& thePF);
343
344   //! Performs the building of the result.
345   //! To build the result of any other operation
346   //! it will be necessary to override this method.
347   Standard_EXPORT virtual void PerformInternal1 (const BOPAlgo_PaveFiller& thePF);
348
349   //! Builds the result of operation.
350   //! The method is called for each of the arguments type and
351   //! adds into the result the splits of the arguments of that type.
352   Standard_EXPORT virtual void BuildResult (const TopAbs_ShapeEnum theType);
353
354
355 protected: //! @name Checking input arguments
356
357   //! Checks the input data.
358   Standard_EXPORT virtual void CheckData() Standard_OVERRIDE;
359
360   //! Checks if the intersection algorithm has Errors/Warnings.
361   Standard_EXPORT void CheckFiller();
362
363   //! Prepares the result shape by making it empty compound.
364   Standard_EXPORT virtual void Prepare();
365
366
367 protected: //! @name Fill Images of VERTICES
368
369   //! Fills the images of vertices.
370   Standard_EXPORT void FillImagesVertices();
371
372
373 protected: //! @name Fill Images of EDGES
374
375   //! Fills the images of edges.
376   Standard_EXPORT void FillImagesEdges();
377
378
379 protected: //! @name Fill Images of CONTAINERS
380
381   //! Fills the images of containers (WIRES/SHELLS/COMPSOLID).
382   Standard_EXPORT void FillImagesContainers (const TopAbs_ShapeEnum theType);
383
384   //! Builds the image of the given container using the splits
385   //! of its sub-shapes.
386   Standard_EXPORT void FillImagesContainer (const TopoDS_Shape& theS, const TopAbs_ShapeEnum theType);
387
388
389 protected: //! @name Fill Images of FACES
390
391   //! Fills the images of faces.
392   //! The method consists of three steps:
393   //! 1. Build the splits of faces;
394   //! 2. Find SD faces;
395   //! 3. Add internal vertices (if any) to faces.
396   Standard_EXPORT void FillImagesFaces();
397
398   //! Builds the splits of faces using the information from the
399   //! intersection stage stored in Data Structure.
400   Standard_EXPORT virtual void BuildSplitFaces();
401
402   //! Looks for the same domain faces among the splits of the faces.
403   //! Updates the map of images with SD faces.
404   Standard_EXPORT void FillSameDomainFaces();
405
406   //! Classifies the alone vertices on faces relatively its splits
407   //! and adds them as INTERNAL into the splits.
408   Standard_EXPORT void FillInternalVertices();
409
410
411 protected: //! @name Fill Images of SOLIDS
412
413   //! Fills the images of solids.
414   //! The method consists of four steps:
415   //! 1. Build the draft solid - just rebuild the solid using the splits of faces;
416   //! 2. Find faces from other arguments located inside the solids;
417   //! 3. Build splits of solid using the inside faces;
418   //! 4. Fill internal shapes for the splits (Wires and vertices).
419   Standard_EXPORT void FillImagesSolids();
420
421   //! Builds the draft solid by rebuilding the shells of the solid
422   //! with the splits of faces.
423   Standard_EXPORT void BuildDraftSolid (const TopoDS_Shape& theSolid,
424                                         TopoDS_Shape& theDraftSolid,
425                                         TopTools_ListOfShape& theLIF);
426
427   //! Finds faces located inside each solid.
428   Standard_EXPORT virtual void FillIn3DParts(TopTools_DataMapOfShapeShape& theDraftSolids);
429
430   //! Builds the splits of the solids using their draft versions
431   //! and faces located inside.
432   Standard_EXPORT void BuildSplitSolids(TopTools_DataMapOfShapeShape& theDraftSolids);
433
434   //! Classifies the vertices and edges from the arguments relatively
435   //! splits of solids and makes them INTERNAL for solids.
436   Standard_EXPORT void FillInternalShapes();
437
438
439 protected: //! @name Fill Images of COMPOUNDS
440
441   //! Fills the images of compounds.
442   Standard_EXPORT void FillImagesCompounds();
443
444   //! Builds the image of the given compound.
445   Standard_EXPORT void FillImagesCompound (const TopoDS_Shape& theS,
446                                            TopTools_MapOfShape& theMF);
447
448 protected: //! @name Post treatment
449
450   //! Post treatment of the result of the operation.
451   //! The method checks validity of the sub-shapes of the result
452   //! and updates the tolerances to make them valid.
453   Standard_EXPORT virtual void PostTreat();
454
455
456 protected: //! @name Fields
457
458   TopTools_ListOfShape myArguments;             //!< Arguments of the operation
459   TopTools_MapOfShape myMapFence;               //!< Fence map providing the uniqueness of the shapes in the list of arguments
460   BOPAlgo_PPaveFiller myPaveFiller;             //!< Pave Filler - algorithm for sub-shapes intersection
461   BOPDS_PDS myDS;                               //!< Data Structure - holder of intersection information
462   Handle(IntTools_Context) myContext;           //!< Context - tool for cashing heavy algorithms such as Projectors and Classifiers
463   Standard_Integer myEntryPoint;                //!< EntryPoint - controls the deletion of the PaveFiller, which could live longer than the Builder
464   TopTools_DataMapOfShapeListOfShape myImages;  //!< Images - map of Images of the sub-shapes of arguments
465   TopTools_DataMapOfShapeShape myShapesSD;      //!< ShapesSD - map of SD Shapes
466   TopTools_DataMapOfShapeListOfShape myOrigins; //!< Origins - map of Origins, back map of Images
467   TopTools_DataMapOfShapeListOfShape myInParts; //!< InParts - map of own and acquired IN faces of the arguments solids
468   Standard_Boolean myNonDestructive;            //!< Safe processing option allows avoiding modification of the input shapes
469   BOPAlgo_GlueEnum myGlue;                      //!< Gluing option allows speeding up the intersection of the input shapes
470   Standard_Boolean myCheckInverted;             //!< Check inverted option allows disabling the check of input solids on inverted status
471
472 };
473
474 #endif // _BOPAlgo_Builder_HeaderFile