From: Vera Sdobnova Date: Thu, 1 Oct 2020 12:34:55 +0000 (+0300) Subject: 0027191: Documentation - redesign of information architecture -- revision (user guides) X-Git-Tag: V7_5_0_beta~13 X-Git-Url: http://git.dev.opencascade.org/gitweb/?a=commitdiff_plain;h=e6c8fcfed4845eef3e08754cb2e9b222e6363f42;p=occt-copy.git 0027191: Documentation - redesign of information architecture -- revision (user guides) Revision of User Guides - Changes in User Guides Section to correspond with OCCT Overview structure: Mesh became a direct subsection of User Guides (it was a part of Modeling Algorithms). TObj is included into OCAF. - Changes in User Guides – Modeling Algorithms section: Fillets and Chamfers, Offsets, Drafts, Pipes and Evolved shapes, Sewing, Features, 3D Model Defeaturing, 3D Model Periodicity, Object Modification are moved into The Topology API section. - Changes in User Guides – Modeling Data section: Naming shapes, sub-shapes, their orientation and state section is renamed to Shape content. Shape Location is moved into Shape content section. Storage of Shapes is moved into BRep Format section of Specification. Lists and Maps of Shapes subsection is moved into Topology - Exploration of Topological Data Structures. - Some pictures in User Guides (Foundation Classes, Modeling Data, Modeling Algorithms) and Tutorial are updated to improve quality and correct mistakes. --- diff --git a/dox/FILES_HTML.txt b/dox/FILES_HTML.txt index 46e89cb7a2..5fbca28ed3 100644 --- a/dox/FILES_HTML.txt +++ b/dox/FILES_HTML.txt @@ -33,13 +33,13 @@ user_guides/user_guides.md user_guides/foundation_classes/foundation_classes.md user_guides/modeling_data/modeling_data.md user_guides/modeling_algos/modeling_algos.md +user_guides/mesh/mesh.md user_guides/shape_healing/shape_healing.md user_guides/visualization/visualization.md user_guides/iges/iges.md user_guides/step/step.md user_guides/xde/xde.md user_guides/ocaf/ocaf.md -user_guides/tobj/tobj.md user_guides/draw_test_harness/draw_test_harness.md user_guides/inspector/inspector.md user_guides/vis/vis.md diff --git a/dox/FILES_PDF.txt b/dox/FILES_PDF.txt index a26c0f7464..c7850a7006 100644 --- a/dox/FILES_PDF.txt +++ b/dox/FILES_PDF.txt @@ -4,21 +4,22 @@ # Empty spaces are allowed. # Strings starting with '#' are treated as comments and ignored. -specification/brep_wp/brep_wp.md +tutorial/tutorial.md + +upgrade/upgrade.md + user_guides/foundation_classes/foundation_classes.md -user_guides/iges/iges.md user_guides/modeling_data/modeling_data.md user_guides/modeling_algos/modeling_algos.md -specification/boolean_operations/boolean_operations.md -user_guides/shape_healing/shape_healing.md +user_guides/mesh/mesh.md user_guides/ocaf/ocaf.md -user_guides/step/step.md -user_guides/draw_test_harness/draw_test_harness.md -user_guides/inspector/inspector.md -user_guides/tobj/tobj.md user_guides/visualization/visualization.md -user_guides/xde/xde.md user_guides/vis/vis.md +user_guides/iges/iges.md +user_guides/step/step.md +user_guides/xde/xde.md +user_guides/inspector/inspector.md +user_guides/draw_test_harness/draw_test_harness.md contribution/contribution_workflow/contribution_workflow.md contribution/documentation/documentation.md @@ -26,7 +27,6 @@ contribution/coding_rules.md contribution/git_guide/git_guide.md contribution/tests/tests.md -upgrade/upgrade.md +specification/boolean_operations/boolean_operations.md +specification/brep_format.md specification/pbr_math.md - -tutorial/tutorial.md diff --git a/dox/introduction/introduction.md b/dox/introduction/introduction.md index e1b9c43f4a..d2df5501b6 100644 --- a/dox/introduction/introduction.md +++ b/dox/introduction/introduction.md @@ -281,7 +281,7 @@ Each sub-domain of Shape Healing has its own scope of functionality: | Customization | Modifies the shape representation to fit specific needs. | The shape is not modified, only the mathematical form of its internal representation is changed. | | Processing | Mechanism of shape modification via a user-editable resource file. | | -For more details, refer to @ref occt_shg "Shape Healing User's guide". +For more details, refer to @ref occt_user_guides__shape_healing "Shape Healing User's guide". @subsection intro_overview_ocaf Application Framework diff --git a/dox/user_guides/draw_test_harness/draw_test_harness.md b/dox/user_guides/draw_test_harness/draw_test_harness.md index 5104cfe955..255352e87c 100644 --- a/dox/user_guides/draw_test_harness/draw_test_harness.md +++ b/dox/user_guides/draw_test_harness/draw_test_harness.md @@ -6979,7 +6979,7 @@ sr is a shape COMPOUND FORWARD Free Modified The new algorithm of Boolean operations avoids a large number of weak points and limitations presented in the old Boolean operation algorithm. It also provides wider range of options and diagnostics. -The algorithms of Boolean component are fully described in the @ref specification__boolean_1 "Boolean Operations" of boolean operation user guide. +The algorithms of Boolean component are fully described in the @ref specification__boolean_operations "Boolean Operations" of boolean operation user guide. For the Draw commands to perform operations in Boolean component, read the dedicated section @ref occt_draw_bop "Boolean operations commands" @@ -11733,4 +11733,3 @@ The procedure consists in defining the system variables and using the *pload* co Draw[]> set env(CSF_MyDrawPluginDefaults) /users/test Draw[]> pload -MyDrawPlugin ALL ~~~~ - diff --git a/dox/user_guides/foundation_classes/foundation_classes.md b/dox/user_guides/foundation_classes/foundation_classes.md index 9a144a9080..45844ef7eb 100644 --- a/dox/user_guides/foundation_classes/foundation_classes.md +++ b/dox/user_guides/foundation_classes/foundation_classes.md @@ -7,7 +7,6 @@ Foundation Classes {#occt_user_guides__foundation_classes} This manual explains how to use Open CASCADE Technology (**OCCT**) Foundation Classes. It provides basic documentation on foundation classes. -For advanced information on foundation classes and their applications, see our E-learning & Training offerings. Foundation Classes provide a variety of general-purpose services such as automated dynamic memory management (manipulation of objects by handle), collections, exception handling, genericity by down-casting and plug-in creation. diff --git a/dox/user_guides/foundation_classes/images/foundation_classes_image004.png b/dox/user_guides/foundation_classes/images/foundation_classes_image004.png index 6d00d38d4a..9dfe2ac521 100644 Binary files a/dox/user_guides/foundation_classes/images/foundation_classes_image004.png and b/dox/user_guides/foundation_classes/images/foundation_classes_image004.png differ diff --git a/dox/user_guides/foundation_classes/images/foundation_classes_image005.png b/dox/user_guides/foundation_classes/images/foundation_classes_image005.png index 6ad4232577..a11addb082 100644 Binary files a/dox/user_guides/foundation_classes/images/foundation_classes_image005.png and b/dox/user_guides/foundation_classes/images/foundation_classes_image005.png differ diff --git a/dox/user_guides/foundation_classes/images/foundation_classes_image006.png b/dox/user_guides/foundation_classes/images/foundation_classes_image006.png index 6e920054ac..a57756d0a8 100644 Binary files a/dox/user_guides/foundation_classes/images/foundation_classes_image006.png and b/dox/user_guides/foundation_classes/images/foundation_classes_image006.png differ diff --git a/dox/user_guides/iges/iges.md b/dox/user_guides/iges/iges.md index 76654aa7d9..3e09800e06 100644 --- a/dox/user_guides/iges/iges.md +++ b/dox/user_guides/iges/iges.md @@ -1,4 +1,4 @@ -IGES Support {#occt_user_guides__iges} +IGES Translator {#occt_user_guides__iges} ================== @tableofcontents @@ -15,7 +15,7 @@ Other kinds of data such as colors and names can be read or written with the hel * an IGES entity is an entity in the IGES normal sense. * a root entity is the highest level entity of any given type, e.g. type 144 for surfaces and type 186 for solids. Roots are not referenced by other entities. -This manual mainly explains how to convert an IGES file to an Open CASCADE Technology (**OCCT**) shape and vice versa. It provides basic documentation on conversion. For advanced information on conversion, see our E-learning & Training offerings. +This manual mainly explains how to convert an IGES file to an Open CASCADE Technology (**OCCT**) shape and vice versa. It provides basic documentation on conversion. IGES files produced in accordance with IGES standard versions up to and including version 5.3 can be read. IGES files that are produced by this interface conform to IGES version 5.3 (Initial Graphics Exchange Specification, IGES 5.3. ANS US PRO/IPO-100-1996). diff --git a/dox/user_guides/mesh/images/modeling_algos_image056.png b/dox/user_guides/mesh/images/modeling_algos_image056.png new file mode 100644 index 0000000000..f1f724ee37 Binary files /dev/null and b/dox/user_guides/mesh/images/modeling_algos_image056.png differ diff --git a/dox/user_guides/mesh/images/modeling_algos_image057.png b/dox/user_guides/mesh/images/modeling_algos_image057.png new file mode 100644 index 0000000000..450b8c6f12 Binary files /dev/null and b/dox/user_guides/mesh/images/modeling_algos_image057.png differ diff --git a/dox/user_guides/mesh/images/modeling_algos_mesh_001.svg b/dox/user_guides/mesh/images/modeling_algos_mesh_001.svg new file mode 100644 index 0000000000..a02e84db7f --- /dev/null +++ b/dox/user_guides/mesh/images/modeling_algos_mesh_001.svg @@ -0,0 +1,263 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +BRepMesh Workflow + + + + + + +Create Model Data Structure + + + + + + + +IMeshData_Model : [1] + + + + + + +Discretize Edges 3D & 2D Curves + + + + + + + +IMeshData_Model : [1] + + + + + + +Heal Discrete Model + + + + +Preprocess Discrete Model + + + + +Discretize Faces + + + + +Postprocess Discrete Model + + + +TopoDS_Shape + +Mesh + + + +Meshing Parameters : IMeshTools_Parameters + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dox/user_guides/mesh/images/modeling_algos_mesh_002.svg b/dox/user_guides/mesh/images/modeling_algos_mesh_002.svg new file mode 100644 index 0000000000..c3d8ae5d69 --- /dev/null +++ b/dox/user_guides/mesh/images/modeling_algos_mesh_002.svg @@ -0,0 +1,715 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +IMeshTools_Parameters + + + +Deflection : Real [1] + +Angle : Real [1] + +MinSize : Real [1] + +Relative : Boolean [1] + +InParallel : Boolean [1] + +InternalVerticesMode : +Boolean [1] + +ControlSurfaceDeflection : +Boolean [1] + +CleanModel : Boolean [1] + + + + + + + + +IMeshTools_Context + + + +myParameters : IMeshTools_Parameters [1] + +myModel : [1] + +myModelBuilder : IMeshTools_ModelBuilder [1] + +myEdgeDiscret : IMeshTools_ModelAlgo [1] + +myModelHealer : IMeshTools_ModelAlgo [1] + +myPreProcessor : IMeshTools_ModelAlgo [1] + +myFaceDiscret : IMeshTools_ModelAlgo [1] + +myPostProcessor : IMeshTools_ModelAlgo [1] + +GetParameters() + +ChangeParameters() + +BuildModel() + +GetModel() + +DiscretizeEdges() + +HealModel() + +PreProcessModel() + +DiscretizeFaces() + +PostProcessModel() + +SetModelBuilder() + +GetModelBuilder() + +SetEdgeDiscret() + +GetEdgeDiscret() + +SetModelHealer() + +GetModelHealer() + +SetPreProcessor() + +GetPreProcessor() + +SetFaceDiscret() + +GetFaceDiscret() + +SetPostProcessor() + +GetPostProcessor() + +Clean() + + + + + + + + +IMeshTools_ModelBuilder + + + +Perform(TopoDS_Shape : , +IMeshTools_Parameter : ) + + + + + + + + +IMeshTools_ModelAlgo + + + +Perform(IMeshData_Model : , +IMeshTools_Parameters : ) + + + + + + + + +IMeshData_Model + + + +GetMaxSize() + +FacesNb() + +AddFace() + +GetFace() + +EdgesNb() + +AddEdge() + +GetEdge() + + + + + + + + +IMeshTools_MeshBuilder + + + +SetContext() + +GetContext() + +Perform() + + + + + + + + +<<use>> + + + + + +<<use>> + + + + + +<<use>> + + + +caches +context[1] +parameters[1] + + + + + +caches +context[1] +builder[1] + + + + + +caches +context[1] +model[1] + + + + + +caches +context[1] +algo[5] + + + + + +<<use>> + + + + + diff --git a/dox/user_guides/mesh/images/modeling_algos_mesh_003.svg b/dox/user_guides/mesh/images/modeling_algos_mesh_003.svg new file mode 100644 index 0000000000..78b14e96bb --- /dev/null +++ b/dox/user_guides/mesh/images/modeling_algos_mesh_003.svg @@ -0,0 +1,5085 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + IMeshData_Shape + + + + myShape : + TopoDS_Shape [1] + + SetShape() + + GetShape() + + + + + + + + + IMeshData_Model + + + + GetMaxSize() + + FacesNb() + + AddFace() + + GetFace() + + EdgesNb() + + AddEdge() + + GetEdge() + + + + + + + + + IMeshData_TessellatedShape + + + + SetDeflection() + + GetDeflection() + + + + + + + + + IMeshData_Edge + + + + GetEdge() + + SetCurve() + + GetCurve() + + PCurvesNb() + + AddPCurve() + + GetPCurve() + + Clear() + + IsFree() + + GetAngularDeflection() + + SetAngularDeflection() + + SetSameParam() + + GetSameParam() + + SetSameRange() + + GetSameRange() + + SetDegenerated() + + GetDegenerated() + + + + + + + + + IMeshData_Wire + + + + GetWire() + + EdgesNb() + + AddEdge() + + GetEdge() + + GetEdgeOrientation() + + + + + + + + + IMeshData_Face + + + + GetFace() + + WiresNb() + + AddWire() + + GetWire() + + GetSurface() + + IsValid() + + + + + + + + + IMeshData_StatusOwner + + + + IsEqual() + + IsSet() + + SetStatus() + + UnsetStatus() + + GetStatusMask() + + + + + + + + + IMeshData_ParametersList + + + + GetParameter() + + ParametersNb() + + Clear() + + + + + + + + + IMeshData_Curve + + + + InsertPoint() + + AddPoint() + + GetPoint() + + RemovePoint() + + + + + + + + + IMeshData_PCurve + + + + InsertPoint() + + AddPoint() + + GetPoint() + + RemovePoint() + + GetIndex() + + IsForward() + + IsInternal() + + GetOrientation() + + GetFace() + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + has + edge[1] + curve[1] + + + + + has + edge[1] + pcurve[*] + + + + + references + pcurve[1] + face[1] + + + + has + face[1] + wire[1..*] + + + + has + wire[1] + edge[1..*] + + + + + has + model[1] + edge[*] + + + + + has + model[1] + face[*] + + + + + + + + + + diff --git a/dox/user_guides/mesh/images/modeling_algos_mesh_004.svg b/dox/user_guides/mesh/images/modeling_algos_mesh_004.svg new file mode 100644 index 0000000000..2ca4c42e08 --- /dev/null +++ b/dox/user_guides/mesh/images/modeling_algos_mesh_004.svg @@ -0,0 +1,820 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +IMeshTools_MeshAlgoFactory + + + +GetAlgo(GeomAbs_SurfaceType : , +IMeshTools_Parameters : ) + + + + + + + + +BRepMesh_MeshAlgoFactory + + + + + + +Triangulation Algo + + + + + +IMeshTools_MeshAlgo + + + +Perform(IMeshData_Face : , +IMeshTools_Parameters : ) + + + + + + + + +BRepMesh_DelaunayBaseMeshAlgo + + + + + + +BRepMesh_DelaunayNodeInsertionMeshAlgo +<RangeSplitter> + + + + + + +BRepMesh_DelaunayDeflectionControlMeshAlgo +<RangeSplitter> + + + + + + +BRepMesh_SweepLineMeshAlgo + + + + + + +BRepMesh_SweepLineNodeInsertionMeshAlgo +<RangeSplitter> + + + + + + +RangeSplitter + + + + + +BRepMesh_DefaultRangeSplitter + + + + + + +BRepMesh_ConeRangeSplitter + + + + + + +BRepMesh_CylinderRangeSplitter + + + + + + +BRepMesh_SphereRangeSplitter + + + + + + +BRepMesh_UVParamRangeSplitter + + + + + + +BRepMesh_TorusRangeSplitter + + + + + + +BRepMesh_NURBSRangeSplitter + + + + + + +BRepMesh_BoundaryParamsRangeSplitter + + + + + + + + + + + +BRepMesh_BaseMeshAlgo + + + + + + +BRepMesh_DataStructureOfDelaun + + + + + + +BRepMesh_NodeInsertionMeshAlgo +<RangeSplitter, BaseClass> + + + + + + + + + + + +BRepMesh_FaceDiscret + + + + + +RangeSplitter->T, BaseClass->BRepMesh_SweepLineMeshAlgo + + + + +RangeSplitter->RangeSplitter + + + + + + + + + + + + + + + + + + + +RangeSplitter->RangeSplitter + + + + + + + + + +RangeSplitter->T, BaseClass->BRepMesh_DelaunayBaseMeshAlgo + + + + + + + + + + + + + + + + + + + + + + + + + + + +RangeSplitter->RangeSplitter + + + +<<use>> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +RangeSplitter->RangeSplitter + + + + +RangeSplitter->RangeSplitter + + + + +RangeSplitter->RangeSplitter + + + +<<use>> + + + +<<use>> + + + + + + + + + + + +<<use>> + + + + + + + + + +RangeSplitter->T, BaseClass->BRepMesh_DelaunayBaseMeshAlgo + + + + +RangeSplitter->T, BaseClass->BRepMesh_SweepLineMeshAlgo + + + + + + + + + + + + + + + + + + + + diff --git a/dox/user_guides/mesh/mesh.md b/dox/user_guides/mesh/mesh.md new file mode 100644 index 0000000000..43976aae64 --- /dev/null +++ b/dox/user_guides/mesh/mesh.md @@ -0,0 +1,228 @@ +Mesh {#occt_user_guides__mesh} +========================= + +@tableofcontents + +@section occt_modalg_11_1 Mesh presentations + +In addition to support of exact geometrical representation of 3D objects Open CASCADE Technology provides functionality to work with tessellated representations of objects in form of meshes. + +Open CASCADE Technology mesh functionality provides: +- data structures to store surface mesh data associated to shapes, and some basic algorithms to handle these data +- data structures and algorithms to build surface triangular mesh from *BRep* objects (shapes). +- tools to extend 3D visualization capabilities of Open CASCADE Technology with displaying meshes along with associated pre- and post-processor data. + +Open CASCADE Technology includes two mesh converters: +- VRML converter translates Open CASCADE shapes to VRML 1.0 files (Virtual Reality Modeling Language). Open CASCADE shapes may be translated in two representations: shaded or wireframe. A shaded representation present shapes as sets of triangles computed by a mesh algorithm while a wireframe representation present shapes as sets of curves. +- STL converter translates Open CASCADE shapes to STL files. STL (STtereoLithography) format is widely used for rapid prototyping. + +Open CASCADE SAS also offers Advanced Mesh Products: +- Open CASCADE Mesh Framework (OMF) +- Express Mesh + +Besides, we can efficiently help you in the fields of surface and volume meshing algorithms, mesh optimization algorithms etc. If you require a qualified advice about meshing algorithms, do not hesitate to benefit from the expertise of our team in that domain. + +The projects dealing with numerical simulation can benefit from using SALOME - an Open Source Framework for CAE with CAD data interfaces, generic Pre- and Post- F.E. processors and API for integrating F.E. solvers. + +Learn more about SALOME platform on https://www.salome-platform.org + +@section occt_modalg_11_2 Meshing algorithm + +The algorithm of shape triangulation is provided by the functionality of *BRepMesh_IncrementalMesh* class, which adds a triangulation of the shape to its topological data structure. This triangulation is used to visualize the shape in shaded mode. + +~~~~~ +#include +#include +#include + +Standard_Boolean meshing_explicit_parameters() +{ + const Standard_Real aRadius = 10.0; + const Standard_Real aHeight = 25.0; + BRepPrimAPI_MakeCylinder aCylinder(aRadius, aHeight); + TopoDS_Shape aShape = aCylinder.Shape(); + + const Standard_Real aLinearDeflection = 0.01; + const Standard_Real anAngularDeflection = 0.5; + BRepMesh_IncrementalMesh aMesher (aShape, aLinearDeflection, Standard_False, anAngularDeflection, Standard_True); + const Standard_Integer aStatus = aMesher.GetStatusFlags(); + return !aStatus; +} + +Standard_Boolean meshing_imeshtools_parameters() +{ + const Standard_Real aRadius = 10.0; + const Standard_Real aHeight = 25.0; + BRepPrimAPI_MakeCylinder aCylinder(aRadius, aHeight); + TopoDS_Shape aShape = aCylinder.Shape(); + + IMeshTools_Parameters aMeshParams; + aMeshParams.Deflection = 0.01; + aMeshParams.Angle = 0.5; + aMeshParams.Relative = Standard_False; + aMeshParams.InParallel = Standard_True; + aMeshParams.MinSize = Precision::Confusion(); + aMeshParams.InternalVerticesMode = Standard_True; + aMeshParams.ControlSurfaceDeflection = Standard_True; + + BRepMesh_IncrementalMesh aMesher (aShape, aMeshParams); + const Standard_Integer aStatus = aMesher.GetStatusFlags(); + return !aStatus; +} +~~~~~ + +The default meshing algorithm *BRepMesh_IncrementalMesh* has two major options to define triangulation -- linear and angular deflections. + +At the first step all edges from a face are discretized according to the specified parameters. + +At the second step, the faces are tessellated. Linear deflection limits the distance between a curve and its tessellation, whereas angular deflection limits the angle between subsequent segments in a polyline. + +@figure{/user_guides/mesh/images/modeling_algos_image056.png,"Deflection parameters of BRepMesh_IncrementalMesh algorithm",420} + +There are additional options to control behavior of the meshing of face interior: *DeflectionInterior* and *AngleInterior*. *DeflectionInterior* limits the distance between triangles and the face interior. *AngleInterior* (used for tessellation of B-spline faces only) limits the angle between normals (N1, N2 and N3 in the picture) in the nodes of every link of the triangle. There is an exception for the links along the face boundary edges, "Angular Deflection" is used for them during edges discretization. + +@figure{/user_guides/mesh/images/modeling_algos_image057.png,"Linear and angular interior deflections",420} + +Note that if a given value of linear deflection is less than shape tolerance then the algorithm will skip this value and will take into account the shape tolerance. + +The application should provide deflection parameters to compute a satisfactory mesh. Angular deflection is relatively simple and allows using a default value (12-20 degrees). Linear deflection has an absolute meaning and the application should provide the correct value for its models. Giving small values may result in a too huge mesh (consuming a lot of memory, which results in a long computation time and slow rendering) while big values result in an ugly mesh. + +For an application working in dimensions known in advance it can be reasonable to use the absolute linear deflection for all models. This provides meshes according to metrics and precision used in the application (for example, it it is known that the model will be stored in meters, 0.004 m is enough for most tasks). + +However, an application that imports models created in other applications may not use the same deflection for all models. Note that actually this is an abnormal situation and this application is probably just a viewer for CAD models with dimensions varying by an order of magnitude. This problem can be solved by introducing the concept of a relative linear deflection with some LOD (level of detail). The level of detail is a scale factor for absolute deflection, which is applied to model dimensions. + +Meshing covers a shape with a triangular mesh. Other than hidden line removal, you can use meshing to transfer the shape to another tool: a manufacturing tool, a shading algorithm, a finite element algorithm, or a collision algorithm. + +You can obtain information on the shape by first exploring it. To access triangulation of a face in the shape later, use *BRepTool::Triangulation*. To access a polygon, which is the approximation of an edge of the face, use *BRepTool::PolygonOnTriangulation*. + +@section occt_modalg_11_3 BRepMesh Architecture +@subsection occt_modalg_11_3_1 Goals + +The main goals of the chosen architecture are: + * Remove tight connections between data structures, auxiliary tools and algorithms to create an extensible solution, easy for maintenance and improvements; + * Separate the code among several functional units responsible for specific operation for the sake of simplification of debugging and readability; + * Introduce new data structures enabling the possibility to manipulate a discrete model of a particular entity (edge, wire, face) in order to perform computations locally instead of processing the entire model; + * Implement a new triangulation algorithm replacing the existing functionality that contains overcomplicated solutions that need to be moved to the upper level. In addition, provide the possibility to change the algorithm depending on surface type (initially to speed up meshing of planes). + +@subsection occt_modalg_11_3_2 General workflow +@figure{/user_guides/mesh/images/modeling_algos_mesh_001.svg,"General workflow of BRepMesh component",500} + +Generally, the workflow of the component can be divided into six parts: + * **Creation of model data structure**: source *TopoDS_Shape* passed to algorithm is analyzed and exploded into faces and edges. The reflection corresponding to each topological entity is created in the data model. Note that underlying algorithms use the data model as input and access it via a common interface which allows creating a custom data model with necessary dependencies between particular entities (see the paragraph "Data model interface"); + * **Discretize edges 3D & 2D curves**: 3D curve as well as an associated set of 2D curves of each model edge is discretized in order to create a coherent skeleton used as a base in face meshing process. If an edge of the source shape already contains polygonal data which suits the specified parameters, it is extracted from the shape and stored in the model as is. Each edge is processed separately, the adjacency is not taken into account; + * **Heal discrete model**: the source *TopoDS_Shape* can contain problems, such as open wires or self-intersections, introduced during design, exchange or modification of model. In addition, some problems like self-intersections can be introduced by roughly discretized edges. This stage is responsible for analysis of a discrete model in order to detect and repair problems or to refuse further processing of a model part in case if a problem cannot be solved; + * **Preprocess discrete model**: defines actions specific to the implemented approach to be performed before meshing of faces. By default, this operation iterates over model faces, checks the consistency of existing triangulations and cleans topological faces and adjacent edges from polygonal data in case of inconsistency or marks a face of the discrete model as not required for the computation; + * **Discretize faces**: represents the core part performing mesh generation for a particular face based on 2D discrete data. This operation caches polygonal data associated with face edges in the data model for further processing and stores the generated mesh to *TopoDS_Face*; + * **Postprocess discrete model**: defines actions specific for the implemented approach to be performed after meshing of faces. By default, this operation stores polygonal data obtained at the previous stage to *TopoDS_Edge* objects of the source model. + +@subsection occt_modalg_11_3_3 Common interfaces +The component structure contains two units: IMeshData (see Data model interface) and IMeshTools, defining common interfaces for the data model and algorithmic tools correspondingly. Class *IMeshTools_Context* represents a connector between these units. The context class caches the data model as well as the tools corresponding to each of six stages of the workflow mentioned above and provides methods to call the corresponding tool safely (designed similarly to *IntTools_Context* in order to keep consistency with OCCT core tools). All stages, except for the first one, use the data model as input and perform a specific action on the entire structure. Thus, API class *IMeshTools_ModelAlgo* is defined in order to unify the interface of tools manipulating the data model. Each tool supposed to process the data model should inherit this interface enabling the possibility to cache it in context. In contrast to others, the model builder interface is defined by another class *IMeshTools_ModelBuilder* due to a different meaning of the stage. The entry point starting the entire workflow is represented by *IMeshTools_MeshBuilder*. + +The default implementation of *IMeshTools_Context* is given in *BRepMesh_Context* class initializing the context by instances of default algorithmic tools. + +The factory interface *IMeshTools_MeshAlgoFactory* gives the possibility to change the triangulation algorithm for a specific surface. The factory returns an instance of the triangulation algorithm via *IMeshTools_MeshAlgo* interface depending on the type of surface passed as parameter. It is supposed to be used at the face discretization stage. + +The default implementation of AlgoFactory is given in *BRepMesh_MeshAlgoFactory* returning algorithms of different complexity chosen according to the passed surface type. In its turn, it is used as the initializer of *BRepMesh_FaceDiscret* algorithm representing the starter of face discretization stage. + +@figure{/user_guides/mesh/images/modeling_algos_mesh_002.svg,"Interface describing entry point to meshing workflow",500} + +Remaining interfaces describe auxiliary tools: + * *IMeshTools_CurveTessellator*: provides a common interface to the algorithms responsible for creation of discrete polygons on 3D and 2D curves as well as tools for extraction of existing polygons from *TopoDS_Edge* allowing to obtain discrete points and the corresponding parameters on curve regardless of the implementation details (see examples of usage of derived classes *BRepMesh_CurveTessellator*, *BRepMesh_EdgeTessellationExtractor* in *BRepMesh_EdgeDiscret*); + * *IMeshTools_ShapeExplorer*: the last two interfaces represent visitor design pattern and are intended to separate iteration over elements of topological shape (edges and faces) from the operations performed on a particular element; + * *IMeshTools_ShapeVisitor*: provides a common interface for operations on edges and faces of the target topological shape. It can be used in couple with *IMeshTools_ShapeExplorer*. The default implementation available in *BRepMesh_ShapeVisitor* performs initialization of the data model. The advantage of such approach is that the implementation of *IMeshTools_ShapeVisitor* can be changed according to the specific data model whereas the shape explorer implementation remains the same. + +@subsection occt_modalg_11_3_4 Create model data structure +The data structures intended to keep discrete and temporary data required by underlying algorithms are created at the first stage of the meshing procedure. Generally, the model represents dependencies between entities of the source topological shape suitable for the target task. + +#### Data model interface +Unit IMeshData provides common interfaces specifying the data model API used on different stages of the entire workflow. Dependencies and references of the designed interfaces are given in the figure below. A specific interface implementation depends on the target application which allows the developer to implement different models and use custom low-level data structures, e.g. different collections, either NCollection or STL. *IMeshData_Shape* is used as the base class for all data structures and tools keeping the topological shape in order to avoid possible copy-paste. + +The default implementation of interfaces is given in BRepMeshData unit. The main aim of the default data model is to provide features performing discretization of edges in a parallel mode. Thus, curve, pcurve and other classes are based on STL containers and smart-pointers as far as NCollection does not provide thread-safety for some cases (e.g. *NCollection_Sequence*). In addition, it closely reflects topology of the source shape, i.e. the number of edges in the data model is equal to the number of edges in the source model; each edge contains a set of pcurves associated with its adjacent faces which allows creation of discrete polygons for all pcurves or the 3D curve of a particular edge in a separate thread. + +**Advantages**: +In case of necessity, the data model (probably with algorithms for its processing) can be easily substituted by another implementation supporting another kind of dependencies between elements. + +An additional example of a different data model is the case when it is not required to create a mesh with discrete polygons synchronized between adjacent faces, i.e. in case of necessity to speed up creation of a rough per-face tessellation used for visualization or quick computation only (the approach used in *XDEDRAW_Props*). + +@figure{/user_guides/mesh/images/modeling_algos_mesh_003.svg,"Common API of data model",500} + +#### Collecting data model +At this stage the data model is filled by entities according to the topological structure of the source shape. A default implementation of the data model is given in BRepMeshData unit and represents the model as two sets: a set of edges and a set of faces. Each face consists of one or several wires, the first of which always represents the outer wire, while others are internal. In its turn, each wire depicts the ordered sequence of oriented edges. Each edge is characterized by a single 3D curve and zero (in case of free edge) or more 2D curves associated with faces adjacent to this edge. Both 3D and 2D curves represent a set of pairs point-parameter defined in 3D and 2D space of the reference face correspondingly. An additional difference between a curve and a pcurve is that the latter has a reference to the face it is defined for. + +Model filler algorithm is represented by *BRepMesh_ShapeVisitor* class creating the model as a reflection to topological shape with help of *BRepMesh_ShapeExplorer* performing iteration over edges and faces of the target shape. Note that the algorithm operates on a common interface of the data model and creates a structure without any knowledge about the implementation details and underlying data structures. The entry point to collecting functionality is *BRepMesh_ModelBuilder* class. + +@subsection occt_modalg_11_3_5 Discretize edges 3D & 2D curves +At this stage only the edges of the data model are considered. Each edge is processed separately (with the possibility to run processing in multiple threads). The edge is checked for existing polygonal data. In case if at least one representation exists and suits the meshing parameters, it is recuperated and used as reference data for tessellation of the whole set of pcurves as well as 3D curve assigned to the edge (see *BRepMesh_EdgeTessellationExtractor*). Otherwise, a new tessellation algorithm is created and used to generate the initial polygon (see *BRepMesh_CurveTessellator*) and the edge is marked as outdated. In addition, the model edge is updated by deflection as well as recomputed same range, same parameter and degeneracy parameters. See *BRepMesh_EdgeDiscret* for implementation details. + +IMeshData unit defines interface *IMeshData_ParametersListArrayAdaptor*, which is intended to adapt arbitrary data structures to the *NCollection_Array1* container API. This solution is made to use both *NCollection_Array1* and *IMeshData_Curve* as the source for *BRepMesh_EdgeParameterProvider* tool intended to generate a consistent parametrization taking into account the same parameter property. + +@subsection occt_modalg_11_3_6 Heal discrete model +In general, this stage represents a set of operations performed on the entire discrete model in order to resolve inconsistencies due to the problems caused by design, translation or rough discretization. A different sequence of operations can be performed depending on the target triangulation algorithm, e.g. there are different approaches to process self-intersections – either to amplify edges discretization by decreasing the target precision or to split links at the intersection points. At this stage the whole set of edges is considered in aggregate and their adjacency is taken into account. A default implementation of the model healer is given in *BRepMesh_ModelHealer* which performs the following actions: + * Iterates over model faces and checks their wires for consistency, i.e. whether the wires are closed and do not contain self-intersections. The data structures are designed free of collisions, thus it is possible to run processing in a parallel mode; + * Forcibly connects the ends of adjacent edges in the parametric space, closing gaps between possible disconnected parts. The aim of this operation is to create a correct discrete model defined relatively to the parametric space of the target face taking into account connectivity and tolerances of 3D space only. This means that no specific computations are made to determine U and V tolerance; + * Registers intersections on edges forming the face shape. Two solutions are possible in order to resolve self-intersection: + * Decrease deflection of a particular edge and update its discrete model. After that the workflow "intersection check – amplification" is repeated up to 5 times. As the result, target edges contain a finer tessellation and meshing continues or the face is marked by *IMeshData_SelfIntersectingWire* status and refused from further processing; + * Split target edges by intersection point and synchronize the updated polygon with curve and remaining pcurves associated to each edge. This operation presents a more robust solution comparing to the amplification procedure with a guaranteed result, but it is more difficult for implementation from the point of view of synchronization functionality. + +@subsection occt_modalg_11_3_7 Preprocess discrete model +This stage implements actions to be performed before meshing of faces. Depending on target goals it can be changed or omitted. By default, *BRepMesh_ModelPreProcessor* implements the functionality checking topological faces for consistency of existing triangulation, i.e.: consistency with the target deflection parameter; indices of nodes referenced by triangles do not exceed the number of nodes stored in a triangulation. If the face fails some checks, it is cleaned from triangulation and its adjacent edges are cleaned from existing polygons. This does not affect a discrete model and does not require any recomputation as the model keeps tessellations for the whole set of edges despite consistency of their polygons. + +@subsection occt_modalg_11_3_8 Discretize faces +Discretization of faces is the general part of meshing algorithm. At this stage edges tessellation data obtained and processed on previous steps is used to form contours of target faces and passed as input to the triangulation algorithm. Default implementation is provided by *BRepMesh_FaceDiscret* class which represents a starter for triangulation algorithm. It iterates over faces available in the data model, creates an instance of the triangulation algorithm according to the type of surface associated with each face via *IMeshTools_MeshAlgoFactory* and executes it. Each face is processed separately, thus it is possible to process faces in a parallel mode. The class diagram of face discretization is given in the figure below. + +@figure{/user_guides/mesh/images/modeling_algos_mesh_004.svg,"Class diagram of face discrete stage",300} + +In general, face meshing algorithms have the following structure: + * *BRepMesh_BaseMeshAlgo* implements *IMeshTools_MeshAlgo* interface and the base functionality for inherited algorithms. The main goal of this class is to initialize an instance of *BRepMesh_DataStructureOfDelaun* as well as auxiliary data structures suitable for nested algorithms using face model data passed as input parameter. Despite implementation of triangulation algorithm this structure is currently supposed as common for OCCT. However, the user is free to implement a custom algorithm and supporting data structure accessible via *IMeshTools_MeshAlgo* interface, e.g. to connect a 3-rd party meshing tool that does not support *TopoDS_Shape* out of box. For this, such structure provides the possibility to distribute connectors to various algorithms in the form of plugins; + * *BRepMesh_DelaunayBaseMeshAlgo* and *BRepMesh_SweepLineMeshAlgo* classes implement core meshing functionality operating directly on an instance of *BRepMesh_DataStructureOfDelaun*. The algorithms represent mesh generation tools adding new points from the data structure to the final mesh; + * *BRepMesh_NodeInsertionMeshAlgo* class represents a wrapper intended to extend the algorithm inherited from *BRepMesh_BaseMeshAlgo* to enable the functionality generating surface nodes and inserting them into the structure. On this level, an instance of the classification tool is created and can be used to accept-reject internal nodes. In addition, computations necessary for scaling UV coordinates of points relatively to the range specified for the corresponding direction are performed. As far as both triangulation algorithms work on static data provided by the structure, new nodes are added at the initialization stage. Surface nodes are generated by an auxiliary tool called range splitter and passed as template parameter (see Range splitter); + * Classes *BRepMesh_DelaunayNodeInsertionMeshAlgo* and *BRepMesh_SweepLineNodeInsertionMeshAlgo* implement algorithm-specific functionality related to addition of internal nodes supplementing functionality provided by *BRepMesh_NodeInsertionMeshAlgo*; + * *BRepMesh_DelaunayDeflectionControlMeshAlgo* extends functionality of *BRepMesh_DelaunayNodeInsertionMeshAlgo* by additional procedure controlling deflection of generated triangles. + + + + + +BRepMesh provides user a way to switch default triangulation algorithm to a custom one, either implemented by user or available worldwide. There are three base classes that can be currently used to integrate 3rd-party algorithms: + +* *BRepMesh_ConstrainedBaseMeshAlgo* base class for tools providing generation of triangulations with constraints requiring no common processing by BRepMesh; +* *BRepMesh_CustomBaseMeshAlgo* provides the entry point for generic algorithms without support of constraints and supposed for generation of base mesh only. Constraint edges are processed using standard functionality provided by the component itself upon background mesh produced by 3rd-party solver; +* *BRepMesh_CustomDelaunayBaseMeshAlgo* contains initialization part for tools used by BRepMesh for checks or optimizations using results of 3rd-party algorithm. + +Meshing algorithms could be provided by implemeting *IMeshTools_MeshAlgoFactory* with related interfaces and passing it to *BRepMesh_Context::SetFaceDiscret()*. OCCT comes with two base 2D meshing algorithms: *BRepMesh_MeshAlgoFactory* (used by default) and *BRepMesh_DelabellaMeshAlgoFactory*. + +The following example demonstrates how it could be done from *Draw* environment: + +~~~~~ +psphere s 10 + +### Default Algo ### +incmesh s 0.0001 -algo default + +### Delabella Algo ### +incmesh s 0.0001 -algo delabella +~~~~~ + +The code snippet below shows passing a custom mesh factory to BRepMesh_IncrementalMesh: + +~~~~~ +IMeshTools_Parameters aMeshParams; +Handle(IMeshTools_Context) aContext = new BRepMesh_Context(); +aContext->SetFaceDiscret (new BRepMesh_FaceDiscret (new BRepMesh_DelabellaMeshAlgoFactory())); + +BRepMesh_IncrementalMesh aMesher; +aMesher.SetShape (aShape); +aMesher.ChangeParameters() = aMeshParams; + +aMesher.Perform (aContext); +~~~~~ + +#### Range splitter +Range splitter tools provide functionality to generate internal surface nodes defined within the range computed using discrete model data. The base functionality is provided by *BRepMesh_DefaultRangeSplitter* which can be used without modifications in case of planar surface. The default splitter does not generate any internal node. + +*BRepMesh_ConeRangeSplitter*, *BRepMesh_CylinderRangeSplitter* and *BRepMesh_SphereRangeSplitter* are specializations of the default splitter intended for quick generation of internal nodes for the corresponding type of analytical surface. + +*BRepMesh_UVParamRangeSplitter* implements base functionality taking discretization points of face border into account for node generation. Its successors BRepMesh_TorusRangeSplitter and *BRepMesh_NURBSRangeSplitter* extend the base functionality for toroidal and NURBS surfaces correspondingly. + +@subsection occt_modalg_11_3_9 Postprocess discrete model +This stage implements actions to be performed after meshing of faces. Depending on target goals it can be changed or omitted. By default, *BRepMesh_ModelPostProcessor* commits polygonal data stored in the data model to *TopoDS_Edge*. \ No newline at end of file diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image003.png b/dox/user_guides/modeling_algos/images/modeling_algos_image003.png index d3ee059e52..6d51f6e72b 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image003.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image003.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image004.png b/dox/user_guides/modeling_algos/images/modeling_algos_image004.png index 6b371fb255..de827453c3 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image004.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image004.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image014.png b/dox/user_guides/modeling_algos/images/modeling_algos_image014.png index 42bf360518..2820ffa093 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image014.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image014.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image015.png b/dox/user_guides/modeling_algos/images/modeling_algos_image015.png index 7ff604a603..ea9bebb18d 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image015.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image015.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image016.png b/dox/user_guides/modeling_algos/images/modeling_algos_image016.png index 2e1367d331..919d1dcfe7 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image016.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image016.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image017.png b/dox/user_guides/modeling_algos/images/modeling_algos_image017.png index 88e0101e49..c56ae77fd2 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image017.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image017.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image021.png b/dox/user_guides/modeling_algos/images/modeling_algos_image021.png index d390c72d98..54bd1b6457 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image021.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image021.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image023.png b/dox/user_guides/modeling_algos/images/modeling_algos_image023.png index 505d403a5f..42061ea6d9 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image023.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image023.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image028.png b/dox/user_guides/modeling_algos/images/modeling_algos_image028.png index d93ccea447..072eb71bab 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image028.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image028.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image030.png b/dox/user_guides/modeling_algos/images/modeling_algos_image030.png index 7ce050d437..bd23d61bb9 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image030.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image030.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image035.png b/dox/user_guides/modeling_algos/images/modeling_algos_image035.png index df85effd0c..1a5f60f6b1 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image035.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image035.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image037.gif b/dox/user_guides/modeling_algos/images/modeling_algos_image037.gif new file mode 100644 index 0000000000..4693c9cbf0 Binary files /dev/null and b/dox/user_guides/modeling_algos/images/modeling_algos_image037.gif differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image040.png b/dox/user_guides/modeling_algos/images/modeling_algos_image040.png index 6a44f40111..b72cd4ce9b 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image040.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image040.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image041.png b/dox/user_guides/modeling_algos/images/modeling_algos_image041.png index 281438243a..263b4b3378 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image041.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image041.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image043.png b/dox/user_guides/modeling_algos/images/modeling_algos_image043.png index 31c47f92f7..504d71726c 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image043.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image043.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image045.png b/dox/user_guides/modeling_algos/images/modeling_algos_image045.png index 8ab7eba802..d9c5dfb7d2 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image045.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image045.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image047.png b/dox/user_guides/modeling_algos/images/modeling_algos_image047.png index 784681e85e..f0c0b1472f 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image047.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image047.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image048.png b/dox/user_guides/modeling_algos/images/modeling_algos_image048.png index 5f9a7369f4..a35fc4bd39 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image048.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image048.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image049.png b/dox/user_guides/modeling_algos/images/modeling_algos_image049.png index 746e721f0a..ec330cc88d 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image049.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image049.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image051.png b/dox/user_guides/modeling_algos/images/modeling_algos_image051.png index f52a14560c..c0eb80ee61 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image051.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image051.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image056.png b/dox/user_guides/modeling_algos/images/modeling_algos_image056.png deleted file mode 100644 index f1f724ee37..0000000000 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image056.png and /dev/null differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image057.png b/dox/user_guides/modeling_algos/images/modeling_algos_image057.png deleted file mode 100644 index 450b8c6f12..0000000000 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image057.png and /dev/null differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_image058.png b/dox/user_guides/modeling_algos/images/modeling_algos_image058.png index 6d96ab4d51..61179be280 100644 Binary files a/dox/user_guides/modeling_algos/images/modeling_algos_image058.png and b/dox/user_guides/modeling_algos/images/modeling_algos_image058.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_mesh_001.svg b/dox/user_guides/modeling_algos/images/modeling_algos_mesh_001.svg deleted file mode 100644 index a02e84db7f..0000000000 --- a/dox/user_guides/modeling_algos/images/modeling_algos_mesh_001.svg +++ /dev/null @@ -1,263 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -BRepMesh Workflow - - - - - - -Create Model Data Structure - - - - - - - -IMeshData_Model : [1] - - - - - - -Discretize Edges 3D & 2D Curves - - - - - - - -IMeshData_Model : [1] - - - - - - -Heal Discrete Model - - - - -Preprocess Discrete Model - - - - -Discretize Faces - - - - -Postprocess Discrete Model - - - -TopoDS_Shape - -Mesh - - - -Meshing Parameters : IMeshTools_Parameters - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_mesh_002.svg b/dox/user_guides/modeling_algos/images/modeling_algos_mesh_002.svg deleted file mode 100644 index c3d8ae5d69..0000000000 --- a/dox/user_guides/modeling_algos/images/modeling_algos_mesh_002.svg +++ /dev/null @@ -1,715 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -IMeshTools_Parameters - - - -Deflection : Real [1] - -Angle : Real [1] - -MinSize : Real [1] - -Relative : Boolean [1] - -InParallel : Boolean [1] - -InternalVerticesMode : -Boolean [1] - -ControlSurfaceDeflection : -Boolean [1] - -CleanModel : Boolean [1] - - - - - - - - -IMeshTools_Context - - - -myParameters : IMeshTools_Parameters [1] - -myModel : [1] - -myModelBuilder : IMeshTools_ModelBuilder [1] - -myEdgeDiscret : IMeshTools_ModelAlgo [1] - -myModelHealer : IMeshTools_ModelAlgo [1] - -myPreProcessor : IMeshTools_ModelAlgo [1] - -myFaceDiscret : IMeshTools_ModelAlgo [1] - -myPostProcessor : IMeshTools_ModelAlgo [1] - -GetParameters() - -ChangeParameters() - -BuildModel() - -GetModel() - -DiscretizeEdges() - -HealModel() - -PreProcessModel() - -DiscretizeFaces() - -PostProcessModel() - -SetModelBuilder() - -GetModelBuilder() - -SetEdgeDiscret() - -GetEdgeDiscret() - -SetModelHealer() - -GetModelHealer() - -SetPreProcessor() - -GetPreProcessor() - -SetFaceDiscret() - -GetFaceDiscret() - -SetPostProcessor() - -GetPostProcessor() - -Clean() - - - - - - - - -IMeshTools_ModelBuilder - - - -Perform(TopoDS_Shape : , -IMeshTools_Parameter : ) - - - - - - - - -IMeshTools_ModelAlgo - - - -Perform(IMeshData_Model : , -IMeshTools_Parameters : ) - - - - - - - - -IMeshData_Model - - - -GetMaxSize() - -FacesNb() - -AddFace() - -GetFace() - -EdgesNb() - -AddEdge() - -GetEdge() - - - - - - - - -IMeshTools_MeshBuilder - - - -SetContext() - -GetContext() - -Perform() - - - - - - - - -<<use>> - - - - - -<<use>> - - - - - -<<use>> - - - -caches -context[1] -parameters[1] - - - - - -caches -context[1] -builder[1] - - - - - -caches -context[1] -model[1] - - - - - -caches -context[1] -algo[5] - - - - - -<<use>> - - - - - diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_mesh_003.svg b/dox/user_guides/modeling_algos/images/modeling_algos_mesh_003.svg deleted file mode 100644 index 78b14e96bb..0000000000 --- a/dox/user_guides/modeling_algos/images/modeling_algos_mesh_003.svg +++ /dev/null @@ -1,5085 +0,0 @@ - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - IMeshData_Shape - - - - myShape : - TopoDS_Shape [1] - - SetShape() - - GetShape() - - - - - - - - - IMeshData_Model - - - - GetMaxSize() - - FacesNb() - - AddFace() - - GetFace() - - EdgesNb() - - AddEdge() - - GetEdge() - - - - - - - - - IMeshData_TessellatedShape - - - - SetDeflection() - - GetDeflection() - - - - - - - - - IMeshData_Edge - - - - GetEdge() - - SetCurve() - - GetCurve() - - PCurvesNb() - - AddPCurve() - - GetPCurve() - - Clear() - - IsFree() - - GetAngularDeflection() - - SetAngularDeflection() - - SetSameParam() - - GetSameParam() - - SetSameRange() - - GetSameRange() - - SetDegenerated() - - GetDegenerated() - - - - - - - - - IMeshData_Wire - - - - GetWire() - - EdgesNb() - - AddEdge() - - GetEdge() - - GetEdgeOrientation() - - - - - - - - - IMeshData_Face - - - - GetFace() - - WiresNb() - - AddWire() - - GetWire() - - GetSurface() - - IsValid() - - - - - - - - - IMeshData_StatusOwner - - - - IsEqual() - - IsSet() - - SetStatus() - - UnsetStatus() - - GetStatusMask() - - - - - - - - - IMeshData_ParametersList - - - - GetParameter() - - ParametersNb() - - Clear() - - - - - - - - - IMeshData_Curve - - - - InsertPoint() - - AddPoint() - - GetPoint() - - RemovePoint() - - - - - - - - - IMeshData_PCurve - - - - InsertPoint() - - AddPoint() - - GetPoint() - - RemovePoint() - - GetIndex() - - IsForward() - - IsInternal() - - GetOrientation() - - GetFace() - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - has - edge[1] - curve[1] - - - - - has - edge[1] - pcurve[*] - - - - - references - pcurve[1] - face[1] - - - - has - face[1] - wire[1..*] - - - - has - wire[1] - edge[1..*] - - - - - has - model[1] - edge[*] - - - - - has - model[1] - face[*] - - - - - - - - - - diff --git a/dox/user_guides/modeling_algos/images/modeling_algos_mesh_004.svg b/dox/user_guides/modeling_algos/images/modeling_algos_mesh_004.svg deleted file mode 100644 index 2ca4c42e08..0000000000 --- a/dox/user_guides/modeling_algos/images/modeling_algos_mesh_004.svg +++ /dev/null @@ -1,820 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -IMeshTools_MeshAlgoFactory - - - -GetAlgo(GeomAbs_SurfaceType : , -IMeshTools_Parameters : ) - - - - - - - - -BRepMesh_MeshAlgoFactory - - - - - - -Triangulation Algo - - - - - -IMeshTools_MeshAlgo - - - -Perform(IMeshData_Face : , -IMeshTools_Parameters : ) - - - - - - - - -BRepMesh_DelaunayBaseMeshAlgo - - - - - - -BRepMesh_DelaunayNodeInsertionMeshAlgo -<RangeSplitter> - - - - - - -BRepMesh_DelaunayDeflectionControlMeshAlgo -<RangeSplitter> - - - - - - -BRepMesh_SweepLineMeshAlgo - - - - - - -BRepMesh_SweepLineNodeInsertionMeshAlgo -<RangeSplitter> - - - - - - -RangeSplitter - - - - - -BRepMesh_DefaultRangeSplitter - - - - - - -BRepMesh_ConeRangeSplitter - - - - - - -BRepMesh_CylinderRangeSplitter - - - - - - -BRepMesh_SphereRangeSplitter - - - - - - -BRepMesh_UVParamRangeSplitter - - - - - - -BRepMesh_TorusRangeSplitter - - - - - - -BRepMesh_NURBSRangeSplitter - - - - - - -BRepMesh_BoundaryParamsRangeSplitter - - - - - - - - - - - -BRepMesh_BaseMeshAlgo - - - - - - -BRepMesh_DataStructureOfDelaun - - - - - - -BRepMesh_NodeInsertionMeshAlgo -<RangeSplitter, BaseClass> - - - - - - - - - - - -BRepMesh_FaceDiscret - - - - - -RangeSplitter->T, BaseClass->BRepMesh_SweepLineMeshAlgo - - - - -RangeSplitter->RangeSplitter - - - - - - - - - - - - - - - - - - - -RangeSplitter->RangeSplitter - - - - - - - - - -RangeSplitter->T, BaseClass->BRepMesh_DelaunayBaseMeshAlgo - - - - - - - - - - - - - - - - - - - - - - - - - - - -RangeSplitter->RangeSplitter - - - -<<use>> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -RangeSplitter->RangeSplitter - - - - -RangeSplitter->RangeSplitter - - - - -RangeSplitter->RangeSplitter - - - -<<use>> - - - -<<use>> - - - - - - - - - - - -<<use>> - - - - - - - - - -RangeSplitter->T, BaseClass->BRepMesh_DelaunayBaseMeshAlgo - - - - -RangeSplitter->T, BaseClass->BRepMesh_SweepLineMeshAlgo - - - - - - - - - - - - - - - - - - - - diff --git a/dox/user_guides/modeling_algos/images/modeling_data_image003.png b/dox/user_guides/modeling_algos/images/modeling_data_image003.png new file mode 100644 index 0000000000..593342d591 Binary files /dev/null and b/dox/user_guides/modeling_algos/images/modeling_data_image003.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_data_image014.png b/dox/user_guides/modeling_algos/images/modeling_data_image014.png new file mode 100644 index 0000000000..801244f8e0 Binary files /dev/null and b/dox/user_guides/modeling_algos/images/modeling_data_image014.png differ diff --git a/dox/user_guides/modeling_algos/images/modeling_data_image015.png b/dox/user_guides/modeling_algos/images/modeling_data_image015.png new file mode 100644 index 0000000000..6f98d72fe3 Binary files /dev/null and b/dox/user_guides/modeling_algos/images/modeling_data_image015.png differ diff --git a/dox/user_guides/modeling_algos/modeling_algos.md b/dox/user_guides/modeling_algos/modeling_algos.md index 20734055b0..b763132d32 100644 --- a/dox/user_guides/modeling_algos/modeling_algos.md +++ b/dox/user_guides/modeling_algos/modeling_algos.md @@ -5,7 +5,7 @@ Modeling Algorithms {#occt_user_guides__modeling_algos} @section occt_modalg_1 Introduction -This manual explains how to use the Modeling Algorithms. It provides basic documentation on modeling algorithms. For advanced information on Modeling Algorithms, see our E-learning & Training offerings. +This manual explains how to use the Modeling Algorithms. It provides basic documentation on modeling algorithms. The Modeling Algorithms module brings together a wide range of topological algorithms used in modeling. Along with these tools, you will find the geometric algorithms, which they call. @@ -28,7 +28,7 @@ The Intersections component is used to compute intersections between 2D or 3D ge The *Geom2dAPI_InterCurveCurve* class allows the evaluation of the intersection points (*gp_Pnt2d*) between two geometric curves (*Geom2d_Curve*) and the evaluation of the points of self-intersection of a curve. -@figure{/user_guides/modeling_algos/images/modeling_algos_image003.png,"Intersection and self-intersection of curves",420} +@figure{/user_guides/modeling_algos/images/modeling_algos_image003.png,"Intersection and self-intersection of curves",300} In both cases, the algorithm requires a value for the tolerance (Standard_Real) for the confusion between two points. The default tolerance value used in all constructors is *1.0e-6.* @@ -1050,836 +1050,463 @@ Handle(Geom_Curve) C3d = GeomAPI::To3d(C2d, Pln); ~~~~~ -@section occt_modalg_2_topo_tools Topological Tools - -Open CASCADE Technology topological tools provide algorithms to - * Create wires from edges; - * Create faces from wires; - * Compute state of the shape relatively other shape; - * Orient shapes in container; - * Create new shapes from the existing ones; - * Build PCurves of edges on the faces; - * Check the validity of the shapes; - * Take the point in the face; - * Get the normal direction for the face. +@section occt_modalg_3 Standard Topological Objects +The following standard topological objects can be created: + * Vertices; + * Edges; + * Faces; + * Wires; + * Polygonal wires; + * Shells; + * Solids. -@subsection occt_modalg_2_topo_tools_1 Creation of the faces from wireframe model +There are two root classes for their construction and modification: +* The deferred class *BRepBuilderAPI_MakeShape* is the root of all *BRepBuilderAPI* classes, which build shapes. It inherits from the class *BRepBuilderAPI_Command* and provides a field to store the constructed shape. +* The deferred class *BRepBuilderAPI_ModifyShape* is used as a root for the shape modifications. It inherits *BRepBuilderAPI_MakeShape* and implements the methods used to trace the history of all sub-shapes. -It is possible to create the planar faces from the arbitrary set of planar edges randomly located in 3D space. -This feature might be useful if you need for instance to restore the shape from the wireframe model: - - - - - -
@figure{/user_guides/modeling_algos/images/modeling_algos_image062.png,"Wireframe model",160}@figure{/user_guides/modeling_algos/images/modeling_algos_image063.png,"Faces of the model",160}
+@subsection occt_modalg_3_1 Vertex -To make the faces from edges it is, firstly, necessary to create planar wires from the given edges and than create planar faces from each wire. -The static methods *BOPAlgo_Tools::EdgesToWires* and *BOPAlgo_Tools::WiresToFaces* can be used for that: +*BRepBuilderAPI_MakeVertex* creates a new vertex from a 3D point from gp. ~~~~~ -TopoDS_Shape anEdges = ...; /* The input edges */ -Standard_Real anAngTol = 1.e-8; /* The angular tolerance for distinguishing the planes in which the wires are located */ -Standard_Boolean bShared = Standard_False; /* Defines whether the edges are shared or not */ -// -TopoDS_Shape aWires; /* resulting wires */ -Standard_Integer iErr = BOPAlgo_Tools::EdgesToWires(anEdges, aWires, bShared, anAngTol); -if (iErr) { - cout << "Error: Unable to build wires from given edges\n"; - return; -} -// -TopoDS_Shape aFaces; /* resulting faces */ -Standard_Boolean bDone = BOPAlgo_Tools::WiresToFaces(aWires, aFaces, anAngTol); -if (!bDone) { - cout << "Error: Unable to build faces from wires\n"; - return; -} +gp_Pnt P(0,0,10); +TopoDS_Vertex V = BRepBuilderAPI_MakeVertex(P); ~~~~~ -These methods can also be used separately: - * *BOPAlgo_Tools::EdgesToWires* allows creating planar wires from edges. -The input edges may be not shared, but the output wires will be sharing the coinciding vertices and edges. For this the intersection of the edges is performed. -Although, it is possible to skip the intersection stage (if the input edges are already shared) by passing the corresponding flag into the method. -The input edges are expected to be planar, but the method does not check it. Thus, if the input edges are not planar, the output wires will also be not planar. -In general, the output wires are non-manifold and may contain free vertices, as well as multi-connected vertices. - * *BOPAlgo_Tools::WiresToFaces* allows creating planar faces from the planar wires. -In general, the input wires are non-manifold and may be not closed, but should share the coinciding parts. -The wires located in the same plane and completely included into other wires will create holes in the faces built from outer wires: - - - - - - -
@figure{/user_guides/modeling_algos/images/modeling_algos_image064.png,"Wireframe model",160}@figure{/user_guides/modeling_algos/images/modeling_algos_image065.png,"Two faces (red face has a hole)",160}
+This class always creates a new vertex and has no other methods. +@subsection occt_modalg_3_2 Edge -@subsection occt_modalg_2_topo_tools_2 Classification of the shapes +@subsubsection occt_modalg_3_2_1 Basic edge construction method -The following methods allow classifying the different shapes relatively other shapes: - * The variety of the *BOPTools_AlgoTools::ComputState* methods classify the vertex/edge/face relatively solid; - * *BOPTools_AlgoTools::IsHole* classifies wire relatively face; - * *IntTools_Tools::ClassifyPointByFace* classifies point relatively face. +Use *BRepBuilderAPI_MakeEdge* to create from a curve and vertices. The basic method constructs an edge from a curve, two vertices, and two parameters. -@subsection occt_modalg_2_topo_tools_3 Orientation of the shapes in the container +~~~~~ +Handle(Geom_Curve) C = ...; // a curve +TopoDS_Vertex V1 = ...,V2 = ...;// two Vertices +Standard_Real p1 = ..., p2 = ..;// two parameters +TopoDS_Edge E = BRepBuilderAPI_MakeEdge(C,V1,V2,p1,p2); +~~~~~ -The following methods allow reorienting shapes in the containers: - * *BOPTools_AlgoTools::OrientEdgesOnWire* correctly orients edges on the wire; - * *BOPTools_AlgoTools::OrientFacesOnShell* correctly orients faces on the shell. +where C is the domain of the edge; V1 is the first vertex oriented FORWARD; V2 is the second vertex oriented REVERSED; p1 and p2 are the parameters for the vertices V1 and V2 on the curve. The default tolerance is associated with this edge. -@subsection occt_modalg_2_topo_tools_4 Making new shapes +@figure{/user_guides/modeling_algos/images/modeling_algos_image022.png,"Basic Edge Construction",220} -The following methods allow creating new shapes from the existing ones: - * The variety of the *BOPTools_AlgoTools::MakeNewVertex* creates the new vertices from other vertices and edges; - * *BOPTools_AlgoTools::MakeSplitEdge* splits the edge by the given parameters. +The following rules apply to the arguments: -@subsection occt_modalg_2_topo_tools_5 Building PCurves +**The curve** + * Must not be a Null Handle. + * If the curve is a trimmed curve, the basis curve is used. -The following methods allow building PCurves of edges on faces: - * *BOPTools_AlgoTools::BuildPCurveForEdgeOnFace* computes PCurve for the edge on the face; - * *BOPTools_AlgoTools::BuildPCurveForEdgeOnPlane* and *BOPTools_AlgoTools::BuildPCurveForEdgesOnPlane* allow building PCurves for edges on the planar face; - * *BOPTools_AlgoTools::AttachExistingPCurve* takes PCurve on the face from one edge and attach this PCurve to other edge coinciding with the first one. +**The vertices** + * Can be null shapes. When V1 or V2 is Null the edge is open in the corresponding direction and the corresponding parameter p1 or p2 must be infinite (i.e p1 is RealFirst(), p2 is RealLast()). + * Must be different vertices if they have different 3d locations and identical vertices if they have the same 3d location (identical vertices are used when the curve is closed). -@subsection occt_modalg_2_topo_tools_6 Checking the validity of the shapes +**The parameters** + * Must be increasing and in the range of the curve, i.e.: -The following methods allow checking the validity of the shapes: - * *BOPTools_AlgoTools::IsMicroEdge* detects the small edges; - * *BOPTools_AlgoTools::ComputeTolerance* computes the correct tolerance of the edge on the face; - * *BOPTools_AlgoTools::CorrectShapeTolerances* and *BOPTools_AlgoTools::CorrectTolerances* allow correcting the tolerances of the sub-shapes. - * *BRepLib::FindValidRange* finds a range of 3d curve of the edge not covered by tolerance spheres of vertices. - -@subsection occt_modalg_2_topo_tools_7 Taking a point inside the face +~~~~~ + C->FirstParameter() <= p1 < p2 <= C->LastParameter() +~~~~~ + + * If the parameters are decreasing, the Vertices are switched, i.e. V2 becomes V1 and V1 becomes V2. + * On a periodic curve the parameters p1 and p2 are adjusted by adding or subtracting the period to obtain p1 in the range of the curve and p2 in the range p1 < p2 <= p1+ Period. So on a parametric curve p2 can be greater than the second parameter, see the figure below. + * Can be infinite but the corresponding vertex must be Null (see above). + * The distance between the Vertex 3d location and the point evaluated on the curve with the parameter must be lower than the default precision. -The following methods allow taking a point located inside the face: - * The variety of the *BOPTools_AlgoTools3D::PointNearEdge* allows getting a point inside the face located near the edge; - * *BOPTools_AlgoTools3D::PointInFace* allows getting a point inside the face. +The figure below illustrates two special cases, a semi-infinite edge and an edge on a periodic curve. -@subsection occt_modalg_2_topo_tools_8 Getting normal for the face +@figure{/user_guides/modeling_algos/images/modeling_algos_image023.png,"Infinite and Periodic Edges",220} -The following methods allow getting the normal direction for the face/surface: - * *BOPTools_AlgoTools3D::GetNormalToSurface* computes the normal direction for the surface in the given point defined by UV parameters; - * *BOPTools_AlgoTools3D::GetNormalToFaceOnEdge* computes the normal direction for the face in the point located on the edge of the face; - * *BOPTools_AlgoTools3D::GetApproxNormalToFaceOnEdge* computes the normal direction for the face in the point located near the edge of the face. +@subsubsection occt_modalg_3_2_2 Supplementary edge construction methods +There exist supplementary edge construction methods derived from the basic one. +*BRepBuilderAPI_MakeEdge* class provides methods, which are all simplified calls of the previous one: -@section occt_modalg_3a The Topology API - -The Topology API of Open CASCADE Technology (**OCCT**) includes the following six packages: - * *BRepAlgoAPI* - * *BRepBuilderAPI* - * *BRepFilletAPI* - * *BRepFeat* - * *BRepOffsetAPI* - * *BRepPrimAPI* + * The parameters can be omitted. They are computed by projecting the vertices on the curve. + * 3d points (Pnt from gp) can be given in place of vertices. Vertices are created from the points. Giving vertices is useful when creating connected vertices. + * The vertices or points can be omitted if the parameters are given. The points are computed by evaluating the parameters on the curve. + * The vertices or points and the parameters can be omitted. The first and the last parameters of the curve are used. -The classes provided by the API have the following features: - * The constructors of classes provide different construction methods; - * The class retains different tools used to build objects as fields; - * The class provides a casting method to obtain the result automatically with a function-like call. - -Let us use the class *BRepBuilderAPI_MakeEdge* to create a linear edge from two points. +The five following methods are thus derived from the basic construction: ~~~~~ -gp_Pnt P1(10,0,0), P2(20,0,0); -TopoDS_Edge E = BRepBuilderAPI_MakeEdge(P1,P2); +Handle(Geom_Curve) C = ...; // a curve +TopoDS_Vertex V1 = ...,V2 = ...;// two Vertices +Standard_Real p1 = ..., p2 = ..;// two parameters +gp_Pnt P1 = ..., P2 = ...;// two points +TopoDS_Edge E; +// project the vertices on the curve +E = BRepBuilderAPI_MakeEdge(C,V1,V2); +// Make vertices from points +E = BRepBuilderAPI_MakeEdge(C,P1,P2,p1,p2); +// Make vertices from points and project them +E = BRepBuilderAPI_MakeEdge(C,P1,P2); +// Computes the points from the parameters +E = BRepBuilderAPI_MakeEdge(C,p1,p2); +// Make an edge from the whole curve +E = BRepBuilderAPI_MakeEdge(C); ~~~~~ -This is the simplest way to create edge E from two points P1, P2, but the developer can test for errors when he is not as confident of the data as in the previous example. -~~~~~ -#include -#include -#include -void EdgeTest() -{ -gp_Pnt P1; -gp_Pnt P2; -BRepBuilderAPI_MakeEdge ME(P1,P2); -if (!ME.IsDone()) -{ -// doing ME.Edge() or E = ME here -// would raise StdFail_NotDone -Standard_DomainError::Raise -(“ProcessPoints::Failed to createan edge”); -} -TopoDS_Edge E = ME; -} -~~~~~ +Six methods (the five above and the basic method) are also provided for curves from the gp package in place of Curve from Geom. The methods create the corresponding Curve from Geom and are implemented for the following classes: -In this example an intermediary object ME has been introduced. This can be tested for the completion of the function before accessing the result. More information on **error handling** in the topology programming interface can be found in the next section. +*gp_Lin* creates a *Geom_Line* +*gp_Circ* creates a *Geom_Circle* +*gp_Elips* creates a *Geom_Ellipse* +*gp_Hypr* creates a *Geom_Hyperbola* +*gp_Parab* creates a *Geom_Parabola* -*BRepBuilderAPI_MakeEdge* provides valuable information. For example, when creating an edge from two points, two vertices have to be created from the points. Sometimes you may be interested in getting these vertices quickly without exploring the new edge. Such information can be provided when using a class. The following example shows a function creating an edge and two vertices from two points. +There are also two methods to construct edges from two vertices or two points. These methods assume that the curve is a line; the vertices or points must have different locations. -~~~~~ -void MakeEdgeAndVertices(const gp_Pnt& P1, -const gp_Pnt& P2, -TopoDS_Edge& E, -TopoDS_Vertex& V1, -TopoDS_Vertex& V2) -{ -BRepBuilderAPI_MakeEdge ME(P1,P2); -if (!ME.IsDone()) { -Standard_DomainError::Raise -(“MakeEdgeAndVerices::Failed to create an edge”); -} -E = ME; -V1 = ME.Vextex1(); -V2 = ME.Vertex2(); ~~~~~ -The class *BRepBuilderAPI_MakeEdge* provides two methods *Vertex1* and *Vertex2*, which return two vertices used to create the edge. +TopoDS_Vertex V1 = ...,V2 = ...;// two Vertices +gp_Pnt P1 = ..., P2 = ...;// two points +TopoDS_Edge E; -How can *BRepBuilderAPI_MakeEdge* be both a function and a class? It can do this because it uses the casting capabilities of C++. The *BRepBuilderAPI_MakeEdge* class has a method called Edge; in the previous example the line E = ME could have been written. +// linear edge from two vertices +E = BRepBuilderAPI_MakeEdge(V1,V2); +// linear edge from two points +E = BRepBuilderAPI_MakeEdge(P1,P2); ~~~~~ -E = ME.Edge(); -~~~~~ - -This instruction tells the C++ compiler that there is an **implicit casting** of a *BRepBuilderAPI_MakeEdge* into a *TopoDS_Edge* using the *Edge* method. It means this method is automatically called when a *BRepBuilderAPI_MakeEdge* is found where a *TopoDS_Edge* is required. - -This feature allows you to provide classes, which have the simplicity of function calls when required and the power of classes when advanced processing is necessary. All the benefits of this approach are explained when describing the topology programming interface classes. +@subsubsection occt_modalg_3_2_3 Other information and error status -@subsection occt_modalg_3a_1 Error Handling in the Topology API +The class *BRepBuilderAPI_MakeEdge* can provide extra information and return an error status. -A method can report an error in the two following situations: - * The data or arguments of the method are incorrect, i.e. they do not respect the restrictions specified by the methods in its specifications. Typical example: creating a linear edge from two identical points is likely to lead to a zero divide when computing the direction of the line. - * Something unexpected happened. This situation covers every error not included in the first category. Including: interruption, programming errors in the method or in another method called by the first method, bad specifications of the arguments (i.e. a set of arguments that was not expected to fail). +If *BRepBuilderAPI_MakeEdge* is used as a class, it can provide two vertices. This is useful when the vertices were not provided as arguments, for example when the edge was constructed from a curve and parameters. The two methods *Vertex1* and *Vertex2* return the vertices. Note that the returned vertices can be null if the edge is open in the corresponding direction. -The second situation is supposed to become increasingly exceptional as a system is debugged and it is handled by the **exception mechanism**. Using exceptions avoids handling error statuses in the call to a method: a very cumbersome style of programming. +The *Error* method returns a term of the *BRepBuilderAPI_EdgeError* enumeration. It can be used to analyze the error when *IsDone* method returns False. The terms are: -In the first situation, an exception is also supposed to be raised because the calling method should have verified the arguments and if it did not do so, there is a bug. For example, if before calling *MakeEdge* you are not sure that the two points are non-identical, this situation must be tested. + * **EdgeDone** -- No error occurred, *IsDone* returns True. + * **PointProjectionFailed** -- No parameters were given, but the projection of the 3D points on the curve failed. This happens if the point distance to the curve is greater than the precision. + * **ParameterOutOfRange** -- The given parameters are not in the range *C->FirstParameter()*, *C->LastParameter()* + * **DifferentPointsOnClosedCurve** -- The two vertices or points have different locations but they are the extremities of a closed curve. + * **PointWithInfiniteParameter** -- A finite coordinate point was associated with an infinite parameter (see the Precision package for a definition of infinite values). + * **DifferentsPointAndParameter** -- The distance of the 3D point and the point evaluated on the curve with the parameter is greater than the precision. + * **LineThroughIdenticPoints** -- Two identical points were given to define a line (construction of an edge without curve), *gp::Resolution* is used to test confusion . -Making those validity checks on the arguments can be tedious to program and frustrating as you have probably correctly surmised that the method will perform the test twice. It does not trust you. -As the test involves a great deal of computation, performing it twice is also time-consuming. +The following example creates a rectangle centered on the origin of dimensions H, L with fillets of radius R. The edges and the vertices are stored in the arrays *theEdges* and *theVertices*. We use class *Array1OfShape* (i.e. not arrays of edges or vertices). See the image below. -Consequently, you might be tempted to adopt the highly inadvisable style of programming illustrated in the following example: +@figure{/user_guides/modeling_algos/images/modeling_algos_image024.png,"Creating a Wire",360} ~~~~~ -#include -try { -TopoDS_Edge E = BRepBuilderAPI_MakeEdge(P1,P2); -// go on with the edge -} -catch { -// process the error. -} -~~~~~ - -To help the user, the Topology API classes only raise the exception *StdFail_NotDone*. Any other exception means that something happened which was unforeseen in the design of this API. - -The *NotDone* exception is only raised when the user tries to access the result of the computation and the original data is corrupted. At the construction of the class instance, if the algorithm cannot be completed, the internal flag *NotDone* is set. This flag can be tested and in some situations a more complete description of the error can be queried. If the user ignores the *NotDone* status and tries to access the result, an exception is raised. +#include +#include +#include +#include +#include +#include +#include -~~~~~ -BRepBuilderAPI_MakeEdge ME(P1,P2); -if (!ME.IsDone()) { -// doing ME.Edge() or E = ME here -// would raise StdFail_NotDone -Standard_DomainError::Raise -(“ProcessPoints::Failed to create an edge”); +// Use MakeArc method to make an edge and two vertices +void MakeArc(Standard_Real x,Standard_Real y, +Standard_Real R, +Standard_Real ang, +TopoDS_Shape& E, +TopoDS_Shape& V1, +TopoDS_Shape& V2) +{ +gp_Ax2 Origin = gp::XOY(); +gp_Vec Offset(x, y, 0.); +Origin.Translate(Offset); +BRepBuilderAPI_MakeEdge +ME(gp_Circ(Origin,R), ang, ang+PI/2); +E = ME; +V1 = ME.Vertex1(); +V2 = ME.Vertex2(); } -TopoDS_Edge E = ME; -~~~~~ - - -@subsection occt_modalg_hist History support - -All topological API algorithms support the history of shape modifications (or just History) for their arguments. -Generally, the history is available for the following types of sub-shapes of input shapes: -* Vertex; -* Edge; -* Face. - -Some algorithms also support the history for Solids. - -The history information consists of the following information: -* Information about Deleted shapes; -* Information about Modified shapes; -* Information about Generated shapes. - -The History is filled basing on the result of the operation. History cannot return any shapes not contained in the result. -If the result of the operation is an empty shape, all input shapes will be considered as Deleted and none will have Modified and Generated shapes. -The history information can be accessed by the API methods: -* *Standard_Boolean IsDeleted(const TopoDS_Shape& theS)* - to check if the shape has been Deleted during the operation; -* *const TopTools_ListOfShape& Modified(const TopoDS_Shape& theS)* - to get the shapes Modified from the given shape; -* *const TopTools_ListOfShape& Generated(const TopoDS_Shape& theS)* - to get the shapes Generated from the given shape. +TopoDS_Wire MakeFilletedRectangle(const Standard_Real H, +const Standard_Real L, +const Standard_Real R) +{ +TopTools_Array1OfShape theEdges(1,8); +TopTools_Array1OfShape theVertices(1,8); -@subsubsection occt_modalg_hist_del Deleted shapes +// First create the circular edges and the vertices +// using the MakeArc function described above. +void MakeArc(Standard_Real, Standard_Real, +Standard_Real, Standard_Real, +TopoDS_Shape&, TopoDS_Shape&, TopoDS_Shape&); -The shape is considered as Deleted during the operation if all of the following conditions are met: -* The shape is a part of the argument shapes of the operation; -* The result shape does not contain the shape itself; -* The result shape does not contain any of the splits of the shape. +Standard_Real x = L/2 - R, y = H/2 - R; +MakeArc(x,-y,R,3.*PI/2.,theEdges(2),theVertices(2), +theVertices(3)); +MakeArc(x,y,R,0.,theEdges(4),theVertices(4), +theVertices(5)); +MakeArc(-x,y,R,PI/2.,theEdges(6),theVertices(6), +theVertices(7)); +MakeArc(-x,-y,R,PI,theEdges(8),theVertices(8), +theVertices(1)); +// Create the linear edges +for (Standard_Integer i = 1; i <= 7; i += 2) +{ +theEdges(i) = BRepBuilderAPI_MakeEdge +(TopoDS::Vertex(theVertices(i)),TopoDS::Vertex +(theVertices(i+1))); +} +// Create the wire using the BRepBuilderAPI_MakeWire +BRepBuilderAPI_MakeWire MW; +for (i = 1; i <= 8; i++) +{ +MW.Add(TopoDS::Edge(theEdges(i))); +} +return MW.Wire(); +} +~~~~~ -For example, in the CUT operation between two intersecting solids all vertices/edges/faces located completely inside the Tool solid will be Deleted during the operation. +@subsection occt_modalg_3_3 Edge 2D -@subsubsection occt_modalg_hist_mod Modified shapes +Use *BRepBuilderAPI_MakeEdge2d* class to make edges on a working plane from 2d curves. The working plane is a default value of the *BRepBuilderAPI* package (see the *Plane* methods). -The shape is considered as Modified during the operation if the result shape contains the splits of the shape, not the shape itself. The shape can be modified only into the shapes with the same dimension. -The splits of the shape contained in the result shape are Modified from the shape. -The Modified shapes are created from the sub-shapes of the input shapes and, generally, repeat their geometry. +*BRepBuilderAPI_MakeEdge2d* class is strictly similar to BRepBuilderAPI_MakeEdge, but it uses 2D geometry from gp and Geom2d instead of 3D geometry. -The list of Modified elements will contain only those contributing to the result of the operation. If the list is empty, the shape has not been modified and it is necessary to check if it has been Deleted. +@subsection occt_modalg_3_4 Polygon -For example, after translation of the shape in any direction all its sub-shapes will be modified into their translated copies. +*BRepBuilderAPI_MakePolygon* class is used to build polygonal wires from vertices or points. Points are automatically changed to vertices as in *BRepBuilderAPI_MakeEdge*. -@subsubsection occt_modalg_hist_gen Generated shapes +The basic usage of *BRepBuilderAPI_MakePolygon* is to create a wire by adding vertices or points using the Add method. At any moment, the current wire can be extracted. The close method can be used to close the current wire. In the following example, a closed wire is created from an array of points. -The shapes contained in the result shape are considered as Generated from the input shape if they were produced during the operation and have a different dimension from the shapes from which they were created. +~~~~~ +#include +#include +#include -The list of Generated elements will contain only those included in the result of the operation. If the list is empty, no new shapes have been Generated from the shape. +TopoDS_Wire ClosedPolygon(const TColgp_Array1OfPnt& Points) +{ +BRepBuilderAPI_MakePolygon MP; +for(Standard_Integer i=Points.Lower();i=Points.Upper();i++) +{ +MP.Add(Points(i)); +} +MP.Close(); +return MP; +} +~~~~~ -For example, extrusion of the edge in some direction will create a face. This face will be generated from the edge. +Short-cuts are provided for 2, 3, or 4 points or vertices. Those methods have a Boolean last argument to tell if the polygon is closed. The default value is False. -@subsubsection occt_modalg_hist_tool BRepTools_History +Two examples: -*BRepTools_History* is the general History tool intended for unification of the histories of different algorithms. +Example of a closed triangle from three vertices: +~~~~~ +TopoDS_Wire W = BRepBuilderAPI_MakePolygon(V1,V2,V3,Standard_True); +~~~~~ -*BRepTools_History* can be created from any algorithm supporting the standard history methods *(IsDeleted(), Modified()* and *Generated())*: -~~~~ -// The arguments of the operation -TopoDS_Shape aS = ...; +Example of an open polygon from four points: +~~~~~ +TopoDS_Wire W = BRepBuilderAPI_MakePolygon(P1,P2,P3,P4); +~~~~~ -// Perform transformation on the shape -gp_Trsf aTrsf; -aTrsf.SetTranslationPart(gp_Vec(0, 0, 1)); -BRepBuilderAPI_Transform aTransformer(aS, aTrsf); // Transformation API algorithm -const TopoDS_Shape& aRes = aTransformer.Shape(); +*BRepBuilderAPI_MakePolygon* class maintains a current wire. The current wire can be extracted at any moment and the construction can proceed to a longer wire. After each point insertion, the class maintains the last created edge and vertex, which are returned by the methods *Edge, FirstVertex* and *LastVertex*. -// Create the translation history object -TopTools_ListOfShape anArguments; -anArguments.Append(aS); -BRepTools_History aHistory(anArguments, aTransformer); -~~~~ +When the added point or vertex has the same location as the previous one it is not added to the current wire but the most recently created edge becomes Null. The *Added* method can be used to test this condition. The *MakePolygon* class never raises an error. If no vertex has been added, the *Wire* is *Null*. If two vertices are at the same location, no edge is created. -*BRepTools_History* also allows merging histories. Thus, if you have two or more subsequent operations you can get one final history combined from histories of these operations: +@subsection occt_modalg_3_5 Face -~~~~ -Handle(BRepTools_History) aHist1 = ...; // History of first operation -Handle(BRepTools_History) aHist2 = ...; // History of second operation -~~~~ +Use *BRepBuilderAPI_MakeFace* class to create a face from a surface and wires. An underlying surface is constructed from a surface and optional parametric values. Wires can be added to the surface. A planar surface can be constructed from a wire. An error status can be returned after face construction. -It is possible to merge the second history into the first one: -~~~~ -aHist1->Merge(aHist2); -~~~~ +@subsubsection occt_modalg_3_5_1 Basic face construction method -Or create the new history keeping the two histories unmodified: -~~~~ -Handle(BRepTools_History) aResHistory = new BRepTools_History; -aResHistory->Merge(aHist1); -aResHistory->Merge(aHist2); -~~~~ +A face can be constructed from a surface and four parameters to determine a limitation of the UV space. The parameters are optional, if they are omitted the natural bounds of the surface are used. Up to four edges and vertices are created with a wire. No edge is created when the parameter is infinite. -The possibilities of Merging histories and history creation from the API algorithms allow providing easy History support for the new algorithms. +~~~~~ +Handle(Geom_Surface) S = ...; // a surface +Standard_Real umin,umax,vmin,vmax; // parameters +TopoDS_Face F = BRepBuilderAPI_MakeFace(S,umin,umax,vmin,vmax); +~~~~~ -@subsubsection occt_modalg_hist_draw DRAW history support +@figure{/user_guides/modeling_algos/images/modeling_algos_image025.png,"Basic Face Construction",360} -DRAW History support for the algorithms is provided by three basic commands: -* *isdeleted*; -* *modified*; -* *generated*. +To make a face from the natural boundary of a surface, the parameters are not required: -For more information on the Draw History mechanism, refer to the corresponding chapter in the Draw users guide - @ref occt_draw_hist "History commands". +~~~~~ +Handle(Geom_Surface) S = ...; // a surface +TopoDS_Face F = BRepBuilderAPI_MakeFace(S); +~~~~~ +Constraints on the parameters are similar to the constraints in *BRepBuilderAPI_MakeEdge*. + * *umin,umax (vmin,vmax)* must be in the range of the surface and must be increasing. + * On a *U (V)* periodic surface *umin* and *umax (vmin,vmax)* are adjusted. + * *umin, umax, vmin, vmax* can be infinite. There will be no edge in the corresponding direction. -@section occt_modalg_3 Standard Topological Objects +@subsubsection occt_modalg_3_5_2 Supplementary face construction methods -The following standard topological objects can be created: - * Vertices; - * Edges; - * Faces; - * Wires; - * Polygonal wires; - * Shells; - * Solids. +The two basic constructions (from a surface and from a surface and parameters) are implemented for all *gp* package surfaces, which are transformed in the corresponding Surface from Geom. -There are two root classes for their construction and modification: -* The deferred class *BRepBuilderAPI_MakeShape* is the root of all *BRepBuilderAPI* classes, which build shapes. It inherits from the class *BRepBuilderAPI_Command* and provides a field to store the constructed shape. -* The deferred class *BRepBuilderAPI_ModifyShape* is used as a root for the shape modifications. It inherits *BRepBuilderAPI_MakeShape* and implements the methods used to trace the history of all sub-shapes. +| gp package surface | | Geom package surface | +| :------------------- | :----------- | :------------- | +| *gp_Pln* | | *Geom_Plane* | +| *gp_Cylinder* | | *Geom_CylindricalSurface* | +| *gp_Cone* | creates a | *Geom_ConicalSurface* | +| *gp_Sphere* | | *Geom_SphericalSurface* | +| *gp_Torus* | | *Geom_ToroidalSurface* | -@subsection occt_modalg_3_1 Vertex +Once a face has been created, a wire can be added using the *Add* method. For example, the following code creates a cylindrical surface and adds a wire. -*BRepBuilderAPI_MakeVertex* creates a new vertex from a 3D point from gp. ~~~~~ -gp_Pnt P(0,0,10); -TopoDS_Vertex V = BRepBuilderAPI_MakeVertex(P); +gp_Cylinder C = ..; // a cylinder +TopoDS_Wire W = ...;// a wire +BRepBuilderAPI_MakeFace MF(C); +MF.Add(W); +TopoDS_Face F = MF; ~~~~~ -This class always creates a new vertex and has no other methods. - -@subsection occt_modalg_3_2 Edge +More than one wire can be added to a face, provided that they do not cross each other and they define only one area on the surface. (Note that this is not checked). The edges on a Face must have a parametric curve description. -@subsubsection occt_modalg_3_2_1 Basic edge construction method +If there is no parametric curve for an edge of the wire on the Face it is computed by projection. -Use *BRepBuilderAPI_MakeEdge* to create from a curve and vertices. The basic method constructs an edge from a curve, two vertices, and two parameters. +For one wire, a simple syntax is provided to construct the face from the surface and the wire. The above lines could be written: ~~~~~ -Handle(Geom_Curve) C = ...; // a curve -TopoDS_Vertex V1 = ...,V2 = ...;// two Vertices -Standard_Real p1 = ..., p2 = ..;// two parameters -TopoDS_Edge E = BRepBuilderAPI_MakeEdge(C,V1,V2,p1,p2); +TopoDS_Face F = BRepBuilderAPI_MakeFace(C,W); ~~~~~ -where C is the domain of the edge; V1 is the first vertex oriented FORWARD; V2 is the second vertex oriented REVERSED; p1 and p2 are the parameters for the vertices V1 and V2 on the curve. The default tolerance is associated with this edge. - -@figure{/user_guides/modeling_algos/images/modeling_algos_image022.png,"Basic Edge Construction",220} +A planar face can be created from only a wire, provided this wire defines a plane. For example, to create a planar face from a set of points you can use *BRepBuilderAPI_MakePolygon* and *BRepBuilderAPI_MakeFace*. -The following rules apply to the arguments: +~~~~~ +#include +#include +#include +#include -**The curve** - * Must not be a Null Handle. - * If the curve is a trimmed curve, the basis curve is used. - -**The vertices** - * Can be null shapes. When V1 or V2 is Null the edge is open in the corresponding direction and the corresponding parameter p1 or p2 must be infinite (i.e p1 is RealFirst(), p2 is RealLast()). - * Must be different vertices if they have different 3d locations and identical vertices if they have the same 3d location (identical vertices are used when the curve is closed). +TopoDS_Face PolygonalFace(const TColgp_Array1OfPnt& thePnts) +{ +BRepBuilderAPI_MakePolygon MP; +for(Standard_Integer i=thePnts.Lower(); +i<=thePnts.Upper(); i++) +{ +MP.Add(thePnts(i)); +} +MP.Close(); +TopoDS_Face F = BRepBuilderAPI_MakeFace(MP.Wire()); +return F; +} +~~~~~ -**The parameters** - * Must be increasing and in the range of the curve, i.e.: +The last use of *MakeFace* is to copy an existing face to add new wires. For example, the following code adds a new wire to a face: ~~~~~ - C->FirstParameter() <= p1 < p2 <= C->LastParameter() -~~~~~ - - * If the parameters are decreasing, the Vertices are switched, i.e. V2 becomes V1 and V1 becomes V2. - * On a periodic curve the parameters p1 and p2 are adjusted by adding or subtracting the period to obtain p1 in the range of the curve and p2 in the range p1 < p2 <= p1+ Period. So on a parametric curve p2 can be greater than the second parameter, see the figure below. - * Can be infinite but the corresponding vertex must be Null (see above). - * The distance between the Vertex 3d location and the point evaluated on the curve with the parameter must be lower than the default precision. - -The figure below illustrates two special cases, a semi-infinite edge and an edge on a periodic curve. +TopoDS_Face F = ...; // a face +TopoDS_Wire W = ...; // a wire +F = BRepBuilderAPI_MakeFace(F,W); +~~~~~ -@figure{/user_guides/modeling_algos/images/modeling_algos_image023.png,"Infinite and Periodic Edges",220} +To add more than one wire an instance of the *BRepBuilderAPI_MakeFace* class can be created with the face and the first wire and the new wires inserted with the *Add* method. -@subsubsection occt_modalg_3_2_2 Supplementary edge construction methods +@subsubsection occt_modalg_3_5_3 Error status -There exist supplementary edge construction methods derived from the basic one. +The *Error* method returns an error status, which is a term from the *BRepBuilderAPI_FaceError* enumeration. -*BRepBuilderAPI_MakeEdge* class provides methods, which are all simplified calls of the previous one: +* *FaceDone* -- no error occurred. +* *NoFace* -- no initialization of the algorithm; an empty constructor was used. +* *NotPlanar* -- no surface was given and the wire was not planar. +* *CurveProjectionFailed* -- no curve was found in the parametric space of the surface for an edge. +* *ParametersOutOfRange* -- the parameters *umin, umax, vmin, vmax* are out of the surface. - * The parameters can be omitted. They are computed by projecting the vertices on the curve. - * 3d points (Pnt from gp) can be given in place of vertices. Vertices are created from the points. Giving vertices is useful when creating connected vertices. - * The vertices or points can be omitted if the parameters are given. The points are computed by evaluating the parameters on the curve. - * The vertices or points and the parameters can be omitted. The first and the last parameters of the curve are used. +@subsection occt_modalg_3_6 Wire +The wire is a composite shape built not from a geometry, but by the assembly of edges. *BRepBuilderAPI_MakeWire* class can build a wire from one or more edges or connect new edges to an existing wire. -The five following methods are thus derived from the basic construction: +Up to four edges can be used directly, for example: ~~~~~ -Handle(Geom_Curve) C = ...; // a curve -TopoDS_Vertex V1 = ...,V2 = ...;// two Vertices -Standard_Real p1 = ..., p2 = ..;// two parameters -gp_Pnt P1 = ..., P2 = ...;// two points -TopoDS_Edge E; -// project the vertices on the curve -E = BRepBuilderAPI_MakeEdge(C,V1,V2); -// Make vertices from points -E = BRepBuilderAPI_MakeEdge(C,P1,P2,p1,p2); -// Make vertices from points and project them -E = BRepBuilderAPI_MakeEdge(C,P1,P2); -// Computes the points from the parameters -E = BRepBuilderAPI_MakeEdge(C,p1,p2); -// Make an edge from the whole curve -E = BRepBuilderAPI_MakeEdge(C); +TopoDS_Wire W = BRepBuilderAPI_MakeWire(E1,E2,E3,E4); ~~~~~ - -Six methods (the five above and the basic method) are also provided for curves from the gp package in place of Curve from Geom. The methods create the corresponding Curve from Geom and are implemented for the following classes: - -*gp_Lin* creates a *Geom_Line* -*gp_Circ* creates a *Geom_Circle* -*gp_Elips* creates a *Geom_Ellipse* -*gp_Hypr* creates a *Geom_Hyperbola* -*gp_Parab* creates a *Geom_Parabola* - -There are also two methods to construct edges from two vertices or two points. These methods assume that the curve is a line; the vertices or points must have different locations. +For a higher or unknown number of edges the Add method must be used; for example, to build a wire from an array of shapes (to be edges). ~~~~~ - -TopoDS_Vertex V1 = ...,V2 = ...;// two Vertices -gp_Pnt P1 = ..., P2 = ...;// two points -TopoDS_Edge E; - -// linear edge from two vertices -E = BRepBuilderAPI_MakeEdge(V1,V2); - -// linear edge from two points -E = BRepBuilderAPI_MakeEdge(P1,P2); +TopTools_Array1OfShapes theEdges; +BRepBuilderAPI_MakeWire MW; +for (Standard_Integer i = theEdge.Lower(); +i <= theEdges.Upper(); i++) +MW.Add(TopoDS::Edge(theEdges(i)); +TopoDS_Wire W = MW; ~~~~~ -@subsubsection occt_modalg_3_2_3 Other information and error status - -The class *BRepBuilderAPI_MakeEdge* can provide extra information and return an error status. - -If *BRepBuilderAPI_MakeEdge* is used as a class, it can provide two vertices. This is useful when the vertices were not provided as arguments, for example when the edge was constructed from a curve and parameters. The two methods *Vertex1* and *Vertex2* return the vertices. Note that the returned vertices can be null if the edge is open in the corresponding direction. - -The *Error* method returns a term of the *BRepBuilderAPI_EdgeError* enumeration. It can be used to analyze the error when *IsDone* method returns False. The terms are: - - * **EdgeDone** -- No error occurred, *IsDone* returns True. - * **PointProjectionFailed** -- No parameters were given, but the projection of the 3D points on the curve failed. This happens if the point distance to the curve is greater than the precision. - * **ParameterOutOfRange** -- The given parameters are not in the range *C->FirstParameter()*, *C->LastParameter()* - * **DifferentPointsOnClosedCurve** -- The two vertices or points have different locations but they are the extremities of a closed curve. - * **PointWithInfiniteParameter** -- A finite coordinate point was associated with an infinite parameter (see the Precision package for a definition of infinite values). - * **DifferentsPointAndParameter** -- The distance of the 3D point and the point evaluated on the curve with the parameter is greater than the precision. - * **LineThroughIdenticPoints** -- Two identical points were given to define a line (construction of an edge without curve), *gp::Resolution* is used to test confusion . - -The following example creates a rectangle centered on the origin of dimensions H, L with fillets of radius R. The edges and the vertices are stored in the arrays *theEdges* and *theVertices*. We use class *Array1OfShape* (i.e. not arrays of edges or vertices). See the image below. - -@figure{/user_guides/modeling_algos/images/modeling_algos_image024.png,"Creating a Wire",360} +The class can be constructed with a wire. A wire can also be added. In this case, all the edges of the wires are added. For example to merge two wires: ~~~~~ -#include -#include -#include -#include #include -#include #include -// Use MakeArc method to make an edge and two vertices -void MakeArc(Standard_Real x,Standard_Real y, -Standard_Real R, -Standard_Real ang, -TopoDS_Shape& E, -TopoDS_Shape& V1, -TopoDS_Shape& V2) +TopoDS_Wire MergeWires (const TopoDS_Wire& W1, +const TopoDS_Wire& W2) { -gp_Ax2 Origin = gp::XOY(); -gp_Vec Offset(x, y, 0.); -Origin.Translate(Offset); -BRepBuilderAPI_MakeEdge -ME(gp_Circ(Origin,R), ang, ang+PI/2); -E = ME; -V1 = ME.Vertex1(); -V2 = ME.Vertex2(); +BRepBuilderAPI_MakeWire MW(W1); +MW.Add(W2); +return MW; } +~~~~~ -TopoDS_Wire MakeFilletedRectangle(const Standard_Real H, -const Standard_Real L, -const Standard_Real R) -{ -TopTools_Array1OfShape theEdges(1,8); -TopTools_Array1OfShape theVertices(1,8); +*BRepBuilderAPI_MakeWire* class connects the edges to the wire. When a new edge is added if one of its vertices is shared with the wire it is considered as connected to the wire. If there is no shared vertex, the algorithm searches for a vertex of the edge and a vertex of the wire, which are at the same location (the tolerances of the vertices are used to test if they have the same location). If such a pair of vertices is found, the edge is copied with the vertex of the wire in place of the original vertex. All the vertices of the edge can be exchanged for vertices from the wire. If no connection is found the wire is considered to be disconnected. This is an error. -// First create the circular edges and the vertices -// using the MakeArc function described above. -void MakeArc(Standard_Real, Standard_Real, -Standard_Real, Standard_Real, -TopoDS_Shape&, TopoDS_Shape&, TopoDS_Shape&); +BRepBuilderAPI_MakeWire class can return the last edge added to the wire (Edge method). This edge can be different from the original edge if it was copied. -Standard_Real x = L/2 - R, y = H/2 - R; -MakeArc(x,-y,R,3.*PI/2.,theEdges(2),theVertices(2), -theVertices(3)); -MakeArc(x,y,R,0.,theEdges(4),theVertices(4), -theVertices(5)); -MakeArc(-x,y,R,PI/2.,theEdges(6),theVertices(6), -theVertices(7)); -MakeArc(-x,-y,R,PI,theEdges(8),theVertices(8), -theVertices(1)); -// Create the linear edges -for (Standard_Integer i = 1; i <= 7; i += 2) -{ -theEdges(i) = BRepBuilderAPI_MakeEdge -(TopoDS::Vertex(theVertices(i)),TopoDS::Vertex -(theVertices(i+1))); -} -// Create the wire using the BRepBuilderAPI_MakeWire -BRepBuilderAPI_MakeWire MW; -for (i = 1; i <= 8; i++) -{ -MW.Add(TopoDS::Edge(theEdges(i))); -} -return MW.Wire(); -} -~~~~~ +The Error method returns a term of the *BRepBuilderAPI_WireError* enumeration: +*WireDone* -- no error occurred. +*EmptyWire* -- no initialization of the algorithm, an empty constructor was used. +*DisconnectedWire* -- the last added edge was not connected to the wire. +*NonManifoldWire* -- the wire with some singularity. -@subsection occt_modalg_3_3 Edge 2D +@subsection occt_modalg_3_7 Shell +The shell is a composite shape built not from a geometry, but by the assembly of faces. +Use *BRepBuilderAPI_MakeShell* class to build a Shell from a set of Faces. What may be important is that each face should have the required continuity. That is why an initial surface is broken up into faces. -Use *BRepBuilderAPI_MakeEdge2d* class to make edges on a working plane from 2d curves. The working plane is a default value of the *BRepBuilderAPI* package (see the *Plane* methods). +@subsection occt_modalg_3_8 Solid +The solid is a composite shape built not from a geometry, but by the assembly of shells. Use *BRepBuilderAPI_MakeSolid* class to build a Solid from a set of Shells. Its use is similar to the use of the MakeWire class: shells are added to the solid in the same way that edges are added to the wire in MakeWire. -*BRepBuilderAPI_MakeEdge2d* class is strictly similar to BRepBuilderAPI_MakeEdge, but it uses 2D geometry from gp and Geom2d instead of 3D geometry. -@subsection occt_modalg_3_4 Polygon +@section occt_modalg_4 Primitives -*BRepBuilderAPI_MakePolygon* class is used to build polygonal wires from vertices or points. Points are automatically changed to vertices as in *BRepBuilderAPI_MakeEdge*. +The BRepPrimAPI package provides an API (Application Programming Interface) for construction of primitives such as: + * Boxes; + * Cones; + * Cylinders; + * Prisms. -The basic usage of *BRepBuilderAPI_MakePolygon* is to create a wire by adding vertices or points using the Add method. At any moment, the current wire can be extracted. The close method can be used to close the current wire. In the following example, a closed wire is created from an array of points. +It is possible to create partial solids, such as a sphere limited by longitude. In real models, primitives can be used for easy creation of specific sub-parts. -~~~~~ -#include -#include -#include + * Construction by sweeping along a profile: + * Linear; + * Rotational (through an angle of rotation). -TopoDS_Wire ClosedPolygon(const TColgp_Array1OfPnt& Points) -{ -BRepBuilderAPI_MakePolygon MP; -for(Standard_Integer i=Points.Lower();i=Points.Upper();i++) -{ -MP.Add(Points(i)); -} -MP.Close(); -return MP; -} -~~~~~ +Sweeps are objects obtained by sweeping a profile along a path. The profile can be any topology and the path is usually a curve or a wire. The profile generates objects according to the following rules: + * Vertices generate Edges + * Edges generate Faces. + * Wires generate Shells. + * Faces generate Solids. + * Shells generate Composite Solids. -Short-cuts are provided for 2, 3, or 4 points or vertices. Those methods have a Boolean last argument to tell if the polygon is closed. The default value is False. +It is not allowed to sweep Solids and Composite Solids. Swept constructions along complex profiles such as BSpline curves also available in the BRepOffsetAPI package. This API provides simple, high level calls for the most common operations. -Two examples: +@subsection occt_modalg_4_1 Making Primitives +@subsubsection occt_modalg_4_1_1 Box -Example of a closed triangle from three vertices: -~~~~~ -TopoDS_Wire W = BRepBuilderAPI_MakePolygon(V1,V2,V3,Standard_True); -~~~~~ +The class *BRepPrimAPI_MakeBox* allows building a parallelepiped box. The result is either a **Shell** or a **Solid**. There are four ways to build a box: -Example of an open polygon from four points: +* From three dimensions *dx, dy* and *dz*. The box is parallel to the axes and extends for [0,dx] [0,dy] [0,dz] . +* From a point and three dimensions. The same as above but the point is the new origin. +* From two points, the box is parallel to the axes and extends on the intervals defined by the coordinates of the two points. +* From a system of axes *gp_Ax2* and three dimensions. Same as the first way but the box is parallel to the given system of axes. + +An error is raised if the box is flat in any dimension using the default precision. The following code shows how to create a box: ~~~~~ -TopoDS_Wire W = BRepBuilderAPI_MakePolygon(P1,P2,P3,P4); +TopoDS_Solid theBox = BRepPrimAPI_MakeBox(10.,20.,30.); ~~~~~ -*BRepBuilderAPI_MakePolygon* class maintains a current wire. The current wire can be extracted at any moment and the construction can proceed to a longer wire. After each point insertion, the class maintains the last created edge and vertex, which are returned by the methods *Edge, FirstVertex* and *LastVertex*. +The four methods to build a box are shown in the figure: -When the added point or vertex has the same location as the previous one it is not added to the current wire but the most recently created edge becomes Null. The *Added* method can be used to test this condition. The *MakePolygon* class never raises an error. If no vertex has been added, the *Wire* is *Null*. If two vertices are at the same location, no edge is created. +@figure{/user_guides/modeling_algos/images/modeling_algos_image026.png,"Making Boxes",420} -@subsection occt_modalg_3_5 Face +@subsubsection occt_modalg_4_1_2 Wedge +*BRepPrimAPI_MakeWedge* class allows building a wedge, which is a slanted box, i.e. a box with angles. The wedge is constructed in much the same way as a box i.e. from three dimensions dx,dy,dz plus arguments or from an axis system, three dimensions, and arguments. -Use *BRepBuilderAPI_MakeFace* class to create a face from a surface and wires. An underlying surface is constructed from a surface and optional parametric values. Wires can be added to the surface. A planar surface can be constructed from a wire. An error status can be returned after face construction. - -@subsubsection occt_modalg_3_5_1 Basic face construction method - -A face can be constructed from a surface and four parameters to determine a limitation of the UV space. The parameters are optional, if they are omitted the natural bounds of the surface are used. Up to four edges and vertices are created with a wire. No edge is created when the parameter is infinite. - -~~~~~ -Handle(Geom_Surface) S = ...; // a surface -Standard_Real umin,umax,vmin,vmax; // parameters -TopoDS_Face F = BRepBuilderAPI_MakeFace(S,umin,umax,vmin,vmax); -~~~~~ - -@figure{/user_guides/modeling_algos/images/modeling_algos_image025.png,"Basic Face Construction",360} - -To make a face from the natural boundary of a surface, the parameters are not required: - -~~~~~ -Handle(Geom_Surface) S = ...; // a surface -TopoDS_Face F = BRepBuilderAPI_MakeFace(S); -~~~~~ - -Constraints on the parameters are similar to the constraints in *BRepBuilderAPI_MakeEdge*. - * *umin,umax (vmin,vmax)* must be in the range of the surface and must be increasing. - * On a *U (V)* periodic surface *umin* and *umax (vmin,vmax)* are adjusted. - * *umin, umax, vmin, vmax* can be infinite. There will be no edge in the corresponding direction. - -@subsubsection occt_modalg_3_5_2 Supplementary face construction methods - -The two basic constructions (from a surface and from a surface and parameters) are implemented for all *gp* package surfaces, which are transformed in the corresponding Surface from Geom. - -| gp package surface | | Geom package surface | -| :------------------- | :----------- | :------------- | -| *gp_Pln* | | *Geom_Plane* | -| *gp_Cylinder* | | *Geom_CylindricalSurface* | -| *gp_Cone* | creates a | *Geom_ConicalSurface* | -| *gp_Sphere* | | *Geom_SphericalSurface* | -| *gp_Torus* | | *Geom_ToroidalSurface* | - -Once a face has been created, a wire can be added using the *Add* method. For example, the following code creates a cylindrical surface and adds a wire. - -~~~~~ -gp_Cylinder C = ..; // a cylinder -TopoDS_Wire W = ...;// a wire -BRepBuilderAPI_MakeFace MF(C); -MF.Add(W); -TopoDS_Face F = MF; -~~~~~ - -More than one wire can be added to a face, provided that they do not cross each other and they define only one area on the surface. (Note that this is not checked). The edges on a Face must have a parametric curve description. - -If there is no parametric curve for an edge of the wire on the Face it is computed by projection. - -For one wire, a simple syntax is provided to construct the face from the surface and the wire. The above lines could be written: - -~~~~~ -TopoDS_Face F = BRepBuilderAPI_MakeFace(C,W); -~~~~~ - -A planar face can be created from only a wire, provided this wire defines a plane. For example, to create a planar face from a set of points you can use *BRepBuilderAPI_MakePolygon* and *BRepBuilderAPI_MakeFace*. - -~~~~~ -#include -#include -#include -#include - -TopoDS_Face PolygonalFace(const TColgp_Array1OfPnt& thePnts) -{ -BRepBuilderAPI_MakePolygon MP; -for(Standard_Integer i=thePnts.Lower(); -i<=thePnts.Upper(); i++) -{ -MP.Add(thePnts(i)); -} -MP.Close(); -TopoDS_Face F = BRepBuilderAPI_MakeFace(MP.Wire()); -return F; -} -~~~~~ - -The last use of *MakeFace* is to copy an existing face to add new wires. For example, the following code adds a new wire to a face: - -~~~~~ -TopoDS_Face F = ...; // a face -TopoDS_Wire W = ...; // a wire -F = BRepBuilderAPI_MakeFace(F,W); -~~~~~ - -To add more than one wire an instance of the *BRepBuilderAPI_MakeFace* class can be created with the face and the first wire and the new wires inserted with the *Add* method. - -@subsubsection occt_modalg_3_5_3 Error status - -The *Error* method returns an error status, which is a term from the *BRepBuilderAPI_FaceError* enumeration. - -* *FaceDone* -- no error occurred. -* *NoFace* -- no initialization of the algorithm; an empty constructor was used. -* *NotPlanar* -- no surface was given and the wire was not planar. -* *CurveProjectionFailed* -- no curve was found in the parametric space of the surface for an edge. -* *ParametersOutOfRange* -- the parameters *umin, umax, vmin, vmax* are out of the surface. - -@subsection occt_modalg_3_6 Wire -The wire is a composite shape built not from a geometry, but by the assembly of edges. *BRepBuilderAPI_MakeWire* class can build a wire from one or more edges or connect new edges to an existing wire. - -Up to four edges can be used directly, for example: - -~~~~~ -TopoDS_Wire W = BRepBuilderAPI_MakeWire(E1,E2,E3,E4); -~~~~~ - -For a higher or unknown number of edges the Add method must be used; for example, to build a wire from an array of shapes (to be edges). - -~~~~~ -TopTools_Array1OfShapes theEdges; -BRepBuilderAPI_MakeWire MW; -for (Standard_Integer i = theEdge.Lower(); -i <= theEdges.Upper(); i++) -MW.Add(TopoDS::Edge(theEdges(i)); -TopoDS_Wire W = MW; -~~~~~ - -The class can be constructed with a wire. A wire can also be added. In this case, all the edges of the wires are added. For example to merge two wires: - -~~~~~ -#include -#include - -TopoDS_Wire MergeWires (const TopoDS_Wire& W1, -const TopoDS_Wire& W2) -{ -BRepBuilderAPI_MakeWire MW(W1); -MW.Add(W2); -return MW; -} -~~~~~ - -*BRepBuilderAPI_MakeWire* class connects the edges to the wire. When a new edge is added if one of its vertices is shared with the wire it is considered as connected to the wire. If there is no shared vertex, the algorithm searches for a vertex of the edge and a vertex of the wire, which are at the same location (the tolerances of the vertices are used to test if they have the same location). If such a pair of vertices is found, the edge is copied with the vertex of the wire in place of the original vertex. All the vertices of the edge can be exchanged for vertices from the wire. If no connection is found the wire is considered to be disconnected. This is an error. - -BRepBuilderAPI_MakeWire class can return the last edge added to the wire (Edge method). This edge can be different from the original edge if it was copied. - -The Error method returns a term of the *BRepBuilderAPI_WireError* enumeration: -*WireDone* -- no error occurred. -*EmptyWire* -- no initialization of the algorithm, an empty constructor was used. -*DisconnectedWire* -- the last added edge was not connected to the wire. -*NonManifoldWire* -- the wire with some singularity. - -@subsection occt_modalg_3_7 Shell -The shell is a composite shape built not from a geometry, but by the assembly of faces. -Use *BRepBuilderAPI_MakeShell* class to build a Shell from a set of Faces. What may be important is that each face should have the required continuity. That is why an initial surface is broken up into faces. - -@subsection occt_modalg_3_8 Solid -The solid is a composite shape built not from a geometry, but by the assembly of shells. Use *BRepBuilderAPI_MakeSolid* class to build a Solid from a set of Shells. Its use is similar to the use of the MakeWire class: shells are added to the solid in the same way that edges are added to the wire in MakeWire. - - -@section occt_modalg_3b Object Modification - -@subsection occt_modalg_3b_1 Transformation -*BRepBuilderAPI_Transform* class can be used to apply a transformation to a shape (see class *gp_Trsf*). The methods have a boolean argument to copy or share the original shape, as long as the transformation allows (it is only possible for direct isometric transformations). By default, the original shape is shared. - -The following example deals with the rotation of shapes. - -~~~~~ - -TopoDS_Shape myShape1 = ...; -// The original shape 1 -TopoDS_Shape myShape2 = ...; -// The original shape2 -gp_Trsf T; -T.SetRotation(gp_Ax1(gp_Pnt(0.,0.,0.),gp_Vec(0.,0.,1.)), -2.*PI/5.); -BRepBuilderAPI_Transformation theTrsf(T); -theTrsf.Perform(myShape1); -TopoDS_Shape myNewShape1 = theTrsf.Shape() -theTrsf.Perform(myShape2,Standard_True); -// Here duplication is forced -TopoDS_Shape myNewShape2 = theTrsf.Shape() -~~~~~ - -@subsection occt_modalg_3b_2 Duplication - -Use the *BRepBuilderAPI_Copy* class to duplicate a shape. A new shape is thus created. -In the following example, a solid is copied: - -~~~~~ -TopoDS Solid MySolid; -....// Creates a solid - -TopoDS_Solid myCopy = BRepBuilderAPI_Copy(mySolid); -~~~~~ - - -@section occt_modalg_4 Primitives - -The BRepPrimAPI package provides an API (Application Programming Interface) for construction of primitives such as: - * Boxes; - * Cones; - * Cylinders; - * Prisms. - -It is possible to create partial solids, such as a sphere limited by longitude. In real models, primitives can be used for easy creation of specific sub-parts. - - * Construction by sweeping along a profile: - * Linear; - * Rotational (through an angle of rotation). - -Sweeps are objects obtained by sweeping a profile along a path. The profile can be any topology and the path is usually a curve or a wire. The profile generates objects according to the following rules: - * Vertices generate Edges - * Edges generate Faces. - * Wires generate Shells. - * Faces generate Solids. - * Shells generate Composite Solids. - -It is not allowed to sweep Solids and Composite Solids. Swept constructions along complex profiles such as BSpline curves also available in the BRepOffsetAPI package. This API provides simple, high level calls for the most common operations. - -@subsection occt_modalg_4_1 Making Primitives -@subsubsection occt_modalg_4_1_1 Box - -The class *BRepPrimAPI_MakeBox* allows building a parallelepiped box. The result is either a **Shell** or a **Solid**. There are four ways to build a box: - -* From three dimensions *dx, dy* and *dz*. The box is parallel to the axes and extends for [0,dx] [0,dy] [0,dz] . -* From a point and three dimensions. The same as above but the point is the new origin. -* From two points, the box is parallel to the axes and extends on the intervals defined by the coordinates of the two points. -* From a system of axes *gp_Ax2* and three dimensions. Same as the first way but the box is parallel to the given system of axes. - -An error is raised if the box is flat in any dimension using the default precision. The following code shows how to create a box: -~~~~~ -TopoDS_Solid theBox = BRepPrimAPI_MakeBox(10.,20.,30.); -~~~~~ - -The four methods to build a box are shown in the figure: - -@figure{/user_guides/modeling_algos/images/modeling_algos_image026.png,"Making Boxes",420} - -@subsubsection occt_modalg_4_1_2 Wedge -*BRepPrimAPI_MakeWedge* class allows building a wedge, which is a slanted box, i.e. a box with angles. The wedge is constructed in much the same way as a box i.e. from three dimensions dx,dy,dz plus arguments or from an axis system, three dimensions, and arguments. - -The following figure shows two ways to build wedges. One is to add a dimension *ltx*, which is the length in *x* of the face at *dy*. The second is to add *xmin, xmax, zmin* and *zmax* to describe the face at *dy*. +The following figure shows two ways to build wedges. One is to add a dimension *ltx*, which is the length in *x* of the face at *dy*. The second is to add *xmin, xmax, zmin* and *zmax* to describe the face at *dy*. The first method is a particular case of the second with *xmin = 0, xmax = ltx, zmin = 0, zmax = dz*. To make a centered pyramid you can use *xmin = xmax = dx / 2, zmin = zmax = dz / 2*. @@ -2053,7 +1680,10 @@ TopoDS_Solid R2 = BRepPrimAPI_MakeRevol(F,axis,ang); @figure{/user_guides/modeling_algos/images/modeling_algos_image035.png,"Full and partial rotation",420} -@section occt_modalg_5 Boolean Operations + + + +@section occt_modalg_5 Boolean Operations Boolean operations are used to create new shapes from the combinations of two groups of shapes. @@ -2114,1189 +1744,1184 @@ TopoDS_Shape S = BRepAlgoAPI_Cut(A,B); *BRepAlgoAPI_Section* performs the section, described as a *TopoDS_Compound* made of *TopoDS_Edge*. -@figure{/user_guides/modeling_algos/images/modeling_algos_image037.png,"Section operation",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_image037.png,"Section operation",220} ~~~~~ TopoDS_Shape A = ..., TopoDS_ShapeB = ...; TopoDS_Shape S = BRepAlgoAPI_Section(A,B); ~~~~~ -@section occt_modalg_6 Fillets and Chamfers - -This library provides algorithms to make fillets and chamfers on shape edges. -The following cases are addressed: - * Corners and apexes with different radii; - * Corners and apexes with different concavity. -If there is a concavity, both surfaces that need to be extended and those, which do not, are processed. -@subsection occt_modalg_6_1 Fillets -@subsection occt_modalg_6_1_1 Fillet on shape +@section occt_modalg_2_topo_tools Topological Tools -A fillet is a smooth face replacing a sharp edge. +Open CASCADE Technology topological tools provide algorithms to + * Create wires from edges; + * Create faces from wires; + * Compute state of the shape relatively other shape; + * Orient shapes in container; + * Create new shapes from the existing ones; + * Build PCurves of edges on the faces; + * Check the validity of the shapes; + * Take the point in the face; + * Get the normal direction for the face. -*BRepFilletAPI_MakeFillet* class allows filleting a shape. -To produce a fillet, it is necessary to define the filleted shape at the construction of the class and add fillet descriptions using the *Add* method. +@subsection occt_modalg_2_topo_tools_1 Creation of the faces from wireframe model -A fillet description contains an edge and a radius. The edge must be shared by two faces. The fillet is automatically extended to all edges in a smooth continuity with the original edge. It is not an error to add a fillet twice, the last description holds. +It is possible to create the planar faces from the arbitrary set of planar edges randomly located in 3D space. +This feature might be useful if you need for instance to restore the shape from the wireframe model: -@figure{/user_guides/modeling_algos/images/modeling_algos_image038.png,"Filleting two edges using radii r1 and r2.",360} +@figure{/user_guides/modeling_algos/images/modeling_algos_image062.png,"Wireframe model",160} +@figure{/user_guides/modeling_algos/images/modeling_algos_image063.png,"Faces of the model",160} -In the following example a filleted box with dimensions a,b,c and radius r is created. -### Constant radius +To make the faces from edges it is, firstly, necessary to create planar wires from the given edges and than create planar faces from each wire. +The static methods *BOPAlgo_Tools::EdgesToWires* and *BOPAlgo_Tools::WiresToFaces* can be used for that: +~~~~~ +TopoDS_Shape anEdges = ...; /* The input edges */ +Standard_Real anAngTol = 1.e-8; /* The angular tolerance for distinguishing the planes in which the wires are located */ +Standard_Boolean bShared = Standard_False; /* Defines whether the edges are shared or not */ +// +TopoDS_Shape aWires; /* resulting wires */ +Standard_Integer iErr = BOPAlgo_Tools::EdgesToWires(anEdges, aWires, bShared, anAngTol); +if (iErr) { + cout << "Error: Unable to build wires from given edges\n"; + return; +} +// +TopoDS_Shape aFaces; /* resulting faces */ +Standard_Boolean bDone = BOPAlgo_Tools::WiresToFaces(aWires, aFaces, anAngTol); +if (!bDone) { + cout << "Error: Unable to build faces from wires\n"; + return; +} +~~~~~ +These methods can also be used separately: + * *BOPAlgo_Tools::EdgesToWires* allows creating planar wires from edges. +The input edges may be not shared, but the output wires will be sharing the coinciding vertices and edges. For this the intersection of the edges is performed. +Although, it is possible to skip the intersection stage (if the input edges are already shared) by passing the corresponding flag into the method. +The input edges are expected to be planar, but the method does not check it. Thus, if the input edges are not planar, the output wires will also be not planar. +In general, the output wires are non-manifold and may contain free vertices, as well as multi-connected vertices. + * *BOPAlgo_Tools::WiresToFaces* allows creating planar faces from the planar wires. +In general, the input wires are non-manifold and may be not closed, but should share the coinciding parts. +The wires located in the same plane and completely included into other wires will create holes in the faces built from outer wires: -~~~~~ -#include -#include -#include -#include -#include -#include +@figure{/user_guides/modeling_algos/images/modeling_algos_image064.png,"Wireframe model",160} +@figure{/user_guides/modeling_algos/images/modeling_algos_image065.png,"Two faces (red face has a hole)",160} -TopoDS_Shape FilletedBox(const Standard_Real a, - const Standard_Real b, - const Standard_Real c, - const Standard_Real r) -{ - TopoDS_Solid Box = BRepPrimAPI_MakeBox(a,b,c); - BRepFilletAPI_MakeFillet MF(Box); - // add all the edges to fillet - TopExp_Explorer ex(Box,TopAbs_EDGE); - while (ex.More()) - { - MF.Add(r,TopoDS::Edge(ex.Current())); - ex.Next(); - } - return MF.Shape(); - } -~~~~~ -@figure{/user_guides/modeling_algos/images/modeling_algos_image039.png,"Fillet with constant radius",360} +@subsection occt_modalg_2_topo_tools_2 Classification of the shapes -#### Changing radius +The following methods allow classifying the different shapes relatively other shapes: + * The variety of the *BOPTools_AlgoTools::ComputState* methods classify the vertex/edge/face relatively solid; + * *BOPTools_AlgoTools::IsHole* classifies wire relatively face; + * *IntTools_Tools::ClassifyPointByFace* classifies point relatively face. +@subsection occt_modalg_2_topo_tools_3 Orientation of the shapes in the container -~~~~~ -void CSampleTopologicalOperationsDoc::OnEvolvedblend1() -{ - TopoDS_Shape theBox = BRepPrimAPI_MakeBox(200,200,200); +The following methods allow reorienting shapes in the containers: + * *BOPTools_AlgoTools::OrientEdgesOnWire* correctly orients edges on the wire; + * *BOPTools_AlgoTools::OrientFacesOnShell* correctly orients faces on the shell. - BRepFilletAPI_MakeFillet Rake(theBox); - ChFi3d_FilletShape FSh = ChFi3d_Rational; - Rake.SetFilletShape(FSh); +@subsection occt_modalg_2_topo_tools_4 Making new shapes - TColgp_Array1OfPnt2d ParAndRad(1, 6); - ParAndRad(1).SetCoord(0., 10.); - ParAndRad(1).SetCoord(50., 20.); - ParAndRad(1).SetCoord(70., 20.); - ParAndRad(1).SetCoord(130., 60.); - ParAndRad(1).SetCoord(160., 30.); - ParAndRad(1).SetCoord(200., 20.); +The following methods allow creating new shapes from the existing ones: + * The variety of the *BOPTools_AlgoTools::MakeNewVertex* creates the new vertices from other vertices and edges; + * *BOPTools_AlgoTools::MakeSplitEdge* splits the edge by the given parameters. - TopExp_Explorer ex(theBox,TopAbs_EDGE); - Rake.Add(ParAndRad, TopoDS::Edge(ex.Current())); - TopoDS_Shape evolvedBox = Rake.Shape(); -} -~~~~~ +@subsection occt_modalg_2_topo_tools_5 Building PCurves -@figure{/user_guides/modeling_algos/images/modeling_algos_image040.png,"Fillet with changing radius",360} +The following methods allow building PCurves of edges on faces: + * *BOPTools_AlgoTools::BuildPCurveForEdgeOnFace* computes PCurve for the edge on the face; + * *BOPTools_AlgoTools::BuildPCurveForEdgeOnPlane* and *BOPTools_AlgoTools::BuildPCurveForEdgesOnPlane* allow building PCurves for edges on the planar face; + * *BOPTools_AlgoTools::AttachExistingPCurve* takes PCurve on the face from one edge and attach this PCurve to other edge coinciding with the first one. + +@subsection occt_modalg_2_topo_tools_6 Checking the validity of the shapes + +The following methods allow checking the validity of the shapes: + * *BOPTools_AlgoTools::IsMicroEdge* detects the small edges; + * *BOPTools_AlgoTools::ComputeTolerance* computes the correct tolerance of the edge on the face; + * *BOPTools_AlgoTools::CorrectShapeTolerances* and *BOPTools_AlgoTools::CorrectTolerances* allow correcting the tolerances of the sub-shapes. + * *BRepLib::FindValidRange* finds a range of 3d curve of the edge not covered by tolerance spheres of vertices. -@subsection occt_modalg_6_1_2 Chamfer +@subsection occt_modalg_2_topo_tools_7 Taking a point inside the face -A chamfer is a rectilinear edge replacing a sharp vertex of the face. +The following methods allow taking a point located inside the face: + * The variety of the *BOPTools_AlgoTools3D::PointNearEdge* allows getting a point inside the face located near the edge; + * *BOPTools_AlgoTools3D::PointInFace* allows getting a point inside the face. -The use of *BRepFilletAPI_MakeChamfer* class is similar to the use of *BRepFilletAPI_MakeFillet*, except for the following: -* The surfaces created are ruled and not smooth. -* The *Add* syntax for selecting edges requires one or two distances, one edge and one face (contiguous to the edge). +@subsection occt_modalg_2_topo_tools_8 Getting normal for the face -~~~~~ -Add(dist, E, F) -Add(d1, d2, E, F) with d1 on the face F. -~~~~~ +The following methods allow getting the normal direction for the face/surface: + * *BOPTools_AlgoTools3D::GetNormalToSurface* computes the normal direction for the surface in the given point defined by UV parameters; + * *BOPTools_AlgoTools3D::GetNormalToFaceOnEdge* computes the normal direction for the face in the point located on the edge of the face; + * *BOPTools_AlgoTools3D::GetApproxNormalToFaceOnEdge* computes the normal direction for the face in the point located near the edge of the face. -@figure{/user_guides/modeling_algos/images/modeling_algos_image041.png,"Chamfer",360} -@subsection occt_modalg_6_1_3 Fillet on a planar face -*BRepFilletAPI_MakeFillet2d* class allows constructing fillets and chamfers on planar faces. -To create a fillet on planar face: define it, indicate, which vertex is to be deleted, and give the fillet radius with *AddFillet* method. +@section occt_modalg_3a The Topology API + +The Topology API of Open CASCADE Technology (**OCCT**) includes the following six packages: + * *BRepAlgoAPI* + * *BRepBuilderAPI* + * *BRepFilletAPI* + * *BRepFeat* + * *BRepOffsetAPI* + * *BRepPrimAPI* -A chamfer can be calculated with *AddChamfer* method. It can be described by - * two edges and two distances - * one edge, one vertex, one distance and one angle. -Fillets and chamfers are calculated when addition is complete. +The classes provided by the API have the following features: + * The constructors of classes provide different construction methods; + * The class retains different tools used to build objects as fields; + * The class provides a casting method to obtain the result automatically with a function-like call. + +Let us use the class *BRepBuilderAPI_MakeEdge* to create a linear edge from two points. -If face F2 is created by 2D fillet and chamfer builder from face F1, the builder can be rebuilt (the builder recovers the status it had before deletion). To do so, use the following syntax: ~~~~~ -BRepFilletAPI_MakeFillet2d builder; -builder.Init(F1,F2); +gp_Pnt P1(10,0,0), P2(20,0,0); +TopoDS_Edge E = BRepBuilderAPI_MakeEdge(P1,P2); ~~~~~ -Planar Fillet -------------- +This is the simplest way to create edge E from two points P1, P2, but the developer can test for errors when he is not as confident of the data as in the previous example. ~~~~~ -#include “BRepPrimAPI_MakeBox.hxx” -#include “TopoDS_Shape.hxx” -#include “TopExp_Explorer.hxx” -#include “BRepFilletAPI_MakeFillet2d.hxx” -#include “TopoDS.hxx” -#include “TopoDS_Solid.hxx” - -TopoDS_Shape FilletFace(const Standard_Real a, - const Standard_Real b, - const Standard_Real c, - const Standard_Real r) - +#include +#include +#include +void EdgeTest() { - TopoDS_Solid Box = BRepPrimAPI_MakeBox (a,b,c); - TopExp_Explorer ex1(Box,TopAbs_FACE); - - const TopoDS_Face& F = TopoDS::Face(ex1.Current()); - BRepFilletAPI_MakeFillet2d MF(F); - TopExp_Explorer ex2(F, TopAbs_VERTEX); - while (ex2.More()) - { - MF.AddFillet(TopoDS::Vertex(ex2.Current()),r); - ex2.Next(); - } - // while... - return MF.Shape(); +gp_Pnt P1; +gp_Pnt P2; +BRepBuilderAPI_MakeEdge ME(P1,P2); +if (!ME.IsDone()) +{ +// doing ME.Edge() or E = ME here +// would raise StdFail_NotDone +Standard_DomainError::Raise +(“ProcessPoints::Failed to createan edge”); +} +TopoDS_Edge E = ME; } ~~~~~ -@section occt_modalg_7 Offsets, Drafts, Pipes and Evolved shapes +In this example an intermediary object ME has been introduced. This can be tested for the completion of the function before accessing the result. More information on **error handling** in the topology programming interface can be found in the next section. -These classes provide the following services: +*BRepBuilderAPI_MakeEdge* provides valuable information. For example, when creating an edge from two points, two vertices have to be created from the points. Sometimes you may be interested in getting these vertices quickly without exploring the new edge. Such information can be provided when using a class. The following example shows a function creating an edge and two vertices from two points. - * Creation of offset shapes and their variants such as: - * Hollowing; - * Shelling; - * Lofting; - * Creation of tapered shapes using draft angles; - * Creation of sweeps. - -@subsection occt_modalg_7_1 Offset computation +~~~~~ +void MakeEdgeAndVertices(const gp_Pnt& P1, +const gp_Pnt& P2, +TopoDS_Edge& E, +TopoDS_Vertex& V1, +TopoDS_Vertex& V2) +{ +BRepBuilderAPI_MakeEdge ME(P1,P2); +if (!ME.IsDone()) { +Standard_DomainError::Raise +(“MakeEdgeAndVerices::Failed to create an edge”); +} +E = ME; +V1 = ME.Vextex1(); +V2 = ME.Vertex2(); +~~~~~ -Offset computation can be performed using *BRepOffsetAPI_MakeOffsetShape*. This class provides API to the two different offset algorithms: +The class *BRepBuilderAPI_MakeEdge* provides two methods *Vertex1* and *Vertex2*, which return two vertices used to create the edge. -Offset algorithm based on computation of the analytical continuation. Meaning of the parameters can be found in *BRepOffsetAPI_MakeOffsetShape::PerformByJoin* method description. The list below demonstrates principal scheme of this algorithm: +How can *BRepBuilderAPI_MakeEdge* be both a function and a class? It can do this because it uses the casting capabilities of C++. The *BRepBuilderAPI_MakeEdge* class has a method called Edge; in the previous example the line E = ME could have been written. -* At the first step, the offsets are computed. -* After this, the analytical continuations are computed for each offset. -* Pairwise intersection is computed according to the original topological information (sharing, number of neighbors, etc.). -* The offset shape is assembled. +~~~~~ +E = ME.Edge(); +~~~~~ -The second algorithm is based on the fact that the offset computation for a single face without continuation can always be built. The list below shows simple offset algorithm: -* Each surface is mapped to its geometric offset surface. -* For each edge, pcurves are mapped to the same pcurves on offset surfaces. -* For each edge, 3d curve is constructed by re-approximation of pcurve on the first offset face. -* Position of each vertex in a result shell is computed as average point of all ends of edges sharing that vertex. -* Tolerances are updated according to the resulting geometry. -The possible drawback of the simple algorithm is that it leads, in general case, to tolerance increasing. The tolerances have to grow in order to cover the gaps between the neighbor faces in the output. It should be noted that the actual tolerance growth depends on the offset distance and the quality of joints between the input faces. Anyway the good input shell (smooth connections between adjacent faces) will lead to good result. +This instruction tells the C++ compiler that there is an **implicit casting** of a *BRepBuilderAPI_MakeEdge* into a *TopoDS_Edge* using the *Edge* method. It means this method is automatically called when a *BRepBuilderAPI_MakeEdge* is found where a *TopoDS_Edge* is required. -The snippets below show usage examples: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} - BRepOffsetAPI_MakeOffsetShape OffsetMaker1; - // Computes offset shape using analytical continuation mechanism. - OffsetMaker1.PerformByJoin(Shape, OffsetValue, Tolerance); - if (OffsetMaker1.IsDone()) - NewShape = OffsetMaker1.Shape(); - - BRepOffsetAPI_MakeOffsetShape OffsetMaker2; - // Computes offset shape using simple algorithm. - OffsetMaker2.PerformBySimple(Shape, OffsetValue); - if (OffsetMaker2.IsDone()) - NewShape = OffsetMaker2.Shape(); -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This feature allows you to provide classes, which have the simplicity of function calls when required and the power of classes when advanced processing is necessary. All the benefits of this approach are explained when describing the topology programming interface classes. -@subsection occt_modalg_7_2 Shelling -Shelling is used to offset given faces of a solid by a specific value. It rounds or intersects adjacent faces along its edges depending on the convexity of the edge. -The MakeThickSolidByJoin method of the *BRepOffsetAPI_MakeThickSolid* takes the solid, the list of faces to remove and an offset value as input. - -~~~~~ -TopoDS_Solid SolidInitial = ...; - -Standard_Real Of = ...; -TopTools_ListOfShape LCF; -TopoDS_Shape Result; -Standard_Real Tol = Precision::Confusion(); +@subsection occt_modalg_hist History support -for (Standard_Integer i = 1 ;i <= n; i++) { - TopoDS_Face SF = ...; // a face from SolidInitial - LCF.Append(SF); -} +All topological API algorithms support the history of shape modifications (or just History) for their arguments. +Generally, the history is available for the following types of sub-shapes of input shapes: +* Vertex; +* Edge; +* Face. -BRepOffsetAPI_MakeThickSolid SolidMaker; -SolidMaker.MakeThickSolidByJoin(SolidInitial, - LCF, - Of, - Tol); -if (SolidMaker.IsDone()) - Result = SolidMaker.Shape(); -~~~~~ +Some algorithms also support the history for Solids. -@figure{/user_guides/modeling_algos/images/modeling_algos_image042.png,"Shelling",420} +The history information consists of the following information: +* Information about Deleted shapes; +* Information about Modified shapes; +* Information about Generated shapes. -Also it is possible to create solid between shell, offset shell. This functionality can be called using *BRepOffsetAPI_MakeThickSolid::MakeThickSolidBySimple* method. The code below shows usage example: +The History is filled basing on the result of the operation. History cannot return any shapes not contained in the result. +If the result of the operation is an empty shape, all input shapes will be considered as Deleted and none will have Modified and Generated shapes. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} - BRepOffsetAPI_MakeThickSolid SolidMaker; - SolidMaker.MakeThickSolidBySimple(Shell, OffsetValue); - if (myDone.IsDone()) - Solid = SolidMaker.Shape(); -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The history information can be accessed by the API methods: +* *Standard_Boolean IsDeleted(const TopoDS_Shape& theS)* - to check if the shape has been Deleted during the operation; +* *const TopTools_ListOfShape& Modified(const TopoDS_Shape& theS)* - to get the shapes Modified from the given shape; +* *const TopTools_ListOfShape& Generated(const TopoDS_Shape& theS)* - to get the shapes Generated from the given shape. -@subsection occt_modalg_7_3 Draft Angle +@subsubsection occt_modalg_hist_del Deleted shapes -*BRepOffsetAPI_DraftAngle* class allows modifying a shape by applying draft angles to its planar, cylindrical and conical faces. +The shape is considered as Deleted during the operation if all of the following conditions are met: +* The shape is a part of the argument shapes of the operation; +* The result shape does not contain the shape itself; +* The result shape does not contain any of the splits of the shape. +For example, in the CUT operation between two intersecting solids all vertices/edges/faces located completely inside the Tool solid will be Deleted during the operation. -The class is created or initialized from a shape, then faces to be modified are added; for each face, three arguments are used: - * Direction: the direction with which the draft angle is measured - * Angle: value of the angle - * Neutral plane: intersection between the face and the neutral plane is invariant. +@subsubsection occt_modalg_hist_mod Modified shapes -The following code places a draft angle on several faces of a shape; the same direction, angle and neutral plane are used for each face: +The shape is considered as Modified during the operation if the result shape contains the splits of the shape, not the shape itself. The shape can be modified only into the shapes with the same dimension. +The splits of the shape contained in the result shape are Modified from the shape. +The Modified shapes are created from the sub-shapes of the input shapes and, generally, repeat their geometry. -~~~~~ -TopoDS_Shape myShape = ... -// The original shape -TopTools_ListOfShape ListOfFace; -// Creation of the list of faces to be modified -... +The list of Modified elements will contain only those contributing to the result of the operation. If the list is empty, the shape has not been modified and it is necessary to check if it has been Deleted. -gp_Dir Direc(0.,0.,1.); -// Z direction -Standard_Real Angle = 5.*PI/180.; -// 5 degree angle -gp_Pln Neutral(gp_Pnt(0.,0.,5.), Direc); -// Neutral plane Z=5 -BRepOffsetAPI_DraftAngle theDraft(myShape); -TopTools_ListIteratorOfListOfShape itl; -for (itl.Initialize(ListOfFace); itl.More(); itl.Next()) { - theDraft.Add(TopoDS::Face(itl.Value()),Direc,Angle,Neutral); - if (!theDraft.AddDone()) { - // An error has occurred. The faulty face is given by // ProblematicShape - break; - } -} -if (!theDraft.AddDone()) { - // An error has occurred - TopoDS_Face guilty = theDraft.ProblematicShape(); - ... -} -theDraft.Build(); -if (!theDraft.IsDone()) { - // Problem encountered during reconstruction - ... -} -else { - TopoDS_Shape myResult = theDraft.Shape(); - ... -} -~~~~~ +For example, after translation of the shape in any direction all its sub-shapes will be modified into their translated copies. -@figure{/user_guides/modeling_algos/images/modeling_algos_image043.png,"DraftAngle",420} +@subsubsection occt_modalg_hist_gen Generated shapes -@subsection occt_modalg_7_4 Pipe Constructor +The shapes contained in the result shape are considered as Generated from the input shape if they were produced during the operation and have a different dimension from the shapes from which they were created. -*BRepOffsetAPI_MakePipe* class allows creating a pipe from a Spine, which is a Wire and a Profile which is a Shape. This implementation is limited to spines with smooth transitions, sharp transitions are precessed by *BRepOffsetAPI_MakePipeShell*. To be more precise the continuity must be G1, which means that the tangent must have the same direction, though not necessarily the same magnitude, at neighboring edges. +The list of Generated elements will contain only those included in the result of the operation. If the list is empty, no new shapes have been Generated from the shape. -The angle between the spine and the profile is preserved throughout the pipe. +For example, extrusion of the edge in some direction will create a face. This face will be generated from the edge. -~~~~~ -TopoDS_Wire Spine = ...; -TopoDS_Shape Profile = ...; -TopoDS_Shape Pipe = BRepOffsetAPI_MakePipe(Spine,Profile); -~~~~~ +@subsubsection occt_modalg_hist_tool BRepTools_History -@figure{/user_guides/modeling_algos/images/modeling_algos_image044.png,"Example of a Pipe",320} +*BRepTools_History* is the general History tool intended for unification of the histories of different algorithms. -@subsection occt_modalg_7_5 Evolved Solid +*BRepTools_History* can be created from any algorithm supporting the standard history methods *(IsDeleted(), Modified()* and *Generated())*: +~~~~ +// The arguments of the operation +TopoDS_Shape aS = ...; -*BRepOffsetAPI_MakeEvolved* class allows creating an evolved solid from a Spine (planar face or wire) and a profile (wire). +// Perform transformation on the shape +gp_Trsf aTrsf; +aTrsf.SetTranslationPart(gp_Vec(0, 0, 1)); +BRepBuilderAPI_Transform aTransformer(aS, aTrsf); // Transformation API algorithm +const TopoDS_Shape& aRes = aTransformer.Shape(); -The evolved solid is an unlooped sweep generated by the spine and the profile. +// Create the translation history object +TopTools_ListOfShape anArguments; +anArguments.Append(aS); +BRepTools_History aHistory(anArguments, aTransformer); +~~~~ -The evolved solid is created by sweeping the profile’s reference axes on the spine. The origin of the axes moves to the spine, the X axis and the local tangent coincide and the Z axis is normal to the face. +*BRepTools_History* also allows merging histories. Thus, if you have two or more subsequent operations you can get one final history combined from histories of these operations: -The reference axes of the profile can be defined following two distinct modes: +~~~~ +Handle(BRepTools_History) aHist1 = ...; // History of first operation +Handle(BRepTools_History) aHist2 = ...; // History of second operation +~~~~ -* The reference axes of the profile are the origin axes. -* The references axes of the profile are calculated as follows: - + the origin is given by the point on the spine which is the closest to the profile - + the X axis is given by the tangent to the spine at the point defined above - + the Z axis is the normal to the plane which contains the spine. +It is possible to merge the second history into the first one: +~~~~ +aHist1->Merge(aHist2); +~~~~ -~~~~~ -TopoDS_Face Spine = ...; -TopoDS_Wire Profile = ...; -TopoDS_Shape Evol = -BRepOffsetAPI_MakeEvolved(Spine,Profile); -~~~~~ +Or create the new history keeping the two histories unmodified: +~~~~ +Handle(BRepTools_History) aResHistory = new BRepTools_History; +aResHistory->Merge(aHist1); +aResHistory->Merge(aHist2); +~~~~ -@section occt_modalg_8 Sewing +The possibilities of Merging histories and history creation from the API algorithms allow providing easy History support for the new algorithms. -@subsection occt_modalg_8_1 Introduction +@subsubsection occt_modalg_hist_draw DRAW history support -Sewing allows creation of connected topology (shells and wires) from a set of separate topological elements (faces and edges). For example, Sewing can be used to create of shell from a compound of separate faces. +DRAW History support for the algorithms is provided by three basic commands: +* *isdeleted*; +* *modified*; +* *generated*. -@figure{/user_guides/modeling_algos/images/modeling_algos_image045.png,"Shapes with partially shared edges",320} +For more information on the Draw History mechanism, refer to the corresponding chapter in the Draw users guide - @ref occt_draw_hist "History commands". -It is important to distinguish between sewing and other procedures, which modify the geometry, such as filling holes or gaps, gluing, bending curves and surfaces, etc. +@subsection occt_modalg_6 Fillets and Chamfers -Sewing does not change geometrical representation of the shapes. Sewing applies to topological elements (faces, edges) which are not connected but can be connected because they are geometrically coincident : it adds the information about topological connectivity. Already connected elements are left untouched in case of manifold sewing. +This library provides algorithms to make fillets and chamfers on shape edges. +The following cases are addressed: -Let us define several terms: -* **Floating edges** do not belong to any face; -* **Free boundaries** belong to one face only; -* **Shared edges** belong to several faces, (i.e. two faces in a manifold topology). -* **Sewn faces** should have edges shared with each other. -* **Sewn edges** should have vertices shared with each other. + * Corners and apexes with different radii; + * Corners and apexes with different concavity. -@subsection occt_modalg_8_2 Sewing Algorithm +If there is a concavity, both surfaces that need to be extended and those, which do not, are processed. -The sewing algorithm is one of the basic algorithms used for shape processing, therefore its quality is very important. +@subsubsection occt_modalg_6_1 Fillets +@subsubsection occt_modalg_6_1_1 Fillet on shape -Sewing algorithm is implemented in the class *BRepBuilder_Sewing*. This class provides the following methods: -* loading initial data for global or local sewing; -* setting customization parameters, such as special operation modes, tolerances and output results; -* applying analysis methods that can be used to obtain connectivity data required by external algorithms; -* sewing of the loaded shapes. +A fillet is a smooth face replacing a sharp edge. -Sewing supports working mode with big value tolerance. It is not necessary to repeat sewing step by step while smoothly increasing tolerance. +*BRepFilletAPI_MakeFillet* class allows filleting a shape. -It is also possible to sew edges to wire and to sew locally separate faces and edges from a shape. +To produce a fillet, it is necessary to define the filleted shape at the construction of the class and add fillet descriptions using the *Add* method. -The Sewing algorithm can be subdivided into several independent stages, some of which can be turned on or off using Boolean or other flags. +A fillet description contains an edge and a radius. The edge must be shared by two faces. The fillet is automatically extended to all edges in a smooth continuity with the original edge. It is not an error to add a fillet twice, the last description holds. -In brief, the algorithm should find a set of merge candidates for each free boundary, filter them according to certain criteria, and finally merge the found candidates and build the resulting sewn shape. +@figure{/user_guides/modeling_algos/images/modeling_algos_image038.png,"Filleting two edges using radii r1 and r2.",360} -Each stage of the algorithm or the whole algorithm can be adjusted with the following parameters: -* **Working tolerance** defines the maximal distance between topological elements which can be sewn. It is not ultimate that such elements will be actually sewn as many other criteria are applied to make the final decision. -* **Minimal tolerance** defines the size of the smallest element (edge) in the resulting shape. It is declared that no edges with size less than this value are created after sewing. If encountered, such topology becomes degenerated. -* **Non-manifold mode** enables sewing of non-manifold topology. +In the following example a filleted box with dimensions a,b,c and radius r is created. -#### Example +### Constant radius -To connect a set of *n* contiguous but independent faces, do the following: ~~~~~ - BRepBuilderAPI_Sewing Sew; - Sew.Add(Face1); - Sew.Add(Face2); - ... - Sew.Add(Facen); - Sew.Perform(); - TopoDS_Shape result= Sew.SewedShape(); -~~~~~ - -If all faces have been sewn correctly, the result is a shell. Otherwise, it is a compound. After a successful sewing operation all faces have a coherent orientation. +#include +#include +#include +#include +#include +#include -@subsection occt_modalg_8_3 Tolerance Management +TopoDS_Shape FilletedBox(const Standard_Real a, + const Standard_Real b, + const Standard_Real c, + const Standard_Real r) +{ + TopoDS_Solid Box = BRepPrimAPI_MakeBox(a,b,c); + BRepFilletAPI_MakeFillet MF(Box); -To produce a closed shell, Sewing allows specifying the value of working tolerance, exceeding the size of small faces belonging to the shape. + // add all the edges to fillet + TopExp_Explorer ex(Box,TopAbs_EDGE); + while (ex.More()) + { + MF.Add(r,TopoDS::Edge(ex.Current())); + ex.Next(); + } + return MF.Shape(); + } +~~~~~ -However, if we produce an open shell, it is possible to get incorrect sewing results if the value of working tolerance is too large (i.e. it exceeds the size of faces lying on an open boundary). +@figure{/user_guides/modeling_algos/images/modeling_algos_image039.png,"Fillet with constant radius",360} -The following recommendations can be proposed for tuning-up the sewing process: -- Use as small working tolerance as possible. This will reduce the sewing time and, consequently, the number of incorrectly sewn edges for shells with free boundaries. -- Use as large minimal tolerance as possible. This will reduce the number of small geometry in the shape, both original and appearing after cutting. -- If it is expected to obtain a shell with holes (free boundaries) as a result of sewing, the working tolerance should be set to a value not greater than the size of the smallest element (edge) or smallest distance between elements of such free boundary. Otherwise the free boundary may be sewn only partially. -- It should be mentioned that the Sewing algorithm is unable to understand which small (less than working tolerance) free boundary should be kept and which should be sewn. +#### Changing radius -@subsection occt_modalg_8_4 Manifold and Non-manifold Sewing -To create one or several shells from a set of faces, sewing merges edges, which belong to different faces or one closed face. +~~~~~ +void CSampleTopologicalOperationsDoc::OnEvolvedblend1() +{ + TopoDS_Shape theBox = BRepPrimAPI_MakeBox(200,200,200); -Face sewing supports manifold and non manifold modes. Manifold mode can produce only a manifold shell. Sewing should be used in the non manifold mode to create non manifold shells. + BRepFilletAPI_MakeFillet Rake(theBox); + ChFi3d_FilletShape FSh = ChFi3d_Rational; + Rake.SetFilletShape(FSh); -Manifold sewing of faces merges only two nearest edges belonging to different faces or one closed face with each other. Non manifold sewing of faces merges all edges at a distance less than the specified tolerance. - -For a complex topology it is advisable to apply first the manifold sewing and then the non manifold sewing a minimum possible working tolerance. However, this is not necessary for a easy topology. - -Giving a large tolerance value to non manifold sewing will cause a lot of incorrectness since all nearby geometry will be sewn. - -@subsection occt_modalg_8_5 Local Sewing - -If a shape still has some non-sewn faces or edges after sewing, it is possible to use local sewing with a greater tolerance. + TColgp_Array1OfPnt2d ParAndRad(1, 6); + ParAndRad(1).SetCoord(0., 10.); + ParAndRad(1).SetCoord(50., 20.); + ParAndRad(1).SetCoord(70., 20.); + ParAndRad(1).SetCoord(130., 60.); + ParAndRad(1).SetCoord(160., 30.); + ParAndRad(1).SetCoord(200., 20.); -Local sewing is especially good for open shells. It allows sewing an unwanted hole in one part of the shape and keeping a required hole, which is smaller than the working tolerance specified for the local sewing in the other part of the shape. Local sewing is much faster than sewing on the whole shape. + TopExp_Explorer ex(theBox,TopAbs_EDGE); + Rake.Add(ParAndRad, TopoDS::Edge(ex.Current())); + TopoDS_Shape evolvedBox = Rake.Shape(); +} +~~~~~ -All preexisting connections of the whole shape are kept after local sewing. +@figure{/user_guides/modeling_algos/images/modeling_algos_image040.png,"Fillet with changing radius",360} + +@subsubsection occt_modalg_6_1_2 Chamfer -For example, if you want to sew two open shells having coincided free edges using local sewing, it is necessary to create a compound from two shells then load the full compound using method *BRepBuilderAPI_Sewing::Load()*. After that it is necessary to add local sub-shapes, which should be sewn using method *BRepBuilderAPI_Sewing::Add()*. The result of sewing can be obtained using method *BRepBuilderAPI_Sewing::SewedShape()*. +A chamfer is a rectilinear edge replacing a sharp vertex of the face. -See the example: +The use of *BRepFilletAPI_MakeChamfer* class is similar to the use of *BRepFilletAPI_MakeFillet*, except for the following: +* The surfaces created are ruled and not smooth. +* The *Add* syntax for selecting edges requires one or two distances, one edge and one face (contiguous to the edge). -~~~~ +~~~~~ +Add(dist, E, F) +Add(d1, d2, E, F) with d1 on the face F. +~~~~~ -//initial sewn shapes -TopoDS_Shape aS1, aS2; // these shapes are expected to be well sewn shells -TopoDS_Shape aComp; -BRep_Builder aB; -aB.MakeCompound(aComp); -aB.Add(aComp, aS1); -aB.Add(aComp, aS2); -................................ -aSewing.Load(aComp); +@figure{/user_guides/modeling_algos/images/modeling_algos_image041.png,"Chamfer",360} -//sub shapes which should be locally sewed -aSewing.Add(aF1); -aSewing.Add(aF2); -//performing sewing -aSewing.Perform(); -//result shape -TopoDS_Shape aRes = aSewing.SewedShape(); +@subsubsection occt_modalg_6_1_3 Fillet on a planar face -~~~~ +*BRepFilletAPI_MakeFillet2d* class allows constructing fillets and chamfers on planar faces. +To create a fillet on planar face: define it, indicate, which vertex is to be deleted, and give the fillet radius with *AddFillet* method. -@section occt_modalg_9 Features +A chamfer can be calculated with *AddChamfer* method. It can be described by + * two edges and two distances + * one edge, one vertex, one distance and one angle. +Fillets and chamfers are calculated when addition is complete. -This library contained in *BRepFeat* package is necessary for creation and manipulation of form and mechanical features that go beyond the classical boundary representation of shapes. In that sense, *BRepFeat* is an extension of *BRepBuilderAPI* package. +If face F2 is created by 2D fillet and chamfer builder from face F1, the builder can be rebuilt (the builder recovers the status it had before deletion). To do so, use the following syntax: +~~~~~ +BRepFilletAPI_MakeFillet2d builder; +builder.Init(F1,F2); +~~~~~ -@subsection occt_modalg_9_1 Form Features +Planar Fillet +------------- -The form features are depressions or protrusions including the following types: +~~~~~ +#include “BRepPrimAPI_MakeBox.hxx” +#include “TopoDS_Shape.hxx” +#include “TopExp_Explorer.hxx” +#include “BRepFilletAPI_MakeFillet2d.hxx” +#include “TopoDS.hxx” +#include “TopoDS_Solid.hxx” - * Cylinder; - * Draft Prism; - * Prism; - * Revolved feature; - * Pipe. +TopoDS_Shape FilletFace(const Standard_Real a, + const Standard_Real b, + const Standard_Real c, + const Standard_Real r) -Depending on whether you wish to make a depression or a protrusion, -you can choose either to remove matter (Boolean cut: Fuse equal to 0) or to add it (Boolean fusion: Fuse equal to 1). +{ + TopoDS_Solid Box = BRepPrimAPI_MakeBox (a,b,c); + TopExp_Explorer ex1(Box,TopAbs_FACE); -The semantics of form feature creation is based on the construction of shapes: + const TopoDS_Face& F = TopoDS::Face(ex1.Current()); + BRepFilletAPI_MakeFillet2d MF(F); + TopExp_Explorer ex2(F, TopAbs_VERTEX); + while (ex2.More()) + { + MF.AddFillet(TopoDS::Vertex(ex2.Current()),r); + ex2.Next(); + } + // while... + return MF.Shape(); +} +~~~~~ - * for a certain length in a certain direction; - * up to the limiting face; - * from the limiting face at a height; - * above and/or below a plane. +@subsection occt_modalg_7 Offsets, Drafts, Pipes and Evolved shapes -The shape defining the construction of a feature can be either a supporting edge or a concerned area of a face. +These classes provide the following services: -In case of supporting edge, this contour can be attached to a face of the basis shape by binding. When the contour is bound to this face, the information that the contour will slide on the face becomes available -to the relevant class methods. In case of the concerned area of a face, you can, for example, cut it out and move it at a different height, which defines the limiting face of a protrusion or depression. + * Creation of offset shapes and their variants such as: + * Hollowing; + * Shelling; + * Lofting; + * Creation of tapered shapes using draft angles; + * Creation of sweeps. + +@subsubsection occt_modalg_7_1 Offset computation -Topological definition with local operations of this sort makes calculations simpler -and faster than a global operation. The latter would entail a second phase -of removing unwanted matter to get the same result. +Offset computation can be performed using *BRepOffsetAPI_MakeOffsetShape*. This class provides API to the two different offset algorithms: -The *Form* from *BRepFeat* package is a deferred class used as a root for form features. It inherits *MakeShape* from *BRepBuilderAPI* and provides implementation of methods keep track of all sub-shapes. +Offset algorithm based on computation of the analytical continuation. Meaning of the parameters can be found in *BRepOffsetAPI_MakeOffsetShape::PerformByJoin* method description. The list below demonstrates principal scheme of this algorithm: -@subsubsection occt_modalg_9_1_1 Prism +* At the first step, the offsets are computed. +* After this, the analytical continuations are computed for each offset. +* Pairwise intersection is computed according to the original topological information (sharing, number of neighbors, etc.). +* The offset shape is assembled. -The class *BRepFeat_MakePrism* is used to build a prism interacting with a shape. It is created or initialized from - * a shape (the basic shape), - * the base of the prism, - * a face (the face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not), - * a direction, - * a Boolean indicating the type of operation (fusion=protrusion or cut=depression) on the basic shape, - * another Boolean indicating if the self-intersections have to be found (not used in every case). +The second algorithm is based on the fact that the offset computation for a single face without continuation can always be built. The list below shows simple offset algorithm: +* Each surface is mapped to its geometric offset surface. +* For each edge, pcurves are mapped to the same pcurves on offset surfaces. +* For each edge, 3d curve is constructed by re-approximation of pcurve on the first offset face. +* Position of each vertex in a result shell is computed as average point of all ends of edges sharing that vertex. +* Tolerances are updated according to the resulting geometry. +The possible drawback of the simple algorithm is that it leads, in general case, to tolerance increasing. The tolerances have to grow in order to cover the gaps between the neighbor faces in the output. It should be noted that the actual tolerance growth depends on the offset distance and the quality of joints between the input faces. Anyway the good input shell (smooth connections between adjacent faces) will lead to good result. -There are six Perform methods: -| Method | Description | -| :---------------------- | :------------------------------------- | -| *Perform(Height)* | The resulting prism is of the given length. | -| *Perform(Until)* | The prism is defined between the position of the base and the given face. | -| *Perform(From, Until)* | The prism is defined between the two faces From and Until. | -| *PerformUntilEnd()* | The prism is semi-infinite, limited by the actual position of the base. | -| *PerformFromEnd(Until)* | The prism is semi-infinite, limited by the face Until. | -| *PerformThruAll()* | The prism is infinite. In the case of a depression, the result is similar to a cut with an infinite prism. In the case of a protrusion, infinite parts are not kept in the result. | +The snippets below show usage examples: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} + BRepOffsetAPI_MakeOffsetShape OffsetMaker1; + // Computes offset shape using analytical continuation mechanism. + OffsetMaker1.PerformByJoin(Shape, OffsetValue, Tolerance); + if (OffsetMaker1.IsDone()) + NewShape = OffsetMaker1.Shape(); + + BRepOffsetAPI_MakeOffsetShape OffsetMaker2; + // Computes offset shape using simple algorithm. + OffsetMaker2.PerformBySimple(Shape, OffsetValue); + if (OffsetMaker2.IsDone()) + NewShape = OffsetMaker2.Shape(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**Note** that *Add* method can be used before *Perform* methods to indicate that a face generated by an edge slides onto a face of the base shape. +@subsubsection occt_modalg_7_2 Shelling -In the following sequence, a protrusion is performed, i.e. a face of the shape is changed into a prism. +Shelling is used to offset given faces of a solid by a specific value. It rounds or intersects adjacent faces along its edges depending on the convexity of the edge. +The MakeThickSolidByJoin method of the *BRepOffsetAPI_MakeThickSolid* takes the solid, the list of faces to remove and an offset value as input. ~~~~~ -TopoDS_Shape Sbase = ...; // an initial shape -TopoDS_Face Fbase = ....; // a base of prism - -gp_Dir Extrusion (.,.,.); +TopoDS_Solid SolidInitial = ...; -// An empty face is given as the sketch face +Standard_Real Of = ...; +TopTools_ListOfShape LCF; +TopoDS_Shape Result; +Standard_Real Tol = Precision::Confusion(); -BRepFeat_MakePrism thePrism(Sbase, Fbase, TopoDS_Face(), Extrusion, Standard_True, Standard_True); +for (Standard_Integer i = 1 ;i <= n; i++) { + TopoDS_Face SF = ...; // a face from SolidInitial + LCF.Append(SF); +} -thePrism, Perform(100.); -if (thePrism.IsDone()) { - TopoDS_Shape theResult = thePrism; - ... -} +BRepOffsetAPI_MakeThickSolid SolidMaker; +SolidMaker.MakeThickSolidByJoin(SolidInitial, + LCF, + Of, + Tol); +if (SolidMaker.IsDone()) + Result = SolidMaker.Shape(); ~~~~~ -@figure{/user_guides/modeling_algos/images/modeling_algos_image047.png,"Fusion with MakePrism",320} - -@figure{/user_guides/modeling_algos/images/modeling_algos_image048.png,"Creating a prism between two faces with Perform()",320} +@figure{/user_guides/modeling_algos/images/modeling_algos_image042.png,"Shelling",420} -@subsubsection occt_modalg_9_1_2 Draft Prism +Also it is possible to create solid between shell, offset shell. This functionality can be called using *BRepOffsetAPI_MakeThickSolid::MakeThickSolidBySimple* method. The code below shows usage example: -The class *BRepFeat_MakeDPrism* is used to build draft prism topologies interacting with a basis shape. These can be depressions or protrusions. A class object is created or initialized from: - * a shape (basic shape), - * the base of the prism, - * a face (face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not), - * an angle, - * a Boolean indicating the type of operation (fusion=protrusion or cut=depression) on the basic shape, - * another Boolean indicating if self-intersections have to be found (not used in every case). - -Evidently the input data for MakeDPrism are the same as for MakePrism except for a new parameter Angle and a missing parameter Direction: the direction of the prism generation is determined automatically as the normal to the base of the prism. -The semantics of draft prism feature creation is based on the construction of shapes: - * along a length - * up to a limiting face - * from a limiting face to a height. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} + BRepOffsetAPI_MakeThickSolid SolidMaker; + SolidMaker.MakeThickSolidBySimple(Shell, OffsetValue); + if (myDone.IsDone()) + Solid = SolidMaker.Shape(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The shape defining construction of the draft prism feature can be either the supporting edge or the concerned area of a face. +@subsubsection occt_modalg_7_3 Draft Angle -In case of the supporting edge, this contour can be attached to a face of the basis shape by binding. When the contour is bound to this face, the information that the contour will slide on the face becomes available to the relevant class methods. -In case of the concerned area of a face, it is possible to cut it out and move it to a different height, which will define the limiting face of a protrusion or depression direction . +*BRepOffsetAPI_DraftAngle* class allows modifying a shape by applying draft angles to its planar, cylindrical and conical faces. -The *Perform* methods are the same as for *MakePrism*. -~~~~~ -TopoDS_Shape S = BRepPrimAPI_MakeBox(400.,250.,300.); -TopExp_Explorer Ex; -Ex.Init(S,TopAbs_FACE); -Ex.Next(); -Ex.Next(); -Ex.Next(); -Ex.Next(); -Ex.Next(); -TopoDS_Face F = TopoDS::Face(Ex.Current()); -Handle(Geom_Surface) surf = BRep_Tool::Surface(F); -gp_Circ2d -c(gp_Ax2d(gp_Pnt2d(200.,130.),gp_Dir2d(1.,0.)),50.); -BRepBuilderAPI_MakeWire MW; -Handle(Geom2d_Curve) aline = new Geom2d_Circle(c); -MW.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,PI)); -MW.Add(BRepBuilderAPI_MakeEdge(aline,surf,PI,2.*PI)); -BRepBuilderAPI_MakeFace MKF; -MKF.Init(surf,Standard_False); -MKF.Add(MW.Wire()); -TopoDS_Face FP = MKF.Face(); -BRepLib::BuildCurves3d(FP); -BRepFeat_MakeDPrism MKDP (S,FP,F,10*PI180,Standard_True, - Standard_True); -MKDP.Perform(200); -TopoDS_Shape res1 = MKDP.Shape(); -~~~~~ +The class is created or initialized from a shape, then faces to be modified are added; for each face, three arguments are used: + * Direction: the direction with which the draft angle is measured + * Angle: value of the angle + * Neutral plane: intersection between the face and the neutral plane is invariant. -@figure{/user_guides/modeling_algos/images/modeling_algos_image049.png,"A tapered prism",320} +The following code places a draft angle on several faces of a shape; the same direction, angle and neutral plane are used for each face: -@subsubsection occt_modalg_9_1_3 Revolution +~~~~~ +TopoDS_Shape myShape = ... +// The original shape +TopTools_ListOfShape ListOfFace; +// Creation of the list of faces to be modified +... -The class *BRepFeat_MakeRevol* is used to build a revolution interacting with a shape. It is created or initialized from: - * a shape (the basic shape,) - * the base of the revolution, - * a face (the face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not), - * an axis of revolution, - * a boolean indicating the type of operation (fusion=protrusion or cut=depression) on the basic shape, - * another boolean indicating whether the self-intersections have to be found (not used in every case). +gp_Dir Direc(0.,0.,1.); +// Z direction +Standard_Real Angle = 5.*PI/180.; +// 5 degree angle +gp_Pln Neutral(gp_Pnt(0.,0.,5.), Direc); +// Neutral plane Z=5 +BRepOffsetAPI_DraftAngle theDraft(myShape); +TopTools_ListIteratorOfListOfShape itl; +for (itl.Initialize(ListOfFace); itl.More(); itl.Next()) { + theDraft.Add(TopoDS::Face(itl.Value()),Direc,Angle,Neutral); + if (!theDraft.AddDone()) { + // An error has occurred. The faulty face is given by // ProblematicShape + break; + } +} +if (!theDraft.AddDone()) { + // An error has occurred + TopoDS_Face guilty = theDraft.ProblematicShape(); + ... +} +theDraft.Build(); +if (!theDraft.IsDone()) { + // Problem encountered during reconstruction + ... +} +else { + TopoDS_Shape myResult = theDraft.Shape(); + ... +} +~~~~~ -There are four Perform methods: -| Method | Description | -| :--------------- | :------------ | -| *Perform(Angle)* | The resulting revolution is of the given magnitude. | -| *Perform(Until)* | The revolution is defined between the actual position of the base and the given face. | -| *Perform(From, Until)* | The revolution is defined between the two faces, From and Until. | -| *PerformThruAll()* | The result is similar to Perform(2*PI). | +@figure{/user_guides/modeling_algos/images/modeling_algos_image043.png,"DraftAngle",420} -**Note** that *Add* method can be used before *Perform* methods to indicate that a face generated by an edge slides onto a face of the base shape. +@subsubsection occt_modalg_7_4 Pipe Constructor +*BRepOffsetAPI_MakePipe* class allows creating a pipe from a Spine, which is a Wire and a Profile which is a Shape. This implementation is limited to spines with smooth transitions, sharp transitions are precessed by *BRepOffsetAPI_MakePipeShell*. To be more precise the continuity must be G1, which means that the tangent must have the same direction, though not necessarily the same magnitude, at neighboring edges. -In the following sequence, a face is revolved and the revolution is limited by a face of the base shape. +The angle between the spine and the profile is preserved throughout the pipe. ~~~~~ -TopoDS_Shape Sbase = ...; // an initial shape -TopoDS_Face Frevol = ....; // a base of prism -TopoDS_Face FUntil = ....; // face limiting the revol - -gp_Dir RevolDir (.,.,.); -gp_Ax1 RevolAx(gp_Pnt(.,.,.), RevolDir); - -// An empty face is given as the sketch face - -BRepFeat_MakeRevol theRevol(Sbase, Frevol, TopoDS_Face(), RevolAx, Standard_True, Standard_True); - -theRevol.Perform(FUntil); -if (theRevol.IsDone()) { - TopoDS_Shape theResult = theRevol; - ... -} +TopoDS_Wire Spine = ...; +TopoDS_Shape Profile = ...; +TopoDS_Shape Pipe = BRepOffsetAPI_MakePipe(Spine,Profile); ~~~~~ -@subsubsection occt_modalg_9_1_4 Pipe +@figure{/user_guides/modeling_algos/images/modeling_algos_image044.png,"Example of a Pipe",320} -The class *BRepFeat_MakePipe* constructs compound shapes with pipe features: depressions or protrusions. A class object is created or initialized from: - * a shape (basic shape), - * a base face (profile of the pipe) - * a face (face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not), - * a spine wire - * a Boolean indicating the type of operation (fusion=protrusion or cut=depression) on the basic shape, - * another Boolean indicating if self-intersections have to be found (not used in every case). +@subsubsection occt_modalg_7_5 Evolved Solid -There are three Perform methods: -| Method | Description | -| :-------- | :---------- | -| *Perform()* | The pipe is defined along the entire path (spine wire) | -| *Perform(Until)* | The pipe is defined along the path until a given face | -| *Perform(From, Until)* | The pipe is defined between the two faces From and Until | +*BRepOffsetAPI_MakeEvolved* class allows creating an evolved solid from a Spine (planar face or wire) and a profile (wire). -Let us have a look at the example: +The evolved solid is an unlooped sweep generated by the spine and the profile. -~~~~~ -TopoDS_Shape S = BRepPrimAPI_MakeBox(400.,250.,300.); -TopExp_Explorer Ex; -Ex.Init(S,TopAbs_FACE); -Ex.Next(); -Ex.Next(); -TopoDS_Face F1 = TopoDS::Face(Ex.Current()); -Handle(Geom_Surface) surf = BRep_Tool::Surface(F1); -BRepBuilderAPI_MakeWire MW1; -gp_Pnt2d p1,p2; -p1 = gp_Pnt2d(100.,100.); -p2 = gp_Pnt2d(200.,100.); -Handle(Geom2d_Line) aline = GCE2d_MakeLine(p1,p2).Value(); +The evolved solid is created by sweeping the profile’s reference axes on the spine. The origin of the axes moves to the spine, the X axis and the local tangent coincide and the Z axis is normal to the face. -MW1.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,p1.Distance(p2))); -p1 = p2; -p2 = gp_Pnt2d(150.,200.); -aline = GCE2d_MakeLine(p1,p2).Value(); +The reference axes of the profile can be defined following two distinct modes: -MW1.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,p1.Distance(p2))); -p1 = p2; -p2 = gp_Pnt2d(100.,100.); -aline = GCE2d_MakeLine(p1,p2).Value(); +* The reference axes of the profile are the origin axes. +* The references axes of the profile are calculated as follows: + + the origin is given by the point on the spine which is the closest to the profile + + the X axis is given by the tangent to the spine at the point defined above + + the Z axis is the normal to the plane which contains the spine. -MW1.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,p1.Distance(p2))); -BRepBuilderAPI_MakeFace MKF1; -MKF1.Init(surf,Standard_False); -MKF1.Add(MW1.Wire()); -TopoDS_Face FP = MKF1.Face(); -BRepLib::BuildCurves3d(FP); -TColgp_Array1OfPnt CurvePoles(1,3); -gp_Pnt pt = gp_Pnt(150.,0.,150.); -CurvePoles(1) = pt; -pt = gp_Pnt(200.,100.,150.); -CurvePoles(2) = pt; -pt = gp_Pnt(150.,200.,150.); -CurvePoles(3) = pt; -Handle(Geom_BezierCurve) curve = new Geom_BezierCurve -(CurvePoles); -TopoDS_Edge E = BRepBuilderAPI_MakeEdge(curve); -TopoDS_Wire W = BRepBuilderAPI_MakeWire(E); -BRepFeat_MakePipe MKPipe (S,FP,F1,W,Standard_False, -Standard_True); -MKPipe.Perform(); -TopoDS_Shape res1 = MKPipe.Shape(); +~~~~~ +TopoDS_Face Spine = ...; +TopoDS_Wire Profile = ...; +TopoDS_Shape Evol = +BRepOffsetAPI_MakeEvolved(Spine,Profile); ~~~~~ -@figure{/user_guides/modeling_algos/images/modeling_algos_image050.png,"Pipe depression",240} +@subsection occt_modalg_3b Object Modification -@subsection occt_modalg_9_2 Mechanical Features +@subsubsection occt_modalg_3b_1 Transformation +*BRepBuilderAPI_Transform* class can be used to apply a transformation to a shape (see class *gp_Trsf*). The methods have a boolean argument to copy or share the original shape, as long as the transformation allows (it is only possible for direct isometric transformations). By default, the original shape is shared. -Mechanical features include ribs, protrusions and grooves (or slots), depressions along planar (linear) surfaces or revolution surfaces. +The following example deals with the rotation of shapes. -The semantics of mechanical features is built around giving thickness to a contour. This thickness can either be symmetrical -- on one side of the contour -- or dissymmetrical -- on both sides. As in the semantics of form features, the thickness is defined by construction of shapes in specific contexts. +~~~~~ + +TopoDS_Shape myShape1 = ...; +// The original shape 1 +TopoDS_Shape myShape2 = ...; +// The original shape2 +gp_Trsf T; +T.SetRotation(gp_Ax1(gp_Pnt(0.,0.,0.),gp_Vec(0.,0.,1.)), +2.*PI/5.); +BRepBuilderAPI_Transformation theTrsf(T); +theTrsf.Perform(myShape1); +TopoDS_Shape myNewShape1 = theTrsf.Shape() +theTrsf.Perform(myShape2,Standard_True); +// Here duplication is forced +TopoDS_Shape myNewShape2 = theTrsf.Shape() +~~~~~ -The development contexts differ, however, in the case of mechanical features. -Here they include extrusion: - * to a limiting face of the basis shape; - * to or from a limiting plane; - * to a height. +@subsubsection occt_modalg_3b_2 Duplication -A class object is created or initialized from - * a shape (basic shape); - * a wire (base of rib or groove); - * a plane (plane of the wire); - * direction1 (a vector along which thickness will be built up); - * direction2 (vector opposite to the previous one along which thickness will be built up, may be null); - * a Boolean indicating the type of operation (fusion=rib or cut=groove) on the basic shape; - * another Boolean indicating if self-intersections have to be found (not used in every case). - -@subsubsection occt_modalg_9_2_1 Linear Form - -Linear form is implemented in *MakeLinearForm* class, which creates a rib or a groove along a planar surface. There is one *Perform()* method, which performs a prism from the wire along the *direction1* and *direction2* interacting with base shape *Sbase*. The height of the prism is *Magnitude(Direction1)+Magnitude(direction2)*. +Use the *BRepBuilderAPI_Copy* class to duplicate a shape. A new shape is thus created. +In the following example, a solid is copied: ~~~~~ -BRepBuilderAPI_MakeWire mkw; -gp_Pnt p1 = gp_Pnt(0.,0.,0.); -gp_Pnt p2 = gp_Pnt(200.,0.,0.); -mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); -p1 = p2; -p2 = gp_Pnt(200.,0.,50.); -mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); -p1 = p2; -p2 = gp_Pnt(50.,0.,50.); -mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); -p1 = p2; -p2 = gp_Pnt(50.,0.,200.); -mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); -p1 = p2; -p2 = gp_Pnt(0.,0.,200.); -mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); -p1 = p2; -mkw.Add(BRepBuilderAPI_MakeEdge(p2,gp_Pnt(0.,0.,0.))); -TopoDS_Shape S = BRepBuilderAPI_MakePrism(BRepBuilderAPI_MakeFace - (mkw.Wire()),gp_Vec(gp_Pnt(0.,0.,0.),gp_P - nt(0.,100.,0.))); -TopoDS_Wire W = BRepBuilderAPI_MakeWire(BRepBuilderAPI_MakeEdge(gp_Pnt - (50.,45.,100.), -gp_Pnt(100.,45.,50.))); -Handle(Geom_Plane) aplane = - new Geom_Plane(gp_Pnt(0.,45.,0.), gp_Vec(0.,1.,0.)); -BRepFeat_MakeLinearForm aform(S, W, aplane, gp_Dir - (0.,5.,0.), gp_Dir(0.,-3.,0.), 1, Standard_True); -aform.Perform(); -TopoDS_Shape res = aform.Shape(); -~~~~~ +TopoDS Solid MySolid; +....// Creates a solid -@figure{/user_guides/modeling_algos/images/modeling_algos_image051.png,"Creating a rib",240} +TopoDS_Solid myCopy = BRepBuilderAPI_Copy(mySolid); +~~~~~ -@subsubsection occt_modalg_9_2_3 Gluer +@subsection occt_modalg_3a_1 Error Handling in the Topology API -The class *BRepFeat_Gluer* allows gluing two solids along faces. The contact faces of the glued shape must not have parts outside the contact faces of the basic shape. Upon completion the algorithm gives the glued shape with cut out parts of faces inside the shape. +A method can report an error in the two following situations: + * The data or arguments of the method are incorrect, i.e. they do not respect the restrictions specified by the methods in its specifications. Typical example: creating a linear edge from two identical points is likely to lead to a zero divide when computing the direction of the line. + * Something unexpected happened. This situation covers every error not included in the first category. Including: interruption, programming errors in the method or in another method called by the first method, bad specifications of the arguments (i.e. a set of arguments that was not expected to fail). -The class is created or initialized from two shapes: the “glued” shape and the basic shape (on which the other shape is glued). -Two *Bind* methods are used to bind a face of the glued shape to a face of the basic shape and an edge of the glued shape to an edge of the basic shape. +The second situation is supposed to become increasingly exceptional as a system is debugged and it is handled by the **exception mechanism**. Using exceptions avoids handling error statuses in the call to a method: a very cumbersome style of programming. -**Note** that every face and edge has to be bounded, if two edges of two glued faces are coincident they must be explicitly bounded. +In the first situation, an exception is also supposed to be raised because the calling method should have verified the arguments and if it did not do so, there is a bug. For example, if before calling *MakeEdge* you are not sure that the two points are non-identical, this situation must be tested. -~~~~~ -TopoDS_Shape Sbase = ...; // the basic shape -TopoDS_Shape Sglued = ...; // the glued shape +Making those validity checks on the arguments can be tedious to program and frustrating as you have probably correctly surmised that the method will perform the test twice. It does not trust you. +As the test involves a great deal of computation, performing it twice is also time-consuming. -TopTools_ListOfShape Lfbase; -TopTools_ListOfShape Lfglued; -// Determination of the glued faces -... +Consequently, you might be tempted to adopt the highly inadvisable style of programming illustrated in the following example: -BRepFeat_Gluer theGlue(Sglue, Sbase); -TopTools_ListIteratorOfListOfShape itlb(Lfbase); -TopTools_ListIteratorOfListOfShape itlg(Lfglued); -for (; itlb.More(); itlb.Next(), itlg(Next()) { -const TopoDS_Face& f1 = TopoDS::Face(itlg.Value()); -const TopoDS_Face& f2 = TopoDS::Face(itlb.Value()); -theGlue.Bind(f1,f2); -// for example, use the class FindEdges from LocOpe to -// determine coincident edges -LocOpe_FindEdge fined(f1,f2); -for (fined.InitIterator(); fined.More(); fined.Next()) { -theGlue.Bind(fined.EdgeFrom(),fined.EdgeTo()); -} +~~~~~ +#include +try { +TopoDS_Edge E = BRepBuilderAPI_MakeEdge(P1,P2); +// go on with the edge } -theGlue.Build(); -if (theGlue.IsDone() { -TopoDS_Shape theResult = theGlue; -... +catch { +// process the error. } ~~~~~ -@subsubsection occt_modalg_9_2_4 Split Shape - -The class *BRepFeat_SplitShape* is used to split faces of a shape into wires or edges. The shape containing the new entities is rebuilt, sharing the unmodified ones. - -The class is created or initialized from a shape (the basic shape). -Three Add methods are available: -* *Add(Wire, Face)* -- adds a new wire on a face of the basic shape. -* *Add(Edge, Face)* -- adds a new edge on a face of the basic shape. -* *Add(EdgeNew, EdgeOld)* -- adds a new edge on an existing one (the old edge must contain the new edge). +To help the user, the Topology API classes only raise the exception *StdFail_NotDone*. Any other exception means that something happened which was unforeseen in the design of this API. -**Note** The added wires and edges must define closed wires on faces or wires located between two existing edges. Existing edges must not be intersected. +The *NotDone* exception is only raised when the user tries to access the result of the computation and the original data is corrupted. At the construction of the class instance, if the algorithm cannot be completed, the internal flag *NotDone* is set. This flag can be tested and in some situations a more complete description of the error can be queried. If the user ignores the *NotDone* status and tries to access the result, an exception is raised. ~~~~~ -TopoDS_Shape Sbase = ...; // basic shape -TopoDS_Face Fsplit = ...; // face of Sbase -TopoDS_Wire Wsplit = ...; // new wire contained in Fsplit -BRepFeat_SplitShape Spls(Sbase); -Spls.Add(Wsplit, Fsplit); -TopoDS_Shape theResult = Spls; -... +BRepBuilderAPI_MakeEdge ME(P1,P2); +if (!ME.IsDone()) { +// doing ME.Edge() or E = ME here +// would raise StdFail_NotDone +Standard_DomainError::Raise +(“ProcessPoints::Failed to create an edge”); +} +TopoDS_Edge E = ME; ~~~~~ -@section occt_modalg_10 Hidden Line Removal +@subsection occt_modalg_8 Sewing -To provide the precision required in industrial design, drawings need to offer the possibility of removing lines, which are hidden in a given projection. +@subsubsection occt_modalg_8_1 Introduction -For this the Hidden Line Removal component provides two algorithms: *HLRBRep_Algo* and *HLRBRep_PolyAlgo*. +Sewing allows creation of connected topology (shells and wires) from a set of separate topological elements (faces and edges). For example, Sewing can be used to create of shell from a compound of separate faces. -These algorithms are based on the principle of comparing each edge of the shape to be visualized with each of its faces, and calculating the visible and the hidden parts of each edge. Note that these are not the algorithms used in generating shading, which calculate the visible and hidden parts of each face in a shape to be visualized by comparing each face in the shape with every other face in the same shape. -These algorithms operate on a shape and remove or indicate edges hidden by faces. For a given projection, they calculate a set of lines characteristic of the object being represented. They are also used in conjunction with extraction utilities, which reconstruct a new, simplified shape from a selection of the results of the calculation. This new shape is made up of edges, which represent the shape visualized in the projection. +@figure{/user_guides/modeling_algos/images/modeling_algos_image045.png,"Shapes with partially shared edges",320} -*HLRBRep_Algo* allows working with the shape itself, whereas *HLRBRep_PolyAlgo* works with a polyhedral simplification of the shape. When you use *HLRBRep_Algo*, you obtain an exact result, whereas, when you use *HLRBRep_PolyAlgo*, you reduce the computation time, but obtain polygonal segments. +It is important to distinguish between sewing and other procedures, which modify the geometry, such as filling holes or gaps, gluing, bending curves and surfaces, etc. -No smoothing algorithm is provided. Consequently, a polyhedron will be treated as such and the algorithms will give the results in form of line segments conforming to the mathematical definition of the polyhedron. This is always the case with *HLRBRep_PolyAlgo*. +Sewing does not change geometrical representation of the shapes. Sewing applies to topological elements (faces, edges) which are not connected but can be connected because they are geometrically coincident : it adds the information about topological connectivity. Already connected elements are left untouched in case of manifold sewing. -*HLRBRep_Algo* and *HLRBRep_PolyAlgo* can deal with any kind of object, for example, assemblies of volumes, surfaces, and lines, as long as there are no unfinished objects or points within it. +Let us define several terms: +* **Floating edges** do not belong to any face; +* **Free boundaries** belong to one face only; +* **Shared edges** belong to several faces, (i.e. two faces in a manifold topology). +* **Sewn faces** should have edges shared with each other. +* **Sewn edges** should have vertices shared with each other. -However, there some restrictions in HLR use: - * Points are not processed; - * Infinite faces or lines are not processed. +@subsubsection occt_modalg_8_2 Sewing Algorithm - -@figure{/user_guides/modeling_algos/images/modeling_algos_image052.png,"Sharp, smooth and sewn edges in a simple screw shape",320} +The sewing algorithm is one of the basic algorithms used for shape processing, therefore its quality is very important. -@figure{/user_guides/modeling_algos/images/modeling_algos_image053.png,"Outline edges and isoparameters in the same shape",320} +Sewing algorithm is implemented in the class *BRepBuilder_Sewing*. This class provides the following methods: +* loading initial data for global or local sewing; +* setting customization parameters, such as special operation modes, tolerances and output results; +* applying analysis methods that can be used to obtain connectivity data required by external algorithms; +* sewing of the loaded shapes. -@figure{/user_guides/modeling_algos/images/modeling_algos_image054.png,"A simple screw shape seen with shading",320} +Sewing supports working mode with big value tolerance. It is not necessary to repeat sewing step by step while smoothly increasing tolerance. -@figure{/user_guides/modeling_algos/images/modeling_algos_image055.png,"An extraction showing hidden sharp edges",320} +It is also possible to sew edges to wire and to sew locally separate faces and edges from a shape. +The Sewing algorithm can be subdivided into several independent stages, some of which can be turned on or off using Boolean or other flags. -The following services are related to Hidden Lines Removal : +In brief, the algorithm should find a set of merge candidates for each free boundary, filter them according to certain criteria, and finally merge the found candidates and build the resulting sewn shape. -### Loading Shapes +Each stage of the algorithm or the whole algorithm can be adjusted with the following parameters: +* **Working tolerance** defines the maximal distance between topological elements which can be sewn. It is not ultimate that such elements will be actually sewn as many other criteria are applied to make the final decision. +* **Minimal tolerance** defines the size of the smallest element (edge) in the resulting shape. It is declared that no edges with size less than this value are created after sewing. If encountered, such topology becomes degenerated. +* **Non-manifold mode** enables sewing of non-manifold topology. -To pass a *TopoDS_Shape* to an *HLRBRep_Algo* object, use *HLRBRep_Algo::Add*. With an *HLRBRep_PolyAlgo* object, use *HLRBRep_PolyAlgo::Load*. If you wish to add several shapes, use Add or Load as often as necessary. +#### Example -### Setting view parameters +To connect a set of *n* contiguous but independent faces, do the following: -*HLRBRep_Algo::Projector* and *HLRBRep_PolyAlgo::Projector* set a projector object which defines the parameters of the view. This object is an *HLRAlgo_Projector*. +~~~~~ + BRepBuilderAPI_Sewing Sew; + Sew.Add(Face1); + Sew.Add(Face2); + ... + Sew.Add(Facen); + Sew.Perform(); + TopoDS_Shape result= Sew.SewedShape(); +~~~~~ -### Computing the projections +If all faces have been sewn correctly, the result is a shell. Otherwise, it is a compound. After a successful sewing operation all faces have a coherent orientation. -*HLRBRep_PolyAlgo::Update* launches the calculation of outlines of the shape visualized by the *HLRBRep_PolyAlgo* framework. +@subsubsection occt_modalg_8_3 Tolerance Management -In the case of *HLRBRep_Algo*, use *HLRBRep_Algo::Update*. With this algorithm, you must also call the method *HLRBRep_Algo::Hide* to calculate visible and hidden lines of the shape to be visualized. With an *HLRBRep_PolyAlgo* object, visible and hidden lines are computed by *HLRBRep_PolyHLRToShape*. +To produce a closed shell, Sewing allows specifying the value of working tolerance, exceeding the size of small faces belonging to the shape. -### Extracting edges +However, if we produce an open shell, it is possible to get incorrect sewing results if the value of working tolerance is too large (i.e. it exceeds the size of faces lying on an open boundary). -The classes *HLRBRep_HLRToShape* and *HLRBRep_PolyHLRToShape* present a range of extraction filters for an *HLRBRep_Algo object* and an *HLRBRep_PolyAlgo* object, respectively. They highlight the type of edge from the results calculated by the algorithm on a shape. With both extraction classes, you can highlight the following types of output: - * visible/hidden sharp edges; - * visible/hidden smooth edges; - * visible/hidden sewn edges; - * visible/hidden outline edges. +The following recommendations can be proposed for tuning-up the sewing process: +- Use as small working tolerance as possible. This will reduce the sewing time and, consequently, the number of incorrectly sewn edges for shells with free boundaries. +- Use as large minimal tolerance as possible. This will reduce the number of small geometry in the shape, both original and appearing after cutting. +- If it is expected to obtain a shell with holes (free boundaries) as a result of sewing, the working tolerance should be set to a value not greater than the size of the smallest element (edge) or smallest distance between elements of such free boundary. Otherwise the free boundary may be sewn only partially. +- It should be mentioned that the Sewing algorithm is unable to understand which small (less than working tolerance) free boundary should be kept and which should be sewn. -To perform extraction on an *HLRBRep_PolyHLRToShape* object, use *HLRBRep_PolyHLRToShape::Update* function. +@subsubsection occt_modalg_8_4 Manifold and Non-manifold Sewing -For an *HLRBRep_HLRToShape* object built from an *HLRBRepAlgo* object you can also highlight: - * visible isoparameters and - * hidden isoparameters. +To create one or several shells from a set of faces, sewing merges edges, which belong to different faces or one closed face. -@subsection occt_modalg_10_1 Examples +Face sewing supports manifold and non manifold modes. Manifold mode can produce only a manifold shell. Sewing should be used in the non manifold mode to create non manifold shells. -### HLRBRep_Algo +Manifold sewing of faces merges only two nearest edges belonging to different faces or one closed face with each other. Non manifold sewing of faces merges all edges at a distance less than the specified tolerance. -~~~~~ -// Build The algorithm object -myAlgo = new HLRBRep_Algo(); +For a complex topology it is advisable to apply first the manifold sewing and then the non manifold sewing a minimum possible working tolerance. However, this is not necessary for a easy topology. -// Add Shapes into the algorithm -TopTools_ListIteratorOfListOfShape anIterator(myListOfShape); -for (;anIterator.More();anIterator.Next()) -myAlgo-Add(anIterator.Value(),myNbIsos); +Giving a large tolerance value to non manifold sewing will cause a lot of incorrectness since all nearby geometry will be sewn. -// Set The Projector (myProjector is a -HLRAlgo_Projector) -myAlgo-Projector(myProjector); +@subsubsection occt_modalg_8_5 Local Sewing -// Build HLR -myAlgo->Update(); +If a shape still has some non-sewn faces or edges after sewing, it is possible to use local sewing with a greater tolerance. -// Set The Edge Status -myAlgo->Hide(); +Local sewing is especially good for open shells. It allows sewing an unwanted hole in one part of the shape and keeping a required hole, which is smaller than the working tolerance specified for the local sewing in the other part of the shape. Local sewing is much faster than sewing on the whole shape. -// Build the extraction object : -HLRBRep_HLRToShape aHLRToShape(myAlgo); +All preexisting connections of the whole shape are kept after local sewing. -// extract the results : -TopoDS_Shape VCompound = aHLRToShape.VCompound(); -TopoDS_Shape Rg1LineVCompound = -aHLRToShape.Rg1LineVCompound(); -TopoDS_Shape RgNLineVCompound = -aHLRToShape.RgNLineVCompound(); -TopoDS_Shape OutLineVCompound = -aHLRToShape.OutLineVCompound(); -TopoDS_Shape IsoLineVCompound = -aHLRToShape.IsoLineVCompound(); -TopoDS_Shape HCompound = aHLRToShape.HCompound(); -TopoDS_Shape Rg1LineHCompound = -aHLRToShape.Rg1LineHCompound(); -TopoDS_Shape RgNLineHCompound = -aHLRToShape.RgNLineHCompound(); -TopoDS_Shape OutLineHCompound = -aHLRToShape.OutLineHCompound(); -TopoDS_Shape IsoLineHCompound = -aHLRToShape.IsoLineHCompound(); -~~~~~ +For example, if you want to sew two open shells having coincided free edges using local sewing, it is necessary to create a compound from two shells then load the full compound using method *BRepBuilderAPI_Sewing::Load()*. After that it is necessary to add local sub-shapes, which should be sewn using method *BRepBuilderAPI_Sewing::Add()*. The result of sewing can be obtained using method *BRepBuilderAPI_Sewing::SewedShape()*. + +See the example: + +~~~~ -### HLRBRep_PolyAlgo +//initial sewn shapes +TopoDS_Shape aS1, aS2; // these shapes are expected to be well sewn shells +TopoDS_Shape aComp; +BRep_Builder aB; +aB.MakeCompound(aComp); +aB.Add(aComp, aS1); +aB.Add(aComp, aS2); +................................ +aSewing.Load(aComp); +//sub shapes which should be locally sewed +aSewing.Add(aF1); +aSewing.Add(aF2); +//performing sewing +aSewing.Perform(); +//result shape +TopoDS_Shape aRes = aSewing.SewedShape(); -~~~~~ +~~~~ -// Build The algorithm object -myPolyAlgo = new HLRBRep_PolyAlgo(); +@subsection occt_modalg_9 Features -// Add Shapes into the algorithm -TopTools_ListIteratorOfListOfShape -anIterator(myListOfShape); -for (;anIterator.More();anIterator.Next()) -myPolyAlgo-Load(anIterator.Value()); +This library contained in *BRepFeat* package is necessary for creation and manipulation of form and mechanical features that go beyond the classical boundary representation of shapes. In that sense, *BRepFeat* is an extension of *BRepBuilderAPI* package. -// Set The Projector (myProjector is a -HLRAlgo_Projector) -myPolyAlgo->Projector(myProjector); +@subsubsection occt_modalg_9_1 Form Features -// Build HLR -myPolyAlgo->Update(); +The form features are depressions or protrusions including the following types: -// Build the extraction object : -HLRBRep_PolyHLRToShape aPolyHLRToShape; -aPolyHLRToShape.Update(myPolyAlgo); + * Cylinder; + * Draft Prism; + * Prism; + * Revolved feature; + * Pipe. -// extract the results : -TopoDS_Shape VCompound = -aPolyHLRToShape.VCompound(); -TopoDS_Shape Rg1LineVCompound = -aPolyHLRToShape.Rg1LineVCompound(); -TopoDS_Shape RgNLineVCompound = -aPolyHLRToShape.RgNLineVCompound(); -TopoDS_Shape OutLineVCompound = -aPolyHLRToShape.OutLineVCompound(); -TopoDS_Shape HCompound = -aPolyHLRToShape.HCompound(); -TopoDS_Shape Rg1LineHCompound = -aPolyHLRToShape.Rg1LineHCompound(); -TopoDS_Shape RgNLineHCompound = -aPolyHLRToShape.RgNLineHCompound(); -TopoDS_Shape OutLineHCompound = -aPolyHLRToShape.OutLineHCompound(); -~~~~~ +Depending on whether you wish to make a depression or a protrusion, +you can choose either to remove matter (Boolean cut: Fuse equal to 0) or to add it (Boolean fusion: Fuse equal to 1). -@section occt_modalg_11 Meshing +The semantics of form feature creation is based on the construction of shapes: -@subsection occt_modalg_11_1 Mesh presentations + * for a certain length in a certain direction; + * up to the limiting face; + * from the limiting face at a height; + * above and/or below a plane. -In addition to support of exact geometrical representation of 3D objects Open CASCADE Technology provides functionality to work with tessellated representations of objects in form of meshes. +The shape defining the construction of a feature can be either a supporting edge or a concerned area of a face. -Open CASCADE Technology mesh functionality provides: -- data structures to store surface mesh data associated to shapes, and some basic algorithms to handle these data -- data structures and algorithms to build surface triangular mesh from *BRep* objects (shapes). -- tools to extend 3D visualization capabilities of Open CASCADE Technology with displaying meshes along with associated pre- and post-processor data. +In case of supporting edge, this contour can be attached to a face of the basis shape by binding. When the contour is bound to this face, the information that the contour will slide on the face becomes available +to the relevant class methods. In case of the concerned area of a face, you can, for example, cut it out and move it at a different height, which defines the limiting face of a protrusion or depression. -Open CASCADE Technology includes two mesh converters: -- VRML converter translates Open CASCADE shapes to VRML 1.0 files (Virtual Reality Modeling Language). Open CASCADE shapes may be translated in two representations: shaded or wireframe. A shaded representation present shapes as sets of triangles computed by a mesh algorithm while a wireframe representation present shapes as sets of curves. -- STL converter translates Open CASCADE shapes to STL files. STL (STtereoLithography) format is widely used for rapid prototyping. +Topological definition with local operations of this sort makes calculations simpler +and faster than a global operation. The latter would entail a second phase +of removing unwanted matter to get the same result. -Open CASCADE SAS also offers Advanced Mesh Products: -- Open CASCADE Mesh Framework (OMF) -- Express Mesh +The *Form* from *BRepFeat* package is a deferred class used as a root for form features. It inherits *MakeShape* from *BRepBuilderAPI* and provides implementation of methods keep track of all sub-shapes. -Besides, we can efficiently help you in the fields of surface and volume meshing algorithms, mesh optimization algorithms etc. If you require a qualified advice about meshing algorithms, do not hesitate to benefit from the expertise of our team in that domain. +**Prism** -The projects dealing with numerical simulation can benefit from using SALOME - an Open Source Framework for CAE with CAD data interfaces, generic Pre- and Post- F.E. processors and API for integrating F.E. solvers. +The class *BRepFeat_MakePrism* is used to build a prism interacting with a shape. It is created or initialized from + * a shape (the basic shape), + * the base of the prism, + * a face (the face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not), + * a direction, + * a Boolean indicating the type of operation (fusion=protrusion or cut=depression) on the basic shape, + * another Boolean indicating if the self-intersections have to be found (not used in every case). -Learn more about SALOME platform on https://www.salome-platform.org +There are six Perform methods: +| Method | Description | +| :---------------------- | :------------------------------------- | +| *Perform(Height)* | The resulting prism is of the given length. | +| *Perform(Until)* | The prism is defined between the position of the base and the given face. | +| *Perform(From, Until)* | The prism is defined between the two faces From and Until. | +| *PerformUntilEnd()* | The prism is semi-infinite, limited by the actual position of the base. | +| *PerformFromEnd(Until)* | The prism is semi-infinite, limited by the face Until. | +| *PerformThruAll()* | The prism is infinite. In the case of a depression, the result is similar to a cut with an infinite prism. In the case of a protrusion, infinite parts are not kept in the result. | -@subsection occt_modalg_11_2 Meshing algorithm +**Note** that *Add* method can be used before *Perform* methods to indicate that a face generated by an edge slides onto a face of the base shape. -The algorithm of shape triangulation is provided by the functionality of *BRepMesh_IncrementalMesh* class, which adds a triangulation of the shape to its topological data structure. This triangulation is used to visualize the shape in shaded mode. +In the following sequence, a protrusion is performed, i.e. a face of the shape is changed into a prism. ~~~~~ -#include -#include -#include +TopoDS_Shape Sbase = ...; // an initial shape +TopoDS_Face Fbase = ....; // a base of prism -Standard_Boolean meshing_explicit_parameters() -{ - const Standard_Real aRadius = 10.0; - const Standard_Real aHeight = 25.0; - BRepPrimAPI_MakeCylinder aCylinder(aRadius, aHeight); - TopoDS_Shape aShape = aCylinder.Shape(); - - const Standard_Real aLinearDeflection = 0.01; - const Standard_Real anAngularDeflection = 0.5; - BRepMesh_IncrementalMesh aMesher (aShape, aLinearDeflection, Standard_False, anAngularDeflection, Standard_True); - const Standard_Integer aStatus = aMesher.GetStatusFlags(); - return !aStatus; -} +gp_Dir Extrusion (.,.,.); -Standard_Boolean meshing_imeshtools_parameters() -{ - const Standard_Real aRadius = 10.0; - const Standard_Real aHeight = 25.0; - BRepPrimAPI_MakeCylinder aCylinder(aRadius, aHeight); - TopoDS_Shape aShape = aCylinder.Shape(); - - IMeshTools_Parameters aMeshParams; - aMeshParams.Deflection = 0.01; - aMeshParams.Angle = 0.5; - aMeshParams.Relative = Standard_False; - aMeshParams.InParallel = Standard_True; - aMeshParams.MinSize = Precision::Confusion(); - aMeshParams.InternalVerticesMode = Standard_True; - aMeshParams.ControlSurfaceDeflection = Standard_True; - - BRepMesh_IncrementalMesh aMesher (aShape, aMeshParams); - const Standard_Integer aStatus = aMesher.GetStatusFlags(); - return !aStatus; -} -~~~~~ +// An empty face is given as the sketch face + +BRepFeat_MakePrism thePrism(Sbase, Fbase, TopoDS_Face(), Extrusion, Standard_True, Standard_True); -The default meshing algorithm *BRepMesh_IncrementalMesh* has two major options to define triangulation -- linear and angular deflections. +thePrism, Perform(100.); +if (thePrism.IsDone()) { + TopoDS_Shape theResult = thePrism; + ... +} +~~~~~ -At the first step all edges from a face are discretized according to the specified parameters. +@figure{/user_guides/modeling_algos/images/modeling_algos_image047.png,"Fusion with MakePrism",320} -At the second step, the faces are tessellated. Linear deflection limits the distance between a curve and its tessellation, whereas angular deflection limits the angle between subsequent segments in a polyline. +@figure{/user_guides/modeling_algos/images/modeling_algos_image048.png,"Creating a prism between two faces with Perform()",320} -@figure{/user_guides/modeling_algos/images/modeling_algos_image056.png,"Deflection parameters of BRepMesh_IncrementalMesh algorithm",420} +**Draft Prism** -There are additional options to control behavior of the meshing of face interior: *DeflectionInterior* and *AngleInterior*. *DeflectionInterior* limits the distance between triangles and the face interior. *AngleInterior* (used for tessellation of B-spline faces only) limits the angle between normals (N1, N2 and N3 in the picture) in the nodes of every link of the triangle. There is an exception for the links along the face boundary edges, "Angular Deflection" is used for them during edges discretization. +The class *BRepFeat_MakeDPrism* is used to build draft prism topologies interacting with a basis shape. These can be depressions or protrusions. A class object is created or initialized from: + * a shape (basic shape), + * the base of the prism, + * a face (face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not), + * an angle, + * a Boolean indicating the type of operation (fusion=protrusion or cut=depression) on the basic shape, + * another Boolean indicating if self-intersections have to be found (not used in every case). + +Evidently the input data for MakeDPrism are the same as for MakePrism except for a new parameter Angle and a missing parameter Direction: the direction of the prism generation is determined automatically as the normal to the base of the prism. +The semantics of draft prism feature creation is based on the construction of shapes: + * along a length + * up to a limiting face + * from a limiting face to a height. -@figure{/user_guides/modeling_algos/images/modeling_algos_image057.png,"Linear and angular interior deflections",420} +The shape defining construction of the draft prism feature can be either the supporting edge or the concerned area of a face. -Note that if a given value of linear deflection is less than shape tolerance then the algorithm will skip this value and will take into account the shape tolerance. +In case of the supporting edge, this contour can be attached to a face of the basis shape by binding. When the contour is bound to this face, the information that the contour will slide on the face becomes available to the relevant class methods. +In case of the concerned area of a face, it is possible to cut it out and move it to a different height, which will define the limiting face of a protrusion or depression direction . -The application should provide deflection parameters to compute a satisfactory mesh. Angular deflection is relatively simple and allows using a default value (12-20 degrees). Linear deflection has an absolute meaning and the application should provide the correct value for its models. Giving small values may result in a too huge mesh (consuming a lot of memory, which results in a long computation time and slow rendering) while big values result in an ugly mesh. +The *Perform* methods are the same as for *MakePrism*. -For an application working in dimensions known in advance it can be reasonable to use the absolute linear deflection for all models. This provides meshes according to metrics and precision used in the application (for example, it it is known that the model will be stored in meters, 0.004 m is enough for most tasks). +~~~~~ +TopoDS_Shape S = BRepPrimAPI_MakeBox(400.,250.,300.); +TopExp_Explorer Ex; +Ex.Init(S,TopAbs_FACE); +Ex.Next(); +Ex.Next(); +Ex.Next(); +Ex.Next(); +Ex.Next(); +TopoDS_Face F = TopoDS::Face(Ex.Current()); +Handle(Geom_Surface) surf = BRep_Tool::Surface(F); +gp_Circ2d +c(gp_Ax2d(gp_Pnt2d(200.,130.),gp_Dir2d(1.,0.)),50.); +BRepBuilderAPI_MakeWire MW; +Handle(Geom2d_Curve) aline = new Geom2d_Circle(c); +MW.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,PI)); +MW.Add(BRepBuilderAPI_MakeEdge(aline,surf,PI,2.*PI)); +BRepBuilderAPI_MakeFace MKF; +MKF.Init(surf,Standard_False); +MKF.Add(MW.Wire()); +TopoDS_Face FP = MKF.Face(); +BRepLib::BuildCurves3d(FP); +BRepFeat_MakeDPrism MKDP (S,FP,F,10*PI180,Standard_True, + Standard_True); +MKDP.Perform(200); +TopoDS_Shape res1 = MKDP.Shape(); +~~~~~ -However, an application that imports models created in other applications may not use the same deflection for all models. Note that actually this is an abnormal situation and this application is probably just a viewer for CAD models with dimensions varying by an order of magnitude. This problem can be solved by introducing the concept of a relative linear deflection with some LOD (level of detail). The level of detail is a scale factor for absolute deflection, which is applied to model dimensions. +@figure{/user_guides/modeling_algos/images/modeling_algos_image049.png,"A tapered prism",320} -Meshing covers a shape with a triangular mesh. Other than hidden line removal, you can use meshing to transfer the shape to another tool: a manufacturing tool, a shading algorithm, a finite element algorithm, or a collision algorithm. +**Revolution** -You can obtain information on the shape by first exploring it. To access triangulation of a face in the shape later, use *BRepTool::Triangulation*. To access a polygon, which is the approximation of an edge of the face, use *BRepTool::PolygonOnTriangulation*. +The class *BRepFeat_MakeRevol* is used to build a revolution interacting with a shape. It is created or initialized from: + * a shape (the basic shape,) + * the base of the revolution, + * a face (the face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not), + * an axis of revolution, + * a boolean indicating the type of operation (fusion=protrusion or cut=depression) on the basic shape, + * another boolean indicating whether the self-intersections have to be found (not used in every case). -@subsection occt_modalg_11_3 BRepMesh Architecture -@subsubsection occt_modalg_11_3_1 Goals +There are four Perform methods: +| Method | Description | +| :--------------- | :------------ | +| *Perform(Angle)* | The resulting revolution is of the given magnitude. | +| *Perform(Until)* | The revolution is defined between the actual position of the base and the given face. | +| *Perform(From, Until)* | The revolution is defined between the two faces, From and Until. | +| *PerformThruAll()* | The result is similar to Perform(2*PI). | -The main goals of the chosen architecture are: - * Remove tight connections between data structures, auxiliary tools and algorithms to create an extensible solution, easy for maintenance and improvements; - * Separate the code among several functional units responsible for specific operation for the sake of simplification of debugging and readability; - * Introduce new data structures enabling the possibility to manipulate a discrete model of a particular entity (edge, wire, face) in order to perform computations locally instead of processing the entire model; - * Implement a new triangulation algorithm replacing the existing functionality that contains overcomplicated solutions that need to be moved to the upper level. In addition, provide the possibility to change the algorithm depending on surface type (initially to speed up meshing of planes). +**Note** that *Add* method can be used before *Perform* methods to indicate that a face generated by an edge slides onto a face of the base shape. -@subsubsection occt_modalg_11_3_2 General workflow -@figure{/user_guides/modeling_algos/images/modeling_algos_mesh_001.svg,"General workflow of BRepMesh component",500} -Generally, the workflow of the component can be divided into six parts: - * **Creation of model data structure**: source *TopoDS_Shape* passed to algorithm is analyzed and exploded into faces and edges. The reflection corresponding to each topological entity is created in the data model. Note that underlying algorithms use the data model as input and access it via a common interface which allows creating a custom data model with necessary dependencies between particular entities (see the paragraph "Data model interface"); - * **Discretize edges 3D & 2D curves**: 3D curve as well as an associated set of 2D curves of each model edge is discretized in order to create a coherent skeleton used as a base in face meshing process. If an edge of the source shape already contains polygonal data which suits the specified parameters, it is extracted from the shape and stored in the model as is. Each edge is processed separately, the adjacency is not taken into account; - * **Heal discrete model**: the source *TopoDS_Shape* can contain problems, such as open wires or self-intersections, introduced during design, exchange or modification of model. In addition, some problems like self-intersections can be introduced by roughly discretized edges. This stage is responsible for analysis of a discrete model in order to detect and repair problems or to refuse further processing of a model part in case if a problem cannot be solved; - * **Preprocess discrete model**: defines actions specific to the implemented approach to be performed before meshing of faces. By default, this operation iterates over model faces, checks the consistency of existing triangulations and cleans topological faces and adjacent edges from polygonal data in case of inconsistency or marks a face of the discrete model as not required for the computation; - * **Discretize faces**: represents the core part performing mesh generation for a particular face based on 2D discrete data. This operation caches polygonal data associated with face edges in the data model for further processing and stores the generated mesh to *TopoDS_Face*; - * **Postprocess discrete model**: defines actions specific for the implemented approach to be performed after meshing of faces. By default, this operation stores polygonal data obtained at the previous stage to *TopoDS_Edge* objects of the source model. +In the following sequence, a face is revolved and the revolution is limited by a face of the base shape. -@subsubsection occt_modalg_11_3_3 Common interfaces -The component structure contains two units: IMeshData (see Data model interface) and IMeshTools, defining common interfaces for the data model and algorithmic tools correspondingly. Class *IMeshTools_Context* represents a connector between these units. The context class caches the data model as well as the tools corresponding to each of six stages of the workflow mentioned above and provides methods to call the corresponding tool safely (designed similarly to *IntTools_Context* in order to keep consistency with OCCT core tools). All stages, except for the first one, use the data model as input and perform a specific action on the entire structure. Thus, API class *IMeshTools_ModelAlgo* is defined in order to unify the interface of tools manipulating the data model. Each tool supposed to process the data model should inherit this interface enabling the possibility to cache it in context. In contrast to others, the model builder interface is defined by another class *IMeshTools_ModelBuilder* due to a different meaning of the stage. The entry point starting the entire workflow is represented by *IMeshTools_MeshBuilder*. +~~~~~ +TopoDS_Shape Sbase = ...; // an initial shape +TopoDS_Face Frevol = ....; // a base of prism +TopoDS_Face FUntil = ....; // face limiting the revol -The default implementation of *IMeshTools_Context* is given in *BRepMesh_Context* class initializing the context by instances of default algorithmic tools. +gp_Dir RevolDir (.,.,.); +gp_Ax1 RevolAx(gp_Pnt(.,.,.), RevolDir); -The factory interface *IMeshTools_MeshAlgoFactory* gives the possibility to change the triangulation algorithm for a specific surface. The factory returns an instance of the triangulation algorithm via *IMeshTools_MeshAlgo* interface depending on the type of surface passed as parameter. It is supposed to be used at the face discretization stage. +// An empty face is given as the sketch face -The default implementation of AlgoFactory is given in *BRepMesh_MeshAlgoFactory* returning algorithms of different complexity chosen according to the passed surface type. In its turn, it is used as the initializer of *BRepMesh_FaceDiscret* algorithm representing the starter of face discretization stage. +BRepFeat_MakeRevol theRevol(Sbase, Frevol, TopoDS_Face(), RevolAx, Standard_True, Standard_True); -@figure{/user_guides/modeling_algos/images/modeling_algos_mesh_002.svg,"Interface describing entry point to meshing workflow",500} +theRevol.Perform(FUntil); +if (theRevol.IsDone()) { + TopoDS_Shape theResult = theRevol; + ... +} +~~~~~ -Remaining interfaces describe auxiliary tools: - * *IMeshTools_CurveTessellator*: provides a common interface to the algorithms responsible for creation of discrete polygons on 3D and 2D curves as well as tools for extraction of existing polygons from *TopoDS_Edge* allowing to obtain discrete points and the corresponding parameters on curve regardless of the implementation details (see examples of usage of derived classes *BRepMesh_CurveTessellator*, *BRepMesh_EdgeTessellationExtractor* in *BRepMesh_EdgeDiscret*); - * *IMeshTools_ShapeExplorer*: the last two interfaces represent visitor design pattern and are intended to separate iteration over elements of topological shape (edges and faces) from the operations performed on a particular element; - * *IMeshTools_ShapeVisitor*: provides a common interface for operations on edges and faces of the target topological shape. It can be used in couple with *IMeshTools_ShapeExplorer*. The default implementation available in *BRepMesh_ShapeVisitor* performs initialization of the data model. The advantage of such approach is that the implementation of *IMeshTools_ShapeVisitor* can be changed according to the specific data model whereas the shape explorer implementation remains the same. +**Pipe** -@subsubsection occt_modalg_11_3_4 Create model data structure -The data structures intended to keep discrete and temporary data required by underlying algorithms are created at the first stage of the meshing procedure. Generally, the model represents dependencies between entities of the source topological shape suitable for the target task. +The class *BRepFeat_MakePipe* constructs compound shapes with pipe features: depressions or protrusions. A class object is created or initialized from: + * a shape (basic shape), + * a base face (profile of the pipe) + * a face (face of sketch on which the base has been defined and used to determine whether the base has been defined on the basic shape or not), + * a spine wire + * a Boolean indicating the type of operation (fusion=protrusion or cut=depression) on the basic shape, + * another Boolean indicating if self-intersections have to be found (not used in every case). -#### Data model interface -Unit IMeshData provides common interfaces specifying the data model API used on different stages of the entire workflow. Dependencies and references of the designed interfaces are given in the figure below. A specific interface implementation depends on the target application which allows the developer to implement different models and use custom low-level data structures, e.g. different collections, either NCollection or STL. *IMeshData_Shape* is used as the base class for all data structures and tools keeping the topological shape in order to avoid possible copy-paste. +There are three Perform methods: +| Method | Description | +| :-------- | :---------- | +| *Perform()* | The pipe is defined along the entire path (spine wire) | +| *Perform(Until)* | The pipe is defined along the path until a given face | +| *Perform(From, Until)* | The pipe is defined between the two faces From and Until | -The default implementation of interfaces is given in BRepMeshData unit. The main aim of the default data model is to provide features performing discretization of edges in a parallel mode. Thus, curve, pcurve and other classes are based on STL containers and smart-pointers as far as NCollection does not provide thread-safety for some cases (e.g. *NCollection_Sequence*). In addition, it closely reflects topology of the source shape, i.e. the number of edges in the data model is equal to the number of edges in the source model; each edge contains a set of pcurves associated with its adjacent faces which allows creation of discrete polygons for all pcurves or the 3D curve of a particular edge in a separate thread. +Let us have a look at the example: -**Advantages**: -In case of necessity, the data model (probably with algorithms for its processing) can be easily substituted by another implementation supporting another kind of dependencies between elements. +~~~~~ +TopoDS_Shape S = BRepPrimAPI_MakeBox(400.,250.,300.); +TopExp_Explorer Ex; +Ex.Init(S,TopAbs_FACE); +Ex.Next(); +Ex.Next(); +TopoDS_Face F1 = TopoDS::Face(Ex.Current()); +Handle(Geom_Surface) surf = BRep_Tool::Surface(F1); +BRepBuilderAPI_MakeWire MW1; +gp_Pnt2d p1,p2; +p1 = gp_Pnt2d(100.,100.); +p2 = gp_Pnt2d(200.,100.); +Handle(Geom2d_Line) aline = GCE2d_MakeLine(p1,p2).Value(); -An additional example of a different data model is the case when it is not required to create a mesh with discrete polygons synchronized between adjacent faces, i.e. in case of necessity to speed up creation of a rough per-face tessellation used for visualization or quick computation only (the approach used in *XDEDRAW_Props*). +MW1.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,p1.Distance(p2))); +p1 = p2; +p2 = gp_Pnt2d(150.,200.); +aline = GCE2d_MakeLine(p1,p2).Value(); -@figure{/user_guides/modeling_algos/images/modeling_algos_mesh_003.svg,"Common API of data model",500} +MW1.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,p1.Distance(p2))); +p1 = p2; +p2 = gp_Pnt2d(100.,100.); +aline = GCE2d_MakeLine(p1,p2).Value(); -#### Collecting data model -At this stage the data model is filled by entities according to the topological structure of the source shape. A default implementation of the data model is given in BRepMeshData unit and represents the model as two sets: a set of edges and a set of faces. Each face consists of one or several wires, the first of which always represents the outer wire, while others are internal. In its turn, each wire depicts the ordered sequence of oriented edges. Each edge is characterized by a single 3D curve and zero (in case of free edge) or more 2D curves associated with faces adjacent to this edge. Both 3D and 2D curves represent a set of pairs point-parameter defined in 3D and 2D space of the reference face correspondingly. An additional difference between a curve and a pcurve is that the latter has a reference to the face it is defined for. +MW1.Add(BRepBuilderAPI_MakeEdge(aline,surf,0.,p1.Distance(p2))); +BRepBuilderAPI_MakeFace MKF1; +MKF1.Init(surf,Standard_False); +MKF1.Add(MW1.Wire()); +TopoDS_Face FP = MKF1.Face(); +BRepLib::BuildCurves3d(FP); +TColgp_Array1OfPnt CurvePoles(1,3); +gp_Pnt pt = gp_Pnt(150.,0.,150.); +CurvePoles(1) = pt; +pt = gp_Pnt(200.,100.,150.); +CurvePoles(2) = pt; +pt = gp_Pnt(150.,200.,150.); +CurvePoles(3) = pt; +Handle(Geom_BezierCurve) curve = new Geom_BezierCurve +(CurvePoles); +TopoDS_Edge E = BRepBuilderAPI_MakeEdge(curve); +TopoDS_Wire W = BRepBuilderAPI_MakeWire(E); +BRepFeat_MakePipe MKPipe (S,FP,F1,W,Standard_False, +Standard_True); +MKPipe.Perform(); +TopoDS_Shape res1 = MKPipe.Shape(); +~~~~~ -Model filler algorithm is represented by *BRepMesh_ShapeVisitor* class creating the model as a reflection to topological shape with help of *BRepMesh_ShapeExplorer* performing iteration over edges and faces of the target shape. Note that the algorithm operates on a common interface of the data model and creates a structure without any knowledge about the implementation details and underlying data structures. The entry point to collecting functionality is *BRepMesh_ModelBuilder* class. +@figure{/user_guides/modeling_algos/images/modeling_algos_image050.png,"Pipe depression",240} -@subsubsection occt_modalg_11_3_5 Discretize edges 3D & 2D curves -At this stage only the edges of the data model are considered. Each edge is processed separately (with the possibility to run processing in multiple threads). The edge is checked for existing polygonal data. In case if at least one representation exists and suits the meshing parameters, it is recuperated and used as reference data for tessellation of the whole set of pcurves as well as 3D curve assigned to the edge (see *BRepMesh_EdgeTessellationExtractor*). Otherwise, a new tessellation algorithm is created and used to generate the initial polygon (see *BRepMesh_CurveTessellator*) and the edge is marked as outdated. In addition, the model edge is updated by deflection as well as recomputed same range, same parameter and degeneracy parameters. See *BRepMesh_EdgeDiscret* for implementation details. +@subsubsection occt_modalg_9_2 Mechanical Features -IMeshData unit defines interface *IMeshData_ParametersListArrayAdaptor*, which is intended to adapt arbitrary data structures to the *NCollection_Array1* container API. This solution is made to use both *NCollection_Array1* and *IMeshData_Curve* as the source for *BRepMesh_EdgeParameterProvider* tool intended to generate a consistent parametrization taking into account the same parameter property. +Mechanical features include ribs, protrusions and grooves (or slots), depressions along planar (linear) surfaces or revolution surfaces. -@subsubsection occt_modalg_11_3_6 Heal discrete model -In general, this stage represents a set of operations performed on the entire discrete model in order to resolve inconsistencies due to the problems caused by design, translation or rough discretization. A different sequence of operations can be performed depending on the target triangulation algorithm, e.g. there are different approaches to process self-intersections – either to amplify edges discretization by decreasing the target precision or to split links at the intersection points. At this stage the whole set of edges is considered in aggregate and their adjacency is taken into account. A default implementation of the model healer is given in *BRepMesh_ModelHealer* which performs the following actions: - * Iterates over model faces and checks their wires for consistency, i.e. whether the wires are closed and do not contain self-intersections. The data structures are designed free of collisions, thus it is possible to run processing in a parallel mode; - * Forcibly connects the ends of adjacent edges in the parametric space, closing gaps between possible disconnected parts. The aim of this operation is to create a correct discrete model defined relatively to the parametric space of the target face taking into account connectivity and tolerances of 3D space only. This means that no specific computations are made to determine U and V tolerance; - * Registers intersections on edges forming the face shape. Two solutions are possible in order to resolve self-intersection: - * Decrease deflection of a particular edge and update its discrete model. After that the workflow "intersection check – amplification" is repeated up to 5 times. As the result, target edges contain a finer tessellation and meshing continues or the face is marked by *IMeshData_SelfIntersectingWire* status and refused from further processing; - * Split target edges by intersection point and synchronize the updated polygon with curve and remaining pcurves associated to each edge. This operation presents a more robust solution comparing to the amplification procedure with a guaranteed result, but it is more difficult for implementation from the point of view of synchronization functionality. +The semantics of mechanical features is built around giving thickness to a contour. This thickness can either be symmetrical -- on one side of the contour -- or dissymmetrical -- on both sides. As in the semantics of form features, the thickness is defined by construction of shapes in specific contexts. -@subsubsection occt_modalg_11_3_7 Preprocess discrete model -This stage implements actions to be performed before meshing of faces. Depending on target goals it can be changed or omitted. By default, *BRepMesh_ModelPreProcessor* implements the functionality checking topological faces for consistency of existing triangulation, i.e.: consistency with the target deflection parameter; indices of nodes referenced by triangles do not exceed the number of nodes stored in a triangulation. If the face fails some checks, it is cleaned from triangulation and its adjacent edges are cleaned from existing polygons. This does not affect a discrete model and does not require any recomputation as the model keeps tessellations for the whole set of edges despite consistency of their polygons. +The development contexts differ, however, in the case of mechanical features. +Here they include extrusion: + * to a limiting face of the basis shape; + * to or from a limiting plane; + * to a height. -@subsubsection occt_modalg_11_3_8 Discretize faces -Discretization of faces is the general part of meshing algorithm. At this stage edges tessellation data obtained and processed on previous steps is used to form contours of target faces and passed as input to the triangulation algorithm. Default implementation is provided by *BRepMesh_FaceDiscret* class which represents a starter for triangulation algorithm. It iterates over faces available in the data model, creates an instance of the triangulation algorithm according to the type of surface associated with each face via *IMeshTools_MeshAlgoFactory* and executes it. Each face is processed separately, thus it is possible to process faces in a parallel mode. The class diagram of face discretization is given in the figure below. - -@figure{/user_guides/modeling_algos/images/modeling_algos_mesh_004.svg,"Class diagram of face discrete stage",300} +A class object is created or initialized from + * a shape (basic shape); + * a wire (base of rib or groove); + * a plane (plane of the wire); + * direction1 (a vector along which thickness will be built up); + * direction2 (vector opposite to the previous one along which thickness will be built up, may be null); + * a Boolean indicating the type of operation (fusion=rib or cut=groove) on the basic shape; + * another Boolean indicating if self-intersections have to be found (not used in every case). + +**Linear Form** + +Linear form is implemented in *MakeLinearForm* class, which creates a rib or a groove along a planar surface. There is one *Perform()* method, which performs a prism from the wire along the *direction1* and *direction2* interacting with base shape *Sbase*. The height of the prism is *Magnitude(Direction1)+Magnitude(direction2)*. -In general, face meshing algorithms have the following structure: - * *BRepMesh_BaseMeshAlgo* implements *IMeshTools_MeshAlgo* interface and the base functionality for inherited algorithms. The main goal of this class is to initialize an instance of *BRepMesh_DataStructureOfDelaun* as well as auxiliary data structures suitable for nested algorithms using face model data passed as input parameter. Despite implementation of triangulation algorithm this structure is currently supposed as common for OCCT. However, the user is free to implement a custom algorithm and supporting data structure accessible via *IMeshTools_MeshAlgo* interface, e.g. to connect a 3-rd party meshing tool that does not support *TopoDS_Shape* out of box. For this, such structure provides the possibility to distribute connectors to various algorithms in the form of plugins; - * *BRepMesh_DelaunayBaseMeshAlgo* and *BRepMesh_SweepLineMeshAlgo* classes implement core meshing functionality operating directly on an instance of *BRepMesh_DataStructureOfDelaun*. The algorithms represent mesh generation tools adding new points from the data structure to the final mesh; - * *BRepMesh_NodeInsertionMeshAlgo* class represents a wrapper intended to extend the algorithm inherited from *BRepMesh_BaseMeshAlgo* to enable the functionality generating surface nodes and inserting them into the structure. On this level, an instance of the classification tool is created and can be used to accept-reject internal nodes. In addition, computations necessary for scaling UV coordinates of points relatively to the range specified for the corresponding direction are performed. As far as both triangulation algorithms work on static data provided by the structure, new nodes are added at the initialization stage. Surface nodes are generated by an auxiliary tool called range splitter and passed as template parameter (see Range splitter); - * Classes *BRepMesh_DelaunayNodeInsertionMeshAlgo* and *BRepMesh_SweepLineNodeInsertionMeshAlgo* implement algorithm-specific functionality related to addition of internal nodes supplementing functionality provided by *BRepMesh_NodeInsertionMeshAlgo*; - * *BRepMesh_DelaunayDeflectionControlMeshAlgo* extends functionality of *BRepMesh_DelaunayNodeInsertionMeshAlgo* by additional procedure controlling deflection of generated triangles. +~~~~~ +BRepBuilderAPI_MakeWire mkw; +gp_Pnt p1 = gp_Pnt(0.,0.,0.); +gp_Pnt p2 = gp_Pnt(200.,0.,0.); +mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); +p1 = p2; +p2 = gp_Pnt(200.,0.,50.); +mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); +p1 = p2; +p2 = gp_Pnt(50.,0.,50.); +mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); +p1 = p2; +p2 = gp_Pnt(50.,0.,200.); +mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); +p1 = p2; +p2 = gp_Pnt(0.,0.,200.); +mkw.Add(BRepBuilderAPI_MakeEdge(p1,p2)); +p1 = p2; +mkw.Add(BRepBuilderAPI_MakeEdge(p2,gp_Pnt(0.,0.,0.))); +TopoDS_Shape S = BRepBuilderAPI_MakePrism(BRepBuilderAPI_MakeFace + (mkw.Wire()),gp_Vec(gp_Pnt(0.,0.,0.),gp_P + nt(0.,100.,0.))); +TopoDS_Wire W = BRepBuilderAPI_MakeWire(BRepBuilderAPI_MakeEdge(gp_Pnt + (50.,45.,100.), +gp_Pnt(100.,45.,50.))); +Handle(Geom_Plane) aplane = + new Geom_Plane(gp_Pnt(0.,45.,0.), gp_Vec(0.,1.,0.)); +BRepFeat_MakeLinearForm aform(S, W, aplane, gp_Dir + (0.,5.,0.), gp_Dir(0.,-3.,0.), 1, Standard_True); +aform.Perform(); +TopoDS_Shape res = aform.Shape(); +~~~~~ -BRepMesh provides user a way to switch default triangulation algorithm to a custom one, either implemented by user or available worldwide. -There are three base classes that can be currently used to integrate 3rd-party algorithms: - * *BRepMesh_ConstrainedBaseMeshAlgo* base class for tools providing generation of triangulations with constraints requiring no common processing by BRepMesh; - * *BRepMesh_CustomBaseMeshAlgo* provides the entry point for generic algorithms without support of constraints and supposed for generation of base mesh only. - Constraint edges are processed using standard functionality provided by the component itself upon background mesh produced by 3rd-party solver; - * *BRepMesh_CustomDelaunayBaseMeshAlgo* contains initialization part for tools used by BRepMesh for checks or optimizations using results of 3rd-party algorithm. +@figure{/user_guides/modeling_algos/images/modeling_algos_image051.png,"Creating a rib",240} -Meshing algorithms could be provided by implemeting IMeshTools_MeshAlgoFactory with related interfaces and passing it to BRepMesh_Context::SetFaceDiscret(). -OCCT comes with two base 2D meshing algorithms: BRepMesh_MeshAlgoFactory (used by default) and BRepMesh_DelabellaMeshAlgoFactory. +**Gluer** -The following example demonstrates how it could be done from Draw environment: -~~~~~ -psphere s 10 +The class *BRepFeat_Gluer* allows gluing two solids along faces. The contact faces of the glued shape must not have parts outside the contact faces of the basic shape. Upon completion the algorithm gives the glued shape with cut out parts of faces inside the shape. -### Default Algo ### -incmesh s 0.0001 -algo default +The class is created or initialized from two shapes: the “glued” shape and the basic shape (on which the other shape is glued). +Two *Bind* methods are used to bind a face of the glued shape to a face of the basic shape and an edge of the glued shape to an edge of the basic shape. -### Delabella Algo ### -incmesh s 0.0001 -algo delabella -~~~~~ +**Note** that every face and edge has to be bounded, if two edges of two glued faces are coincident they must be explicitly bounded. -The code snippet below shows passing a custom mesh factory to BRepMesh_IncrementalMesh: ~~~~~ -IMeshTools_Parameters aMeshParams; -Handle(IMeshTools_Context) aContext = new BRepMesh_Context(); -aContext->SetFaceDiscret (new BRepMesh_FaceDiscret (new BRepMesh_DelabellaMeshAlgoFactory())); +TopoDS_Shape Sbase = ...; // the basic shape +TopoDS_Shape Sglued = ...; // the glued shape -BRepMesh_IncrementalMesh aMesher; -aMesher.SetShape (aShape); -aMesher.ChangeParameters() = aMeshParams; +TopTools_ListOfShape Lfbase; +TopTools_ListOfShape Lfglued; +// Determination of the glued faces +... -aMesher.Perform (aContext); +BRepFeat_Gluer theGlue(Sglue, Sbase); +TopTools_ListIteratorOfListOfShape itlb(Lfbase); +TopTools_ListIteratorOfListOfShape itlg(Lfglued); +for (; itlb.More(); itlb.Next(), itlg(Next()) { +const TopoDS_Face& f1 = TopoDS::Face(itlg.Value()); +const TopoDS_Face& f2 = TopoDS::Face(itlb.Value()); +theGlue.Bind(f1,f2); +// for example, use the class FindEdges from LocOpe to +// determine coincident edges +LocOpe_FindEdge fined(f1,f2); +for (fined.InitIterator(); fined.More(); fined.Next()) { +theGlue.Bind(fined.EdgeFrom(),fined.EdgeTo()); +} +} +theGlue.Build(); +if (theGlue.IsDone() { +TopoDS_Shape theResult = theGlue; +... +} ~~~~~ -#### Range splitter -Range splitter tools provide functionality to generate internal surface nodes defined within the range computed using discrete model data. The base functionality is provided by *BRepMesh_DefaultRangeSplitter* which can be used without modifications in case of planar surface. The default splitter does not generate any internal node. +@subsubsection occt_modalg_9_2_4 Split Shape -*BRepMesh_ConeRangeSplitter*, *BRepMesh_CylinderRangeSplitter* and *BRepMesh_SphereRangeSplitter* are specializations of the default splitter intended for quick generation of internal nodes for the corresponding type of analytical surface. +The class *BRepFeat_SplitShape* is used to split faces of a shape into wires or edges. The shape containing the new entities is rebuilt, sharing the unmodified ones. -*BRepMesh_UVParamRangeSplitter* implements base functionality taking discretization points of face border into account for node generation. Its successors BRepMesh_TorusRangeSplitter and *BRepMesh_NURBSRangeSplitter* extend the base functionality for toroidal and NURBS surfaces correspondingly. +The class is created or initialized from a shape (the basic shape). +Three Add methods are available: +* *Add(Wire, Face)* -- adds a new wire on a face of the basic shape. +* *Add(Edge, Face)* -- adds a new edge on a face of the basic shape. +* *Add(EdgeNew, EdgeOld)* -- adds a new edge on an existing one (the old edge must contain the new edge). -@subsubsection occt_modalg_11_3_9 Postprocess discrete model -This stage implements actions to be performed after meshing of faces. Depending on target goals it can be changed or omitted. By default, *BRepMesh_ModelPostProcessor* commits polygonal data stored in the data model to *TopoDS_Edge*. +**Note** The added wires and edges must define closed wires on faces or wires located between two existing edges. Existing edges must not be intersected. +~~~~~ +TopoDS_Shape Sbase = ...; // basic shape +TopoDS_Face Fsplit = ...; // face of Sbase +TopoDS_Wire Wsplit = ...; // new wire contained in Fsplit +BRepFeat_SplitShape Spls(Sbase); +Spls.Add(Wsplit, Fsplit); +TopoDS_Shape theResult = Spls; +... +~~~~~ -@section occt_modalg_defeaturing 3D Model Defeaturing +@subsection occt_modalg_defeaturing 3D Model Defeaturing The Open CASCADE Technology Defeaturing algorithm is intended for removal of the unwanted parts or features from the model. These parts can be holes, protrusions, gaps, chamfers, fillets, etc. @@ -3353,14 +2978,11 @@ Take a look at the simple shape on the image below: Removal of all three faces of the gap is not going to work, because there will be no face to fill the transverse part of the step. Although, removal of only two faces, keeping one of the transverse faces, will fill the gap with the kept face: - - - - - -
@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im002.png,"Keeping the right transverse face",220}@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im003.png,"Keeping the left transverse face",220}
-@subsection occt_modalg_defeaturing_usage Usage +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im002.png,"Keeping the right transverse face",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im003.png,"Keeping the left transverse face",220} + +@subsubsection occt_modalg_defeaturing_usage Usage Here is the example of usage of the *BRepAlgoAPI_Defeaturing* algorithm on the C++ level: ~~~~ @@ -3409,72 +3031,55 @@ The @ref occt_draw_hist "standard history commands" can be used to track the his For more details on commands above, refer to the @ref occt_draw_defeaturing "Defeaturing commands" of the Draw test harness user guide. -@subsection occt_modalg_defeaturing_examples Examples +@subsubsection occt_modalg_defeaturing_examples Examples Here are the examples of defeaturing of the ANC101 model: @figure{/user_guides/modeling_algos/images/modeling_algos_rf_im004.png,"ANC101 model",220} - - - - - - - - - - - - - - - - - - - - - - - - - -
@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im005.png,"Removing the cylindrical protrusion",220}@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im006.png,"Result",220}
@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im007.png,"Removing the cylindrical holes",220}@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im008.png,"Result",220}
@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im009.png,"Removing the cylindrical holes",220}@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im010.png,"Result",220}
@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im011.png,"Removing the small gaps in the front",220}@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im012.png,"Result",220}
@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im013.png,"Removing the gaps in the front completely",220}@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im014.png,"Result",220}
@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im015.png,"Removing the cylindrical protrusion",220}@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im016.png,"Result",220}
+ +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im005.png,"Removing the cylindrical protrusion",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im006.png,"Result",220} + +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im007.png,"Removing the cylindrical holes",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im008.png,"Result",220} + +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im009.png,"Removing the cylindrical holes",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im010.png,"Result",220} + +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im011.png,"Removing the small gaps in the front",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im012.png,"Result",220} + +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im013.png,"Removing the gaps in the front completely",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im014.png,"Result",220} + +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im015.png,"Removing the cylindrical protrusion",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im016.png,"Result",220} Here are the few examples of defeaturing of the model containing boxes with blends: -@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im017.png,"Box blend model",220} - - - - - - - - - - - - - - - - - - - - - - - - - - -
@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im018.png,"Removing the blend",220}@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im019.png,"Result",220}
@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im020.png,"Removing the blend",220}@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im021.png,"Result",220}
@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im022.png,"Removing the blend",220}@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im023.png,"Result",220}
@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im024.png,"Removing the blend",220}@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im025.png,"Result",220}
@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im026.png,"Removing the blend",220}@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im027.png,"Result",220}
@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im028.png,"Removing the blend",220}@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im029.png,"Result",220}
- - -@section occt_modalg_makeperiodic 3D Model Periodicity +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im017.png,"Box blend model",220} + +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im018.png,"Removing the blend",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im019.png,"Result",220} + +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im020.png,"Removing the blend",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im021.png,"Result",220} + +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im022.png,"Removing the blend",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im023.png,"Result",220} + +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im024.png,"Removing the blend",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im025.png,"Result",220} + +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im026.png,"Removing the blend",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im027.png,"Result",220} + +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im028.png,"Removing the blend",220} +@figure{/user_guides/modeling_algos/images/modeling_algos_rf_im029.png,"Result",220} + + +@subsection occt_modalg_makeperiodic 3D Model Periodicity Open CASCADE Technology provides tools for making an arbitrary 3D model (or just shape) periodic in 3D space in the specified directions. @@ -3508,7 +3113,7 @@ If necessary the algorithm will trim the shape to fit into the requested period E.g. let's make the L-shape periodic only in X direction with the period 2 starting at X parameter 4: @figure{/user_guides/modeling_algos/images/modeling_algos_mkperiodic_im005.png,"Periodic trimmed shape",220} -@subsection occt_modalg_makeperiodic_how_it_works How the shape is made periodic +@subsubsection occt_modalg_makeperiodic_how_it_works How the shape is made periodic 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; @@ -3520,12 +3125,12 @@ Repeated copying of the geometry ensures that the corner edges of the periodic s Thus, in the periodic shape the geometry from positive side of the shape is always copied on the negative side of periodic directions. -@subsection occt_modalg_makeperiodic_association Opposite shapes association +@subsubsection occt_modalg_makeperiodic_association Opposite shapes association The algorithm also associates the identical (or twin) shapes located on the opposite sides of the periodic shape. By the construction, the twin shapes should always have the same geometry and distanced from each other on the period. It is possible that the shape does not have any twins. It means that when repeating this shape will not touch the opposite side of the shape. In the example when the periods of the shape are grater than its extensions, non of the sub-shapes has a twin. -@subsection occt_modalg_makeperiodic_repetition Periodic shape repetition +@subsubsection occt_modalg_makeperiodic_repetition Periodic shape repetition The algorithm also provides the methods to repeat the periodic shape in periodic directions. To repeat shape the algorithm makes the requested number of copies of the shape and translates them one by one on the time * period value. After all copies are made and translated they are glued to have valid shape. @@ -3534,7 +3139,7 @@ Single subsequent repetition in any direction will result already in 6 shapes. The repetitions can be cleared and started over. -@subsection occt_modalg_makeperiodic_history History support +@subsubsection occt_modalg_makeperiodic_history History support The algorithm supports the history of shapes modifications, thus it is possible to track how the shapes have been changed to make it periodic and what new shapes have been created during repetitions. Both split history and history of periodic shape repetition are available here. Note, that all repeated shapes are stored as generated into the history. @@ -3542,7 +3147,7 @@ Both split history and history of periodic shape repetition are available here. *BRepTools_History* is used for history support. -@subsection occt_modalg_makeperiodic_errors Errors/Warnings +@subsubsection occt_modalg_makeperiodic_errors Errors/Warnings The algorithm supports the Error/Warning reporting system which allows obtaining the extended overview of the errors and warning occurred during the operation. As soon as any error appears the algorithm stops working. The warnings allow continuing the job, informing the user that something went wrong. @@ -3554,7 +3159,7 @@ The algorithm returns the following alerts: For more information on the error/warning reporting system please see the chapter @ref specification__boolean_ers "Errors and warnings reporting system" of Boolean operations user guide. -@subsection occt_modalg_makeperiodic_usage Usage +@subsubsection occt_modalg_makeperiodic_usage Usage The algorithm is implemented in the class *BOPAlgo_MakePeriodic*. Here is the example of its usage on the API level: @@ -3618,7 +3223,7 @@ To track the history of a shape modification during MakePeriodic operation the @ To have possibility to access the error/warning shapes of the operation use the *bdrawwarnshapes* command before running the algorithm (see command usage in the @ref specification__boolean_ers "Errors and warnings reporting system" of Boolean operations user guide). -@subsection occt_modalg_makeperiodic_examples Examples +@subsubsection occt_modalg_makeperiodic_examples Examples Imagine that you need to make the drills in the plate on the same distance from each other. To model this process it is necessary to make a lot of cylinders (simulating the drills) and cut these cylinders from the plate. With the periodicity tool, the process looks very simple: @@ -3639,6 +3244,158 @@ bcut result plate drills @figure{/user_guides/modeling_algos/images/modeling_algos_mkperiodic_im006.png,"Plate with drills",220} +@section occt_modalg_10 Hidden Line Removal + +To provide the precision required in industrial design, drawings need to offer the possibility of removing lines, which are hidden in a given projection. + +For this the Hidden Line Removal component provides two algorithms: *HLRBRep_Algo* and *HLRBRep_PolyAlgo*. + +These algorithms are based on the principle of comparing each edge of the shape to be visualized with each of its faces, and calculating the visible and the hidden parts of each edge. Note that these are not the algorithms used in generating shading, which calculate the visible and hidden parts of each face in a shape to be visualized by comparing each face in the shape with every other face in the same shape. +These algorithms operate on a shape and remove or indicate edges hidden by faces. For a given projection, they calculate a set of lines characteristic of the object being represented. They are also used in conjunction with extraction utilities, which reconstruct a new, simplified shape from a selection of the results of the calculation. This new shape is made up of edges, which represent the shape visualized in the projection. + +*HLRBRep_Algo* allows working with the shape itself, whereas *HLRBRep_PolyAlgo* works with a polyhedral simplification of the shape. When you use *HLRBRep_Algo*, you obtain an exact result, whereas, when you use *HLRBRep_PolyAlgo*, you reduce the computation time, but obtain polygonal segments. + +No smoothing algorithm is provided. Consequently, a polyhedron will be treated as such and the algorithms will give the results in form of line segments conforming to the mathematical definition of the polyhedron. This is always the case with *HLRBRep_PolyAlgo*. + +*HLRBRep_Algo* and *HLRBRep_PolyAlgo* can deal with any kind of object, for example, assemblies of volumes, surfaces, and lines, as long as there are no unfinished objects or points within it. + +However, there some restrictions in HLR use: + * Points are not processed; + * Infinite faces or lines are not processed. + + +@figure{/user_guides/modeling_algos/images/modeling_algos_image052.png,"Sharp, smooth and sewn edges in a simple screw shape",320} + +@figure{/user_guides/modeling_algos/images/modeling_algos_image053.png,"Outline edges and isoparameters in the same shape",320} + +@figure{/user_guides/modeling_algos/images/modeling_algos_image054.png,"A simple screw shape seen with shading",320} + +@figure{/user_guides/modeling_algos/images/modeling_algos_image055.png,"An extraction showing hidden sharp edges",320} + + +The following services are related to Hidden Lines Removal : + +### Loading Shapes + +To pass a *TopoDS_Shape* to an *HLRBRep_Algo* object, use *HLRBRep_Algo::Add*. With an *HLRBRep_PolyAlgo* object, use *HLRBRep_PolyAlgo::Load*. If you wish to add several shapes, use Add or Load as often as necessary. + +### Setting view parameters + +*HLRBRep_Algo::Projector* and *HLRBRep_PolyAlgo::Projector* set a projector object which defines the parameters of the view. This object is an *HLRAlgo_Projector*. + +### Computing the projections + +*HLRBRep_PolyAlgo::Update* launches the calculation of outlines of the shape visualized by the *HLRBRep_PolyAlgo* framework. + +In the case of *HLRBRep_Algo*, use *HLRBRep_Algo::Update*. With this algorithm, you must also call the method *HLRBRep_Algo::Hide* to calculate visible and hidden lines of the shape to be visualized. With an *HLRBRep_PolyAlgo* object, visible and hidden lines are computed by *HLRBRep_PolyHLRToShape*. + +### Extracting edges + +The classes *HLRBRep_HLRToShape* and *HLRBRep_PolyHLRToShape* present a range of extraction filters for an *HLRBRep_Algo object* and an *HLRBRep_PolyAlgo* object, respectively. They highlight the type of edge from the results calculated by the algorithm on a shape. With both extraction classes, you can highlight the following types of output: + * visible/hidden sharp edges; + * visible/hidden smooth edges; + * visible/hidden sewn edges; + * visible/hidden outline edges. + +To perform extraction on an *HLRBRep_PolyHLRToShape* object, use *HLRBRep_PolyHLRToShape::Update* function. + +For an *HLRBRep_HLRToShape* object built from an *HLRBRepAlgo* object you can also highlight: + * visible isoparameters and + * hidden isoparameters. + +@subsection occt_modalg_10_1 Examples + +### HLRBRep_Algo + +~~~~~ +// Build The algorithm object +myAlgo = new HLRBRep_Algo(); + +// Add Shapes into the algorithm +TopTools_ListIteratorOfListOfShape anIterator(myListOfShape); +for (;anIterator.More();anIterator.Next()) +myAlgo-Add(anIterator.Value(),myNbIsos); + +// Set The Projector (myProjector is a +HLRAlgo_Projector) +myAlgo-Projector(myProjector); + +// Build HLR +myAlgo->Update(); + +// Set The Edge Status +myAlgo->Hide(); + +// Build the extraction object : +HLRBRep_HLRToShape aHLRToShape(myAlgo); + +// extract the results : +TopoDS_Shape VCompound = aHLRToShape.VCompound(); +TopoDS_Shape Rg1LineVCompound = +aHLRToShape.Rg1LineVCompound(); +TopoDS_Shape RgNLineVCompound = +aHLRToShape.RgNLineVCompound(); +TopoDS_Shape OutLineVCompound = +aHLRToShape.OutLineVCompound(); +TopoDS_Shape IsoLineVCompound = +aHLRToShape.IsoLineVCompound(); +TopoDS_Shape HCompound = aHLRToShape.HCompound(); +TopoDS_Shape Rg1LineHCompound = +aHLRToShape.Rg1LineHCompound(); +TopoDS_Shape RgNLineHCompound = +aHLRToShape.RgNLineHCompound(); +TopoDS_Shape OutLineHCompound = +aHLRToShape.OutLineHCompound(); +TopoDS_Shape IsoLineHCompound = +aHLRToShape.IsoLineHCompound(); +~~~~~ + +### HLRBRep_PolyAlgo + + +~~~~~ + +// Build The algorithm object +myPolyAlgo = new HLRBRep_PolyAlgo(); + +// Add Shapes into the algorithm +TopTools_ListIteratorOfListOfShape +anIterator(myListOfShape); +for (;anIterator.More();anIterator.Next()) +myPolyAlgo-Load(anIterator.Value()); + +// Set The Projector (myProjector is a +HLRAlgo_Projector) +myPolyAlgo->Projector(myProjector); + +// Build HLR +myPolyAlgo->Update(); + +// Build the extraction object : +HLRBRep_PolyHLRToShape aPolyHLRToShape; +aPolyHLRToShape.Update(myPolyAlgo); + +// extract the results : +TopoDS_Shape VCompound = +aPolyHLRToShape.VCompound(); +TopoDS_Shape Rg1LineVCompound = +aPolyHLRToShape.Rg1LineVCompound(); +TopoDS_Shape RgNLineVCompound = +aPolyHLRToShape.RgNLineVCompound(); +TopoDS_Shape OutLineVCompound = +aPolyHLRToShape.OutLineVCompound(); +TopoDS_Shape HCompound = +aPolyHLRToShape.HCompound(); +TopoDS_Shape Rg1LineHCompound = +aPolyHLRToShape.Rg1LineHCompound(); +TopoDS_Shape RgNLineHCompound = +aPolyHLRToShape.RgNLineHCompound(); +TopoDS_Shape OutLineHCompound = +aPolyHLRToShape.OutLineHCompound(); +~~~~~ + + + @section occt_modalg_makeconnected Making touching shapes connected Open CASCADE Technology provides tools for making the same-dimensional touching shapes connected (or glued), i.e. for making the coinciding geometries topologically shared among shapes. diff --git a/dox/user_guides/modeling_data/images/modeling_data_image003.png b/dox/user_guides/modeling_data/images/modeling_data_image003.png index df9682b596..593342d591 100644 Binary files a/dox/user_guides/modeling_data/images/modeling_data_image003.png and b/dox/user_guides/modeling_data/images/modeling_data_image003.png differ diff --git a/dox/user_guides/modeling_data/images/modeling_data_image014.png b/dox/user_guides/modeling_data/images/modeling_data_image014.png index 48cfa12d3d..801244f8e0 100644 Binary files a/dox/user_guides/modeling_data/images/modeling_data_image014.png and b/dox/user_guides/modeling_data/images/modeling_data_image014.png differ diff --git a/dox/user_guides/modeling_data/images/modeling_data_image015.png b/dox/user_guides/modeling_data/images/modeling_data_image015.png index 277cbb6ffa..6f98d72fe3 100644 Binary files a/dox/user_guides/modeling_data/images/modeling_data_image015.png and b/dox/user_guides/modeling_data/images/modeling_data_image015.png differ diff --git a/dox/user_guides/modeling_data/modeling_data.md b/dox/user_guides/modeling_data/modeling_data.md index 0de514e7d0..c8cd9d965c 100644 --- a/dox/user_guides/modeling_data/modeling_data.md +++ b/dox/user_guides/modeling_data/modeling_data.md @@ -7,7 +7,7 @@ Modeling Data {#occt_user_guides__modeling_data} Modeling Data supplies data structures to represent 2D and 3D geometric models. -This manual explains how to use Modeling Data. For advanced information on modeling data, see our E-learning & Training offerings. +This manual explains how to use Modeling Data. @section occt_modat_1 Geometry Utilities @@ -548,181 +548,6 @@ However, the Geom package essentially provides data structures, not algorithms. You can refer to the GC package to find more evolved construction algorithms for Geom objects. -@section occt_modat_4 Properties of Shapes - -@subsection occt_modat_4_1 Local Properties of Shapes - -BRepLProp package provides the Local Properties of Shapes component, -which contains algorithms computing various local properties on edges and faces in a BRep model. - -The local properties which may be queried are: - - * for a point of parameter u on a curve which supports an edge : - * the point, - * the derivative vectors, up to the third degree, - * the tangent vector, - * the normal, - * the curvature, and the center of curvature; - * for a point of parameter (u, v) on a surface which supports a face : - * the point, - * the derivative vectors, up to the second degree, - * the tangent vectors to the u and v isoparametric curves, - * the normal vector, - * the minimum or maximum curvature, and the corresponding directions of curvature; - * the degree of continuity of a curve which supports an edge, built by the concatenation of two other edges, at their junction point. - -Analyzed edges and faces are described as BRepAdaptor curves and surfaces, -which provide shapes with an interface for the description of their geometric support. -The base point for local properties is defined by its u parameter value on a curve, or its (u, v) parameter values on a surface. - -@subsection occt_modat_4_2 Local Properties of Curves and Surfaces - -The "Local Properties of Curves and Surfaces" component provides algorithms for computing various local properties on a Geom curve (in 2D or 3D space) or a surface. It is composed of: - - * Geom2dLProp package, which allows computing Derivative and Tangent vectors (normal and curvature) of a parametric point on a 2D curve; - * GeomLProp package, which provides local properties on 3D curves and surfaces - * LProp package, which provides an enumeration used to characterize a particular point on a 2D curve. - -Curves are either Geom_Curve curves (in 3D space) or Geom2d_Curve curves (in the plane). -Surfaces are Geom_Surface surfaces. The point on which local properties are calculated -is defined by its u parameter value on a curve, and its (u,v) parameter values on a surface. - -It is possible to query the same local properties for points as mentioned above, and additionally for 2D curves: - - * the points corresponding to a minimum or a maximum of curvature; - * the inflection points. - - -#### Example: How to check the surface concavity - -To check the concavity of a surface, proceed as follows: - - 1. Sample the surface and compute at each point the Gaussian curvature. - 2. If the value of the curvature changes of sign, the surface is concave or convex depending on the point of view. - 3. To compute a Gaussian curvature, use the class SLprops from GeomLProp, which instantiates the generic class SLProps from LProp and use the method GaussianCurvature. - -@subsection occt_modat_4_2a Continuity of Curves and Surfaces - -Types of supported continuities for curves and surfaces are described in *GeomAbs_Shape* enumeration. - -In respect of curves, the following types of continuity are supported (see the figure below): - * C0 (*GeomAbs_C0*) - parametric continuity. It is the same as G0 (geometric continuity), so the last one is not represented by separate variable. - * G1 (*GeomAbs_G1*) - tangent vectors on left and on right are parallel. - * C1 (*GeomAbs_C1*) - indicates the continuity of the first derivative. - * G2 (*GeomAbs_G2*) - in addition to G1 continuity, the centers of curvature on left and on right are the same. - * C2 (*GeomAbs_C2*) - continuity of all derivatives till the second order. - * C3 (*GeomAbs_C3*) - continuity of all derivatives till the third order. - * CN (*GeomAbs_CN*) - continuity of all derivatives till the N-th order (infinite order of continuity). - -*Note:* Geometric continuity (G1, G2) means that the curve can be reparametrized to have parametric (C1, C2) continuity. - -@figure{/user_guides/modeling_data/images/modeling_data_continuity_curves.svg,"Continuity of Curves",420} - -The following types of surface continuity are supported: - * C0 (*GeomAbs_C0*) - parametric continuity (the surface has no points or curves of discontinuity). - * G1 (*GeomAbs_G1*) - surface has single tangent plane in each point. - * C1 (*GeomAbs_C1*) - indicates the continuity of the first derivatives. - * G2 (*GeomAbs_G2*) - in addition to G1 continuity, principal curvatures and directions are continuous. - * C2 (*GeomAbs_C2*) - continuity of all derivatives till the second order. - * C3 (*GeomAbs_C3*) - continuity of all derivatives till the third order. - * CN (*GeomAbs_CN*) - continuity of all derivatives till the N-th order (infinite order of continuity). - -@figure{/user_guides/modeling_data/images/modeling_data_continuity_surfaces.svg,"Continuity of Surfaces",420} - -Against single surface, the connection of two surfaces (see the figure above) defines its continuity in each intersection point only. Smoothness of connection is a minimal value of continuities on the intersection curve. - - -@subsection occt_modat_4_2b Regularity of Shared Edges - -Regularity of an edge is a smoothness of connection of two faces sharing this edge. In other words, regularity is a minimal continuity between connected faces in each point on edge. - -Edge's regularity can be set by *BRep_Builder::Continuity* method. To get the regularity use *BRep_Tool::Continuity* method. - -Some algorithms like @ref occt_modalg_6 "Fillet" set regularity of produced edges by their own algorithms. On the other hand, some other algorithms (like @ref specification__boolean_operations "Boolean Operations", @ref occt_user_guides__shape_healing "Shape Healing", etc.) do not set regularity. If the regularity is needed to be set correctly on a shape, the method *BRepLib::EncodeRegularity* can be used. It calculates and sets correct values for all edges of the shape. - -The regularity flag is extensively used by the following high level algorithms: @ref occt_modalg_6_1_2 "Chamfer", @ref occt_modalg_7_3 "Draft Angle", @ref occt_modalg_10 "Hidden Line Removal", @ref occt_modalg_9_2_3 "Gluer". - - -@subsection occt_modat_4_3 Global Properties of Shapes - -The Global Properties of Shapes component provides algorithms for computing the global -properties of a composite geometric system in 3D space, and frameworks to query the computed results. - -The global properties computed for a system are : - * mass, - * mass center, - * matrix of inertia, - * moment about an axis, - * radius of gyration about an axis, - * principal properties of inertia such as principal axis, principal moments, and principal radius of gyration. - -Geometric systems are generally defined as shapes. Depending on the way they are analyzed, these shapes will give properties of: - - * lines induced from the edges of the shape, - * surfaces induced from the faces of the shape, or - * volumes induced from the solid bounded by the shape. - -The global properties of several systems may be brought together to give the global properties of the system composed of the sum of all individual systems. - -The Global Properties of Shapes component is composed of: -* seven functions for computing global properties of a shape: one function for lines, two functions for surfaces and four functions for volumes. The choice of functions depends on input parameters and algorithms used for computation (BRepGProp global functions), -* a framework for computing global properties for a set of points (GProp_PGProps), -* a general framework to bring together the global properties retained by several more elementary frameworks, and provide a general programming interface to consult computed global properties. - -Packages *GeomLProp* and *Geom2dLProp* provide algorithms calculating the local properties of curves and surfaces - -A curve (for one parameter) has the following local properties: -- Point -- Derivative -- Tangent -- Normal -- Curvature -- Center of curvature. - -A surface (for two parameters U and V) has the following local properties: -- point -- derivative for U and V) -- tangent line (for U and V) -- normal -- max curvature -- min curvature -- main directions of curvature -- mean curvature -- Gaussian curvature - -The following methods are available: -* *CLProps* -- calculates the local properties of a curve (tangency, curvature,normal); -* *CurAndInf2d* -- calculates the maximum and minimum curvatures and the inflection points of 2d curves; -* *SLProps* -- calculates the local properties of a surface (tangency, the normal and curvature). -* *Continuity* -- calculates regularity at the junction of two curves. - -Note that the B-spline curve and surface are accepted but they are not cut into pieces of the desired continuity. It is the global continuity, which is seen. - -@subsection occt_modat_4_4 Adaptors for Curves and Surfaces - -Some Open CASCADE Technology general algorithms may work theoretically on numerous types of curves or surfaces. - -To do this, they simply get the services required of the analyzed curve or surface through an interface so as to a single API, whatever the type of curve or surface. These interfaces are called adaptors. - -For example, Adaptor3d_Curve is the abstract class which provides the required services by an algorithm which uses any 3d curve. - - GeomAdaptor package provides interfaces: - * On a Geom curve; - * On a curve lying on a Geom surface; - * On a Geom surface; - - Geom2dAdaptor package provides interfaces : - * On a Geom2d curve. - - BRepAdaptor package provides interfaces: - * On a Face - * On an Edge - -When you write an algorithm which operates on geometric objects, use Adaptor3d (or Adaptor2d) objects. - -As a result, you can use the algorithm with any kind of object, if you provide for this object an interface derived from *Adaptor3d* or *Adaptor2d*. -These interfaces are easy to use: simply create an adapted curve or surface from a *Geom2d* curve, and then use this adapted curve as an argument for the algorithm? which requires it. - @section occt_modat_5 Topology @@ -763,39 +588,9 @@ Three additional packages provide tools to access and manipulate this abstract t * TopTools package provides basic tools to use on topological data structures. * TopExp package provides classes to explore and manipulate the topological data structures described in the TopoDS package. * BRepTools package provides classes to explore, manipulate, read and write BRep data structures. These more complex data structures combine topological descriptions with additional geometric information, and include rules for evaluating equivalence of different possible representations of the same object, for example, a point. + -@subsection occt_modat_5_1 Shape Location - -A local coordinate system can be viewed as either of the following: -- A right-handed trihedron with an origin and three orthonormal vectors. The *gp_Ax2* package corresponds to this definition. -- A transformation of a +1 determinant, allowing the transformation of coordinates between local and global references frames. This corresponds to the *gp_Trsf*. - -*TopLoc* package distinguishes two notions: -- *TopLoc_Datum3D* class provides the elementary reference coordinate, represented by a right-handed orthonormal system of axes or by a right-handed unitary transformation. -- *TopLoc_Location* class provides the composite reference coordinate made from elementary ones. It is a marker composed of a chain of references to elementary markers. The resulting cumulative transformation is stored in order to avoid recalculating the sum of the transformations for the whole list. - -@figure{/user_guides/modeling_data/images/modeling_data_image005.png,"Structure of TopLoc_Location",420} - -Two reference coordinates are equal if they are made up of the same elementary coordinates in the same order. There is no numerical comparison. Two coordinates can thus correspond to the same transformation without being equal if they were not built from the same elementary coordinates. - -For example, consider three elementary coordinates: -R1, R2, R3 -The composite coordinates are: -C1 = R1 * R2, -C2 = R2 * R3 -C3 = C1 * R3 -C4 = R1 * C2 - -**NOTE** C3 and C4 are equal because they are both R1 * R2 * R3. - -The *TopLoc* package is chiefly targeted at the topological data structure, but it can be used for other purposes. - -Change of coordinates ---------------------- - -*TopLoc_Datum3D* class represents a change of elementary coordinates. Such changes must be shared so this class inherits from *Standard_Transient*. The coordinate is represented by a transformation *gp_Trsfpackage*. This transformation has no scaling factor. - -@subsection occt_modat_5_2 Naming shapes, sub-shapes, their orientation and state +@subsection occt_modat_5_2 Shape content The **TopAbs** package provides general enumerations describing the basic concepts of topology and methods to handle these enumerations. It contains no classes. This package has been separated from the rest of the topology because the notions it contains are sufficiently general to be used by all topological tools. This avoids redefinition of enumerations by remaining independent of modeling resources. The TopAbs package defines three notions: - **Type** *TopAbs_ShapeEnum*; @@ -879,6 +674,37 @@ The State enumeration can also be used to specify various parts of an object. Th @figure{/user_guides/modeling_data/images/modeling_data_image010.png,"State specifies the parts of an edge intersecting a face",420} +@subsubsection occt_modat_5_1 Shape Location + +A local coordinate system can be viewed as either of the following: +- A right-handed trihedron with an origin and three orthonormal vectors. The *gp_Ax2* package corresponds to this definition. +- A transformation of a +1 determinant, allowing the transformation of coordinates between local and global references frames. This corresponds to the *gp_Trsf*. + +*TopLoc* package distinguishes two notions: +- *TopLoc_Datum3D* class provides the elementary reference coordinate, represented by a right-handed orthonormal system of axes or by a right-handed unitary transformation. +- *TopLoc_Location* class provides the composite reference coordinate made from elementary ones. It is a marker composed of a chain of references to elementary markers. The resulting cumulative transformation is stored in order to avoid recalculating the sum of the transformations for the whole list. + +@figure{/user_guides/modeling_data/images/modeling_data_image005.png,"Structure of TopLoc_Location",420} + +Two reference coordinates are equal if they are made up of the same elementary coordinates in the same order. There is no numerical comparison. Two coordinates can thus correspond to the same transformation without being equal if they were not built from the same elementary coordinates. + +For example, consider three elementary coordinates: +R1, R2, R3 +The composite coordinates are: +C1 = R1 * R2, +C2 = R2 * R3 +C3 = C1 * R3 +C4 = R1 * C2 + +**NOTE** C3 and C4 are equal because they are both R1 * R2 * R3. + +The *TopLoc* package is chiefly targeted at the topological data structure, but it can be used for other purposes. + +Change of coordinates +--------------------- + +*TopLoc_Datum3D* class represents a change of elementary coordinates. Such changes must be shared so this class inherits from *Standard_Transient*. The coordinate is represented by a transformation *gp_Trsfpackage*. This transformation has no scaling factor. + @subsection occt_modat_5_3 Manipulating shapes and sub-shapes The *TopoDS* package describes the topological data structure with the following characteristics: @@ -1106,7 +932,7 @@ The following steps are performed: } ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsection occt_modat_5_5 Lists and Maps of Shapes +@subsubsection occt_modat_5_5 Lists and Maps of Shapes **TopTools** package contains tools for exploiting the *TopoDS* data structure. It is an instantiation of the tools from *TCollection* package with the Shape classes of *TopoDS*. @@ -1257,7 +1083,7 @@ Below is the auxiliary function, which copies the element of rank *i* from the m } ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsubsection occt_modat_5_5_1 Wire Explorer +**Wire Explorer** *BRepTools_WireExplorer* class can access edges of a wire in their order of connection. @@ -1277,22 +1103,180 @@ For example, in the wire in the image we want to recuperate the edges in the ord } ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsection occt_modat_5_6 Storage of shapes +@section occt_modat_4 Properties of Shapes -*BRepTools* and *BinTools* packages contain methods *Read* and *Write* allowing to read and write a Shape to/from a stream or a file. -The methods provided by *BRepTools* package use ASCII storage format; *BinTools* package uses binary format. -Each of these methods has two arguments: -- a *TopoDS_Shape* object to be read/written; -- a stream object or a file name to read from/write to. +@subsection occt_modat_4_1 Local Properties of Shapes -The following sample code reads a shape from ASCII file and writes it to a binary one: +BRepLProp package provides the Local Properties of Shapes component, +which contains algorithms computing various local properties on edges and faces in a BRep model. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} - TopoDS_Shape aShape; - if (BRepTools::Read (aShape, "source_file.txt")) { - BinTools::Write (aShape, "result_file.bin"); - } -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The local properties which may be queried are: + + * for a point of parameter u on a curve which supports an edge : + * the point, + * the derivative vectors, up to the third degree, + * the tangent vector, + * the normal, + * the curvature, and the center of curvature; + * for a point of parameter (u, v) on a surface which supports a face : + * the point, + * the derivative vectors, up to the second degree, + * the tangent vectors to the u and v isoparametric curves, + * the normal vector, + * the minimum or maximum curvature, and the corresponding directions of curvature; + * the degree of continuity of a curve which supports an edge, built by the concatenation of two other edges, at their junction point. + +Analyzed edges and faces are described as BRepAdaptor curves and surfaces, +which provide shapes with an interface for the description of their geometric support. +The base point for local properties is defined by its u parameter value on a curve, or its (u, v) parameter values on a surface. + +@subsection occt_modat_4_2 Local Properties of Curves and Surfaces + +The "Local Properties of Curves and Surfaces" component provides algorithms for computing various local properties on a Geom curve (in 2D or 3D space) or a surface. It is composed of: + + * Geom2dLProp package, which allows computing Derivative and Tangent vectors (normal and curvature) of a parametric point on a 2D curve; + * GeomLProp package, which provides local properties on 3D curves and surfaces + * LProp package, which provides an enumeration used to characterize a particular point on a 2D curve. + +Curves are either Geom_Curve curves (in 3D space) or Geom2d_Curve curves (in the plane). +Surfaces are Geom_Surface surfaces. The point on which local properties are calculated +is defined by its u parameter value on a curve, and its (u,v) parameter values on a surface. + +It is possible to query the same local properties for points as mentioned above, and additionally for 2D curves: + + * the points corresponding to a minimum or a maximum of curvature; + * the inflection points. + + +#### Example: How to check the surface concavity + +To check the concavity of a surface, proceed as follows: + + 1. Sample the surface and compute at each point the Gaussian curvature. + 2. If the value of the curvature changes of sign, the surface is concave or convex depending on the point of view. + 3. To compute a Gaussian curvature, use the class SLprops from GeomLProp, which instantiates the generic class SLProps from LProp and use the method GaussianCurvature. + +@subsection occt_modat_4_2a Continuity of Curves and Surfaces + +Types of supported continuities for curves and surfaces are described in *GeomAbs_Shape* enumeration. + +In respect of curves, the following types of continuity are supported (see the figure below): + * C0 (*GeomAbs_C0*) - parametric continuity. It is the same as G0 (geometric continuity), so the last one is not represented by separate variable. + * G1 (*GeomAbs_G1*) - tangent vectors on left and on right are parallel. + * C1 (*GeomAbs_C1*) - indicates the continuity of the first derivative. + * G2 (*GeomAbs_G2*) - in addition to G1 continuity, the centers of curvature on left and on right are the same. + * C2 (*GeomAbs_C2*) - continuity of all derivatives till the second order. + * C3 (*GeomAbs_C3*) - continuity of all derivatives till the third order. + * CN (*GeomAbs_CN*) - continuity of all derivatives till the N-th order (infinite order of continuity). + +*Note:* Geometric continuity (G1, G2) means that the curve can be reparametrized to have parametric (C1, C2) continuity. + +@figure{/user_guides/modeling_data/images/modeling_data_continuity_curves.svg,"Continuity of Curves",420} + +The following types of surface continuity are supported: + * C0 (*GeomAbs_C0*) - parametric continuity (the surface has no points or curves of discontinuity). + * G1 (*GeomAbs_G1*) - surface has single tangent plane in each point. + * C1 (*GeomAbs_C1*) - indicates the continuity of the first derivatives. + * G2 (*GeomAbs_G2*) - in addition to G1 continuity, principal curvatures and directions are continuous. + * C2 (*GeomAbs_C2*) - continuity of all derivatives till the second order. + * C3 (*GeomAbs_C3*) - continuity of all derivatives till the third order. + * CN (*GeomAbs_CN*) - continuity of all derivatives till the N-th order (infinite order of continuity). + +@figure{/user_guides/modeling_data/images/modeling_data_continuity_surfaces.svg,"Continuity of Surfaces",420} + +Against single surface, the connection of two surfaces (see the figure above) defines its continuity in each intersection point only. Smoothness of connection is a minimal value of continuities on the intersection curve. + + +@subsection occt_modat_4_2b Regularity of Shared Edges + +Regularity of an edge is a smoothness of connection of two faces sharing this edge. In other words, regularity is a minimal continuity between connected faces in each point on edge. + +Edge's regularity can be set by *BRep_Builder::Continuity* method. To get the regularity use *BRep_Tool::Continuity* method. + +Some algorithms like @ref occt_modalg_6 "Fillet" set regularity of produced edges by their own algorithms. On the other hand, some other algorithms (like @ref specification__boolean_operations "Boolean Operations", @ref occt_user_guides__shape_healing "Shape Healing", etc.) do not set regularity. If the regularity is needed to be set correctly on a shape, the method *BRepLib::EncodeRegularity* can be used. It calculates and sets correct values for all edges of the shape. + +The regularity flag is extensively used by the following high level algorithms: @ref occt_modalg_6_1_2 "Chamfer", @ref occt_modalg_7_3 "Draft Angle", @ref occt_modalg_10 "Hidden Line Removal", @ref occt_modalg_9_2 "Gluer". + + +@subsection occt_modat_4_3 Global Properties of Shapes + +The Global Properties of Shapes component provides algorithms for computing the global +properties of a composite geometric system in 3D space, and frameworks to query the computed results. + +The global properties computed for a system are : + * mass, + * mass center, + * matrix of inertia, + * moment about an axis, + * radius of gyration about an axis, + * principal properties of inertia such as principal axis, principal moments, and principal radius of gyration. + +Geometric systems are generally defined as shapes. Depending on the way they are analyzed, these shapes will give properties of: + + * lines induced from the edges of the shape, + * surfaces induced from the faces of the shape, or + * volumes induced from the solid bounded by the shape. + +The global properties of several systems may be brought together to give the global properties of the system composed of the sum of all individual systems. + +The Global Properties of Shapes component is composed of: +* seven functions for computing global properties of a shape: one function for lines, two functions for surfaces and four functions for volumes. The choice of functions depends on input parameters and algorithms used for computation (BRepGProp global functions), +* a framework for computing global properties for a set of points (GProp_PGProps), +* a general framework to bring together the global properties retained by several more elementary frameworks, and provide a general programming interface to consult computed global properties. + +Packages *GeomLProp* and *Geom2dLProp* provide algorithms calculating the local properties of curves and surfaces + +A curve (for one parameter) has the following local properties: +- Point +- Derivative +- Tangent +- Normal +- Curvature +- Center of curvature. + +A surface (for two parameters U and V) has the following local properties: +- point +- derivative for U and V) +- tangent line (for U and V) +- normal +- max curvature +- min curvature +- main directions of curvature +- mean curvature +- Gaussian curvature + +The following methods are available: +* *CLProps* -- calculates the local properties of a curve (tangency, curvature,normal); +* *CurAndInf2d* -- calculates the maximum and minimum curvatures and the inflection points of 2d curves; +* *SLProps* -- calculates the local properties of a surface (tangency, the normal and curvature). +* *Continuity* -- calculates regularity at the junction of two curves. + +Note that the B-spline curve and surface are accepted but they are not cut into pieces of the desired continuity. It is the global continuity, which is seen. + +@subsection occt_modat_4_4 Adaptors for Curves and Surfaces + +Some Open CASCADE Technology general algorithms may work theoretically on numerous types of curves or surfaces. + +To do this, they simply get the services required of the analyzed curve or surface through an interface so as to a single API, whatever the type of curve or surface. These interfaces are called adaptors. + +For example, Adaptor3d_Curve is the abstract class which provides the required services by an algorithm which uses any 3d curve. + + GeomAdaptor package provides interfaces: + * On a Geom curve; + * On a curve lying on a Geom surface; + * On a Geom surface; + + Geom2dAdaptor package provides interfaces : + * On a Geom2d curve. + + BRepAdaptor package provides interfaces: + * On a Face + * On an Edge + +When you write an algorithm which operates on geometric objects, use Adaptor3d (or Adaptor2d) objects. + +As a result, you can use the algorithm with any kind of object, if you provide for this object an interface derived from *Adaptor3d* or *Adaptor2d*. +These interfaces are easy to use: simply create an adapted curve or surface from a *Geom2d* curve, and then use this adapted curve as an argument for the algorithm? which requires it. @section occt_modat_6 Bounding boxes diff --git a/dox/user_guides/ocaf/images/tobj_image003.png b/dox/user_guides/ocaf/images/tobj_image003.png new file mode 100644 index 0000000000..ffb6b1168b Binary files /dev/null and b/dox/user_guides/ocaf/images/tobj_image003.png differ diff --git a/dox/user_guides/ocaf/images/tobj_image004.png b/dox/user_guides/ocaf/images/tobj_image004.png new file mode 100644 index 0000000000..264cca7d66 Binary files /dev/null and b/dox/user_guides/ocaf/images/tobj_image004.png differ diff --git a/dox/user_guides/ocaf/images/tobj_image005.png b/dox/user_guides/ocaf/images/tobj_image005.png new file mode 100644 index 0000000000..cf79264f42 Binary files /dev/null and b/dox/user_guides/ocaf/images/tobj_image005.png differ diff --git a/dox/user_guides/ocaf/images/tobj_image006.png b/dox/user_guides/ocaf/images/tobj_image006.png new file mode 100644 index 0000000000..6b1343b1b7 Binary files /dev/null and b/dox/user_guides/ocaf/images/tobj_image006.png differ diff --git a/dox/user_guides/ocaf/images/tobj_image007.png b/dox/user_guides/ocaf/images/tobj_image007.png new file mode 100644 index 0000000000..3919188a0f Binary files /dev/null and b/dox/user_guides/ocaf/images/tobj_image007.png differ diff --git a/dox/user_guides/ocaf/images/tobj_image008.png b/dox/user_guides/ocaf/images/tobj_image008.png new file mode 100644 index 0000000000..970d9b15db Binary files /dev/null and b/dox/user_guides/ocaf/images/tobj_image008.png differ diff --git a/dox/user_guides/ocaf/ocaf.md b/dox/user_guides/ocaf/ocaf.md index e5694279e3..80dc90e74f 100644 --- a/dox/user_guides/ocaf/ocaf.md +++ b/dox/user_guides/ocaf/ocaf.md @@ -6,8 +6,7 @@ OCAF {#occt_user_guides__ocaf} @section occt_ocaf_1 Introduction This manual explains how to use the Open CASCADE Application Framework (OCAF). -It provides basic documentation on using OCAF. For advanced information on OCAF -and its applications, see our E-learning & Training offerings. +It provides basic documentation on using OCAF. @subsection occt_ocaf_1_1 Purpose of OCAF @@ -512,7 +511,7 @@ Choosing the alternative way of implementation of new data types allows to forge Let’s study the implementation of the same data type in both ways by the example of transformation represented by *gp_Trsf* class. The class *gp_Trsf* defines the transformation according to the type (*gp_TrsfForm*) and a set of parameters of the particular type of transformation (two points or a vector for translation, an axis and an angle for rotation, and so on). -1. The first way: creation of a new attribute. The implementation of the transformation by creation of a new attribute is represented in the @ref occt_ocaf_11 "Samples". +1. The first way: creation of a new attribute. The implementation of the transformation by creation of a new attribute is represented in the @ref samples__ocaf "Samples". 2. The second way: creation of a new data type by means of combination of standard attributes. Depending on the type of transformation it may be kept in data framework by different standard attributes. For example, a translation is defined by two points. Therefore the data tree for translation looks like this: * Type of transformation (gp_Translation) as *TDataStd_Integer*; @@ -1820,554 +1819,957 @@ Both the XML format and the XML OCAF persistence code are extensible in the sens * Add (in the new *DocumentStorageDriver*) the *targetNamespace* accompanied with its prefix, using method *XmlDrivers_DocumentStorageDriver::AddNamespace*. The same is done for all namespaces objects which are used by the new persistence, with the exception of the "ocaf" namespace. * Pass (in every OCAF attribute driver) the namespace prefix of the *targetNamespace* to the constructor of *XmlMDF_ADriver*. -@section occt_ocaf_10 GLOSSARY +@section occt_tobj TObj Package -* **Application** -- a document container holding all documents containing all application data. -* **Application data** -- the data produced by an application, as opposed to data referring to it. -* **Associativity of data** -- the ability to propagate modifications made to one document to other documents, which refer to such document. Modification propagation is: - * unidirectional, that is, from the referenced to the referencing document(s), or - * bi-directional, from the referencing to the referenced document and vice-versa. -* **Attribute** -- a container for application data. An attribute is attached to a label in the hierarchy of the data framework. -* **Child** -- a label created from another label, which by definition, is the father label. -* **Compound document** -- a set of interdependent documents, linked to each other by means of external references. These references provide the associativity of data. -* **Data framework** -- a tree-like data structure which in OCAF, is a tree of labels with data attached to them in the form of attributes. This tree of labels is accessible through the services of the *TDocStd_Document* class. -* **Document** -- a container for a data framework which grants access to the data, and is, in its turn, contained by an application. A document also allows you to: - * Manage modifications, providing Undo and Redo functions - * Manage command transactions - * Update external links - * Manage save and restore options - * Store the names of software extensions. -* **Driver** -- an abstract class, which defines the communications protocol with a system. -* **Entry** -- an ASCII character string containing the tag list of a label. For example: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} -0:3:24:7:2:7 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +@subsection occt_tobj_1 Introduction -* **External links** -- references from one data structure to another data structure in another document. -To store these references properly, a label must also contain an external link attribute. -* **Father** -- a label, from which other labels have been created. The other labels are, by definition, the children of this label. -* **Framework** -- a group of co-operating classes which enable a design to be re-used for a given category of problem. The framework guides the architecture of the application by breaking it up into abstract classes, each of which has different responsibilities and collaborates in a predefined way. Application developer creates a specialized framework by: - * defining new classes which inherit from these abstract classes - * composing framework class instances - * implementing the services required by the framework. +This document describes the package TObj, which is an add-on +to the Open CASCADE Application Framework (OCAF). -In C++, the application behavior is implemented in virtual functions redefined in these derived classes. This is known as overriding. +This package provides a set of classes and auxiliary tools facilitating +the creation of object-oriented data models on top of low-level OCAF data structures. +This includes: -* **GUID** -- Global Universal ID. A string of 37 characters intended to uniquely identify an object. For example: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} -2a96b602-ec8b-11d0-bee7-080009dc3333 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * Definition of classes representing data objects. Data objects store their data using primitive OCAF attributes, taking advantage of OCAF mechanisms for Undo/Redo and persistence. At the same time they provide a higher level abstraction over the pure OCAF document structure (labels / attributes). + * Organization of the data model as a hierarchical (tree-like) structure of objects. + * Support of cross-references between objects within one model or among different models. In case of cross-model references the models should depend hierarchically. + * Persistence mechanism for storing *TObj* objects in OCAF files, which allows storing and retrieving objects of derived types without writing additional code to support persistence. -* **Label** -- a point in the data framework, which allows data to be attached to it by means of attributes. It has a name in the form of an entry, which identifies its place in the data framework. -* **Modified label** -- containing attributes whose data has been modified. -* **Reference key** -- an invariant reference, which may refer to any type of data used in an application. In its transient form, it is a label in the data framework, and the data is attached to it in the form of attributes. In its persistent form, it is an entry of the label. It allows an application to recover any entity in the current session or in a previous session. -* **Resource file** -- a file containing a list of each document’s schema name and the storage and retrieval plug-ins for that document. -* **Root** -- the starting point of the data framework. This point is the top label in the framework. It is represented by the [0] entry and is created at the same time with the document you are working on. -* **Scope** -- the set of all the attributes and labels which depend on a given label. -* **Tag list** -- a list of integers, which identify the place of a label in the data framework. This list is displayed in an entry. -* **Topological naming** -- systematic referencing of topological entities so that these entities can still be identified after the models they belong to have gone through several steps in modeling. In other words, topological naming allows you to track entities through the steps in the modeling process. This referencing is needed when a model is edited and regenerated, and can be seen as a mapping of labels and name attributes of the entities in the old version of a model to those of the corresponding entities in its new version. Note that if the topology of a model changes during the modeling, this mapping may not fully coincide. A Boolean operation, for example, may split edges. -* **Topological tracking** -- following a topological entity in a model through the steps taken to edit and regenerate that model. -* **Valid label** -- in a data framework, this is a label, which is already recomputed in the scope of regeneration sequence and includes the label containing a feature which is to be recalculated. Consider the case of a box to which you first add a fillet, then a protrusion feature. For recalculation purposes, only valid labels of each construction stage are used. In recalculating a fillet, they are only those of the box and the fillet, not the protrusion feature which was added afterwards. +This document describes basic principles of logical and physical organization +of TObj-based data models and typical approaches to implementation of classes representing model objects. -@section occt_ocaf_11 Samples +@subsubsection occt_tobj_1_1 Applicability -@subsection occt_ocaf_11_a Getting Started +The main purpose of the *TObj* data model is rapid development +of the object-oriented data models for applications, using the existing +functionality provided by OCAF (Undo/Redo and persistence) +without the necessity to redevelop such functionality from scratch. - At the beginning of your development, you first define an application class by inheriting from the Application abstract class. - You only have to create and determine the resources of the application - for specifying the format of your documents (you generally use the standard one) and their file extension. - - Then, you design the application data model by organizing attributes you choose among those provided with OCAF. - You can specialize these attributes using the User attribute. For example, if you need a reflection coefficient, - you aggregate a User attribute identified as a reflection coefficient - with a Real attribute containing the value of the coefficient (as such, you don't define a new class). - - If you need application specific data not provided with OCAF, for example, - to incorporate a finite element model in the data structure, - you define a new attribute class containing the mesh, - and you include its persistent homologue in a new file format. - - Once you have implemented the commands which create and modify the data structure - according to your specification, OCAF provides you, without any additional programming: - - * Persistent reference to any data, including geometric elements — several documents can be linked with such reference; - * Document-View association; - * Ready-to-use functions such as : - * Undo-redo; - * Save and open application data. - - Finally, you develop the application's graphical user interface using the toolkit of your choice, for example: - * KDE Qt or GNOME GTK+ on Linux; - * Microsoft Foundation Classes (MFC) on Windows Motif on Sun; - * Other commercial products such as Ilog Views. +As opposed to using bare OCAF (at the level of labels and attributes), +TObj facilitates dealing with higher level abstracts, which are closer +to the application domain. It works best when the application data are naturally +organized in hierarchical structures, and is especially useful for complex data +models with dependencies between objects belonging to different parts of the model. + +It should be noted that *TObj* is efficient for representing data structures containing +a limited number of objects at each level of the data structure (typically less than 1000). +A greater number of objects causes performance problems due to list-based organization of OCAF documents. Therefore, other methods of storage, such as arrays, are advisable for data models or their sub-parts containing a great number of uniform objects. However, these methods +can be combined with the usage of *TObj* to represent the high-level structure of the model. + +@subsection occt_tobj_2 TObj Model + +@subsubsection occt_tobj_2_1 TObj Model structure + +In the *TObj* data model the data are separated from the interfaces that manage them. + +It should be emphasized that *TObj* package defines only the interfaces and the basic structure of the model and objects, while the actual contents and structure of the model of a particular application are defined by its specific classes inherited from *TObj* classes. The implementation can add its own features or even change the default behaviour and the data layout, though this is not recommended. + +Logically the *TObj* data model is represented as a tree of model objects, with upper-level objects typically being collections of other objects (called *partitions*, represented by the class *TObj_Partition*). The root object of the model is called the *Main partition* and is maintained by the model itself. This partition contains a list of sub-objects called its *children* each sub-object may contain its own children (according to its type), etc. + +@figure{/user_guides/ocaf/images/tobj_image003.png,"TObj Data Model",240} + +As the *TObj* Data Model is based on OCAF (Open CASCADE Application Framework) technology, +it stores its data in the underlying OCAF document. The OCAF document consists of a tree of +items called *labels*. Each label has some data attached to it in the form of *attributes*, +and may contain an arbitrary number of sub-labels. Each sub-label is identified by its sequential +number called the *tag*. The complete sequence of tag numbers of the label +and its parents starting from the document root constitutes the complete *entry* +of the label, which uniquely identifies its position in the document. + +Generally the structure of the OCAF tree of the *TObj* data +model corresponds to the logical structure of the model and can be presented as in the following picture: + +@figure{/user_guides/ocaf/images/tobj_image004.png,"TObj Data Model mapped on OCAF document",360} + +All data of the model are stored in the root label (0:1) of the OCAF document. +An attribute *TObj_TModel* is located in this root label. It +stores the object of type *TObj_Model*. This object serves as a main interface tool +to access all data and functionalities of the data model. + +In simple cases all data needed by the application may be +contained in a single data model. Moreover, *TObj* gives the possibility to +distribute the data between several interconnected data models. This can be +especially useful for the applications dealing with great amounts of data. because +only the data required for the current operation is loaded in the memory at one time. +It is presumed that the models have a hierarchical (tree-like) structure, +where the objects of the child models can refer to the objects of the parent +models, not vice-versa. Provided that the correct order of loading and closing +of the models is ensured, the *TObj* classes will maintain references between the objects automatically. + +@subsubsection occt_tobj_2_2 Data Model basic features + +The class *TObj_Model* describing the data model provides the following functionalities: + + * Loading and saving of the model from or in a file (methods *Load* and *Save*) + * Closing and removal of the model from memory (method *Close*) + * Definition of the full file name of the persistence storage for this model (method *GetFile*) + * Tools to organize data objects in partitions and iterate on objects (methods *GetObjects*, *GetMainPartition*, *GetChildren*, *getPartition*, *getElementPartition*) + * Mechanism to give unique names to model objects + * Copy (*clone*) of the model (methods *NewEmpty* and *Paste*) + * Support of earlier model formats for proper conversion of a model loaded from a file written by a previous version of the application (methods *GetFormatVersion* and *SetFormatVersion*) + * Interface to check and update the model if necessary (method *Update*) + * Support of several data models in one application. For this feature use OCAF multi-transaction manager, unique names and GUIDs of the data model (methods *GetModelName*, *GetGUID*) + +@subsubsection occt_tobj_2_3 Model Persistence + +The persistent representation of any OCAF model is contained in an XML or a binary file, +which is defined by the format string returned by the method *GetFormat*. +The default implementation works with a binary OCAF document format (*BinOcaf*). +The other available format is *XmlOcaf*. The class **TObj_Model** declares and provides a default +implementation of two virtual methods: + +~~~~~{.cpp} + virtual Standard_Boolean Load (const char* theFile); + virtual Standard_Boolean SaveAs (const char* theFile); +~~~~~ + +which retrieve and store the model from or +in the OCAF file. The descendants +should define the following protected method to support Load and Save operations: + +~~~~~{.cpp} + virtual Standard_Boolean initNewModel (const Standard_Boolean IsNew); +~~~~~ + +This method is called by *Load* after creation of a new model +or after its loading from the file; its purpose is to perform +the necessary initialization of the model (such as creation of necessary top-level +partitions, model update due to version changes etc.). Note that if +the specified file does not exist, method *Load* will create +a new document and call *initNewModel* with the argument **True**. +If the file has been normally loaded, the argument **False** is passed. +Thus, a new empty *TObj* model is created by calling *Load* with an empty +string or the path to a nonexistent file as argument. + +The method *Load* returns **True** if the model has been retrieved successfully +(or created a new), or **False** if the model could not be loaded. +If no errors have been detected during initialization (model retrieval or creation), +the virtual method *AfterRetrieval* is invoked for all objects of the model. +This method initializes or updates the objects immediately after the model initialization. +It could be useful when some object data should be imported from an OCAF attribute into transient +fields which could be changed outside of the OCAF transaction mechanism. +Such fields can be stored into OCAF attributes for saving into persistent storage during the save operation. + +To avoid memory leaks, the *TObj_Model* class destructor invokes *Close* method +which clears the OCAF document and removes all data from memory before the model is destroyed. + +For XML and binary persistence of the *TObj* data model the corresponding drivers are implemented +in *BinLDrivers*, *BinMObj* and *XmlLDrivers*, *XmlMObj* packages. +These packages contain retrieval and storage drivers for the model, model objects and custom attributes +from the *TObj* package. The schemas support persistence for the standard OCAF and *TObj* attributes. +This is sufficient for the implementation of simple data models, but +in some cases it can be reasonable to add specific OCAF attributes to +facilitate the storage of the data specific to the application. +In this case the schema should be extended using the standard OCAF mechanism. + +@subsubsection occt_tobj_2_4 Access to the objects in the model + +All objects in the model are stored in the main partition and accessed by iterators. +To access all model objects use: + +~~~~~{.cpp} + virtual Handle(TObj_ObjectIterator) GetObjects () const; +~~~~~ + +This method returns a recursive iterator on all objects stored in the model. + +~~~~~{.cpp} + virtual Handle(TObj_ObjectIterator) GetChildren () const; +~~~~~ + +This method returns an iterator on child objects of the main partition. +Use the following method to get the main partition: + +~~~~~{.cpp} + Handle(TObj_Partition) GetMainPartition() const; +~~~~~ + +To receive the iterator on objects of a specific type *AType* use the following call: + +~~~~~{.cpp} + GetMainPartition()->GetChildren(STANDARD_TYPE(AType) ); +~~~~~ + +The set of protected methods is provided for descendant classes to deal with partitions: + +~~~~~{.cpp} + virtual Handle(TObj_Partition) getPartition (const TDF_Label, const Standard_Boolean theHidden) const; +~~~~~ + +This method returns (creating if necessary) a partition in the specified label of the document. +The partition can be created as hidden (*TObj_HiddenPartition* class). +A hidden partition can be useful to distinguish the data that +should not be visible to the user when browsing the model in the application. + +The following two methods allow getting (creating) a partition +in the sub-label of the specified label in the document +(the label of the main partition for the second method) and with the given name: + +~~~~~{.cpp} + virtual Handle(TObj_Partition) getPartition (const TDF_Label, const Standard_Integer theIndex, const TCollection_ExtendedString& theName, const Standard_Boolean theHidden) const; + virtual Handle(TObj_Partition) getPartition (const Standard_Integer theIndex, const TCollection_ExtendedString& theName, const Standard_Boolean theHidden) const; +~~~~~ + +If the default object naming and the name register mechanism +is turned on, the object can be found in the model by its unique name: + +~~~~~{.cpp} + Handle(TObj_Object) FindObject (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary) const; +~~~~~ + +@subsubsection occt_tobj_2_5 Own model data + +The model object can store its own data in the Data label +of its main partition, however, there is no standard API for +setting and getting these data types. The descendants can add +their own data using standard OCAF methods. The enumeration DataTag is defined +in *TObj_Model* to avoid conflict of data labels used by this class +and its descendants, similarly to objects (see below). + +@subsubsection occt_tobj_2_6 Object naming + +The basic implementation of *TObj_Model* provides the default +naming mechanism: all objects must have unique names, +which are registered automatically in the data model dictionary. +The dictionary is a *TObj_TNameContainer* +attribute whose instance is located in the model root label. +If necessary, the developer can add several dictionaries into +the specific partitions, providing the name registration in the +correct name dictionary and restoring the name map after document is loaded from file. +To ignore name registering it is necessary to redefine the methods *SetName*, +*AfterRetrieval* of the *TObj_Object* class and skip the registration of the object name. +Use the following methods for the naming mechanism: + +~~~~~{.cpp} + Standard_Boolean IsRegisteredName (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary ) const; +~~~~~ + +Returns **True** if the object name is already registered in the indicated (or model) dictionary. + +~~~~~{.cpp} + void RegisterName (const Handle(TCollection_HExtendedString)& theName, const TDF_Label& theLabel, const Handle(TObj_TNameContainer)& theDictionary ) const; +~~~~~ + +Registers the object name with the indicated label where the object +is located in the OCAF document. Note that the default implementation +of the method *SetName* of the object registers the new name automatically +(if the name is not yet registered for any other object) + +~~~~~{.cpp} + void UnRegisterName (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary ) const; +~~~~~ + +Unregisters the name from the dictionary. Ther names of *TObj* model +objects are removed from the dictionary when the objects are deleted from the model. + +~~~~~{.cpp} + Handle(TObj_TNameContainer) GetDictionary() const; +~~~~~ + +Returns a default instance of the model dictionary (located at the model root label). +The default implementation works only with one dictionary. +If there are a necessity to have more than one dictionary for the model objects, +it is recommended to redefine the corresponding virtual method of TObj_Object +that returns the dictionary where names of objects should be registered. + +@subsubsection occt_tobj_2_7 API for transaction mechanism + +Class *TObj_Model* provides the API for transaction mechanism (supported by OCAF): + +~~~~~{.cpp} + Standard_Boolean HasOpenCommand() const; +~~~~~ + +Returns True if a Command transaction is open + +~~~~~{.cpp} + void OpenCommand() const; +~~~~~ + +Opens a new command transaction. + +~~~~~{.cpp} + void CommitCommand() const; +~~~~~ + +Commits the Command transaction. Does nothing If there is no open Command transaction. + +~~~~~{.cpp} + void AbortCommand() const; +~~~~~ + +Aborts the Command transaction. Does nothing if there is no open Command transaction. + +~~~~~{.cpp} + Standard_Boolean IsModified() const; +~~~~~ + +Returns True if the model document has a modified status (has changes after the last save) + +~~~~~{.cpp} + void SetModified( const Standard_Boolean ); +~~~~~ + +Changes the modified status by force. For synchronization of transactions +within several *TObj_Model* documents use class *TDocStd_MultiTransactionManager*. + +@subsubsection occt_tobj_28 Model format and version + +Class *TObj_Model* provides the descendant classes with a means to control +the format of the persistent file by choosing the schema used to store or retrieve operations. + +~~~~~{.cpp} + virtual TCollection_ExtendedString GetFormat () const; +~~~~~ + +Returns the string *TObjBin* or *TObjXml* indicating +the current persistent mechanism. The default value is *TObjBin*. +Due to the evolution of functionality of the developed application, +the contents and the structure of its data model vary from version to version. +*TObj* package provides a basic mechanism supporting backward versions compatibility, +which means that newer versions of the application will be able to read +Data Model files created by previous versions (but not vice-versa) with a minimum loss of data. +For each type of Data Model, all known versions of the data format +should be enumerated in increasing order, incremented with every change +of the model format. The current version of the model +format is stored in the model file and can be checked upon retrieval. + +~~~~~{.cpp} + Standard_Integer GetFormatVersion() const; +~~~~~ + +Returns the format version stored in the model file + +~~~~~{.cpp} + void SetFormatVersion(const Standard_Integer theVersion); +~~~~~ + +Defines the format version used for save. + +Upon loading a model, the method *initNewModel()*, called immediately +after opening a model from disk (on the level of the OCAF document), +provides a specific code that checks the format version stored in that model. +If it is older than the current version of the application, the data update can be performed. +Each model can have its own specific conversion code +that performs the necessary data conversion to make them compliant with the current version. + +When the conversion ends the user is advised of that by the messenger interface +provided by the model (see messaging chapter for more details), +and the model version is updated. If the version of data model is not supported +(it is newer than the current or too old), the load operation should fail. +The program updating the model after version change can be implemented as static +methods directly in C++ files of the corresponding Data Model classes, +not exposing it to the other parts of the application. +These codes can use direct access to the model and objects data (attributes) +not using objects interfaces, because the data model API and object classes +could have already been changed. + +Note that this mechanism has been designed to maintain version compatibility +for the changes of data stored in the model, not for the changes of +low-level format of data files (such as the storage format of a specific OCAF attribute). +If the format of data files changes, a specific treatment on a case-by-case basis will be required. + +@subsubsection occt_tobj_2_9 Model update + +The following methods are used for model update to ensure its consistency +with respect to the other models in case of cross-model dependencies: + +~~~~~{.cpp} + virtual Standard_Boolean Update(); +~~~~~ + +This method is usually called after loading of the model. +The default implementation does nothing and returns **True**. + +~~~~~{.cpp} + virtual Standard_Boolean initNewModel( const Standard_Boolean IsNew); +~~~~~ + +This method performs model initialization, check and updates (as described above). + +~~~~~{.cpp} + virtual void updateBackReferences( const Handle(TObj_Object)& theObj); +~~~~~ + +This method is called from the previous method to update back references +of the indicated object after the retrieval of the model from file +(see data model - object relationship chapter for more details) + +@subsubsection occt_tobj_2_10 Model copying + +To copy the model between OCAF documents use the following methods: + +~~~~~{.cpp} + virtual Standard_Boolean Paste (Handle(TObj_Model) theModel, Handle(TDF_RelocationTable) theRelocTable = 0 ); +~~~~~ + +Pastes the current model to the new model. The relocation table +ensures correct copying of the sub-data shared by several parts of the model. +It stores a map of processed original objects of relevant types in their copies. + +~~~~~{.cpp} + virtual Handle(TObj_Model) NewEmpty() = 0; +~~~~~ + +Redefines a pure virtual method to create a new empty instance of the model. + +~~~~~{.cpp} + void CopyReferences ( const Handle(TObj_Model)& theTarget, const Handle(TDF_RelocationTable)& theRelocTable); +~~~~~ + +Copies the references from the current model to the target model. + +@subsubsection occt_tobj_2_11 Messaging + +The messaging is organised using Open CASCADE Messenger from the package Message. +The messenger is stored as the field of the model instance +and can be set and retrieved by the following methods: + +~~~~~{.cpp} + void SetMessenger( const Handle(Message_Messenger)& ); + Handle(Message_Messenger) Messenger() const; +~~~~~ + +A developer should create his own instance of the Messenger +bound to the application user interface, and attribute it to the model +for future usage. In particular the messenger is used for reporting +errors and warnings in the persistence mechanism. +Each message has a unique string identifier (key). +All message keys are stored in a special resource file TObj.msg. +This file should be loaded at the start of the application +by call to the appropriate method of the class *Message_MsgFile*. + +@subsection occt_tobj_3 Model object + +Class *TObj_Object* provides basic interface and default implementation +of important features of *TObj* model objects. This implementation defines +basic approaches that are recommended for all descendants, +and provides tools to facilitate their usage. + +@figure{/user_guides/ocaf/images/tobj_image005.png,"TObj objects hierarchy",170} + +@subsubsection occt_tobj_3_1 Separation of data and interface + +In the *TObj* data model, the data are separated from the interfaces that manage them. +The data belonging to a model object are stored in its root label and sub-labels +in the form of standard OCAF attributes. This allows using standard OCAF mechanisms +for work with these data, and eases the implementation of the persistence mechanism. + +The instance of the interface which serves as an API for managing object data +(e.g. represents the model object) is stored in the root label of the object, +and typically does not bring its own data. The interface classes are organized in a hierarchy +corresponding to the natural hierarchy of the model objects according to the application. + +In the text below the term 'object' is used to denote either the instance +of the interface class or the object itself (both interface and data stored in OCAF). + +The special type of attribute *TObj_TObject* is used for storing instances of objects interfaces +in the OCAF tree. *TObj_TObject* is a simple container for the object of type *TObj_Object*. +All objects (interfaces) of the data model inherit this class. + +@figure{/user_guides/ocaf/images/tobj_image006.png,"TObj object stored on OCAF label",360} + + +@subsubsection occt_tobj_3_2 Basic features + +The *TObj_Object* class provides some basic features that can be inherited (or, if necessary, redefined) by the descendants: + + * Gives access to the model to which the object belongs (method *GetModel*) and to the OCAF label in which the object is stored (method *GetLabel*). + * Supports references (and back references) to other objects in the same or in another model (methods *getReference*, *setReference*, *addReference*, *GetReferences*, *GetBackReferences*, *AddBackReference*, *RemoveBackReference*, *ReplaceReference*) + * Provides the ability to contain child objects, as it is actual for partition objects (methods *GetChildren*, *GetFatherObject*) + * Organizes its data in the OCAF structure by separating the sub-labels of the main label intended for various kinds of data and providing tools to organize these data (see below). The kinds of data stored separately are: + * Child objects stored in the label returned by the method *GetChildLabel* + * References to other objects stored in the label returned by the method *GetReferenceLabel* + * Other data, both common to all objects and specific for each subtype of the model object, are stored in the label returned by the method *GetDataLabel* + * Provides unique names of all objects in the model (methods *GetDictionary*, *GetName*, *SetName*) + * Provides unified means to maintain persistence (implemented in descendants with the help of macros *DECLARE_TOBJOCAF_PERSISTENCE* and *IMPLEMENT_TOBJOCAF_PERSISTENCE*) + * Allows an object to remove itself from the OCAF document and check the depending objects can be deleted according to the back references (method *Detach*) + * Implements methods for identification and versioning of objects + * Manages the object interaction with OCAF Undo/Redo mechanism (method *IsAlive*, *AfterRetrieval*, *BeforeStoring*) + * Allows make a clone (methods *Clone*, *CopyReferences*, *CopyChildren*, *copyData*) + * Contains additional word of bit flags (methods *GetFlags*, *SetFlags*, *TestFlags*, *ClearFlags*) + * Defines the interface to sort the objects by rank (methods *GetOrder*, *SetOrder*) + * Provides a number of auxiliary methods for descendants to set/get the standard attribute values, such as int, double, string, arrays etc. + +An object can be received from the model by the following methods: + +~~~~~{.cpp} + static Standard_Boolean GetObj ( const TDF_Label& theLabel, Handle(TObj_Object)& theResObject, const Standard_Boolean isSuper = Standard_False ); +~~~~~ + +Returns *True* if the object has been found in the indicated label (or in the upper level label if *isSuper* is *True*). + +~~~~~{.cpp} + Handle(TObj_Object) GetFatherObject ( const Handle(Standard_Type)& theType = NULL ) const; +~~~~~ + +Returns the father object of the indicated type +for the current object (the direct father object if the type is NULL). + +@subsubsection occt_tobj_3_3 Data layout and inheritance + +As far as the data objects are separated from the interfaces and stored in the OCAF tree, +the functionality to support inheritance is required. Each object has its own data +and references stored in the labels in the OCAF tree. All data are stored in the sub-tree +of the main object label. If it is necessary to inherit a class from the base class, +the descendant class should use different labels for data and references than its ancestor. + +Therefore each *TObj* class can reserve the range of tags in each of +*Data*, *References*, and *Child* sub-labels. +The reserved range is declared by the enumeration defined +in the class scope (called DataTag, RefTag, and ChildTag, respectively). +The item *First* of the enumeration of each type is defined via the *Last* item +of the corresponding enumeration of the parent class, thus ensuring that the tag numbers +do not overlap. The item *Last* of the enumeration defines the last tag reserved by this class. +Other items of the enumeration define the tags used for storing particular data items of the object. +See the declaration of the TObj_Partition class for the example. + +*TObj_Object* class provides a set of auxiliary methods for descendants +to access the data stored in sub-labels by their tag numbers: + +~~~~~{.cpp} + TDF_Label getDataLabel (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const; + TDF_Label getReferenceLabel (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const; +~~~~~ + +Returns the label in *Data* or *References* sub-labels at a given tag number (theRank1). +The second argument, theRank2, allows accessing the next level of hierarchy +(theRank2-th sub-label of theRank1-th data label). +This is useful when the data to be stored are represented by multiple OCAF attributes +of the same type (e.g. sequences of homogeneous data or references). + +The get/set methods allow easily accessing the data located in the specified data label +for the most widely used data types (*Standard_Real*, *Standard_Integer*, *TCollection_HExtendedString*, + *TColStd_HArray1OfReal*, *TColStd_HArray1OfInteger*, *TColStd_HArray1OfExtendedString*). +For instance, methods provided for real numbers are: + +~~~~~{.cpp} + Standard_Real getReal (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const; + Standard_Boolean setReal (const Standard_Real theValue, const Standard_Integer theRank1, const Standard_Integer theRank2 = 0, const Standard_Real theTolerance = 0.) const; +~~~~~ + +Similar methods are provided to access references to other objects: + +~~~~~{.cpp} + Handle(TObj_Object) getReference (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const; + Standard_Boolean setReference (const Handle(TObj_Object) &theObject, const Standard_Integer theRank1, const Standard_Integer theRank2 = 0); +~~~~~ + +The method *addReference* gives an easy way to store a sequence of homogeneous references in one label. + +~~~~~{.cpp} + TDF_Label addReference (const Standard_Integer theRank1, const Handle(TObj_Object) &theObject); +~~~~~ + +Note that while references to other objects should be defined by descendant classes +individually according to the type of object, *TObj_Object* provides methods +to manipulate (check, remove, iterate) the existing references in the uniform way, as described below. + +@subsubsection occt_tobj_3_4 Persistence + +The persistence of the *TObj* Data Model is implemented with the help +of standard OCAF mechanisms (a schema defining necessary plugins, drivers, etc.). +This implies the possibility to store/retrieve all data that are stored +as standard OCAF attributes., The corresponding handlers are added +to the drivers for *TObj*-specific attributes. + +The special tool is provided for classes inheriting from *TObj_Object* +to add the new types of persistence without regeneration of the OCAF schema. +The class *TObj_Persistence* provides basic means for that: + + * automatic run-time registration of object types + * creation of a new object of the specified type (one of the registered types) + +Two macros defined in the file TObj_Persistence.hxx have to be included in the definition +of each model object class inheriting TObj_Object to activate the persistence mechanism: + +~~~~~{.cpp} + DECLARE_TOBJOCAF_PERSISTENCE (classname, ancestorname) +~~~~~ + +Should be included in the private section of declaration of each class inheriting +*TObj_Object* (hxx file). This macro adds an additional constructor to the object class, +and declares an auxiliary (private) class inheriting *TObj_Persistence* +that provides a tool to create a new object of the proper type. + +~~~~~{.cpp} + IMPLEMENT_TOBJOCAF_PERSISTENCE (classname) +~~~~~ + +Should be included in .cxx file of each object class that should be saved and restored. +This is not needed for abstract types of objects. This macro implements the functions +declared by the previous macro and creates a static member +that automatically registers that type for persistence. + +When the attribute *TObj_TObject* that contains the interface object is saved, +its persistence handler stores the runtime type of the object class. +When the type is restored the handler dynamically recognizes the type +and creates the corresponding object using mechanisms provided by *TObj_Persistence*. + +@subsubsection occt_tobj_3_5 Names of objects + +All *TObj* model objects have names by which the user can refer to the object. +Upon creation, each object receives a default name, constructed +from the prefix corresponding to the object type (more precisely, the prefix is defined +by the partition to which the object belongs), and the index of the object in the current partition. +The user has the possibility to change this name. The uniqueness of the name in the model is ensured +by the naming mechanism (if the name is already used, it cannot be attributed to another object). +This default implementation of *TObj* package works with a single instance of the name container (dictionary) +for name registration of objects and it is enough in most simple projects. +If necessary, it is easy to redefine a couple of object methods +(for instance *GetDictionary*()) and to take care of construction and initialization of containers. + +This functionality is provided by the following methods: + +~~~~~{.cpp} + virtual Handle(TObj_TNameContainer) GetDictionary() const; +~~~~~ + +Returns the name container where the name of object should be registered. +The default implementation returns the model name container. + +~~~~~{.cpp} + Handle(TCollection_HExtendedString) GetName() const; + Standard_Boolean GetName( TCollection_ExtendedString& theName ) const; + Standard_Boolean GetName( TCollection_AsciiString& theName ) const; +~~~~~ + +Returns the object name. The methods with in / out argument return False if the object name is not defined. + +~~~~~{.cpp} + virtual Standard_Boolean SetName ( const Handle(TCollection_HExtendedString)& theName ) const; + Standard_Boolean SetName ( const Handle(TCollection_HAsciiString)& theName ) const; + Standard_Boolean SetName ( const Standard_CString theName ) const; +~~~~~ + +Attributes a new name to the object and returns **True** if the name has been attributed successfully. +Returns False if the name has been already attributed to another object. +The last two methods are short-cuts to the first one. + +@subsubsection occt_tobj_3_6 References between objects + +Class *TObj_Object* allows creating references to other objects in the model. +Such references describe relations among objects which are not adequately reflected +by the hierarchical objects structure in the model (parent-child relationship). + +The references are stored internally using the attribute TObj_TReference. +This attribute is located in the sub-label of the referring object (called *master*) +and keeps reference to the main label of the referred object. +At the same time the referred object can maintain the back reference to the master object. + +@figure{/user_guides/ocaf/images/tobj_image007.png,"Objects relationship",360} + + + +The back references are stored not in the OCAF document but as a transient field +of the object; they are created when the model is restored from file, +and updated automatically when the references are manipulated. +The class *TObj_TReference* allows storing references between objects +from different *TObj* models, facilitating the construction of complex relations between objects. + +The most used methods for work with references are: + +~~~~~{.cpp} + virtual Standard_Boolean HasReference( const Handle(TObj_Object)& theObject) const; +~~~~~ + +Returns True if the current object refers to the indicated object. + +~~~~~{.cpp} + virtual Handle(TObj_ObjectIterator) GetReferences ( const Handle(Standard_Type)& theType = NULL ) const; +~~~~~ + +Returns an iterator on the object references. The optional argument *theType* +restricts the types of referred objects, or does not if it is NULL. + +~~~~~{.cpp} + virtual void RemoveAllReferences(); +~~~~~ + +Removes all references from the current object. + +~~~~~{.cpp} + virtual void RemoveReference( const Handle(TObj_Object)& theObject ); +~~~~~ + +Removes the reference to the indicated object. + +~~~~~{.cpp} + virtual Handle(TObj_ObjectIterator) GetBackReferences ( const Handle(Standard_Type)& theType = NULL ) const; +~~~~~ + +Returns an iterator on the object back references. +The argument theType restricts the types of master objects, or does not if it is NULL. + +~~~~~{.cpp} + virtual void ReplaceReference ( const Handle(TObj_Object)& theOldObject, const Handle(TObj_Object)& theNewObject ); +~~~~~ + +Replaces the reference to theOldObject by the reference to *theNewObject*. +The handle theNewObject may be NULL to remove the reference. + +~~~~~{.cpp} + virtual Standard_Boolean RelocateReferences ( const TDF_Label& theFromRoot, const TDF_Label& theToRoot, const Standard_Boolean theUpdateackRefs = Standard_True ); +~~~~~ + +Replaces all references to a descendant label of *theFromRoot* +by the references to an equivalent label under *theToRoot*. +Returns **False** if the resulting reference does not point at a *TObj_Object*. +Updates back references if theUpdateackRefs is **True**. + +~~~~~{.cpp} + virtual Standard_Boolean CanRemoveReference ( const Handle(TObj_Object)& theObj) const; +~~~~~ + +Returns **True** if the reference can be removed and the master object +will remain valid (*weak* reference). +Returns **False** if the master object cannot be valid without the referred object (*strong* reference). +This affects the behaviour of objects removal from the model -- if the reference cannot be removed, +either the referred object will not be removed, or both the referred +and the master objects will be removed (depends on the deletion mode in the method **Detach**) + +@subsubsection occt_tobj_3_7 Creation and deletion of objects + +It is recommended that all objects inheriting from *TObj_Object* + should implement the same approach to creation and deletion. - You can also implement the user interface in the Java language using - the Swing-based Java Application Desktop component (JAD) provided with OCAF. - -@subsection occt_ocaf_11_1 Implementation of Attribute Transformation in a HXX file +The object of the *TObj* data model cannot be created independently +of the model instance, as far as it stores the object data in OCAF data structures. +Therefore an object class cannot be created directly as its constructor is protected. + +Instead, each object should provide a static method *Create*(), which accepts the model, +with the label, which stores the object and other type-dependent parameters +necessary for proper definition of the object. This method creates a new object with its data +(a set of OCAF attributes) in the specified label, and returns a handle to the object's interface. + +The method *Detach*() is provided for deletion of objects from OCAF model. +Object data are deleted from the corresponding OCAF label; however, +the handle on object remains valid. The only operation available after object deletion +is the method *IsAlive*() checking whether the object has been deleted or not, +which returns False if the object has been deleted. + +When the object is deleted from the data model, the method checks +whether there are any alive references to the object. +Iterating on references the object asks each referring (master) object +whether the reference can be removed. If the master object can be unlinked, +the reference is removed, otherwise the master object will be removed too +or the referred object will be kept alive. This check is performed by the method *Detach* , +but the behavior depends on the deletion mode *TObj_DeletingMode*: + + * **TObj_FreeOnly** -- the object will be destroyed only if it is free, i.e. there are no references to it from other objects + * **TObj_KeepDepending** -- the object will be destroyed if there are no strong references to it from master objects (all references can be unlinked) + * **TObj_Force** -- the object and all depending master objects that have strong references to it will be destroyed. + +The most used methods for object removing are: + +~~~~~{.cpp} + virtual Standard_Boolean CanDetachObject (const TObj_DeletingMode theMode = TObj_FreeOnly ); +~~~~~ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} -#include +Returns **True** if the object can be deleted with the indicated deletion mode. -#include -#include -#include -#include +~~~~~{.cpp} + virtual Standard_Boolean Detach ( const TObj_DeletingMode theMode = TObj_FreeOnly ); +~~~~~ -// This attribute implements a transformation data container -class MyPackage_Transformation : public TDF_Attribute -{ -public: - //!@ name Static methods +Removes the object from the document if possible +(according to the indicated deletion mode). +Unlinks references from removed objects. +Returns **True** if the objects have been successfully deleted. - //! The method returns a unique GUID of this attribute. - //! By means of this GUID this attribute may be identified - //! among other attributes attached to the same label. - Standard_EXPORT static const Standard_GUID& GetID (); +@subsubsection occt_tobj_3_8 Transformation and replication of object data - //! Finds or creates the attribute attached to . - //! The found or created attribute is returned. - Standard_EXPORT static Handle(MyPackage_Transformation) Set (const TDF_Label theLabel); +*TObj_Object* provides a number of special virtual methods to support replications of objects. These methods should be redefined by descendants when necessary. - //!@ name Methods for access to the attribute data - - //! The method returns the transformation. - Standard_EXPORT gp_Trsf Get () const; +~~~~~{.cpp} + virtual Handle(TObj_Object) Clone (const TDF_Label& theTargetLabel, Handle(TDF_RelocationTable) theRelocTable = 0); +~~~~~ - //!@ name Methods for setting the data of transformation +Copies the object to theTargetLabel. The new object will have all references of its original. +Returns a handle to the new object (null handle if fail). The data are copied directly, +but the name is changed by adding the postfix *_copy*. +To assign different names to the copies redefine the method: - //! The method defines a rotation type of transformation. - Standard_EXPORT void SetRotation (const gp_Ax1& theAxis, Standard_Real theAngle); +~~~~~{.cpp} + virtual Handle(TCollection_HExtendedString) GetNameForClone ( const Handle(TObj_Object)& ) const; +~~~~~ - //! The method defines a translation type of transformation. - Standard_EXPORT void SetTranslation (const gp_Vec& theVector); +Returns the name for a new object copy. It could be useful to return the same object name +if the copy will be in the other model or in the other partition with its own dictionary. +The method *Clone* uses the following public methods for object data replications: - //! The method defines a point mirror type of transformation (point symmetry). - Standard_EXPORT void SetMirror (const gp_Pnt& thePoint); +~~~~~{.cpp} + virtual void CopyReferences (const const Handle(TObj_Object)& theTargetObject, const Handle(TDF_RelocationTable) theRelocTable); +~~~~~ - //! The method defines an axis mirror type of transformation (axial symmetry). - Standard_EXPORT void SetMirror (const gp_Ax1& theAxis); +Adds to the copy of the original object its references. - //! The method defines a point mirror type of transformation (planar symmetry). - Standard_EXPORT void SetMirror (const gp_Ax2& thePlane); +~~~~~{.cpp} + virtual void CopyChildren (TDF_Label& theTargetLabel, const Handle(TDF_RelocationTable) theRelocTable); +~~~~~ - //! The method defines a scale type of transformation. - Standard_EXPORT void SetScale (const gp_Pnt& thePoint, Standard_Real theScale); +Copies the children of an object to the target child label. - //! The method defines a complex type of transformation from one co-ordinate system to another. - Standard_EXPORT void SetTransformation (const gp_Ax3& theCoordinateSystem1, const gp_Ax3& theCoordinateSystem2); +@subsubsection occt_tobj_3_9 Object flags - //!@ name Overridden methods from TDF_Attribute - - //! The method returns a unique GUID of the attribute. - //! By means of this GUID this attribute may be identified among other attributes attached to the same label. - Standard_EXPORT const Standard_GUID& ID () const; +Each instance of *TObj_Object* stores a set of bit flags, +which facilitate the storage of auxiliary logical information assigned to the objects +(object state). Several typical state flags are defined in the enumeration *ObjectState*: - //! The method is called on Undo / Redo. - //! It copies the content of theAttribute into this attribute (copies the fields). - Standard_EXPORT void Restore (const Handle(TDF_Attribute)& theAttribute); + * *ObjectState_Hidden* -- the object is marked as hidden + * *ObjectState_Saved* -- the object has (or should have) the corresponding saved file on disk + * *ObjectState_Imported* -- the object is imported from somewhere + * *ObjectState_ImportedByFile* -- the object has been imported from file and should be updated to have correct relations with other objects + * *ObjectState_Ordered* -- the partition contains objects that can be ordered. - //! It creates a new instance of this attribute. - //! It is called on Copy / Paste, Undo / Redo. - Standard_EXPORT Handle(TDF_Attribute) NewEmpty () const; +The user (developer) can define any new flags in descendant classes. +To set/get an object, the flags use the following methods: - //! The method is called on Copy / Paste. - //! It copies the content of this attribute into theAttribute (copies the fields). - Standard_EXPORT void Paste (const Handle(TDF_Attribute)& theAttribute, const Handle(TDF_RelocationTable)& theRelocationTable); +~~~~~{.cpp} + Standard_Integer GetFlags() const; + void SetFlags( const Standard_Integer theMask ); + Stadnard_Boolean TestFlags( const Standard_Integer theMask ) const; + void ClearFlags( const Standard_Integer theMask = 0 ); +~~~~~ - //! Prints the content of this attribute into the stream. - Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS); +In addition, the generic virtual interface stores the logical properties +of the object class in the form of a set of bit flags. +Type flags can be received by the method: - //!@ name Constructor +~~~~~{.cpp} + virtual Standard_Integer GetTypeFlags() const; +~~~~~ - //! The C++ constructor of this atribute class. - //! Usually it is never called outside this class. - Standard_EXPORT MyPackage_Transformation(); +The default implementation returns the flag **Visible** +defined in the enumeration *TypeFlags*. This flag is used to define visibility +of the object for the user browsing the model (see class *TObj_HiddenPartition*). +Other flags can be added by the applications. -private: - gp_TrsfForm myType; +@subsubsection occt_tobj_310 Partitions - // Axes (Ax1, Ax2, Ax3) - gp_Ax1 myAx1; - gp_Ax2 myAx2; - gp_Ax3 myFirstAx3; - gp_Ax3 mySecondAx3; +The special kind of objects defined by the class *TObj_Partition* +(and its descendant *TObj_HiddenPartition*) is provided for partitioning +the model into a hierarchical structure. This object represents the container +of other objects. Each *TObj* model contains the main partition that is placed +in the same OCAF label as the model object, and serves as a root of the object's tree. +A hidden partition is a simple partition with a predefined hidden flag. - // Scalar values - Standard_Real myAngle; - Standard_Real myScale; +The main partition object methods: - // Points - gp_Pnt myFirstPoint; - gp_Pnt mySecondPoint; -}; -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~{.cpp} + TDF_Label NewLabel() const; +~~~~~ -@subsection occt_ocaf_11_2 Implementation of Attribute Transformation in a CPP file +Allocates and returns a new label for creation of a new child object. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} -#include - -//======================================================================= -//function : GetID -//purpose : The method returns a unique GUID of this attribute. -// By means of this GUID this attribute may be identified -// among other attributes attached to the same label. -//======================================================================= -const Standard_GUID& MyPackage_Transformation::GetID() -{ - static Standard_GUID ID("4443368E-C808-4468-984D-B26906BA8573"); - return ID; -} +~~~~~{.cpp} + void SetNamePrefix ( const Handle(TCollection_HExtendedString)& thePrefix); +~~~~~ -//======================================================================= -//function : Set -//purpose : Finds or creates the attribute attached to . -// The found or created attribute is returned. -//======================================================================= -Handle(MyPackage_Transformation) MyPackage_Transformation::Set(const TDF_Label& theLabel) -{ - Handle(MyPackage_Transformation) T; - if (!theLabel.FindAttribute(MyPackage_Transformation::GetID(), T)) - { - T = new MyPackage_Transformation(); - theLabel.AddAttribute(T); - } - return T; -} +Defines the prefix for automatic generation of names of the newly created objects. -//======================================================================= -//function : Get -//purpose : The method returns the transformation. -//======================================================================= -gp_Trsf MyPackage_Transformation::Get() const -{ - gp_Trsf transformation; - switch (myType) - { - case gp_Identity: - { - break; - } - case gp_Rotation: - { - transformation.SetRotation(myAx1, myAngle); - break; - } - case gp_Translation: - { - transformation.SetTranslation(myFirstPoint, mySecondPoint); - break; - } - case gp_PntMirror: - { - transformation.SetMirror(myFirstPoint); - break; - } - case gp_Ax1Mirror: - { - transformation.SetMirror(myAx1); - break; - } - case gp_Ax2Mirror: - { - transformation.SetMirror(myAx2); - break; - } - case gp_Scale: - { - transformation.SetScale(myFirstPoint, myScale); - break; - } - case gp_CompoundTrsf: - { - transformation.SetTransformation(myFirstAx3, mySecondAx3); - break; - } - case gp_Other: - { - break; - } - } - return transformation; -} +~~~~~{.cpp} + Handle(TCollection_HExtendedString) GetNamePrefix() const; +~~~~~ -//======================================================================= -//function : SetRotation -//purpose : The method defines a rotation type of transformation. -//======================================================================= -void MyPackage_Transformation::SetRotation(const gp_Ax1& theAxis, const Standard_Real theAngle) -{ - Backup(); - myType = gp_Rotation; - myAx1 = theAxis; - myAngle = theAngle; -} +Returns the current name prefix. -//======================================================================= -//function : SetTranslation -//purpose : The method defines a translation type of transformation. -//======================================================================= -void MyPackage_Transformation::SetTranslation(const gp_Vec& theVector) -{ - Backup(); - myType = gp_Translation; - myFirstPoint.SetCoord(0, 0, 0); - mySecondPoint.SetCoord(theVector.X(), theVector.Y(), theVector.Z()); -} +~~~~~{.cpp} + Handle(TCollection_HExtendedString) GetNewName ( const Standard_Boolean theIsToChangeCount) const; +~~~~~ -//======================================================================= -//function : SetMirror -//purpose : The method defines a point mirror type of transformation -// (point symmetry). -//======================================================================= -void MyPackage_Transformation::SetMirror(const gp_Pnt& thePoint) -{ - Backup(); - myType = gp_PntMirror; - myFirstPoint = thePoint; -} +Generates the new name and increases the internal counter of child objects if theIsToChangeCount is **True**. -//======================================================================= -//function : SetMirror -//purpose : The method defines an axis mirror type of transformation -// (axial symmetry). -//======================================================================= -void MyPackage_Transformation::SetMirror(const gp_Ax1& theAxis) -{ - Backup(); - myType = gp_Ax1Mirror; - myAx1 = theAxis; -} +~~~~~{.cpp} + Standard_Integer GetLastIndex() const; +~~~~~ -//======================================================================= -//function : SetMirror -//purpose : The method defines a point mirror type of transformation -// (planar symmetry). -//======================================================================= -void MyPackage_Transformation::SetMirror(const gp_Ax2& thePlane) -{ - Backup(); - myType = gp_Ax2Mirror; - myAx2 = thePlane; -} +Returns the last reserved child index. -//======================================================================= -//function : SetScale -//purpose : The method defines a scale type of transformation. -//======================================================================= -void MyPackage_Transformation::SetScale(const gp_Pnt& thePoint, const Standard_Real theScale) -{ - Backup(); - myType = gp_Scale; - myFirstPoint = thePoint; - myScale = theScale; -} +~~~~~{.cpp} + void SetLastIndex( const Standard_Integer theIndex ); +~~~~~ -//======================================================================= -//function : SetTransformation -//purpose : The method defines a complex type of transformation -// from one co-ordinate system to another. -//======================================================================= -void MyPackage_Transformation::SetTransformation(const gp_Ax3& theCoordinateSystem1, - const gp_Ax3& theCoordinateSystem2) -{ - Backup(); - myFirstAx3 = theCoordinateSystem1; - mySecondAx3 = theCoordinateSystem2; -} +Sets the last reserved index. -//======================================================================= -//function : ID -//purpose : The method returns a unique GUID of the attribute. -// By means of this GUID this attribute may be identified -// among other attributes attached to the same label. -//======================================================================= -const Standard_GUID& MyPackage_Transformation::ID() const -{ - return GetID(); -} +@subsection occt_tobj_4 Auxiliary classes -//======================================================================= -//function : Restore -//purpose : The method is called on Undo / Redo. -// It copies the content of -// into this attribute (copies the fields). -//======================================================================= -void MyPackage_Transformation::Restore(const Handle(TDF_Attribute)& theAttribute) -{ - Handle(MyPackage_Transformation) theTransformation = Handle(MyPackage_Transformation)::DownCast(theAttribute); - myType = theTransformation->myType; - myAx1 = theTransformation->myAx1; - myAx2 = theTransformation->myAx2; - myFirstAx3 = theTransformation->myFirstAx3; - mySecondAx3 = theTransformation->mySecondAx3; - myAngle = theTransformation->myAngle; - myScale = theTransformation->myScale; - myFirstPoint = theTransformation->myFirstPoint; - mySecondPoint = theTransformation->mySecondPoint; -} +Apart from the model and the object, package *TObj* provides a set of auxiliary classes: -//======================================================================= -//function : NewEmpty -//purpose : It creates a new instance of this attribute. -// It is called on Copy / Paste, Undo / Redo. -//======================================================================= -Handle(TDF_Attribute) MyPackage_Transformation::NewEmpty() const -{ - return new MyPackage_Transformation(); -} + * *TObj_Application* -- defines OCAF application supporting existence and operation with *TObj* documents. + * *TObj_Assistant* -- class provides an interface to the static data to be used during save and load operations on models. In particular, in case of cross-model dependencies it allows passing information on the parent model to the OCAF loader to correctly resolve the references when loading a dependent model. + * *TObj_TReference* -- OCAF attribute describes the references between objects in the *TObj* model(s). This attribute stores the label of the referred model object, and provides transparent cross-model references. At runtime, these references are simple Handles; in persistence mode, the cross-model references are automatically detected and processed by the persistence mechanism of *TObj_TReference* attribute. + * Other classes starting with *TObj_T...* -- define OCAF attributes used to store TObj-specific classes and some types of data on OCAF labels. + * Iterators -- a set of classes implementing *TObj_ObjectIterator* interface, used for iterations on *TObj* objects: + * *TObj_ObjectIterator* -- a basic abstract class for other *TObj* iterators. Iterates on *TObj_Object* instances. + * *TObj_LabelIterator* -- iterates on object labels in the *TObj* model document + * *TObj_ModelIterator* -- iterates on all objects in the model. Works with sequences of other iterators. + * *TObj_OcafObjectIterator* -- Iterates on *TObj* data model objects. Can iterate on objects of a specific type. + * *TObj_ReferenceIterator* -- iterates on object references. + * *TObj_SequenceIterator* -- iterates on a sequence of *TObj* objects. + * *TObj_CheckModel* -- a tool that checks the internal consistency of the model. The basic implementation checks only the consistency of references between objects. -//======================================================================= -//function : Paste -//purpose : The method is called on Copy / Paste. -// It copies the content of this attribute into -// (copies the fields). -//======================================================================= -void MyPackage_Transformation::Paste(const Handle(TDF_Attribute)& theAttribute, - const Handle(TDF_RelocationTable)& ) const -{ - Handle(MyPackage_Transformation) theTransformation = Handle(MyPackage_Transformation)::DownCast(theAttribute); - theTransformation->myType = myType; - theTransformation->myAx1 = myAx1; - theTransformation->myAx2 = myAx2; - theTransformation->myFirstAx3 = myFirstAx3; - theTransformation->mySecondAx3 = mySecondAx3; - theTransformation->myAngle = myAngle; - theTransformation->myScale = myScale; - theTransformation->myFirstPoint = myFirstPoint; - theTransformation->mySecondPoint = mySecondPoint; -} +The structure of *TObj* iterators hierarchy is presented below: -//======================================================================= -//function : Dump -//purpose : Prints the content of this attribute into the stream. -//======================================================================= -Standard_OStream& MyPackage_Transformation::Dump(Standard_OStream& anOS) const -{ - anOS = "Transformation: "; - switch (myType) - { - case gp_Identity: - { - anOS = "gp_Identity"; - break; - } - case gp_Rotation: - { - anOS = "gp_Rotation"; - break; - } - case gp_Translation: - { - anOS = "gp_Translation"; - break; - } - case gp_PntMirror: - { - anOS = "gp_PntMirror"; - break; - } - case gp_Ax1Mirror: - { - anOS = "gp_Ax1Mirror"; - break; - } - case gp_Ax2Mirror: - { - anOS = "gp_Ax2Mirror"; - break; - } - case gp_Scale: - { - anOS = "gp_Scale"; - break; - } - case gp_CompoundTrsf: - { - anOS = "gp_CompoundTrsf"; - break; - } - case gp_Other: - { - anOS = "gp_Other"; - break; - } - } - return anOS; -} +@figure{/user_guides/ocaf/images/tobj_image008.png,"Hierarchy of iterators",420} + + +@subsection occt_tobj_5 Packaging + +The *TObj* sources are distributed in the following packages: -//======================================================================= -//function : MyPackage_Transformation -//purpose : A constructor. -//======================================================================= -MyPackage_Transformation::MyPackage_Transformation():myType(gp_Identity){ + * *TObj* -- defines basic classes that implement *TObj* interfaces for OCAF-based modelers. + * *BinLDrivers, XmlLDrivers* -- binary and XML driver of *TObj* package + * *BinLPlugin, XmlLPlugin* -- plug-in for binary and XML persistence + * *BinMObj, XmlMObj* -- binary and XML drivers to store and retrieve specific *TObj* data to or from OCAF document + * *TKBinL, TKXmlL* -- toolkits of binary and XML persistence -} + +@section occt_ocaf_10 GLOSSARY + +* **Application** -- a document container holding all documents containing all application data. +* **Application data** -- the data produced by an application, as opposed to data referring to it. +* **Associativity of data** -- the ability to propagate modifications made to one document to other documents, which refer to such document. Modification propagation is: + * unidirectional, that is, from the referenced to the referencing document(s), or + * bi-directional, from the referencing to the referenced document and vice-versa. +* **Attribute** -- a container for application data. An attribute is attached to a label in the hierarchy of the data framework. +* **Child** -- a label created from another label, which by definition, is the father label. +* **Compound document** -- a set of interdependent documents, linked to each other by means of external references. These references provide the associativity of data. +* **Data framework** -- a tree-like data structure which in OCAF, is a tree of labels with data attached to them in the form of attributes. This tree of labels is accessible through the services of the *TDocStd_Document* class. +* **Document** -- a container for a data framework which grants access to the data, and is, in its turn, contained by an application. A document also allows you to: + * Manage modifications, providing Undo and Redo functions + * Manage command transactions + * Update external links + * Manage save and restore options + * Store the names of software extensions. +* **Driver** -- an abstract class, which defines the communications protocol with a system. +* **Entry** -- an ASCII character string containing the tag list of a label. For example: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} +0:3:24:7:2:7 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@subsection occt_ocaf_11_3 Implementation of typical actions with standard OCAF attributes. - -There are four sample files provided in the directory 'OpenCasCade/ros/samples/ocafsamples'. They present typical actions with OCAF services (mainly for newcomers). -The method *Sample()* of each file is not dedicated for execution 'as is', it is rather a set of logical actions using some OCAF services. - -### TDataStd_Sample.cxx -This sample contains templates for typical actions with the following standard OCAF attributes: -- Starting with data framework; -- TDataStd_Integer attribute management; -- TDataStd_RealArray attribute management; -- TDataStd_Comment attribute management; -- TDataStd_Name attribute management; -- TDataStd_UAttribute attribute management; -- TDF_Reference attribute management; -- TDataXtd_Point attribute management; -- TDataXtd_Plane attribute management; -- TDataXtd_Axis attribute management; -- TDataXtd_Geometry attribute management; -- TDataXtd_Constraint attribute management; -- TDataStd_Directory attribute management; -- TDataStd_TreeNode attribute management. - -### TDocStd_Sample.cxx -This sample contains template for the following typical actions: -- creating application; -- creating the new document (document contains a framework); -- retrieving the document from a label of its framework; -- filling a document with data; -- saving a document in the file; -- closing a document; -- opening the document stored in the file; -- copying content of a document to another document with possibility to update the copy in the future. - -### TPrsStd_Sample.cxx -This sample contains template for the following typical actions: -- starting with data framework; -- setting the TPrsStd_AISViewer in the framework; -- initialization of aViewer; -- finding TPrsStd_AISViewer attribute in the DataFramework; -- getting AIS_InteractiveContext from TPrsStd_AISViewer; -- adding driver to the map of drivers; -- getting driver from the map of drivers; -- setting TNaming_NamedShape to \; -- setting the new TPrsStd_AISPresentation to \; -- displaying; -- erasing; -- updating and displaying presentation of the attribute to be displayed; -- setting a color to the displayed attribute; -- getting transparency of the displayed attribute; -- modify attribute; -- updating presentation of the attribute in viewer. - -### TNaming_Sample.cxx -This sample contains template for typical actions with OCAF Topological Naming services. -The following scenario is used: -- data framework initialization; -- creating Box1 and pushing it as PRIMITIVE in DF; -- creating Box2 and pushing it as PRIMITIVE in DF; -- moving Box2 (applying a transformation); -- pushing the selected edges of the top face of Box1 in DF; -- creating a Fillet (using the selected edges) and pushing the result as a modification of Box1; -- creating a Cut (Box1, Box2) as a modification of Box1 and push it in DF; -- recovering the result from DF. +* **External links** -- references from one data structure to another data structure in another document. +To store these references properly, a label must also contain an external link attribute. +* **Father** -- a label, from which other labels have been created. The other labels are, by definition, the children of this label. +* **Framework** -- a group of co-operating classes which enable a design to be re-used for a given category of problem. The framework guides the architecture of the application by breaking it up into abstract classes, each of which has different responsibilities and collaborates in a predefined way. Application developer creates a specialized framework by: + * defining new classes which inherit from these abstract classes + * composing framework class instances + * implementing the services required by the framework. +In C++, the application behavior is implemented in virtual functions redefined in these derived classes. This is known as overriding. + +* **GUID** -- Global Universal ID. A string of 37 characters intended to uniquely identify an object. For example: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} +2a96b602-ec8b-11d0-bee7-080009dc3333 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* **Label** -- a point in the data framework, which allows data to be attached to it by means of attributes. It has a name in the form of an entry, which identifies its place in the data framework. +* **Modified label** -- containing attributes whose data has been modified. +* **Reference key** -- an invariant reference, which may refer to any type of data used in an application. In its transient form, it is a label in the data framework, and the data is attached to it in the form of attributes. In its persistent form, it is an entry of the label. It allows an application to recover any entity in the current session or in a previous session. +* **Resource file** -- a file containing a list of each document’s schema name and the storage and retrieval plug-ins for that document. +* **Root** -- the starting point of the data framework. This point is the top label in the framework. It is represented by the [0] entry and is created at the same time with the document you are working on. +* **Scope** -- the set of all the attributes and labels which depend on a given label. +* **Tag list** -- a list of integers, which identify the place of a label in the data framework. This list is displayed in an entry. +* **Topological naming** -- systematic referencing of topological entities so that these entities can still be identified after the models they belong to have gone through several steps in modeling. In other words, topological naming allows you to track entities through the steps in the modeling process. This referencing is needed when a model is edited and regenerated, and can be seen as a mapping of labels and name attributes of the entities in the old version of a model to those of the corresponding entities in its new version. Note that if the topology of a model changes during the modeling, this mapping may not fully coincide. A Boolean operation, for example, may split edges. +* **Topological tracking** -- following a topological entity in a model through the steps taken to edit and regenerate that model. +* **Valid label** -- in a data framework, this is a label, which is already recomputed in the scope of regeneration sequence and includes the label containing a feature which is to be recalculated. Consider the case of a box to which you first add a fillet, then a protrusion feature. For recalculation purposes, only valid labels of each construction stage are used. In recalculating a fillet, they are only those of the box and the fillet, not the protrusion feature which was added afterwards. diff --git a/dox/user_guides/step/step.md b/dox/user_guides/step/step.md index e65953f7a1..8328a914fb 100644 --- a/dox/user_guides/step/step.md +++ b/dox/user_guides/step/step.md @@ -1,4 +1,4 @@ -STEP processor {#occt_user_guides__step} +STEP Translator {#occt_user_guides__step} ======================== @tableofcontents @@ -22,9 +22,7 @@ File translation is performed in the programming mode, via C++ calls. @ref occt_user_guides__shape_healing "Shape Healing" toolkit provides tools to heal various problems, which may be encountered in translated shapes, and to make them valid in Open CASCADE. The Shape Healing is smoothly connected to STEP translator using the same API, only the names of API packages change. -For testing the STEP component in DRAW Test Harness, a set of commands for reading and writing STEP files and analysis of relevant data are provided by the *TKXSDRAW* plugin. - -See also our E-learning & Training offerings. +For testing the STEP component in DRAW Test Harness, a set of commands for reading and writing STEP files and analysis of relevant data are provided by the *TKXSDRAW* plugin. @subsection occt_step_1_1 STEP Exchanges in Open Cascade technology diff --git a/dox/user_guides/tobj/images/tobj_image003.png b/dox/user_guides/tobj/images/tobj_image003.png deleted file mode 100644 index ffb6b1168b..0000000000 Binary files a/dox/user_guides/tobj/images/tobj_image003.png and /dev/null differ diff --git a/dox/user_guides/tobj/images/tobj_image004.png b/dox/user_guides/tobj/images/tobj_image004.png deleted file mode 100644 index 264cca7d66..0000000000 Binary files a/dox/user_guides/tobj/images/tobj_image004.png and /dev/null differ diff --git a/dox/user_guides/tobj/images/tobj_image005.png b/dox/user_guides/tobj/images/tobj_image005.png deleted file mode 100644 index cf79264f42..0000000000 Binary files a/dox/user_guides/tobj/images/tobj_image005.png and /dev/null differ diff --git a/dox/user_guides/tobj/images/tobj_image006.png b/dox/user_guides/tobj/images/tobj_image006.png deleted file mode 100644 index 6b1343b1b7..0000000000 Binary files a/dox/user_guides/tobj/images/tobj_image006.png and /dev/null differ diff --git a/dox/user_guides/tobj/images/tobj_image007.png b/dox/user_guides/tobj/images/tobj_image007.png deleted file mode 100644 index 3919188a0f..0000000000 Binary files a/dox/user_guides/tobj/images/tobj_image007.png and /dev/null differ diff --git a/dox/user_guides/tobj/images/tobj_image008.png b/dox/user_guides/tobj/images/tobj_image008.png deleted file mode 100644 index 970d9b15db..0000000000 Binary files a/dox/user_guides/tobj/images/tobj_image008.png and /dev/null differ diff --git a/dox/user_guides/tobj/tobj.md b/dox/user_guides/tobj/tobj.md deleted file mode 100644 index 155091b738..0000000000 --- a/dox/user_guides/tobj/tobj.md +++ /dev/null @@ -1,910 +0,0 @@ -TObj Package {#occt_user_guides__tobj} -================== - -@tableofcontents - -@section occt_tobj_1 Introduction - -This document describes the package TObj, which is an add-on -to the Open CASCADE Application Framework (OCAF). - -This package provides a set of classes and auxiliary tools facilitating -the creation of object-oriented data models on top of low-level OCAF data structures. -This includes: - - * Definition of classes representing data objects. Data objects store their data using primitive OCAF attributes, taking advantage of OCAF mechanisms for Undo/Redo and persistence. At the same time they provide a higher level abstraction over the pure OCAF document structure (labels / attributes). - * Organization of the data model as a hierarchical (tree-like) structure of objects. - * Support of cross-references between objects within one model or among different models. In case of cross-model references the models should depend hierarchically. - * Persistence mechanism for storing *TObj* objects in OCAF files, which allows storing and retrieving objects of derived types without writing additional code to support persistence. - -This document describes basic principles of logical and physical organization -of TObj-based data models and typical approaches to implementation of classes representing model objects. - -@subsection occt_tobj_1_1 Applicability - -The main purpose of the *TObj* data model is rapid development -of the object-oriented data models for applications, using the existing -functionality provided by OCAF (Undo/Redo and persistence) -without the necessity to redevelop such functionality from scratch. - -As opposed to using bare OCAF (at the level of labels and attributes), -TObj facilitates dealing with higher level abstracts, which are closer -to the application domain. It works best when the application data are naturally -organized in hierarchical structures, and is especially useful for complex data -models with dependencies between objects belonging to different parts of the model. - -It should be noted that *TObj* is efficient for representing data structures containing -a limited number of objects at each level of the data structure (typically less than 1000). -A greater number of objects causes performance problems due to list-based organization of OCAF documents. Therefore, other methods of storage, such as arrays, are advisable for data models or their sub-parts containing a great number of uniform objects. However, these methods -can be combined with the usage of *TObj* to represent the high-level structure of the model. - -@section occt_tobj_2 TObj Model - -@subsection occt_tobj_2_1 TObj Model structure - -In the *TObj* data model the data are separated from the interfaces that manage them. - -It should be emphasized that *TObj* package defines only the interfaces and the basic structure of the model and objects, while the actual contents and structure of the model of a particular application are defined by its specific classes inherited from *TObj* classes. The implementation can add its own features or even change the default behaviour and the data layout, though this is not recommended. - -Logically the *TObj* data model is represented as a tree of model objects, with upper-level objects typically being collections of other objects (called *partitions*, represented by the class *TObj_Partition*). The root object of the model is called the *Main partition* and is maintained by the model itself. This partition contains a list of sub-objects called its *children* each sub-object may contain its own children (according to its type), etc. - -@figure{/user_guides/tobj/images/tobj_image003.png,"TObj Data Model",240} - -As the *TObj* Data Model is based on OCAF (Open CASCADE Application Framework) technology, -it stores its data in the underlying OCAF document. The OCAF document consists of a tree of -items called *labels*. Each label has some data attached to it in the form of *attributes*, -and may contain an arbitrary number of sub-labels. Each sub-label is identified by its sequential -number called the *tag*. The complete sequence of tag numbers of the label -and its parents starting from the document root constitutes the complete *entry* -of the label, which uniquely identifies its position in the document. - -Generally the structure of the OCAF tree of the *TObj* data -model corresponds to the logical structure of the model and can be presented as in the following picture: - -@figure{/user_guides/tobj/images/tobj_image004.png,"TObj Data Model mapped on OCAF document",360} - -All data of the model are stored in the root label (0:1) of the OCAF document. -An attribute *TObj_TModel* is located in this root label. It -stores the object of type *TObj_Model*. This object serves as a main interface tool -to access all data and functionalities of the data model. - -In simple cases all data needed by the application may be -contained in a single data model. Moreover, *TObj* gives the possibility to -distribute the data between several interconnected data models. This can be -especially useful for the applications dealing with great amounts of data. because -only the data required for the current operation is loaded in the memory at one time. -It is presumed that the models have a hierarchical (tree-like) structure, -where the objects of the child models can refer to the objects of the parent -models, not vice-versa. Provided that the correct order of loading and closing -of the models is ensured, the *TObj* classes will maintain references between the objects automatically. - -@subsection occt_tobj_2_2 Data Model basic features - -The class *TObj_Model* describing the data model provides the following functionalities: - - * Loading and saving of the model from or in a file (methods *Load* and *Save*) - * Closing and removal of the model from memory (method *Close*) - * Definition of the full file name of the persistence storage for this model (method *GetFile*) - * Tools to organize data objects in partitions and iterate on objects (methods *GetObjects*, *GetMainPartition*, *GetChildren*, *getPartition*, *getElementPartition*) - * Mechanism to give unique names to model objects - * Copy (*clone*) of the model (methods *NewEmpty* and *Paste*) - * Support of earlier model formats for proper conversion of a model loaded from a file written by a previous version of the application (methods *GetFormatVersion* and *SetFormatVersion*) - * Interface to check and update the model if necessary (method *Update*) - * Support of several data models in one application. For this feature use OCAF multi-transaction manager, unique names and GUIDs of the data model (methods *GetModelName*, *GetGUID*) - -@subsection occt_tobj_2_3 Model Persistence - -The persistent representation of any OCAF model is contained in an XML or a binary file, -which is defined by the format string returned by the method *GetFormat*. -The default implementation works with a binary OCAF document format (*BinOcaf*). -The other available format is *XmlOcaf*. The class **TObj_Model** declares and provides a default -implementation of two virtual methods: - -~~~~~{.cpp} - virtual Standard_Boolean Load (const char* theFile); - virtual Standard_Boolean SaveAs (const char* theFile); -~~~~~ - -which retrieve and store the model from or -in the OCAF file. The descendants -should define the following protected method to support Load and Save operations: - -~~~~~{.cpp} - virtual Standard_Boolean initNewModel (const Standard_Boolean IsNew); -~~~~~ - -This method is called by *Load* after creation of a new model -or after its loading from the file; its purpose is to perform -the necessary initialization of the model (such as creation of necessary top-level -partitions, model update due to version changes etc.). Note that if -the specified file does not exist, method *Load* will create -a new document and call *initNewModel* with the argument **True**. -If the file has been normally loaded, the argument **False** is passed. -Thus, a new empty *TObj* model is created by calling *Load* with an empty -string or the path to a nonexistent file as argument. - -The method *Load* returns **True** if the model has been retrieved successfully -(or created a new), or **False** if the model could not be loaded. -If no errors have been detected during initialization (model retrieval or creation), -the virtual method *AfterRetrieval* is invoked for all objects of the model. -This method initializes or updates the objects immediately after the model initialization. -It could be useful when some object data should be imported from an OCAF attribute into transient -fields which could be changed outside of the OCAF transaction mechanism. -Such fields can be stored into OCAF attributes for saving into persistent storage during the save operation. - -To avoid memory leaks, the *TObj_Model* class destructor invokes *Close* method -which clears the OCAF document and removes all data from memory before the model is destroyed. - -For XML and binary persistence of the *TObj* data model the corresponding drivers are implemented -in *BinLDrivers*, *BinMObj* and *XmlLDrivers*, *XmlMObj* packages. -These packages contain retrieval and storage drivers for the model, model objects and custom attributes -from the *TObj* package. The schemas support persistence for the standard OCAF and *TObj* attributes. -This is sufficient for the implementation of simple data models, but -in some cases it can be reasonable to add specific OCAF attributes to -facilitate the storage of the data specific to the application. -In this case the schema should be extended using the standard OCAF mechanism. - -@subsection occt_tobj_2_4 Access to the objects in the model - -All objects in the model are stored in the main partition and accessed by iterators. -To access all model objects use: - -~~~~~{.cpp} - virtual Handle(TObj_ObjectIterator) GetObjects () const; -~~~~~ - -This method returns a recursive iterator on all objects stored in the model. - -~~~~~{.cpp} - virtual Handle(TObj_ObjectIterator) GetChildren () const; -~~~~~ - -This method returns an iterator on child objects of the main partition. -Use the following method to get the main partition: - -~~~~~{.cpp} - Handle(TObj_Partition) GetMainPartition() const; -~~~~~ - -To receive the iterator on objects of a specific type *AType* use the following call: - -~~~~~{.cpp} - GetMainPartition()->GetChildren(STANDARD_TYPE(AType) ); -~~~~~ - -The set of protected methods is provided for descendant classes to deal with partitions: - -~~~~~{.cpp} - virtual Handle(TObj_Partition) getPartition (const TDF_Label, const Standard_Boolean theHidden) const; -~~~~~ - -This method returns (creating if necessary) a partition in the specified label of the document. -The partition can be created as hidden (*TObj_HiddenPartition* class). -A hidden partition can be useful to distinguish the data that -should not be visible to the user when browsing the model in the application. - -The following two methods allow getting (creating) a partition -in the sub-label of the specified label in the document -(the label of the main partition for the second method) and with the given name: - -~~~~~{.cpp} - virtual Handle(TObj_Partition) getPartition (const TDF_Label, const Standard_Integer theIndex, const TCollection_ExtendedString& theName, const Standard_Boolean theHidden) const; - virtual Handle(TObj_Partition) getPartition (const Standard_Integer theIndex, const TCollection_ExtendedString& theName, const Standard_Boolean theHidden) const; -~~~~~ - -If the default object naming and the name register mechanism -is turned on, the object can be found in the model by its unique name: - -~~~~~{.cpp} - Handle(TObj_Object) FindObject (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary) const; -~~~~~ - -@subsection occt_tobj_2_5 Own model data - -The model object can store its own data in the Data label -of its main partition, however, there is no standard API for -setting and getting these data types. The descendants can add -their own data using standard OCAF methods. The enumeration DataTag is defined -in *TObj_Model* to avoid conflict of data labels used by this class -and its descendants, similarly to objects (see below). - -@subsection occt_tobj_2_6 Object naming - -The basic implementation of *TObj_Model* provides the default -naming mechanism: all objects must have unique names, -which are registered automatically in the data model dictionary. -The dictionary is a *TObj_TNameContainer* -attribute whose instance is located in the model root label. -If necessary, the developer can add several dictionaries into -the specific partitions, providing the name registration in the -correct name dictionary and restoring the name map after document is loaded from file. -To ignore name registering it is necessary to redefine the methods *SetName*, -*AfterRetrieval* of the *TObj_Object* class and skip the registration of the object name. -Use the following methods for the naming mechanism: - -~~~~~{.cpp} - Standard_Boolean IsRegisteredName (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary ) const; -~~~~~ - -Returns **True** if the object name is already registered in the indicated (or model) dictionary. - -~~~~~{.cpp} - void RegisterName (const Handle(TCollection_HExtendedString)& theName, const TDF_Label& theLabel, const Handle(TObj_TNameContainer)& theDictionary ) const; -~~~~~ - -Registers the object name with the indicated label where the object -is located in the OCAF document. Note that the default implementation -of the method *SetName* of the object registers the new name automatically -(if the name is not yet registered for any other object) - -~~~~~{.cpp} - void UnRegisterName (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary ) const; -~~~~~ - -Unregisters the name from the dictionary. Ther names of *TObj* model -objects are removed from the dictionary when the objects are deleted from the model. - -~~~~~{.cpp} - Handle(TObj_TNameContainer) GetDictionary() const; -~~~~~ - -Returns a default instance of the model dictionary (located at the model root label). -The default implementation works only with one dictionary. -If there are a necessity to have more than one dictionary for the model objects, -it is recommended to redefine the corresponding virtual method of TObj_Object -that returns the dictionary where names of objects should be registered. - -@subsection occt_tobj_2_7 API for transaction mechanism - -Class *TObj_Model* provides the API for transaction mechanism (supported by OCAF): - -~~~~~{.cpp} - Standard_Boolean HasOpenCommand() const; -~~~~~ - -Returns True if a Command transaction is open - -~~~~~{.cpp} - void OpenCommand() const; -~~~~~ - -Opens a new command transaction. - -~~~~~{.cpp} - void CommitCommand() const; -~~~~~ - -Commits the Command transaction. Does nothing If there is no open Command transaction. - -~~~~~{.cpp} - void AbortCommand() const; -~~~~~ - -Aborts the Command transaction. Does nothing if there is no open Command transaction. - -~~~~~{.cpp} - Standard_Boolean IsModified() const; -~~~~~ - -Returns True if the model document has a modified status (has changes after the last save) - -~~~~~{.cpp} - void SetModified( const Standard_Boolean ); -~~~~~ - -Changes the modified status by force. For synchronization of transactions -within several *TObj_Model* documents use class *TDocStd_MultiTransactionManager*. - -@subsection occt_tobj_28 Model format and version - -Class *TObj_Model* provides the descendant classes with a means to control -the format of the persistent file by choosing the schema used to store or retrieve operations. - -~~~~~{.cpp} - virtual TCollection_ExtendedString GetFormat () const; -~~~~~ - -Returns the string *TObjBin* or *TObjXml* indicating -the current persistent mechanism. The default value is *TObjBin*. -Due to the evolution of functionality of the developed application, -the contents and the structure of its data model vary from version to version. -*TObj* package provides a basic mechanism supporting backward versions compatibility, -which means that newer versions of the application will be able to read -Data Model files created by previous versions (but not vice-versa) with a minimum loss of data. -For each type of Data Model, all known versions of the data format -should be enumerated in increasing order, incremented with every change -of the model format. The current version of the model -format is stored in the model file and can be checked upon retrieval. - -~~~~~{.cpp} - Standard_Integer GetFormatVersion() const; -~~~~~ - -Returns the format version stored in the model file - -~~~~~{.cpp} - void SetFormatVersion(const Standard_Integer theVersion); -~~~~~ - -Defines the format version used for save. - -Upon loading a model, the method *initNewModel()*, called immediately -after opening a model from disk (on the level of the OCAF document), -provides a specific code that checks the format version stored in that model. -If it is older than the current version of the application, the data update can be performed. -Each model can have its own specific conversion code -that performs the necessary data conversion to make them compliant with the current version. - -When the conversion ends the user is advised of that by the messenger interface -provided by the model (see messaging chapter for more details), -and the model version is updated. If the version of data model is not supported -(it is newer than the current or too old), the load operation should fail. -The program updating the model after version change can be implemented as static -methods directly in C++ files of the corresponding Data Model classes, -not exposing it to the other parts of the application. -These codes can use direct access to the model and objects data (attributes) -not using objects interfaces, because the data model API and object classes -could have already been changed. - -Note that this mechanism has been designed to maintain version compatibility -for the changes of data stored in the model, not for the changes of -low-level format of data files (such as the storage format of a specific OCAF attribute). -If the format of data files changes, a specific treatment on a case-by-case basis will be required. - -@subsection occt_tobj_2_9 Model update - -The following methods are used for model update to ensure its consistency -with respect to the other models in case of cross-model dependencies: - -~~~~~{.cpp} - virtual Standard_Boolean Update(); -~~~~~ - -This method is usually called after loading of the model. -The default implementation does nothing and returns **True**. - -~~~~~{.cpp} - virtual Standard_Boolean initNewModel( const Standard_Boolean IsNew); -~~~~~ - -This method performs model initialization, check and updates (as described above). - -~~~~~{.cpp} - virtual void updateBackReferences( const Handle(TObj_Object)& theObj); -~~~~~ - -This method is called from the previous method to update back references -of the indicated object after the retrieval of the model from file -(see data model - object relationship chapter for more details) - -@subsection occt_tobj_2_10 Model copying - -To copy the model between OCAF documents use the following methods: - -~~~~~{.cpp} - virtual Standard_Boolean Paste (Handle(TObj_Model) theModel, Handle(TDF_RelocationTable) theRelocTable = 0 ); -~~~~~ - -Pastes the current model to the new model. The relocation table -ensures correct copying of the sub-data shared by several parts of the model. -It stores a map of processed original objects of relevant types in their copies. - -~~~~~{.cpp} - virtual Handle(TObj_Model) NewEmpty() = 0; -~~~~~ - -Redefines a pure virtual method to create a new empty instance of the model. - -~~~~~{.cpp} - void CopyReferences ( const Handle(TObj_Model)& theTarget, const Handle(TDF_RelocationTable)& theRelocTable); -~~~~~ - -Copies the references from the current model to the target model. - -@subsection occt_tobj_2_11 Messaging - -The messaging is organised using Open CASCADE Messenger from the package Message. -The messenger is stored as the field of the model instance -and can be set and retrieved by the following methods: - -~~~~~{.cpp} - void SetMessenger( const Handle(Message_Messenger)& ); - Handle(Message_Messenger) Messenger() const; -~~~~~ - -A developer should create his own instance of the Messenger -bound to the application user interface, and attribute it to the model -for future usage. In particular the messenger is used for reporting -errors and warnings in the persistence mechanism. -Each message has a unique string identifier (key). -All message keys are stored in a special resource file TObj.msg. -This file should be loaded at the start of the application -by call to the appropriate method of the class *Message_MsgFile*. - -@section occt_tobj_3 Model object - -Class *TObj_Object* provides basic interface and default implementation -of important features of *TObj* model objects. This implementation defines -basic approaches that are recommended for all descendants, -and provides tools to facilitate their usage. - -@figure{/user_guides/tobj/images/tobj_image005.png,"TObj objects hierarchy",170} - -@subsection occt_tobj_3_1 Separation of data and interface - -In the *TObj* data model, the data are separated from the interfaces that manage them. -The data belonging to a model object are stored in its root label and sub-labels -in the form of standard OCAF attributes. This allows using standard OCAF mechanisms -for work with these data, and eases the implementation of the persistence mechanism. - -The instance of the interface which serves as an API for managing object data -(e.g. represents the model object) is stored in the root label of the object, -and typically does not bring its own data. The interface classes are organized in a hierarchy -corresponding to the natural hierarchy of the model objects according to the application. - -In the text below the term 'object' is used to denote either the instance -of the interface class or the object itself (both interface and data stored in OCAF). - -The special type of attribute *TObj_TObject* is used for storing instances of objects interfaces -in the OCAF tree. *TObj_TObject* is a simple container for the object of type *TObj_Object*. -All objects (interfaces) of the data model inherit this class. - -@figure{/user_guides/tobj/images/tobj_image006.png,"TObj object stored on OCAF label",360} - - -@subsection occt_tobj_3_2 Basic features - -The *TObj_Object* class provides some basic features that can be inherited (or, if necessary, redefined) by the descendants: - - * Gives access to the model to which the object belongs (method *GetModel*) and to the OCAF label in which the object is stored (method *GetLabel*). - * Supports references (and back references) to other objects in the same or in another model (methods *getReference*, *setReference*, *addReference*, *GetReferences*, *GetBackReferences*, *AddBackReference*, *RemoveBackReference*, *ReplaceReference*) - * Provides the ability to contain child objects, as it is actual for partition objects (methods *GetChildren*, *GetFatherObject*) - * Organizes its data in the OCAF structure by separating the sub-labels of the main label intended for various kinds of data and providing tools to organize these data (see below). The kinds of data stored separately are: - * Child objects stored in the label returned by the method *GetChildLabel* - * References to other objects stored in the label returned by the method *GetReferenceLabel* - * Other data, both common to all objects and specific for each subtype of the model object, are stored in the label returned by the method *GetDataLabel* - * Provides unique names of all objects in the model (methods *GetDictionary*, *GetName*, *SetName*) - * Provides unified means to maintain persistence (implemented in descendants with the help of macros *DECLARE_TOBJOCAF_PERSISTENCE* and *IMPLEMENT_TOBJOCAF_PERSISTENCE*) - * Allows an object to remove itself from the OCAF document and check the depending objects can be deleted according to the back references (method *Detach*) - * Implements methods for identification and versioning of objects - * Manages the object interaction with OCAF Undo/Redo mechanism (method *IsAlive*, *AfterRetrieval*, *BeforeStoring*) - * Allows make a clone (methods *Clone*, *CopyReferences*, *CopyChildren*, *copyData*) - * Contains additional word of bit flags (methods *GetFlags*, *SetFlags*, *TestFlags*, *ClearFlags*) - * Defines the interface to sort the objects by rank (methods *GetOrder*, *SetOrder*) - * Provides a number of auxiliary methods for descendants to set/get the standard attribute values, such as int, double, string, arrays etc. - -An object can be received from the model by the following methods: - -~~~~~{.cpp} - static Standard_Boolean GetObj ( const TDF_Label& theLabel, Handle(TObj_Object)& theResObject, const Standard_Boolean isSuper = Standard_False ); -~~~~~ - -Returns *True* if the object has been found in the indicated label (or in the upper level label if *isSuper* is *True*). - -~~~~~{.cpp} - Handle(TObj_Object) GetFatherObject ( const Handle(Standard_Type)& theType = NULL ) const; -~~~~~ - -Returns the father object of the indicated type -for the current object (the direct father object if the type is NULL). - -@subsection occt_tobj_3_3 Data layout and inheritance - -As far as the data objects are separated from the interfaces and stored in the OCAF tree, -the functionality to support inheritance is required. Each object has its own data -and references stored in the labels in the OCAF tree. All data are stored in the sub-tree -of the main object label. If it is necessary to inherit a class from the base class, -the descendant class should use different labels for data and references than its ancestor. - -Therefore each *TObj* class can reserve the range of tags in each of -*Data*, *References*, and *Child* sub-labels. -The reserved range is declared by the enumeration defined -in the class scope (called DataTag, RefTag, and ChildTag, respectively). -The item *First* of the enumeration of each type is defined via the *Last* item -of the corresponding enumeration of the parent class, thus ensuring that the tag numbers -do not overlap. The item *Last* of the enumeration defines the last tag reserved by this class. -Other items of the enumeration define the tags used for storing particular data items of the object. -See the declaration of the TObj_Partition class for the example. - -*TObj_Object* class provides a set of auxiliary methods for descendants -to access the data stored in sub-labels by their tag numbers: - -~~~~~{.cpp} - TDF_Label getDataLabel (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const; - TDF_Label getReferenceLabel (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const; -~~~~~ - -Returns the label in *Data* or *References* sub-labels at a given tag number (theRank1). -The second argument, theRank2, allows accessing the next level of hierarchy -(theRank2-th sub-label of theRank1-th data label). -This is useful when the data to be stored are represented by multiple OCAF attributes -of the same type (e.g. sequences of homogeneous data or references). - -The get/set methods allow easily accessing the data located in the specified data label -for the most widely used data types (*Standard_Real*, *Standard_Integer*, *TCollection_HExtendedString*, - *TColStd_HArray1OfReal*, *TColStd_HArray1OfInteger*, *TColStd_HArray1OfExtendedString*). -For instance, methods provided for real numbers are: - -~~~~~{.cpp} - Standard_Real getReal (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const; - Standard_Boolean setReal (const Standard_Real theValue, const Standard_Integer theRank1, const Standard_Integer theRank2 = 0, const Standard_Real theTolerance = 0.) const; -~~~~~ - -Similar methods are provided to access references to other objects: - -~~~~~{.cpp} - Handle(TObj_Object) getReference (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const; - Standard_Boolean setReference (const Handle(TObj_Object) &theObject, const Standard_Integer theRank1, const Standard_Integer theRank2 = 0); -~~~~~ - -The method *addReference* gives an easy way to store a sequence of homogeneous references in one label. - -~~~~~{.cpp} - TDF_Label addReference (const Standard_Integer theRank1, const Handle(TObj_Object) &theObject); -~~~~~ - -Note that while references to other objects should be defined by descendant classes -individually according to the type of object, *TObj_Object* provides methods -to manipulate (check, remove, iterate) the existing references in the uniform way, as described below. - -@subsection occt_tobj_3_4 Persistence - -The persistence of the *TObj* Data Model is implemented with the help -of standard OCAF mechanisms (a schema defining necessary plugins, drivers, etc.). -This implies the possibility to store/retrieve all data that are stored -as standard OCAF attributes., The corresponding handlers are added -to the drivers for *TObj*-specific attributes. - -The special tool is provided for classes inheriting from *TObj_Object* -to add the new types of persistence without regeneration of the OCAF schema. -The class *TObj_Persistence* provides basic means for that: - - * automatic run-time registration of object types - * creation of a new object of the specified type (one of the registered types) - -Two macros defined in the file TObj_Persistence.hxx have to be included in the definition -of each model object class inheriting TObj_Object to activate the persistence mechanism: - -~~~~~{.cpp} - DECLARE_TOBJOCAF_PERSISTENCE (classname, ancestorname) -~~~~~ - -Should be included in the private section of declaration of each class inheriting -*TObj_Object* (hxx file). This macro adds an additional constructor to the object class, -and declares an auxiliary (private) class inheriting *TObj_Persistence* -that provides a tool to create a new object of the proper type. - -~~~~~{.cpp} - IMPLEMENT_TOBJOCAF_PERSISTENCE (classname) -~~~~~ - -Should be included in .cxx file of each object class that should be saved and restored. -This is not needed for abstract types of objects. This macro implements the functions -declared by the previous macro and creates a static member -that automatically registers that type for persistence. - -When the attribute *TObj_TObject* that contains the interface object is saved, -its persistence handler stores the runtime type of the object class. -When the type is restored the handler dynamically recognizes the type -and creates the corresponding object using mechanisms provided by *TObj_Persistence*. - -@subsection occt_tobj_3_5 Names of objects - -All *TObj* model objects have names by which the user can refer to the object. -Upon creation, each object receives a default name, constructed -from the prefix corresponding to the object type (more precisely, the prefix is defined -by the partition to which the object belongs), and the index of the object in the current partition. -The user has the possibility to change this name. The uniqueness of the name in the model is ensured -by the naming mechanism (if the name is already used, it cannot be attributed to another object). -This default implementation of *TObj* package works with a single instance of the name container (dictionary) -for name registration of objects and it is enough in most simple projects. -If necessary, it is easy to redefine a couple of object methods -(for instance *GetDictionary*()) and to take care of construction and initialization of containers. - -This functionality is provided by the following methods: - -~~~~~{.cpp} - virtual Handle(TObj_TNameContainer) GetDictionary() const; -~~~~~ - -Returns the name container where the name of object should be registered. -The default implementation returns the model name container. - -~~~~~{.cpp} - Handle(TCollection_HExtendedString) GetName() const; - Standard_Boolean GetName( TCollection_ExtendedString& theName ) const; - Standard_Boolean GetName( TCollection_AsciiString& theName ) const; -~~~~~ - -Returns the object name. The methods with in / out argument return False if the object name is not defined. - -~~~~~{.cpp} - virtual Standard_Boolean SetName ( const Handle(TCollection_HExtendedString)& theName ) const; - Standard_Boolean SetName ( const Handle(TCollection_HAsciiString)& theName ) const; - Standard_Boolean SetName ( const Standard_CString theName ) const; -~~~~~ - -Attributes a new name to the object and returns **True** if the name has been attributed successfully. -Returns False if the name has been already attributed to another object. -The last two methods are short-cuts to the first one. - -@subsection occt_tobj_3_6 References between objects - -Class *TObj_Object* allows creating references to other objects in the model. -Such references describe relations among objects which are not adequately reflected -by the hierarchical objects structure in the model (parent-child relationship). - -The references are stored internally using the attribute TObj_TReference. -This attribute is located in the sub-label of the referring object (called *master*) -and keeps reference to the main label of the referred object. -At the same time the referred object can maintain the back reference to the master object. - -@figure{/user_guides/tobj/images/tobj_image007.png,"Objects relationship",360} - - - -The back references are stored not in the OCAF document but as a transient field -of the object; they are created when the model is restored from file, -and updated automatically when the references are manipulated. -The class *TObj_TReference* allows storing references between objects -from different *TObj* models, facilitating the construction of complex relations between objects. - -The most used methods for work with references are: - -~~~~~{.cpp} - virtual Standard_Boolean HasReference( const Handle(TObj_Object)& theObject) const; -~~~~~ - -Returns True if the current object refers to the indicated object. - -~~~~~{.cpp} - virtual Handle(TObj_ObjectIterator) GetReferences ( const Handle(Standard_Type)& theType = NULL ) const; -~~~~~ - -Returns an iterator on the object references. The optional argument *theType* -restricts the types of referred objects, or does not if it is NULL. - -~~~~~{.cpp} - virtual void RemoveAllReferences(); -~~~~~ - -Removes all references from the current object. - -~~~~~{.cpp} - virtual void RemoveReference( const Handle(TObj_Object)& theObject ); -~~~~~ - -Removes the reference to the indicated object. - -~~~~~{.cpp} - virtual Handle(TObj_ObjectIterator) GetBackReferences ( const Handle(Standard_Type)& theType = NULL ) const; -~~~~~ - -Returns an iterator on the object back references. -The argument theType restricts the types of master objects, or does not if it is NULL. - -~~~~~{.cpp} - virtual void ReplaceReference ( const Handle(TObj_Object)& theOldObject, const Handle(TObj_Object)& theNewObject ); -~~~~~ - -Replaces the reference to theOldObject by the reference to *theNewObject*. -The handle theNewObject may be NULL to remove the reference. - -~~~~~{.cpp} - virtual Standard_Boolean RelocateReferences ( const TDF_Label& theFromRoot, const TDF_Label& theToRoot, const Standard_Boolean theUpdateackRefs = Standard_True ); -~~~~~ - -Replaces all references to a descendant label of *theFromRoot* -by the references to an equivalent label under *theToRoot*. -Returns **False** if the resulting reference does not point at a *TObj_Object*. -Updates back references if theUpdateackRefs is **True**. - -~~~~~{.cpp} - virtual Standard_Boolean CanRemoveReference ( const Handle(TObj_Object)& theObj) const; -~~~~~ - -Returns **True** if the reference can be removed and the master object -will remain valid (*weak* reference). -Returns **False** if the master object cannot be valid without the referred object (*strong* reference). -This affects the behaviour of objects removal from the model -- if the reference cannot be removed, -either the referred object will not be removed, or both the referred -and the master objects will be removed (depends on the deletion mode in the method **Detach**) - -@subsection occt_tobj_3_7 Creation and deletion of objects - -It is recommended that all objects inheriting from *TObj_Object* - should implement the same approach to creation and deletion. - -The object of the *TObj* data model cannot be created independently -of the model instance, as far as it stores the object data in OCAF data structures. -Therefore an object class cannot be created directly as its constructor is protected. - -Instead, each object should provide a static method *Create*(), which accepts the model, -with the label, which stores the object and other type-dependent parameters -necessary for proper definition of the object. This method creates a new object with its data -(a set of OCAF attributes) in the specified label, and returns a handle to the object's interface. - -The method *Detach*() is provided for deletion of objects from OCAF model. -Object data are deleted from the corresponding OCAF label; however, -the handle on object remains valid. The only operation available after object deletion -is the method *IsAlive*() checking whether the object has been deleted or not, -which returns False if the object has been deleted. - -When the object is deleted from the data model, the method checks -whether there are any alive references to the object. -Iterating on references the object asks each referring (master) object -whether the reference can be removed. If the master object can be unlinked, -the reference is removed, otherwise the master object will be removed too -or the referred object will be kept alive. This check is performed by the method *Detach* , -but the behavior depends on the deletion mode *TObj_DeletingMode*: - - * **TObj_FreeOnly** -- the object will be destroyed only if it is free, i.e. there are no references to it from other objects - * **TObj_KeepDepending** -- the object will be destroyed if there are no strong references to it from master objects (all references can be unlinked) - * **TObj_Force** -- the object and all depending master objects that have strong references to it will be destroyed. - -The most used methods for object removing are: - -~~~~~{.cpp} - virtual Standard_Boolean CanDetachObject (const TObj_DeletingMode theMode = TObj_FreeOnly ); -~~~~~ - -Returns **True** if the object can be deleted with the indicated deletion mode. - -~~~~~{.cpp} - virtual Standard_Boolean Detach ( const TObj_DeletingMode theMode = TObj_FreeOnly ); -~~~~~ - -Removes the object from the document if possible -(according to the indicated deletion mode). -Unlinks references from removed objects. -Returns **True** if the objects have been successfully deleted. - -@subsection occt_tobj_3_8 Transformation and replication of object data - -*TObj_Object* provides a number of special virtual methods to support replications of objects. These methods should be redefined by descendants when necessary. - -~~~~~{.cpp} - virtual Handle(TObj_Object) Clone (const TDF_Label& theTargetLabel, Handle(TDF_RelocationTable) theRelocTable = 0); -~~~~~ - -Copies the object to theTargetLabel. The new object will have all references of its original. -Returns a handle to the new object (null handle if fail). The data are copied directly, -but the name is changed by adding the postfix *_copy*. -To assign different names to the copies redefine the method: - -~~~~~{.cpp} - virtual Handle(TCollection_HExtendedString) GetNameForClone ( const Handle(TObj_Object)& ) const; -~~~~~ - -Returns the name for a new object copy. It could be useful to return the same object name -if the copy will be in the other model or in the other partition with its own dictionary. -The method *Clone* uses the following public methods for object data replications: - -~~~~~{.cpp} - virtual void CopyReferences (const const Handle(TObj_Object)& theTargetObject, const Handle(TDF_RelocationTable) theRelocTable); -~~~~~ - -Adds to the copy of the original object its references. - -~~~~~{.cpp} - virtual void CopyChildren (TDF_Label& theTargetLabel, const Handle(TDF_RelocationTable) theRelocTable); -~~~~~ - -Copies the children of an object to the target child label. - -@subsection occt_tobj_3_9 Object flags - -Each instance of *TObj_Object* stores a set of bit flags, -which facilitate the storage of auxiliary logical information assigned to the objects -(object state). Several typical state flags are defined in the enumeration *ObjectState*: - - * *ObjectState_Hidden* -- the object is marked as hidden - * *ObjectState_Saved* -- the object has (or should have) the corresponding saved file on disk - * *ObjectState_Imported* -- the object is imported from somewhere - * *ObjectState_ImportedByFile* -- the object has been imported from file and should be updated to have correct relations with other objects - * *ObjectState_Ordered* -- the partition contains objects that can be ordered. - -The user (developer) can define any new flags in descendant classes. -To set/get an object, the flags use the following methods: - -~~~~~{.cpp} - Standard_Integer GetFlags() const; - void SetFlags( const Standard_Integer theMask ); - Stadnard_Boolean TestFlags( const Standard_Integer theMask ) const; - void ClearFlags( const Standard_Integer theMask = 0 ); -~~~~~ - -In addition, the generic virtual interface stores the logical properties -of the object class in the form of a set of bit flags. -Type flags can be received by the method: - -~~~~~{.cpp} - virtual Standard_Integer GetTypeFlags() const; -~~~~~ - -The default implementation returns the flag **Visible** -defined in the enumeration *TypeFlags*. This flag is used to define visibility -of the object for the user browsing the model (see class *TObj_HiddenPartition*). -Other flags can be added by the applications. - -@subsection occt_tobj_310 Partitions - -The special kind of objects defined by the class *TObj_Partition* -(and its descendant *TObj_HiddenPartition*) is provided for partitioning -the model into a hierarchical structure. This object represents the container -of other objects. Each *TObj* model contains the main partition that is placed -in the same OCAF label as the model object, and serves as a root of the object's tree. -A hidden partition is a simple partition with a predefined hidden flag. - -The main partition object methods: - -~~~~~{.cpp} - TDF_Label NewLabel() const; -~~~~~ - -Allocates and returns a new label for creation of a new child object. - -~~~~~{.cpp} - void SetNamePrefix ( const Handle(TCollection_HExtendedString)& thePrefix); -~~~~~ - -Defines the prefix for automatic generation of names of the newly created objects. - -~~~~~{.cpp} - Handle(TCollection_HExtendedString) GetNamePrefix() const; -~~~~~ - -Returns the current name prefix. - -~~~~~{.cpp} - Handle(TCollection_HExtendedString) GetNewName ( const Standard_Boolean theIsToChangeCount) const; -~~~~~ - -Generates the new name and increases the internal counter of child objects if theIsToChangeCount is **True**. - -~~~~~{.cpp} - Standard_Integer GetLastIndex() const; -~~~~~ - -Returns the last reserved child index. - -~~~~~{.cpp} - void SetLastIndex( const Standard_Integer theIndex ); -~~~~~ - -Sets the last reserved index. - -@section occt_tobj_4 Auxiliary classes - -Apart from the model and the object, package *TObj* provides a set of auxiliary classes: - - * *TObj_Application* -- defines OCAF application supporting existence and operation with *TObj* documents. - * *TObj_Assistant* -- class provides an interface to the static data to be used during save and load operations on models. In particular, in case of cross-model dependencies it allows passing information on the parent model to the OCAF loader to correctly resolve the references when loading a dependent model. - * *TObj_TReference* -- OCAF attribute describes the references between objects in the *TObj* model(s). This attribute stores the label of the referred model object, and provides transparent cross-model references. At runtime, these references are simple Handles; in persistence mode, the cross-model references are automatically detected and processed by the persistence mechanism of *TObj_TReference* attribute. - * Other classes starting with *TObj_T...* -- define OCAF attributes used to store TObj-specific classes and some types of data on OCAF labels. - * Iterators -- a set of classes implementing *TObj_ObjectIterator* interface, used for iterations on *TObj* objects: - * *TObj_ObjectIterator* -- a basic abstract class for other *TObj* iterators. Iterates on *TObj_Object* instances. - * *TObj_LabelIterator* -- iterates on object labels in the *TObj* model document - * *TObj_ModelIterator* -- iterates on all objects in the model. Works with sequences of other iterators. - * *TObj_OcafObjectIterator* -- Iterates on *TObj* data model objects. Can iterate on objects of a specific type. - * *TObj_ReferenceIterator* -- iterates on object references. - * *TObj_SequenceIterator* -- iterates on a sequence of *TObj* objects. - * *TObj_CheckModel* -- a tool that checks the internal consistency of the model. The basic implementation checks only the consistency of references between objects. - -The structure of *TObj* iterators hierarchy is presented below: - -@figure{/user_guides/tobj/images/tobj_image008.png,"Hierarchy of iterators",420} - - -@section occt_tobj_5 Packaging - -The *TObj* sources are distributed in the following packages: - - * *TObj* -- defines basic classes that implement *TObj* interfaces for OCAF-based modelers. - * *BinLDrivers, XmlLDrivers* -- binary and XML driver of *TObj* package - * *BinLPlugin, XmlLPlugin* -- plug-in for binary and XML persistence - * *BinMObj, XmlMObj* -- binary and XML drivers to store and retrieve specific *TObj* data to or from OCAF document - * *TKBinL, TKXmlL* -- toolkits of binary and XML persistence - - - diff --git a/dox/user_guides/user_guides.md b/dox/user_guides/user_guides.md index 57d88f2e9e..bf8192f0b7 100644 --- a/dox/user_guides/user_guides.md +++ b/dox/user_guides/user_guides.md @@ -6,14 +6,13 @@ OCCT User Guides are organized by OCCT modules: * @subpage occt_user_guides__foundation_classes "Foundation Classes" * @subpage occt_user_guides__modeling_data "Modeling Data" * @subpage occt_user_guides__modeling_algos "Modeling Algorithms" - * @subpage occt_user_guides__shape_healing "Shape Healing" +* @subpage occt_user_guides__mesh "Mesh" +* @subpage occt_user_guides__shape_healing "Shape Healing" * @subpage occt_user_guides__visualization "Visualization" - * @subpage occt_user_guides__vis "VTK Integration Services" -* Data Exchange - * @subpage occt_user_guides__iges "IGES translator" - * @subpage occt_user_guides__step "STEP translator" - * @subpage occt_user_guides__xde "Extended Data Exchange (XDE)" +* @subpage occt_user_guides__vis "VTK Integration Services" +* @subpage occt_user_guides__iges "IGES Translator" +* @subpage occt_user_guides__step "STEP Translator" +* @subpage occt_user_guides__xde "Extended Data Exchange (XDE)" * @subpage occt_user_guides__ocaf "Open CASCADE Application Framework (OCAF)" - * @subpage occt_user_guides__tobj "TObj package" * @subpage occt_user_guides__test_harness "DRAW Test Harness" * @subpage occt_user_guides__inspector "Inspector" diff --git a/dox/user_guides/visualization/visualization.md b/dox/user_guides/visualization/visualization.md index fdb948d807..df6545eed3 100644 --- a/dox/user_guides/visualization/visualization.md +++ b/dox/user_guides/visualization/visualization.md @@ -42,8 +42,6 @@ To answer different needs of CASCADE users, this User's Guide offers the followi chapter 2 @ref occt_visu_2 "Fundamental Concepts", chapter 3 @ref occt_visu_3 "AIS: Application Interactive Services", and 4 @ref occt_visu_4 "3D Presentations". You may want to begin with the chapter presenting AIS. -For advanced information on visualization algorithms, see our E-learning & Training offerings. - @section occt_visu_2 Fundamental Concepts @subsection occt_visu_2_1 Presentation @@ -1545,28 +1543,34 @@ aViewer->SetDefaultBackgroundColor (Quantity_NOC_DARKVIOLET); // Create a structure in this Viewer Handle(Graphic3d_Structure) aStruct = new Graphic3d_Structure (aViewer->StructureManager()); aStruct->SetVisual (Graphic3d_TOS_SHADING); // Type of structure + // Create a group of primitives in this structure Handle(Graphic3d_Group) aPrsGroup = aStruct->NewGroup(); + // Fill this group with one quad of size 100 Handle(Graphic3d_ArrayOfTriangleStrips) aTriangles = new Graphic3d_ArrayOfTriangleStrips (4); aTriangles->AddVertex (-100./2., -100./2., 0.0); aTriangles->AddVertex (-100./2., 100./2., 0.0); aTriangles->AddVertex ( 100./2., -100./2., 0.0); aTriangles->AddVertex ( 100./2., 100./2., 0.0); + Handle(Graphic3d_AspectFillArea3d) anAspects = new Graphic3d_AspectFillArea3d (Aspect_IS_SOLID, Quantity_NOC_RED, Quantity_NOC_RED, Aspect_TOL_SOLID, 1.0f, Graphic3d_NOM_GOLD, Graphic3d_NOM_GOLD); aPrsGroup->SetGroupPrimitivesAspect (anAspects); aPrsGroup->AddPrimitiveArray (aTriangles); + // Create Ambient and Infinite Lights in this Viewer Handle(V3d_AmbientLight) aLight1 = new V3d_AmbientLight (Quantity_NOC_GRAY50); Handle(V3d_DirectionalLight) aLight2 = new V3d_DirectionalLight (V3d_Zneg, Quantity_NOC_WHITE, true); aViewer->AddLight (aLight1); aViewer->AddLight (aLight2); aViewer->SetLightOn(); + // Create a 3D quality Window with the same DisplayConnection Handle(Xw_Window) aWindow = new Xw_Window (aDispConnection, "Test V3d", 100, 100, 500, 500); aWindow->Map(); // Map this Window to this screen + // Create a Perspective View in this Viewer Handle(V3d_View) aView = new V3d_View (aViewer); aView->Camera()->SetProjectionType (Graphic3d_Camera::Projection_Perspective); @@ -1622,7 +1626,7 @@ aView->Update(); // update the Visualization in this View @subsubsection occt_visu_4_4_5 Perspective Projection -**Field of view (FOVy)** -- defines the field of camera view by y axis in degrees (45° is default). +**Field of view (FOVy)** -- defines the field of camera view by y axis in degrees (45° is default). @figure{camera_perspective.png,"Perspective frustum",420} @@ -1643,7 +1647,7 @@ There are two types of IOD: * _Graphic3d_Camera::IODType_Absolute_ : Intraocular distance is defined as an absolute value. * _Graphic3d_Camera::IODType_Relative_ : Intraocular distance is defined relative to the camera focal length (as its coefficient). -**Field of view (FOV)** -- defines the field of camera view by y axis in degrees (45° is default). +**Field of view (FOV)** -- defines the field of camera view by y axis in degrees (45° is default). **ZFocus** -- defines the distance to the point of stereographic focus. diff --git a/dox/user_guides/xde/xde.md b/dox/user_guides/xde/xde.md index e2a92615a9..04a4389153 100644 --- a/dox/user_guides/xde/xde.md +++ b/dox/user_guides/xde/xde.md @@ -5,7 +5,7 @@ @section occt_xde_1 Introduction -This manual explains how to use the Extended Data Exchange (XDE). It provides basic documentation on setting up and using XDE. For advanced information on XDE and its applications, see our E-learning & Training offerings. +This manual explains how to use the Extended Data Exchange (XDE). It provides basic documentation on setting up and using XDE. The Extended Data Exchange (XDE) module allows extending the scope of exchange by translating additional data attached to geometric BREP data, thereby improving the interoperability with external software.