src/GEOMUtils/GEOMUtils.hxx

   1 // Copyright (C) 2007-2024  CEA, EDF, 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 Return type of shape for explode. In case of compound it will be a type of its first sub shape.
 160    * \param theShape The shape to get type of.
 161    * \retval TopAbs_ShapeEnum Return type of shape for explode.
 162    */
 163   Standard_EXPORT TopAbs_ShapeEnum GetTypeOfSimplePart (const TopoDS_Shape& theShape);
 164
 165   /*!
 166    * \brief Find an edge of theShape, closest to thePoint.
 167    *
 168    * \param theShape The shape to explore.
 169    * \param thePoint The point near the required edge.
 170    * \retval TopoDS_Shape Returns the found edge or an empty shape if multiple edges found.
 171    */
 172   Standard_EXPORT TopoDS_Shape GetEdgeNearPoint (const TopoDS_Shape&  theShape,
 173                                                  const TopoDS_Vertex& thePoint);
 174
 175   /*!
 176    * \brief Compute precise bounding box of the shape based on the rough bounding box.
 177    *
 178    * \param theShape the shape.
 179    * \param theBox rough bounding box on input; precise bounding box on output.
 180    * \retval Standard_True in case of success; Standard_False otherwise.
 181    */
 182   Standard_EXPORT Standard_Boolean PreciseBoundingBox(const TopoDS_Shape &theShape, Bnd_Box &theBox);
 183
 184   /*!
 185    * \brief Computes minumal distance between two shapes for singular cases
 186    *        (workaround for bugs 19899, 19908 and 19910 from Mantis).
 187    *
 188    * \param aSh1 the first shape
 189    * \param aSh2 the second shape
 190    * \param Ptmp1 the output result point on the first shape
 191    * \param Ptmp2 the output result point on the second shape
 192    * \retval negative value if it is not a singular case; actual distance for singular case.
 193    */
 194   Standard_EXPORT Standard_Real GetMinDistanceSingular(const TopoDS_Shape& aSh1,
 195                                                        const TopoDS_Shape& aSh2,
 196                                                        gp_Pnt& Ptmp1, gp_Pnt& Ptmp2);
 197
 198   /*!
 199    * \brief Computes minumal distance between two shapes.
 200    *
 201    * \param theShape1 the first shape
 202    * \param theShape2 the second shape
 203    * \param thePnt1 the output result point on the first shape
 204    * \param thePnt2 the output result point on the second shape
 205    * \retval negative value in case of failure; otherwise the real distance.
 206    */
 207   Standard_EXPORT Standard_Real GetMinDistance(const TopoDS_Shape& theShape1,
 208                                                const TopoDS_Shape& theShape2,
 209                                                gp_Pnt& thePnt1, gp_Pnt& thePnt2);
 210
 211   /*!
 212    * \brief Computes normal projection of \a thePoint to \a theFace.
 213    *
 214    * \param thePoint the 3d point
 215    * \param theFace the face shape
 216    * \param theU the output U parameter of the point on the face
 217    * \param theV the output V parameter of the point on the face
 218    * \param theTol the tolerance value. Maximum of theTol and 1e-04 will be used for calculation.
 219    * \retval the projection (3d point) if found, throws an exception otherwise
 220    */
 221   Standard_EXPORT gp_Pnt ProjectPointOnFace(const gp_Pnt& thePoint,
 222                                             const TopoDS_Shape& theFace,
 223                                             double& theU, double& theV,
 224                                             const double theTol = 1e-04);
 225
 226   /*!
 227    * \brief Returns the point clicked in 3D view.
 228    *
 229    * \param x The X coordinate in the view.
 230    * \param y The Y coordinate in the view.
 231    * \param theView View where the given point takes place.
 232    * \retval gp_Pnt Returns the point clicked in 3D view
 233    */
 234   Standard_EXPORT gp_Pnt ConvertClickToPoint( int x, int y, Handle(V3d_View) theView );
 235
 236   /*!
 237    * \brief Convert dependency tree data to the string representation
 238    *
 239    * \param tree dependency tree data
 240    * \param dependencyStr output string
 241    */
 242   Standard_EXPORT void ConvertTreeToString( const TreeModel& tree,
 243                                             std::string& dependencyStr );
 244
 245   /*!
 246    * \brief Restore dependency tree data from the string representation
 247    *
 248    * \param dependencyStr string representation of tree data
 249    * \param tree output dependency tree data
 250    */
 251   Standard_EXPORT void ConvertStringToTree( const std::string& dependencyStr,
 252                                             TreeModel& tree );
 253
 254   /*!
 255    * \brief Check shape
 256    *
 257    * \param shape input shape object
 258    * \param checkGeometry when set to \c true, causes check of underlying geometry
 259    *        in addition to the topology
 260    * \return \c true if shape is valid or \c false otherwise
 261    */
 262   Standard_EXPORT bool CheckShape( TopoDS_Shape& shape, bool checkGeometry = false );
 263
 264   /*!
 265    * \brief Check boolean and partition operations arguments
 266    *
 267    * \param theShape the argument of an operation to be checked
 268    * \return \c true if the argument is valid for a boolean or partition
 269    *         operation or \c false otherwise
 270    */
 271   Standard_EXPORT bool CheckBOPArguments(const TopoDS_Shape &theShape);
 272
 273   /*!
 274    * \brief Limit shape tolerance to the given value
 275    *
 276    * \param shape shape being fixed
 277    * \param type topology type which tolerance is to be limited; TopAbs_SHAPE means
 278    *             all types of topology
 279    * \param tolerance expected tolerance value (1e-7 by default)
 280    * \param checkGeometry check geometry validity of result
 281    * \return \c true if resulting shape is valid
 282    *
 283    * \note Resulting tolerance of the shape is not mandatory equal to requested value
 284    *       as it might be changed by fixshape operation in order to get valid shape where possible
 285    * \note By default, result only checked for topology validity; check of geometry can be done by
 286    *       passing \c true to \a checkGeometry parameter
 287    */
 288   Standard_EXPORT bool FixShapeTolerance( TopoDS_Shape& shape,
 289                                           TopAbs_ShapeEnum type,
 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                                           Standard_Real tolerance = Precision::Confusion(),
 299                                           bool checkGeometry = false );
 300
 301   /*!
 302    * \brief Limit shape tolerance to the given value
 303    * This is overloaded function, it behaves exactly as previous one
 304    */
 305   Standard_EXPORT bool FixShapeTolerance( TopoDS_Shape& shape,
 306                                           bool checkGeometry );
 307
 308   /*!
 309    * \brief Fix curves of the given shape
 310    *
 311    * The function checks each curve of the input shape in the following way:
 312    * - compute deviation of the curve from the underlying surface in a set of points
 313    *   computed with the certain discretization step value
 314    * - find maximum tolerance between computed deviation values
 315    * - limit tolerance of the curve with the computed maximum value
 316    *
 317    * \param shape shape being fixed
 318    * \return \c true if resulting shape is valid
 319    */
 320   Standard_EXPORT bool FixShapeCurves( TopoDS_Shape& shape );
 321
 322   /*!
 323    * \brief Write shape to the BREP file
 324    *
 325    * \param source shape
 326    * \return \c true if file was written or \c false otherwise
 327    */
 328   Standard_EXPORT bool Write( const TopoDS_Shape& shape,
 329                               const char* fileName );
 330
 331   /*!
 332    * \brief Extract single SOLID from COMPSOLID or COMPOUND.
 333    *
 334    * If the argument shape is a COMPOUND or COMPSOLID and there's
 335    * only single simple-shape type inside, this sub-shape is returned as a result;
 336    * otherwise, the shape is not changed.
 337    *
 338    * \param shape compound or compsolid being processed.
 339    * \retval TopoDS_Shape resulting shape
 340    */
 341   Standard_EXPORT TopoDS_Shape ReduceCompound( const TopoDS_Shape& shape );
 342
 343   /*!
 344    * \brief Get default deflection coefficient used for triangulation
 345    * \return default deflection value
 346    */
 347   Standard_EXPORT double DefaultDeflection();
 348
 349   /*!
 350    * \brief Generate triangulation for \a theShape.
 351    *
 352    * \param theShape shape to be meshed.
 353    * \param theDeflection deflection coefficient to be used.
 354    * \param theForced if \c true, causes generation of mesh regardless it is already present in the shape.
 355    * \param theAngleDeflection angular deflection coefficient to be used.
 356    * \param isRelative if true, \a theDeflection is considered relative to \a theShape maximum axial dimension.
 357    * \param doPostCheck if true, check mesh generation result and return corresponding boolean value.
 358    * \retval bool Returns false in the following cases:
 359    *              1. The shape has neither faces nor edges, i.e. impossible to build triangulation or polygon.
 360    *              2. \a theForced is false and \a theShape has no mesh or has incomplete mesh.
 361    *              3. \a doPostCheck is true and mesh generation failed or produced an incomplete mesh.
 362    */
 363   Standard_EXPORT bool MeshShape( const TopoDS_Shape theShape,
 364                                   const double theDeflection = DefaultDeflection(),
 365                                   const bool theForced = true,
 366                                   const double theAngleDeflection = 0.5,
 367                                   const bool isRelative = true,
 368                                   const bool doPostCheck = false);
 369
 370   /*!
 371    * \brief Build a triangulation on \a theShape if it is absent.
 372    * \param theShape The shape to check/build triangulation on.
 373    * \retval bool Returns false if the shape has no faces, i.e. impossible to build triangulation.
 374    */
 375   Standard_EXPORT bool CheckTriangulation (const TopoDS_Shape& theShape);
 376
 377   /**
 378    * \brief Check if the shape is not a closed wire or edge.
 379    *
 380    * This function is used for pipe creation algorithm to test if
 381    * the pipe path is not closed. It returns false if theShape is a wire or
 382    * an edge with coincident end vertices. Otherwise it returns true.
 383    *
 384    * \param theShape the shape to be tested.
 385    * \return true if theShape is not a closed wire or edge.
 386    */
 387   Standard_EXPORT bool IsOpenPath(const TopoDS_Shape &theShape);
 388
 389   /**
 390    * This function compares two tolerances. The shape tolerance (the first
 391    * argument) is considered less than the reference tolerance (the second
 392    * argument) if theTolShape < theTolRef - Tolerance(theTolRef). theTolShape is
 393    * considered greater than theTolRef if theTolShape > theTolRef +
 394    * Tolerance(theTolRef). Otherwise these tolerances are equal.
 395    * Tolerance(theTolRef) = theTolRef*DEFAULT_TOLERANCE_TOLERANCE. But this value
 396    * should not be greated than DEFAULT_MAX_TOLERANCE_TOLERANCE.
 397    *
 398    * \param theTolShape the shape tolerance
 399    * \param theTolRef the reference tolerance
 400    * \return -1 if theTolShape is less than theTolRef; 1 if theTolShape is greater
 401    * than theTolRef; 0 if they are equal
 402    */
 403   Standard_EXPORT int CompareToleranceValues(const double theTolShape,
 404                                              const double theTolRef);
 405
 406   /**
 407    * Check if the comarison of tolerances fit the condition. The comparison of
 408    * tolerances is performed using the function CompareToleranceValues.
 409    *
 410    * \param theCondition the condition
 411    * \param theTolShape the shape tolerance
 412    * \param theTolRef the reference tolerance
 413    * \return true if the shape tolerance fits the condition; false otherwise.
 414    */
 415   Standard_EXPORT bool IsFitCondition(const ComparisonCondition theCondition,
 416                                       const double              theTolShape,
 417                                       const double              theTolRef);
 418
 419 }
 420
 421 #endif