EIC code displayed by LXR master/​include/​opencascade/​BOPAlgo_MakePeriodic.hxx	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-01-18 10:03:04

 // Created on: 2018-03-16
 // Created by: Eugeny MALTCHIKOV
 // Copyright (c) 2018 OPEN CASCADE SAS
 //
 // This file is part of Open CASCADE Technology software library.
 //
 // This library is free software; you can redistribute it and/or modify it under
 // the terms of the GNU Lesser General Public License version 2.1 as published
 // by the Free Software Foundation, with special exception defined in the file
 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
 // distribution for complete text of the license and disclaimer of any warranty.
 //
 // Alternatively, this file may be used under the terms of Open CASCADE
 // commercial license or contractual agreement.
 
 #ifndef _BOPAlgo_MakePeriodic_HeaderFile
 #define _BOPAlgo_MakePeriodic_HeaderFile
 
 #include <Standard.hxx>
 #include <Standard_DefineAlloc.hxx>
 #include <Standard_Handle.hxx>
 
 #include <BOPAlgo_Options.hxx>
 #include <BRepTools_History.hxx>
 #include <Standard_Boolean.hxx>
 #include <TopoDS_Shape.hxx>
 #include <TopTools_DataMapOfShapeShape.hxx>
 
 //! BOPAlgo_MakePeriodic is the tool for making an arbitrary shape periodic
 //! in 3D space in specified directions.
 //!
 //! Periodicity of the shape means that the shape can be repeated in any
 //! periodic direction any number of times without creation of the new
 //! geometry or splits.
 //!
 //! The idea is to make the shape look identical on the opposite sides of the
 //! periodic directions, so when translating the copy of a shape on the period
 //! there will be no coinciding parts of different dimensions.
 //!
 //! If necessary the algorithm will trim the shape to fit it into the
 //! requested period by splitting it by the planes limiting the shape's
 //! requested period.
 //!
 //! For making the shape periodic in certain direction the algorithm performs
 //! the following steps:
 //! * Creates the copy of the shape and moves it on the period into negative
 //!   side of the requested direction;
 //! * Splits the negative side of the shape by the moved copy, ensuring copying
 //!   of the geometry from positive side to negative;
 //! * Creates the copy of the shape (with already split negative side) and moves
 //!   it on the period into the positive side of the requested direction;
 //! * Splits the positive side of the shape by the moved copy, ensuring copying
 //!   of the geometry from negative side to positive.
 //!
 //! The algorithm also associates the identical (or twin) shapes located
 //! on the opposite sides of the result shape.
 //! Using the *GetTwins()* method it is possible to get the twin shapes from
 //! the opposite sides.
 //!
 //! Algorithm also provides the methods to repeat the periodic shape in
 //! periodic directions. The subsequent repetitions are performed on the
 //! repeated shape, thus repeating the shape two times in X direction will
 //! create result in three shapes (original plus two copies).
 //! Single subsequent repetition will result already in 6 shapes.
 //! The repetitions can be cleared and started over.
 //!
 //! The algorithm supports History of shapes modifications, thus
 //! it is possible to track how the shape has been changed to make it periodic
 //! and what new shapes have been created during repetitions.
 //!
 //! The algorithm supports the parallel processing mode, which allows faster
 //! completion of the operations.
 //!
 //! The algorithm supports the Error/Warning system and returns the following alerts:
 //! - *BOPAlgo_AlertNoPeriodicityRequired* - Error alert is given if no periodicity
 //!                                          has been requested in any direction;
 //! - *BOPAlgo_AlertUnableToTrim* - Error alert is given if the trimming of the shape
 //!                                 for fitting it into requested period has failed;
 //! - *BOPAlgo_AlertUnableToMakeIdentical* - Error alert is given if splitting of the
 //!                                          shape by its moved copies has failed;
 //! - *BOPAlgo_AlertUnableToRepeat* - Warning alert is given if the gluing of the repeated
 //!                                   shapes has failed.
 //!
 //! Example of usage of the algorithm:
 //! ~~~~
 //! TopoDS_Shape aShape = ...;                 // The shape to make periodic
 //! Standard_Boolean bMakeXPeriodic = ...;     // Flag for making or not the shape periodic in X direction
 //! Standard_Real aXPeriod = ...;              // X period for the shape
 //! Standard_Boolean isXTrimmed = ...;         // Flag defining whether it is necessary to trimming
 //!                                            // the shape to fit to X period
 //! Standard_Real aXFirst = ...;               // Start of the X period
 //!                                            // (really necessary only if the trimming is requested)
 //! Standard_Boolean bRunParallel = ...;       // Parallel processing mode or single
 //!
 //! BOPAlgo_MakePeriodic aPeriodicityMaker;                   // Periodicity maker
 //! aPeriodicityMaker.SetShape(aShape);                       // Set the shape
 //! aPeriodicityMaker.MakeXPeriodic(bMakePeriodic, aXPeriod); // Making the shape periodic in X direction
 //! aPeriodicityMaker.SetTrimmed(isXTrimmed, aXFirst);        // Trim the shape to fit X period
 //! aPeriodicityMaker.SetRunParallel(bRunParallel);           // Set the parallel processing mode
 //! aPeriodicityMaker.Perform();                              // Performing the operation
 //!
 //! if (aPeriodicityMaker.HasErrors())                        // Check for the errors
 //! {
 //!   // errors treatment
 //!   Standard_SStream aSStream;
 //!   aPeriodicityMaker.DumpErrors(aSStream);
 //!   return;
 //! }
 //! if (aPeriodicityMaker.HasWarnings())                      // Check for the warnings
 //! {
 //!   // warnings treatment
 //!   Standard_SStream aSStream;
 //!   aPeriodicityMaker.DumpWarnings(aSStream);
 //! }
 //! const TopoDS_Shape& aPeriodicShape = aPeriodicityMaker.Shape(); // Result periodic shape
 //!
 //!
 //! aPeriodicityMaker.XRepeat(2);                                    // Making repetitions
 //! const TopoDS_Shape& aRepeat = aPeriodicityMaker.RepeatedShape(); // Getting the repeated shape
 //! aPeriodicityMaker.ClearRepetitions();                            // Clearing the repetitions
 //! ~~~~
 //!
 class BOPAlgo_MakePeriodic : public BOPAlgo_Options
 {
 public:
 
   DEFINE_STANDARD_ALLOC
 
 public: //! @name Constructor
 
   //! Empty constructor
   BOPAlgo_MakePeriodic() : BOPAlgo_Options()
   {
     myRepeatPeriod[0] = myRepeatPeriod[1] = myRepeatPeriod[2] = 0.0;
   }
 
 
 public: //! @name Setting the shape to make it periodic
 
   //! Sets the shape to make it periodic.
   //! @param theShape [in] The shape to make periodic.
   void SetShape(const TopoDS_Shape& theShape)
   {
     myInputShape = theShape;
   }
 
 
 public: //! @name Definition of the structure to keep all periodicity parameters
 
   //! Structure to keep all periodicity parameters:
   struct PeriodicityParams
   {
     PeriodicityParams()
     {
       Clear();
     }
 
     //! Returns all previously set parameters to default values
     void Clear()
     {
       myPeriodic[0] = myPeriodic[1] = myPeriodic[2] = Standard_False;
       myPeriod[0] = myPeriod[1] = myPeriod[2] = 0.0;
       myIsTrimmed[0] = myIsTrimmed[1] = myIsTrimmed[2] = Standard_True;
       myPeriodFirst[0] = myPeriodFirst[1] = myPeriodFirst[2] = 0.0;
     }
 
     Standard_Boolean myPeriodic[3];  //!< Array of flags defining whether the shape should be
                                      //! periodic in XYZ directions
     Standard_Real myPeriod[3];       //!< Array of XYZ period values. Defining the period for any
                                      //! direction the corresponding flag for that direction in
                                      //! myPeriodic should be set to true
     Standard_Boolean myIsTrimmed[3]; //!< Array of flags defining whether the input shape has to be
                                      //! trimmed to fit the required period in the required direction
     Standard_Real myPeriodFirst[3];  //!< Array of start parameters of the XYZ periods: required for trimming
   };
 
 
 public: //! @name Setters/Getters for periodicity parameters structure
 
   //! Sets the periodicity parameters.
   //! @param theParams [in] Periodicity parameters
   void SetPeriodicityParameters(const PeriodicityParams& theParams)
   {
     myPeriodicityParams = theParams;
   }
 
   const PeriodicityParams& PeriodicityParameters() const
   {
     return myPeriodicityParams;
   }
 
 
 public: //! @name Methods for setting/getting periodicity info using ID as a direction
 
   //! Sets the flag to make the shape periodic in specified direction:
   //! - 0 - X direction;
   //! - 1 - Y direction;
   //! - 2 - Z direction.
   //!
   //! @param theDirectionID [in] The direction's ID;
   //! @param theIsPeriodic [in] Flag defining periodicity in given direction;
   //! @param thePeriod [in] Required period in given direction.
   void MakePeriodic(const Standard_Integer theDirectionID,
                     const Standard_Boolean theIsPeriodic,
                     const Standard_Real thePeriod = 0.0)
   {
     Standard_Integer id = ToDirectionID(theDirectionID);
     myPeriodicityParams.myPeriodic[id] = theIsPeriodic;
     myPeriodicityParams.myPeriod[id] = theIsPeriodic ? thePeriod : 0.0;
   }
 
   //! Returns the info about Periodicity of the shape in specified direction.
   //! @param theDirectionID [in] The direction's ID.
   Standard_Boolean IsPeriodic(const Standard_Integer theDirectionID) const
   {
     return myPeriodicityParams.myPeriodic[ToDirectionID(theDirectionID)];
   }
 
   //! Returns the Period of the shape in specified direction.
   //! @param theDirectionID [in] The direction's ID.
   Standard_Real Period(const Standard_Integer theDirectionID) const
   {
     Standard_Integer id = ToDirectionID(theDirectionID);
     return myPeriodicityParams.myPeriodic[id] ? myPeriodicityParams.myPeriod[id] : 0.0;
   }
 
 
 public: //! @name Named methods for setting/getting info about shape's periodicity
 
   //! Sets the flag to make the shape periodic in X direction.
   //! @param theIsPeriodic [in] Flag defining periodicity in X direction;
   //! @param thePeriod [in] Required period in X direction.
   void MakeXPeriodic(const Standard_Boolean theIsPeriodic,
                      const Standard_Real thePeriod = 0.0)
   {
     MakePeriodic(0, theIsPeriodic, thePeriod);
   }
 
   //! Returns the info about periodicity of the shape in X direction.
   Standard_Boolean IsXPeriodic() const { return IsPeriodic(0); }
 
   //! Returns the XPeriod of the shape
   Standard_Real XPeriod() const { return Period(0); }
 
   //! Sets the flag to make the shape periodic in Y direction.
   //! @param theIsPeriodic [in] Flag defining periodicity in Y direction;
   //! @param thePeriod [in] Required period in Y direction.
   void MakeYPeriodic(const Standard_Boolean theIsPeriodic,
                      const Standard_Real thePeriod = 0.0)
   {
     MakePeriodic(1, theIsPeriodic, thePeriod);
   }
 
   //! Returns the info about periodicity of the shape in Y direction.
   Standard_Boolean IsYPeriodic() const { return IsPeriodic(1); }
 
   //! Returns the YPeriod of the shape.
   Standard_Real YPeriod() const { return Period(1); }
 
   //! Sets the flag to make the shape periodic in Z direction.
   //! @param theIsPeriodic [in] Flag defining periodicity in Z direction;
   //! @param thePeriod [in] Required period in Z direction.
   void MakeZPeriodic(const Standard_Boolean theIsPeriodic,
                      const Standard_Real thePeriod = 0.0)
   {
     MakePeriodic(2, theIsPeriodic, thePeriod);
   }
 
   //! Returns the info about periodicity of the shape in Z direction.
   Standard_Boolean IsZPeriodic() const { return IsPeriodic(2); }
 
   //! Returns the ZPeriod of the shape.
   Standard_Real ZPeriod() const { return Period(2); }
 
 
 public: //! @name Methods for setting/getting trimming info taking Direction ID as a parameter
 
   //! Defines whether the input shape is already trimmed in specified direction
   //! to fit the period in this direction.
   //! Direction is defined by an ID:
   //! - 0 - X direction;
   //! - 1 - Y direction;
   //! - 2 - Z direction.
   //!
   //! If the shape is not trimmed it is required to set the first parameter
   //! of the period in that direction.
   //! The algorithm will make the shape fit into the period.
   //!
   //! Before calling this method, the shape has to be set to be periodic in this direction.
   //!
   //! @param theDirectionID [in] The direction's ID;
   //! @param theIsTrimmed [in] The flag defining trimming of the shape in given direction;
   //! @param theFirst [in] The first periodic parameter in the given direction.
   void SetTrimmed(const Standard_Integer theDirectionID,
                   const Standard_Boolean theIsTrimmed,
                   const Standard_Real theFirst = 0.0)
   {
     Standard_Integer id = ToDirectionID(theDirectionID);
     if (IsPeriodic(id))
     {
       myPeriodicityParams.myIsTrimmed[id] = theIsTrimmed;
       myPeriodicityParams.myPeriodFirst[id] = !theIsTrimmed ? theFirst : 0.0;
     }
   }
 
   //! Returns whether the input shape was trimmed in the specified direction.
   //! @param theDirectionID [in] The direction's ID.
   Standard_Boolean IsInputTrimmed(const Standard_Integer theDirectionID) const
   {
     return myPeriodicityParams.myIsTrimmed[ToDirectionID(theDirectionID)];
   }
 
   //! Returns the first periodic parameter in the specified direction.
   //! @param theDirectionID [in] The direction's ID.
   Standard_Real PeriodFirst(const Standard_Integer theDirectionID) const
   {
     Standard_Integer id = ToDirectionID(theDirectionID);
     return !myPeriodicityParams.myIsTrimmed[id] ? myPeriodicityParams.myPeriodFirst[id] : 0.0;
   }
 
 
 public: //! @name Named methods for setting/getting trimming info
 
   //! Defines whether the input shape is already trimmed in X direction
   //! to fit the X period. If the shape is not trimmed it is required
   //! to set the first parameter for the X period.
   //! The algorithm will make the shape fit into the period.
   //!
   //! Before calling this method, the shape has to be set to be periodic in this direction.
   //!
   //! @param theIsTrimmed [in] Flag defining whether the shape is already trimmed
   //!                          in X direction to fit the X period;
   //! @param theFirst [in] The first X periodic parameter.
   void SetXTrimmed(const Standard_Boolean theIsTrimmed,
                    const Standard_Boolean theFirst = 0.0)
   {
     SetTrimmed(0, theIsTrimmed, theFirst);
   }
 
   //! Returns whether the input shape was already trimmed for X period.
   Standard_Boolean IsInputXTrimmed() const
   {
     return IsInputTrimmed(0);
   }
 
   //! Returns the first parameter for the X period.
   Standard_Real XPeriodFirst() const
   {
     return PeriodFirst(0);
   }
 
   //! Defines whether the input shape is already trimmed in Y direction
   //! to fit the Y period. If the shape is not trimmed it is required
   //! to set the first parameter for the Y period.
   //! The algorithm will make the shape fit into the period.
   //!
   //! Before calling this method, the shape has to be set to be periodic in this direction.
   //!
   //! @param theIsTrimmed [in] Flag defining whether the shape is already trimmed
   //!                          in Y direction to fit the Y period;
   //! @param theFirst [in] The first Y periodic parameter.
   void SetYTrimmed(const Standard_Boolean theIsTrimmed,
                    const Standard_Boolean theFirst = 0.0)
   {
     SetTrimmed(1, theIsTrimmed, theFirst);
   }
 
   //! Returns whether the input shape was already trimmed for Y period.
   Standard_Boolean IsInputYTrimmed() const
   {
     return IsInputTrimmed(1);
   }
 
   //! Returns the first parameter for the Y period.
   Standard_Real YPeriodFirst() const
   {
     return PeriodFirst(1);
   }
 
   //! Defines whether the input shape is already trimmed in Z direction
   //! to fit the Z period. If the shape is not trimmed it is required
   //! to set the first parameter for the Z period.
   //! The algorithm will make the shape fit into the period.
   //!
   //! Before calling this method, the shape has to be set to be periodic in this direction.
   //!
   //! @param theIsTrimmed [in] Flag defining whether the shape is already trimmed
   //!                          in Z direction to fit the Z period;
   //! @param theFirst [in] The first Z periodic parameter.
   void SetZTrimmed(const Standard_Boolean theIsTrimmed,
                    const Standard_Boolean theFirst = 0.0)
   {
     SetTrimmed(2, theIsTrimmed, theFirst);
   }
 
   //! Returns whether the input shape was already trimmed for Z period.
   Standard_Boolean IsInputZTrimmed() const
   {
     return IsInputTrimmed(2);
   }
 
   //! Returns the first parameter for the Z period.
   Standard_Real ZPeriodFirst() const
   {
     return PeriodFirst(2);
   }
 
 public: //! @name Performing  the operation
 
   //! Makes the shape periodic in necessary directions
   Standard_EXPORT void Perform();
 
 
 public: //! @name Using the algorithm to repeat the shape
 
   //! Performs repetition of the shape in specified direction
   //! required number of times.
   //! Negative value of times means that the repetition should
   //! be perform in negative direction.
   //! Makes the repeated shape a base for following repetitions.
   //!
   //! @param theDirectionID [in] The direction's ID;
   //! @param theTimes [in] Requested number of repetitions.
   Standard_EXPORT const TopoDS_Shape& RepeatShape(const Standard_Integer theDirectionID,
                                                   const Standard_Integer theTimes);
 
   //! Repeats the shape in X direction specified number of times.
   //! Negative value of times means that the repetition should be
   //! perform in negative X direction.
   //! Makes the repeated shape a base for following repetitions.
   //!
   //! @param theTimes [in] Requested number of repetitions.
   const TopoDS_Shape& XRepeat(const Standard_Integer theTimes)
   {
     return RepeatShape(0, theTimes);
   }
 
   //! Repeats the shape in Y direction specified number of times.
   //! Negative value of times means that the repetition should be
   //! perform in negative Y direction.
   //! Makes the repeated shape a base for following repetitions.
   //!
   //! @param theTimes [in] Requested number of repetitions.
   const TopoDS_Shape& YRepeat(const Standard_Integer theTimes)
   {
     return RepeatShape(1, theTimes);
   }
 
   //! Repeats the shape in Z direction specified number of times.
   //! Negative value of times means that the repetition should be
   //! perform in negative Z direction.
   //! Makes the repeated shape a base for following repetitions.
   //!
   //! @param theTimes [in] Requested number of repetitions.
   const TopoDS_Shape& ZRepeat(const Standard_Integer theTimes)
   {
     return RepeatShape(2, theTimes);
   }
 
 
 public: //! @name Starting the repetitions over
 
   //! Returns the repeated shape
   const TopoDS_Shape& RepeatedShape() const { return myRepeatedShape; }
 
   //! Clears all performed repetitions.
   //! The next repetition will be performed on the base shape.
   void ClearRepetitions()
   {
     myRepeatPeriod[0] = myRepeatPeriod[1] = myRepeatPeriod[2] = 0.0;
     myRepeatedShape.Nullify();
     myRepeatedTwins.Clear();
     if (!myHistory.IsNull())
     {
       myHistory->Clear();
       if (!mySplitHistory.IsNull())
         myHistory->Merge(mySplitHistory);
     }
   }
 
 public: //! @name Obtaining the result shape
 
   //! Returns the resulting periodic shape
   const TopoDS_Shape& Shape() const { return myShape; }
 
 
 public: //! @name Getting the identical shapes
 
   //! Returns the identical shapes for the given shape located
   //! on the opposite periodic side.
   //! Returns empty list in case the shape has no twin.
   //!
   //! @param theS [in] Shape to get the twins for.
   const TopTools_ListOfShape& GetTwins(const TopoDS_Shape& theS) const
   {
     static TopTools_ListOfShape empty;
     const TopTools_ListOfShape* aTwins =
       myRepeatedTwins.IsEmpty() ? myTwins.Seek(theS) : myRepeatedTwins.Seek(theS);
     return (aTwins ? *aTwins : empty);
   }
 
 
 public: //! @name Getting the History of the algorithm
 
   //! Returns the History of the algorithm
   const Handle(BRepTools_History)& History() const
   {
     return myHistory;
   }
 
 public: //! @name Clearing the algorithm from previous runs
 
   //! Clears the algorithm from previous runs
   void Clear()
   {
     BOPAlgo_Options::Clear();
     myPeriodicityParams.Clear();
     myShape.Nullify();
     if (!mySplitHistory.IsNull())
       mySplitHistory->Clear();
     if (!myHistory.IsNull())
       myHistory->Clear();
 
     ClearRepetitions();
   }
 
 
 public: //! @name Conversion of the integer to ID of periodic direction
 
   //! Converts the integer to ID of periodic direction
   static Standard_Integer ToDirectionID(const Standard_Integer theDirectionID)
   {
     return Abs(theDirectionID % 3);
   }
 
 
 protected: //! @name Protected methods performing the operation
 
   //! Checks the validity of input data
   Standard_EXPORT void CheckData();
 
   //! Trims the shape to fit to the periodic bounds
   Standard_EXPORT void Trim();
 
   //! Makes the shape identical on opposite sides
   Standard_EXPORT void MakeIdentical();
 
   //! Splits the negative side of the shape with the geometry
   //! located on the positive side copying the geometry from
   //! positive side to the negative.
   Standard_EXPORT void SplitNegative();
 
   //! Splits the positive side of the shape with the geometry
   //! located on the negative side of the shape.
   //! Ensures that the geometries on the opposite sides will
   //! be identical.
   //! Associates the identical opposite sub-shapes.
   Standard_EXPORT void SplitPositive();
 
   //! Splits the shape by the given tools, copying the geometry of coinciding
   //! parts from the given tools to the split shape.
   //! @param theTools [in] The tools to split the shape and take the geometry
   //!                      for coinciding parts.
   //! @param theSplitShapeHistory [out] The history of shape split
   //! @param theSplitToolsHistory [out] The history of tools modifications during the split
   Standard_EXPORT void SplitShape(const TopTools_ListOfShape& theTools,
                                   Handle(BRepTools_History) theSplitShapeHistory = NULL,
                                   Handle(BRepTools_History) theSplitToolsHistory = NULL);
 
   //! Updates the map of twins after periodic shape repetition.
   //! @param theTranslationHistory [in] The history of translation of the periodic shape.
   //! @param theGluingHistory [in] The history of gluing of the repeated shapes.
   Standard_EXPORT void UpdateTwins(const BRepTools_History& theTranslationHistory,
                                    const BRepTools_History& theGluingHistory);
 
 
 protected: //! @name Fields
 
   // Inputs
   TopoDS_Shape myInputShape;         //!< Input shape to make periodic
 
   PeriodicityParams myPeriodicityParams; //!< Periodicity parameters
 
   // Results
   TopoDS_Shape myShape;                //!< Resulting periodic shape (base for repetitions)
   TopoDS_Shape myRepeatedShape;        //!< Resulting shape after making repetitions of the base
   Standard_Real myRepeatPeriod[3];     //!< XYZ repeat period
   TopTools_DataMapOfShapeListOfShape myRepeatedTwins; //!< Map of associations of the identical sub-shapes
                                                       //! after repetition of the periodic shape
 
   // Twins
   TopTools_DataMapOfShapeListOfShape myTwins; //!< Map of associations of the identical sub-shapes
                                               //! located on the opposite sides of the shape
 
   // History
   Handle(BRepTools_History) mySplitHistory;  //!< Split history - history of shapes modification
                                              //! after the split for making the shape periodic
   Handle(BRepTools_History) myHistory;       //!< Final history of shapes modifications
                                              //! (to include the history of shape repetition)
 
 };
 
 #endif // _BOPAlgo_MakePeriodic_HeaderFile

This page was automatically generated by the 2.3.7 LXR engine. The LXR team