src/BRepTools/BRepTools_History.hxx

   1 // Created on: 2017-04-21
   2 // Created by: Alexander Bobkov
   3 // Copyright (c) 2017 OPEN CASCADE SAS
   4 //
   5 // This file is part of Open CASCADE Technology software library.
   6 //
   7 // This library is free software; you can redistribute it and/or modify it under
   8 // the terms of the GNU Lesser General Public License version 2.1 as published
   9 // by the Free Software Foundation, with special exception defined in the file
  10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 // distribution for complete text of the license and disclaimer of any warranty.
  12 //
  13 // Alternatively, this file may be used under the terms of Open CASCADE
  14 // commercial license or contractual agreement.
  15
  16 #ifndef _BRepTools_History_HeaderFile
  17 #define _BRepTools_History_HeaderFile
  18
  19 #include <NCollection_Handle.hxx>
  20 #include <TopTools_DataMapOfShapeListOfShape.hxx>
  21 #include <TopTools_MapOfShape.hxx>
  22
  23 class BRepTools_History;
  24 DEFINE_STANDARD_HANDLE(BRepTools_History, Standard_Transient)
  25
  26 //! The history keeps the following relations between the input shapes
  27 //! (S1, ..., Sm) and output shapes (T1, ..., Tn):
  28 //! 1) an output shape Tj is generated from an input shape Si: Tj <= G(Si);
  29 //! 2) a output shape Tj is modified from an input shape Si: Tj <= M(Si);
  30 //! 3) an input shape (Si) is removed: R(Si) == 1.
  31 //!
  32 //! The relations are kept only for shapes of types vertex, edge, face, and
  33 //! solid.
  34 //!
  35 //! The last relation means that:
  36 //! 1) shape Si is not an output shape and
  37 //! 2) no any shape is generated or modified (produced) from shape Si:
  38 //! R(Si) == 1 ==> Si != Tj, G(Si) == 0, M(Si) == 0.
  39 //!
  40 //! No any shape could be generated and modified from the same shape
  41 //! simultaneously: sets G(Si) and M(Si) are not intersected
  42 //! (G(Si) ^ M(Si) == 0).
  43 //!
  44 //! Each output shape should be:
  45 //! 1) an input shape or
  46 //! 2) generated or modified from an input shape (even generated from the
  47 //!   implicit null shape if necessary):
  48 //!   Tj == Si V (exists Si that Tj <= G(Si) U M(Si)).
  49 //!
  50 //! Recommendations to choose between relations 'generated' and 'modified':
  51 //! 1) a shape is generated from input shapes if it dimension is greater or
  52 //!   smaller than the dimensions of the input shapes;
  53 //! 2) a shape is generated from input shapes if these shapes are also output
  54 //!   shapes;
  55 //! 3) a shape is generated from input shapes of the same dimension if it is
  56 //!   produced by joining shapes generated from these shapes;
  57 //! 4) a shape is modified from an input shape if it replaces the input shape by
  58 //!   changes of the location, the tolerance, the bounds of the parametrical
  59 //!   space (the faces for a solid), the parametrization and/or by applying of
  60 //!   an approximation;
  61 //! 5) a shape is modified from input shapes of the same dimension if it is
  62 //!   produced by joining shapes modified from these shapes.
  63 //!
  64 //! Two sequential histories:
  65 //! - one history (H12) of shapes S1, ..., Sm to shapes T1, ..., Tn and
  66 //! - another history (H23) of shapes T1, ..., Tn to shapes Q1, ..., Ql
  67 //! could be merged to the single history (H13) of shapes S1, ..., Sm to shapes
  68 //! Q1, ..., Ql.
  69 //!
  70 //! During the merge:
  71 //! 1) if shape Tj is generated from shape Si then each shape generated or
  72 //!   modified from shape Tj is considered as a shape generated from shape Si
  73 //!   among shapes Q1, ..., Ql:
  74 //!   Tj <= G12(Si), Qk <= G23(Tj) U M23(Tj) ==> Qk <= G13(Si).
  75 //! 2) if shape Tj is modified from shape Si, shape Qk is generated from shape
  76 //!   Tj then shape Qk is considered as a shape generated from shape Si among
  77 //!   shapes Q1, ..., Ql:
  78 //!   Tj <= M12(Si), Qk <= G23(Tj) ==> Qk <= G13(Si);
  79 //! 3) if shape Tj is modified from shape Si, shape Qk is modified from shape
  80 //!   Tj then shape Qk is considered as a shape modified from shape Si among
  81 //!   shapes Q1, ..., Ql:
  82 //!   Tj <= M12(Si), Qk <= M23(Tj) ==> Qk <= M13(Si);
  83 class BRepTools_History: public Standard_Transient
  84 {
  85 public:
  86
  87   //! The types of the historical relations.
  88   enum TRelationType
  89   {
  90     TRelationType_Removed,
  91     TRelationType_Generated,
  92     TRelationType_Modified
  93   };
  94
  95 public:
  96
  97   //! Returns 'true' if the type of the shape is supported by the history.
  98   static Standard_Boolean IsSupportedType(const TopoDS_Shape& theShape)
  99   {
 100     const TopAbs_ShapeEnum aType = theShape.ShapeType();
 101     return aType == TopAbs_VERTEX || aType == TopAbs_EDGE ||
 102       aType == TopAbs_FACE || aType == TopAbs_SOLID;
 103   }
 104
 105 public: //! Methods to set the history.
 106
 107   //! Set the second shape as generated one from the first shape.
 108   Standard_EXPORT void AddGenerated(
 109     const TopoDS_Shape& theInitial, const TopoDS_Shape& theGenerated);
 110
 111   //! Set the second shape as modified one from the first shape.
 112   Standard_EXPORT void AddModified(
 113     const TopoDS_Shape& theInitial, const TopoDS_Shape& theModified);
 114
 115   //! Set the shape as removed one.
 116   Standard_EXPORT void Remove(const TopoDS_Shape& theRemoved);
 117
 118   //! Set the second shape as the only generated one from the first one.
 119   Standard_EXPORT void ReplaceGenerated(
 120     const TopoDS_Shape& theInitial, const TopoDS_Shape& theGenerated);
 121
 122   //! Set the second shape as the only modified one from the first one.
 123   Standard_EXPORT void ReplaceModified(
 124     const TopoDS_Shape& theInitial, const TopoDS_Shape& theModified);
 125
 126   //! Clears the history.
 127   void Clear()
 128   {
 129     myShapeToModified.Clear();
 130     myShapeToGenerated.Clear();
 131     myRemoved.Clear();
 132   }
 133
 134 public: //! Methods to read the history.
 135
 136   //! Returns all shapes generated from the shape.
 137   Standard_EXPORT
 138   const TopTools_ListOfShape& Generated(const TopoDS_Shape& theInitial) const;
 139
 140   //! Returns all shapes modified from the shape.
 141   Standard_EXPORT
 142   const TopTools_ListOfShape& Modified(const TopoDS_Shape& theInitial) const;
 143
 144   //! Returns 'true' if the shape is removed.
 145   Standard_EXPORT
 146   Standard_Boolean IsRemoved(const TopoDS_Shape& theInitial) const;
 147
 148 public: //! A method to merge a next history to this history.
 149
 150   //! Merges the next history to this history.
 151   Standard_EXPORT void Merge(const Handle(BRepTools_History)& theHistory23);
 152
 153 public:
 154
 155   //! Define the OCCT RTTI for the type.
 156   DEFINE_STANDARD_RTTIEXT(BRepTools_History, Standard_Transient)
 157
 158 private:
 159   //! Prepares the shapes generated from the first shape to set the second one
 160   //! as generated one from the first one by the addition or the replacement.
 161   //! Returns 'true' on success.
 162   Standard_Boolean prepareGenerated(
 163     const TopoDS_Shape& theInitial, const TopoDS_Shape& theGenerated);
 164
 165   //! Prepares the shapes modified from the first shape to set the second one
 166   //! as modified one from the first one by the addition or the replacement.
 167   //! Returns 'true' on success.
 168   Standard_Boolean prepareModified(
 169     const TopoDS_Shape& theInitial, const TopoDS_Shape& theModified);
 170
 171 private: //! Data to keep the history.
 172
 173   //! Maps each input shape to all shapes modified from it.
 174   //! If an input shape is not bound to the map then
 175   //! there is no shapes modified from the shape.
 176   //! No any shape should be mapped to an empty list.
 177   TopTools_DataMapOfShapeListOfShape myShapeToModified;
 178
 179   //! Maps each input shape to all shapes generated from it.
 180   //! If an input shape is not bound to the map then
 181   //! there is no shapes generated from the shape.
 182   //! No any shape should be mapped to an empty list.
 183   TopTools_DataMapOfShapeListOfShape myShapeToGenerated;
 184
 185   TopTools_MapOfShape myRemoved; //!< The removed shapes.
 186
 187 private: //! Auxiliary members to read the history.
 188
 189   //! An auxiliary empty list.
 190   static const TopTools_ListOfShape myEmptyList;
 191
 192   //! A method to export the auxiliary list.
 193   Standard_EXPORT static const TopTools_ListOfShape& emptyList();
 194
 195 private:
 196
 197   //! Auxiliary messages.
 198   static const char* myMsgUnsupportedType;
 199   static const char* myMsgGeneratedAndRemoved;
 200   static const char* myMsgModifiedAndRemoved;
 201   static const char* myMsgGeneratedAndModified;
 202 };
 203
 204 #endif // _BRepTools_History_HeaderFile