1 // Copyright (C) 2007-2024 CEA, EDF, OPEN CASCADE
3 // Copyright (C) 2003-2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
4 // CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
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.
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.
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
20 // See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
23 #ifndef _GEOMUtils_HXX_
24 #define _GEOMUtils_HXX_
26 #include <Standard_Macro.hxx>
27 #include <TopoDS_Shape.hxx>
28 #include <TopoDS_Vertex.hxx>
30 #include <TopTools_ListOfShape.hxx>
37 #include <V3d_View.hxx>
39 #include <NCollection_DataMap.hxx>
50 inline Standard_Boolean IsEqual (const TopoDS_Shape& S1, const TopoDS_Shape& S2)
59 * This enumeration represents comparison conditions.
61 enum ComparisonCondition {
62 CC_GT, ///< Greater then
63 CC_GE, ///< Greater then or equal to
65 CC_LE ///< Less then or equal to
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;
74 * \brief Compute numerical functor for the shape.
76 * Resulting value can be used to sort out shapes according to some parameter.
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
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
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
92 Standard_EXPORT std::pair<double, double> ShapeToDouble (const TopoDS_Shape& theShape,
93 bool isOldSorting = false);
96 * \brief Get Local Coordinate System, corresponding to the given shape.
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.
102 Standard_EXPORT gp_Ax3 GetPosition (const TopoDS_Shape& theShape);
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.
112 Standard_EXPORT gp_Vec GetVector (const TopoDS_Shape& theShape,
113 Standard_Boolean doConsiderOrientation);
116 * \brief Sort shapes in the list by their coordinates.
117 * \param SL The list of shapes to sort.
119 struct CompareShapes //: public std::binary_function<TopoDS_Shape, TopoDS_Shape, bool>
121 CompareShapes (bool isOldSorting)
122 : myIsOldSorting(isOldSorting) {}
124 bool operator() (const TopoDS_Shape& lhs, const TopoDS_Shape& rhs);
126 typedef NCollection_DataMap<TopoDS_Shape, std::pair<double, double> > GEOMUtils_DataMapOfShapeDouble;
127 GEOMUtils_DataMapOfShapeDouble myMap;
132 * \brief Sort shapes by their centers of mass, using formula X*999 + Y*99 + Z*0.9
134 Standard_EXPORT void SortShapes (TopTools_ListOfShape& SL,
135 const Standard_Boolean isOldSorting = Standard_True);
138 * \brief Convert TopoDS_COMPSOLID to TopoDS_COMPOUND.
140 * If the argument shape is not of type TopoDS_COMPSOLID, this method returns it as is.
142 * \param theCompsolid The compsolid to be converted.
143 * \retval TopoDS_Shape Returns the resulting compound.
145 Standard_EXPORT TopoDS_Shape CompsolidToCompound (const TopoDS_Shape& theCompsolid);
148 * \brief Recursively extract all shapes from compounds and compsolids of the given shape into theList.
150 * If theShape is not compound or compsolid, theList will contain only theShape itself.
152 * \param theShape The shape to be exploded.
153 * \param theList Output parameter.
155 Standard_EXPORT void AddSimpleShapes (const TopoDS_Shape& theShape,
156 TopTools_ListOfShape& theList);
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.
163 Standard_EXPORT bool CheckTriangulation (const TopoDS_Shape& theShape);
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.
170 Standard_EXPORT TopAbs_ShapeEnum GetTypeOfSimplePart (const TopoDS_Shape& theShape);
173 * \brief Find an edge of theShape, closest to thePoint.
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.
179 Standard_EXPORT TopoDS_Shape GetEdgeNearPoint (const TopoDS_Shape& theShape,
180 const TopoDS_Vertex& thePoint);
183 * \brief Compute precise bounding box of the shape based on the rough bounding box.
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.
189 Standard_EXPORT Standard_Boolean PreciseBoundingBox(const TopoDS_Shape &theShape, Bnd_Box &theBox);
192 * \brief Computes minumal distance between two shapes for singular cases
193 * (workaround for bugs 19899, 19908 and 19910 from Mantis).
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.
201 Standard_EXPORT Standard_Real GetMinDistanceSingular(const TopoDS_Shape& aSh1,
202 const TopoDS_Shape& aSh2,
203 gp_Pnt& Ptmp1, gp_Pnt& Ptmp2);
206 * \brief Computes minumal distance between two shapes.
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.
214 Standard_EXPORT Standard_Real GetMinDistance(const TopoDS_Shape& theShape1,
215 const TopoDS_Shape& theShape2,
216 gp_Pnt& thePnt1, gp_Pnt& thePnt2);
219 * \brief Computes normal projection of \a thePoint to \a theFace.
221 * \param thePoint the 3d point
222 * \param theFace the face shape
223 * \param theU the output U parameter of the point on the face
224 * \param theV the output V parameter of the point on the face
225 * \param theTol the tolerance value. Maximum of theTol and 1e-04 will be used for calculation.
226 * \retval the projection (3d point) if found, throws an exception otherwise
228 Standard_EXPORT gp_Pnt ProjectPointOnFace(const gp_Pnt& thePoint,
229 const TopoDS_Shape& theFace,
230 double& theU, double& theV,
231 const double theTol = 1e-04);
234 * \brief Returns the point clicked in 3D view.
236 * \param x The X coordinate in the view.
237 * \param y The Y coordinate in the view.
238 * \param theView View where the given point takes place.
239 * \retval gp_Pnt Returns the point clicked in 3D view
241 Standard_EXPORT gp_Pnt ConvertClickToPoint( int x, int y, Handle(V3d_View) theView );
244 * \brief Convert dependency tree data to the string representation
246 * \param tree dependency tree data
247 * \param dependencyStr output string
249 Standard_EXPORT void ConvertTreeToString( const TreeModel& tree,
250 std::string& dependencyStr );
253 * \brief Restore dependency tree data from the string representation
255 * \param dependencyStr string representation of tree data
256 * \param tree output dependency tree data
258 Standard_EXPORT void ConvertStringToTree( const std::string& dependencyStr,
264 * \param shape input shape object
265 * \param checkGeometry when set to \c true, causes check of underlying geometry
266 * in addition to the topology
267 * \return \c true if shape is valid or \c false otherwise
269 Standard_EXPORT bool CheckShape( TopoDS_Shape& shape, bool checkGeometry = false );
272 * \brief Check boolean and partition operations arguments
274 * \param theShape the argument of an operation to be checked
275 * \return \c true if the argument is valid for a boolean or partition
276 * operation or \c false otherwise
278 Standard_EXPORT bool CheckBOPArguments(const TopoDS_Shape &theShape);
281 * \brief Limit shape tolerance to the given value
283 * \param shape shape being fixed
284 * \param type topology type which tolerance is to be limited; TopAbs_SHAPE means
285 * all types of topology
286 * \param tolerance expected tolerance value (1e-7 by default)
287 * \param checkGeometry check geometry validity of result
288 * \return \c true if resulting shape is valid
290 * \note Resulting tolerance of the shape is not mandatory equal to requested value
291 * as it might be changed by fixshape operation in order to get valid shape where possible
292 * \note By default, result only checked for topology validity; check of geometry can be done by
293 * passing \c true to \a checkGeometry parameter
295 Standard_EXPORT bool FixShapeTolerance( TopoDS_Shape& shape,
296 TopAbs_ShapeEnum type,
297 Standard_Real tolerance = Precision::Confusion(),
298 bool checkGeometry = false );
301 * \brief Limit shape tolerance to the given value
302 * This is overloaded function, it behaves exactly as previous one
304 Standard_EXPORT bool FixShapeTolerance( TopoDS_Shape& shape,
305 Standard_Real tolerance = Precision::Confusion(),
306 bool checkGeometry = false );
309 * \brief Limit shape tolerance to the given value
310 * This is overloaded function, it behaves exactly as previous one
312 Standard_EXPORT bool FixShapeTolerance( TopoDS_Shape& shape,
313 bool checkGeometry );
316 * \brief Fix curves of the given shape
318 * The function checks each curve of the input shape in the following way:
319 * - compute deviation of the curve from the underlying surface in a set of points
320 * computed with the certain discretization step value
321 * - find maximum tolerance between computed deviation values
322 * - limit tolerance of the curve with the computed maximum value
324 * \param shape shape being fixed
325 * \return \c true if resulting shape is valid
327 Standard_EXPORT bool FixShapeCurves( TopoDS_Shape& shape );
330 * \brief Write shape to the BREP file
332 * \param source shape
333 * \return \c true if file was written or \c false otherwise
335 Standard_EXPORT bool Write( const TopoDS_Shape& shape,
336 const char* fileName );
339 * \brief Extract single SOLID from COMPSOLID or COMPOUND.
341 * If the argument shape is a COMPOUND or COMPSOLID and there's
342 * only single simple-shape type inside, this sub-shape is returned as a result;
343 * otherwise, the shape is not changed.
345 * \param shape compound or compsolid being processed.
346 * \retval TopoDS_Shape resulting shape
348 Standard_EXPORT TopoDS_Shape ReduceCompound( const TopoDS_Shape& shape );
351 * \brief Generate triangulation for the shape.
353 * \param shape shape being meshed
354 * \param deflection deflection coefficient to be used
355 * \param forced if \c true, causes generation of mesh regardless it is already present in the shape
357 Standard_EXPORT void MeshShape( const TopoDS_Shape shape,
358 double deflection, bool forced = true );
361 * \brief Get default deflection coefficient used for triangulation
362 * \return default deflection value
364 Standard_EXPORT double DefaultDeflection();
367 * \brief Check if the shape is not a closed wire or edge.
369 * This function is used for pipe creation algorithm to test if
370 * the pipe path is not closed. It returns false if theShape is a wire or
371 * an edge with coincident end vertices. Otherwise it returns true.
373 * \param theShape the shape to be tested.
374 * \return true if theShape is not a closed wire or edge.
376 Standard_EXPORT bool IsOpenPath(const TopoDS_Shape &theShape);
379 * This function compares two tolerances. The shape tolerance (the first
380 * argument) is considered less than the reference tolerance (the second
381 * argument) if theTolShape < theTolRef - Tolerance(theTolRef). theTolShape is
382 * considered greater than theTolRef if theTolShape > theTolRef +
383 * Tolerance(theTolRef). Otherwise these tolerances are equal.
384 * Tolerance(theTolRef) = theTolRef*DEFAULT_TOLERANCE_TOLERANCE. But this value
385 * should not be greated than DEFAULT_MAX_TOLERANCE_TOLERANCE.
387 * \param theTolShape the shape tolerance
388 * \param theTolRef the reference tolerance
389 * \return -1 if theTolShape is less than theTolRef; 1 if theTolShape is greater
390 * than theTolRef; 0 if they are equal
392 Standard_EXPORT int CompareToleranceValues(const double theTolShape,
393 const double theTolRef);
396 * Check if the comarison of tolerances fit the condition. The comparison of
397 * tolerances is performed using the function CompareToleranceValues.
399 * \param theCondition the condition
400 * \param theTolShape the shape tolerance
401 * \param theTolRef the reference tolerance
402 * \return true if the shape tolerance fits the condition; false otherwise.
404 Standard_EXPORT bool IsFitCondition(const ComparisonCondition theCondition,
405 const double theTolShape,
406 const double theTolRef);