0029358: Unifysamedomain is unable to merge faces with the same underlying surface
authormsv <msv@opencascade.com>
Tue, 26 Dec 2017 09:14:32 +0000 (12:14 +0300)
committerapn <apn@opencascade.com>
Tue, 26 Dec 2017 16:07:48 +0000 (19:07 +0300)
The documentation has been updated to avoid misunderstanding of algorithm behavior.

src/ShapeUpgrade/ShapeUpgrade_UnifySameDomain.hxx

index ea2db40..5511fa8 100644 (file)
@@ -1,4 +1,4 @@
-//-Copyright: Open CASCADE 2014
+// Copyright: Open CASCADE 2014
 // Created on: 2012-06-09
 // Created by: jgv@ROLEX
 // Copyright (c) 2012-2014 OPEN CASCADE SAS
@@ -34,34 +34,58 @@ class TopoDS_Shape;
 class ShapeUpgrade_UnifySameDomain;
 DEFINE_STANDARD_HANDLE(ShapeUpgrade_UnifySameDomain, Standard_Transient)
 
-//! This tool tries to unify faces and edges of the shape which lies on the same geometry.
-//! Faces/edges considering as 'same-domain' if a group of neighbouring faces/edges lying on coincident surfaces/curves.
+//! This tool tries to unify faces and edges of the shape which lie on the same geometry.
+//! Faces/edges are considering as 'same-domain' if a group of neighbouring faces/edges
+//! are lying on coincident surfaces/curves.
 //! In this case these faces/edges can be unified into one face/edge.
-//! ShapeUpgrade_UnifySameDomain initialized by the shape and the next optional parameters:
+//! ShapeUpgrade_UnifySameDomain is initialized by a shape and the next optional parameters:
 //! UnifyFaces - tries to unify all possible faces
 //! UnifyEdges - tries to unify all possible edges
-//! ConcatBSplines - if this flag set to true then all neighbouring edges which lays 
-//! on the BSpline or Bezier curves with C1 continuity on their common vertices will be merged into one common edge 
-//! The output result of tool is an unified shape
+//! ConcatBSplines - if this flag is set to true then all neighbouring edges, which lay
+//! on BSpline or Bezier curves with C1 continuity on their common vertices,
+//! will be merged into one common edge.
+//!
+//! The input shape can be of any type containing faces or edges - compsolid, solid, shell, 
+//! wire, compound of any kind of shapes. The algorithm preserves the structure of compsolids,
+//! solids, shells and wires. E.g., if two shells have a common edge and the faces sharing
+//! this edge lie on the same surface the algorithm will not unify these faces, otherwise 
+//! the structure of shells would be broken. However, if such faces belong to different
+//! compounds of faces they will be unified.
+//! 
+//! The output result of the tool is the unified shape.
+//!
 //! All the modifications of initial shape are recorded during unifying.
 //! Methods History are intended to: <br>
-//! - set a place holder for the history of the changing of the sub-shapes of
+//! - set a place holder for the history of modifications of sub-shapes of
 //!   the initial shape; <br>
 //! - get the collected history. <br>
 //! The algorithm provides a place holder for the history and collects the
 //! history by default.
-//! To avoid collecting of the history the place holder should be set to the null handle.
+//! To avoid collecting of the history the place holder should be set to null handle.
 class ShapeUpgrade_UnifySameDomain : public Standard_Transient
 {
 
 public:
-  //! empty constructor
+  //! Empty constructor
   Standard_EXPORT ShapeUpgrade_UnifySameDomain();
   
-  Standard_EXPORT ShapeUpgrade_UnifySameDomain(const TopoDS_Shape& aShape, const Standard_Boolean UnifyEdges = Standard_True, const Standard_Boolean UnifyFaces = Standard_True, const Standard_Boolean ConcatBSplines = Standard_False);
+  //! Constructor defining input shape and necessary flags.
+  //! It does not perform unification.
+  Standard_EXPORT ShapeUpgrade_UnifySameDomain
+                   (const TopoDS_Shape& aShape, 
+                    const Standard_Boolean UnifyEdges = Standard_True,
+                    const Standard_Boolean UnifyFaces = Standard_True,
+                    const Standard_Boolean ConcatBSplines = Standard_False);
   
-  //! Initializes with a shape
-  Standard_EXPORT void Initialize (const TopoDS_Shape& aShape, const Standard_Boolean UnifyEdges = Standard_True, const Standard_Boolean UnifyFaces = Standard_True, const Standard_Boolean ConcatBSplines = Standard_False);
+  //! Initializes with a shape and necessary flags.
+  //! It does not perform unification.
+  //! If you intend to nullify the History place holder do it after
+  //! initialization.
+  Standard_EXPORT void Initialize
+                   (const TopoDS_Shape& aShape,
+                    const Standard_Boolean UnifyEdges = Standard_True,
+                    const Standard_Boolean UnifyFaces = Standard_True,
+                    const Standard_Boolean ConcatBSplines = Standard_False);
   
   //! Sets the flag defining whether it is allowed to create
   //! internal edges inside merged faces in the case of non-manifold
@@ -69,16 +93,16 @@ public:
   //! is forbidden. Default value is false.
   Standard_EXPORT void AllowInternalEdges (const Standard_Boolean theValue);
 
-  //! Sets the shape for avoid merging of the faces in given places.
+  //! Sets the shape for avoid merging of the faces/edges.
   //! This shape can be vertex or edge.
-  //! If shape is vertex it forbids merging of connected edges.
-  //! If shape is edge it forbids merging of connected faces.
+  //! If the shape is a vertex it forbids merging of connected edges.
+  //! If the shape is a edge it forbids merging of connected faces.
+  //! This method can be called several times to keep several shapes.
   Standard_EXPORT void KeepShape(const TopoDS_Shape& theShape);
 
-  //! Sets the map of shapes for avoid merging of the faces in given places
-  //! These shapes can be vertexes or edges.
-  //! If shape is vertex it forbids merging of connected edges.
-  //! If shape is edge it forbids merging of connected faces.
+  //! Sets the map of shapes for avoid merging of the faces/edges.
+  //! It allows passing a ready to use map instead of calling many times
+  //! the method KeepShape.
   Standard_EXPORT void KeepShapes(const TopTools_MapOfShape& theShapes);
 
   //! Sets the flag defining the behavior of the algorithm regarding 
@@ -87,19 +111,21 @@ public:
   //! modified during modification process. Default value is true.
   Standard_EXPORT void SetSafeInputMode(Standard_Boolean theValue);
 
-  //! Sets the linear tolerance. Default value is Precision::Confusion().
+  //! Sets the linear tolerance. It plays the role of chord error when
+  //! taking decision about merging of shapes. Default value is Precision::Confusion().
   void SetLinearTolerance(const Standard_Real theValue)
   {
     myLinTol = theValue;
   }
 
-  //! Sets the angular tolerance. Default value is Precision::Angular().
+  //! Sets the angular tolerance. If two shapes form a connection angle greater than 
+  //! this value they will not be merged. Default value is Precision::Angular().
   void SetAngularTolerance(const Standard_Real theValue)
   {
     myAngTol = theValue;
   }
 
-  //! Builds the resulting shape
+  //! Performs unification and builds the resulting shape.
   Standard_EXPORT void Build();
   
   //! Gives the resulting shape
@@ -124,12 +150,12 @@ public:
 
 protected:
 
-  //! this method makes if possible a common face from each
+  //! This method makes if possible a common face from each
   //! group of faces lying on coincident surfaces
   Standard_EXPORT void UnifyFaces();
 
-  //! this method makes if possible a common edge from each
-  //! group of edges connecting common couple of faces
+  //! This method makes if possible a common edge from each
+  //! group of smothly connected edges, which are common for the same couple of faces
   Standard_EXPORT void UnifyEdges();
 
   void IntUnifyFaces(const TopoDS_Shape& theInpShape,
@@ -155,10 +181,4 @@ private:
   Handle(BRepTools_History) myHistory; //!< The history.
 };
 
-
-
-
-
-
-
 #endif // _ShapeUpgrade_UnifySameDomain_HeaderFile