]> SALOME platform Git repositories - modules/geom.git/blob - src/GEOMUtils/GEOMUtils.hxx
Salome HOME
f41b21650e5c38a200021c3a5a3600d8b553beb0
[modules/geom.git] / src / GEOMUtils / GEOMUtils.hxx
1 // Copyright (C) 2007-2022  CEA/DEN, EDF R&D, OPEN CASCADE
2 //
3 // Copyright (C) 2003-2007  OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
4 // CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
5 //
6 // This library is free software; you can redistribute it and/or
7 // modify it under the terms of the GNU Lesser General Public
8 // License as published by the Free Software Foundation; either
9 // version 2.1 of the License, or (at your option) any later version.
10 //
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 // Lesser General Public License for more details.
15 //
16 // You should have received a copy of the GNU Lesser General Public
17 // License along with this library; if not, write to the Free Software
18 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
19 //
20 // See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
21 //
22
23 #ifndef _GEOMUtils_HXX_
24 #define _GEOMUtils_HXX_
25
26 #include <Standard_Macro.hxx>
27 #include <TopoDS_Shape.hxx>
28 #include <TopoDS_Vertex.hxx>
29
30 #include <TopTools_ListOfShape.hxx>
31
32 #include <TopAbs.hxx>
33
34 #include <gp_Ax3.hxx>
35 #include <gp_Vec.hxx>
36
37 #include <V3d_View.hxx>
38
39 #include <NCollection_DataMap.hxx>
40
41 #include <functional>
42
43 #include <map>
44 #include <vector>
45 #include <string>
46 #include <utility>
47
48 class Bnd_Box;
49
50 inline Standard_Boolean IsEqual (const TopoDS_Shape& S1, const TopoDS_Shape& S2)
51 {
52   return S1.IsSame(S2);
53 }
54
55 namespace GEOMUtils
56 {
57
58   /**
59    * This enumeration represents comparison conditions.
60    */
61   enum ComparisonCondition {
62     CC_GT, ///< Greater then
63     CC_GE, ///< Greater then or equal to
64     CC_LT, ///< Less then
65     CC_LE  ///< Less then or equal to
66   };
67
68   typedef std::vector<std::string> NodeLinks;
69   typedef std::map<std::string, NodeLinks> LevelInfo;
70   typedef std::vector<LevelInfo> LevelsList;
71   typedef std::map<std::string,std::pair<LevelsList,LevelsList> > TreeModel;
72
73   /*!
74    * \brief Compute numerical functor for the shape.
75    *
76    * Resulting value can be used to sort out shapes according to some parameter.
77    * 
78    * Returns a pair of two values (dist, functor) where
79    * - \a dist is a some value that is computed according to the center of mass of given shape;
80    * - \a functor is a numerical functor value
81    *
82    * The numerical functor is computed according to the shape's topological properties as follows:
83    * - orientation for vertices 
84    * - length for edges and wires
85    * - area for faces and shells
86    * - volume for solids, compounds, compsolids
87    *
88    * If \a isOldSorting parameter is set to \c true, for all cases linear properties of the shape
89    * are used (to support backward compatibility in some methods). By default, this parameter is
90    * set to \c false.
91    */
92   Standard_EXPORT std::pair<double, double> ShapeToDouble (const TopoDS_Shape& theShape,
93                                                            bool isOldSorting = false);
94
95   /*!
96    * \brief Get Local Coordinate System, corresponding to the given shape.
97    *
98    * Origin of the LCS is situated at the shape's center of mass.
99    * Axes of the LCS are obtained from shape's location or,
100    * if the shape is a planar face, from position of its plane.
101    */
102   Standard_EXPORT gp_Ax3 GetPosition (const TopoDS_Shape& theShape);
103
104   /*!
105    * \brief Get vector, defined by the given edge.
106    * \param theShape The edge.
107    * \param doConsiderOrientation If True, take into account the edge orientation.
108    * \note It is recommended to use doConsiderOrientation=Standard_False, because
109    *       the same edge can have different orientation depending on the way it was
110    *       extracted from a shape.
111    */
112   Standard_EXPORT gp_Vec GetVector (const TopoDS_Shape& theShape,
113                                     Standard_Boolean doConsiderOrientation);
114
115   /*!
116    * \brief Sort shapes in the list by their coordinates.
117    * \param SL The list of shapes to sort.
118    */
119   struct CompareShapes //: public std::binary_function<TopoDS_Shape, TopoDS_Shape, bool>
120   {
121     CompareShapes (bool isOldSorting)
122       : myIsOldSorting(isOldSorting) {}
123
124     bool operator() (const TopoDS_Shape& lhs, const TopoDS_Shape& rhs);
125
126     typedef NCollection_DataMap<TopoDS_Shape, std::pair<double, double> > GEOMUtils_DataMapOfShapeDouble;
127     GEOMUtils_DataMapOfShapeDouble myMap;
128     bool myIsOldSorting;
129   };
130
131   /*!
132    * \brief Sort shapes by their centers of mass, using formula X*999 + Y*99 + Z*0.9
133    */
134   Standard_EXPORT void SortShapes (TopTools_ListOfShape& SL,
135                                    const Standard_Boolean isOldSorting = Standard_True);
136
137   /*!
138    * \brief Convert TopoDS_COMPSOLID to TopoDS_COMPOUND.
139    *
140    * If the argument shape is not of type TopoDS_COMPSOLID, this method returns it as is.
141    *
142    * \param theCompsolid The compsolid to be converted.
143    * \retval TopoDS_Shape Returns the resulting compound.
144    */
145   Standard_EXPORT TopoDS_Shape CompsolidToCompound (const TopoDS_Shape& theCompsolid);
146
147   /*!
148    * \brief Recursively extract all shapes from compounds and compsolids of the given shape into theList.
149    *
150    * If theShape is not compound or compsolid, theList will contain only theShape itself.
151    *
152    * \param theShape The shape to be exploded.
153    * \param theList Output parameter.
154    */
155   Standard_EXPORT void AddSimpleShapes (const TopoDS_Shape& theShape,
156                                         TopTools_ListOfShape& theList);
157
158   /*!
159    * \brief Build a triangulation on \a theShape if it is absent.
160    * \param theShape The shape to check/build triangulation on.
161    * \retval bool Returns false if the shape has no faces, i.e. impossible to build triangulation.
162    */
163   Standard_EXPORT bool CheckTriangulation (const TopoDS_Shape& theShape);
164   
165   /*!
166    * \brief Return type of shape for explode. In case of compound it will be a type of its first sub shape.
167    * \param theShape The shape to get type of.
168    * \retval TopAbs_ShapeEnum Return type of shape for explode.
169    */
170   Standard_EXPORT TopAbs_ShapeEnum GetTypeOfSimplePart (const TopoDS_Shape& theShape);
171
172   /*!
173    * \brief Find an edge of theShape, closest to thePoint.
174    *
175    * \param theShape The shape to explore.
176    * \param thePoint The point near the required edge.
177    * \retval TopoDS_Shape Returns the found edge or an empty shape if multiple edges found.
178    */
179   Standard_EXPORT TopoDS_Shape GetEdgeNearPoint (const TopoDS_Shape&  theShape,
180                                                  const TopoDS_Vertex& thePoint);
181
182   /*!
183    * \brief Compute precise bounding box of the shape based on the rough bounding box.
184    *
185    * \param theShape the shape.
186    * \param theBox rough bounding box on input; precise bounding box on output.
187    * \retval Standard_True in case of success; Standard_False otherwise.
188    */
189   Standard_EXPORT Standard_Boolean PreciseBoundingBox(const TopoDS_Shape &theShape, Bnd_Box &theBox);
190
191   /*!
192    * \brief Computes minumal distance between two shapes for singular cases
193    *        (workaround for bugs 19899, 19908 and 19910 from Mantis).
194    *
195    * \param aSh1 the first shape
196    * \param aSh2 the second shape
197    * \param Ptmp1 the output result point on the first shape
198    * \param Ptmp2 the output result point on the second shape
199    * \retval negative value if it is not a singular case; actual distance for singular case.
200    */
201   Standard_EXPORT Standard_Real GetMinDistanceSingular(const TopoDS_Shape& aSh1,
202                                                        const TopoDS_Shape& aSh2,
203                                                        gp_Pnt& Ptmp1, gp_Pnt& Ptmp2);
204   
205   /*!
206    * \brief Computes minumal distance between two shapes.
207    *
208    * \param theShape1 the first shape
209    * \param theShape2 the second shape
210    * \param thePnt1 the output result point on the first shape
211    * \param thePnt2 the output result point on the second shape
212    * \retval negative value in case of failure; otherwise the real distance.
213    */
214   Standard_EXPORT Standard_Real GetMinDistance(const TopoDS_Shape& theShape1,
215                                                const TopoDS_Shape& theShape2,
216                                                gp_Pnt& thePnt1, gp_Pnt& thePnt2);
217   
218   /*!
219    * \brief Returns the point clicked in 3D view.
220    *
221    * \param x The X coordinate in the view.
222    * \param y The Y coordinate in the view.
223    * \param theView View where the given point takes place.
224    * \retval gp_Pnt Returns the point clicked in 3D view
225    */
226   Standard_EXPORT gp_Pnt ConvertClickToPoint( int x, int y, Handle(V3d_View) theView );
227
228   /*!
229    * \brief Convert dependency tree data to the string representation
230    *
231    * \param tree dependency tree data
232    * \param dependencyStr output string
233    */
234   Standard_EXPORT void ConvertTreeToString( const TreeModel& tree,
235                                             std::string& dependencyStr );
236
237   /*!
238    * \brief Restore dependency tree data from the string representation
239    *
240    * \param dependencyStr string representation of tree data
241    * \param tree output dependency tree data
242    */
243   Standard_EXPORT void ConvertStringToTree( const std::string& dependencyStr,
244                                             TreeModel& tree );
245
246   /*!
247    * \brief Check shape
248    *
249    * \param shape input shape object
250    * \param checkGeometry when set to \c true, causes check of underlying geometry
251    *        in addition to the topology
252    * \return \c true if shape is valid or \c false otherwise
253    */
254   Standard_EXPORT bool CheckShape( TopoDS_Shape& shape, bool checkGeometry = false );
255
256   /*!
257    * \brief Check boolean and partition operations arguments
258    *
259    * \param theShape the argument of an operation to be checked
260    * \return \c true if the argument is valid for a boolean or partition
261    *         operation or \c false otherwise
262    */
263   Standard_EXPORT bool CheckBOPArguments(const TopoDS_Shape &theShape);
264   
265   /*!
266    * \brief Limit shape tolerance to the given value
267    *
268    * \param shape shape being fixed
269    * \param type topology type which tolerance is to be limited; TopAbs_SHAPE means
270    *             all types of topology
271    * \param tolerance expected tolerance value (1e-7 by default)
272    * \param checkGeometry check geometry validity of result
273    * \return \c true if resulting shape is valid
274    *
275    * \note Resulting tolerance of the shape is not mandatory equal to requested value
276    *       as it might be changed by fixshape operation in order to get valid shape where possible
277    * \note By default, result only checked for topology validity; check of geometry can be done by
278    *       passing \c true to \a checkGeometry parameter
279    */
280   Standard_EXPORT bool FixShapeTolerance( TopoDS_Shape& shape,
281                                           TopAbs_ShapeEnum type,
282                                           Standard_Real tolerance = Precision::Confusion(),
283                                           bool checkGeometry = false );
284
285   /*!
286    * \brief Limit shape tolerance to the given value
287    * This is overloaded function, it behaves exactly as previous one
288    */
289   Standard_EXPORT bool FixShapeTolerance( TopoDS_Shape& shape,
290                                           Standard_Real tolerance = Precision::Confusion(),
291                                           bool checkGeometry = false );
292
293   /*!
294    * \brief Limit shape tolerance to the given value
295    * This is overloaded function, it behaves exactly as previous one
296    */
297   Standard_EXPORT bool FixShapeTolerance( TopoDS_Shape& shape,
298                                           bool checkGeometry );
299
300   /*!
301    * \brief Fix curves of the given shape
302    * 
303    * The function checks each curve of the input shape in the following way:
304    * - compute deviation of the curve from the underlying surface in a set of points
305    *   computed with the certain discretization step value
306    * - find maximum tolerance between computed deviation values
307    * - limit tolerance of the curve with the computed maximum value
308    * 
309    * \param shape shape being fixed
310    * \return \c true if resulting shape is valid
311    */
312   Standard_EXPORT bool FixShapeCurves( TopoDS_Shape& shape );
313
314   /*!
315    * \brief Write shape to the BREP file
316    *
317    * \param source shape
318    * \return \c true if file was written or \c false otherwise
319    */
320   Standard_EXPORT bool Write( const TopoDS_Shape& shape,
321                               const char* fileName );
322   
323   /*!
324    * \brief Extract single SOLID from COMPSOLID or COMPOUND.
325    *
326    * If the argument shape is a COMPOUND or COMPSOLID and there's
327    * only single simple-shape type inside, this sub-shape is returned as a result;
328    * otherwise, the shape is not changed.
329    *
330    * \param shape compound or compsolid being processed.
331    * \retval TopoDS_Shape resulting shape
332    */
333   Standard_EXPORT TopoDS_Shape ReduceCompound( const TopoDS_Shape& shape );
334
335   /*!
336    * \brief Generate triangulation for the shape.
337    *
338    * \param shape shape being meshed
339    * \param deflection deflection coefficient to be used
340    * \param forced if \c true, causes generation of mesh regardless it is already present in the shape
341    */
342   Standard_EXPORT void MeshShape( const TopoDS_Shape shape,
343                                   double deflection, bool forced = true );
344
345   /*!
346    * \brief Get default deflection coefficient used for triangulation
347    * \return default deflection value
348    */
349   Standard_EXPORT double DefaultDeflection();
350
351   /**
352    * \brief Check if the shape is not a closed wire or edge.
353    *
354    * This function is used for pipe creation algorithm to test if
355    * the pipe path is not closed. It returns false if theShape is a wire or
356    * an edge with coincident end vertices. Otherwise it returns true.
357    *
358    * \param theShape the shape to be tested.
359    * \return true if theShape is not a closed wire or edge.
360    */
361   Standard_EXPORT bool IsOpenPath(const TopoDS_Shape &theShape);
362
363   /**
364    * This function compares two tolerances. The shape tolerance (the first
365    * argument) is considered less than the reference tolerance (the second
366    * argument) if theTolShape < theTolRef - Tolerance(theTolRef). theTolShape is
367    * considered greater than theTolRef if theTolShape > theTolRef +
368    * Tolerance(theTolRef). Otherwise these tolerances are equal.
369    * Tolerance(theTolRef) = theTolRef*DEFAULT_TOLERANCE_TOLERANCE. But this value
370    * should not be greated than DEFAULT_MAX_TOLERANCE_TOLERANCE.
371    *
372    * \param theTolShape the shape tolerance
373    * \param theTolRef the reference tolerance
374    * \return -1 if theTolShape is less than theTolRef; 1 if theTolShape is greater
375    * than theTolRef; 0 if they are equal
376    */
377   Standard_EXPORT int CompareToleranceValues(const double theTolShape,
378                                              const double theTolRef);
379
380   /**
381    * Check if the comarison of tolerances fit the condition. The comparison of
382    * tolerances is performed using the function CompareToleranceValues.
383    *
384    * \param theCondition the condition
385    * \param theTolShape the shape tolerance
386    * \param theTolRef the reference tolerance
387    * \return true if the shape tolerance fits the condition; false otherwise.
388    */
389   Standard_EXPORT bool IsFitCondition(const ComparisonCondition theCondition,
390                                       const double              theTolShape,
391                                       const double              theTolRef);
392
393 }
394
395 #endif