OCCT基础类库介绍：Modeling Algorithm - The Topology API

The Topology API

拓扑API

The Topology API of Open CASCADE Technology (OCCT) includes the following six packages:
Open CASCADE Technology (OCCT) 的拓扑API包含以下六个包：

• BRepAlgoAPI
  边界表示算法API
• BRepBuilderAPI
  边界表示构建器API
• BRepFilletAPI
  边界表示圆角API
• BRepFeat
  边界表示特征
• BRepOffsetAPI
  边界表示偏移API
• BRepPrimAPI
  边界表示基本体API

The classes provided by the API have the following features:
API 提供的类具有以下特点：

• 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.
下面使用 BRepBuilderAPI_MakeEdge 类从两个点创建直线边。

gp_Pnt P1(10, 0, 0), P2(20, 0, 0); 
TopoDS_Edge E = BRepBuilderAPI_MakeEdge(P1, P2);

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.
这是从两个点 P1、P2 创建边 E 的最简单方法，但当开发人员对数据不像前例中那样有把握时，可以进行错误检测。

#include <gp_Pnt.hxx> 
#include <TopoDS_Edge.hxx> 
#include <BRepBuilderAPI_MakeEdge.hxx> 
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 create an edge"); 
    } 
    TopoDS_Edge E = ME; 
} 

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.
在这个例子中引入了中间对象 ME。这允许在访问结果前测试函数是否完成。拓扑编程接口中关于错误处理的更多信息可在下一节中找到。

BRepBuilderAPI_MakeEdge provides valuable information.
BRepBuilderAPI_MakeEdge 提供了有价值的信息。

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.
例如，从两个点创建边时，必须从这些点创建两个顶点。有时您可能希望快速获取这些顶点而不关注新边。使用该类时可提供此类信息。以下示例展示了一个从两个点创建边和两个顶点的函数。

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.Vertex1(); 
    V2 = ME.Vertex2(); 
}

The class BRepBuilderAPI_MakeEdge provides two methods Vertex1 and Vertex2, which return two vertices used to create the edge.
BRepBuilderAPI_MakeEdge 类提供了 Vertex1 和 Vertex2 两个方法，用于返回创建边时使用的两个顶点。

How can BRepBuilderAPI_MakeEdge be both a function and a class?
为什么 BRepBuilderAPI_MakeEdge 既可以作为函数又可以作为类使用？

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.
这是因为它使用了 C++ 的类型转换功能。BRepBuilderAPI_MakeEdge 类有一个名为 Edge 的方法；在前例中，E = ME 这一行也可以写成：

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.
这条指令告诉 C++ 编译器，存在使用 Edge 方法将 BRepBuilderAPI_MakeEdge 隐式转换为 TopoDS_Edge 的操作。这意味着当需要 TopoDS_Edge 而提供了 BRepBuilderAPI_MakeEdge 时，该方法会被自动调用。

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.
此特性使类能够在需要时具备函数调用的简洁性，并在需要高级处理时具备类的强大功能。这种方法的所有优势将在描述拓扑编程接口类时详细说明。

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:
所有拓扑API算法都为其参数支持形状修改的历史记录（或简称“历史”）。通常，历史记录适用于输入形状的以下子形状类型：

• 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:
历史记录信息可通过以下API方法访问：

• Standard_Boolean IsDeleted(const TopoDS_Shape& theS) - to check if the shape has been Deleted during the operation;
  Standard_Boolean IsDeleted(const TopoDS_Shape& theS) - 检查形状在操作期间是否已被删除；
• const TopTools_ListOfShape& Modified(const TopoDS_Shape& theS) - to get the shapes Modified from the given shape;
  const TopTools_ListOfShape& Modified(const TopoDS_Shape& theS) - 获取从给定形状修改而来的形状；
• const TopTools_ListOfShape& Generated(const TopoDS_Shape& theS) - to get the shapes Generated from the given shape.
  const TopTools_ListOfShape& Generated(const TopoDS_Shape& theS) - 获取从给定形状生成的形状。

Deleted shapes

已删除形状

The shape is considered as Deleted during the operation if all of the following conditions are met:
如果满足以下所有条件，则形状在操作期间被视为已删除：

1. The shape is a part of the argument shapes of the operation;
   形状是操作参数形状的一部分；
2. The result shape does not contain the shape itself;
   结果形状不包含该形状本身；
3. 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.
例如，在两个相交实体的切割（CUT）操作中，完全位于工具实体内部的所有顶点/边/面将在操作期间被删除。

Modified shapes

已修改形状

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.
如果结果形状包含形状的分割部分而不是形状本身，则该形状在操作期间被视为已修改。形状只能修改为相同维度的形状。结果形状中包含的形状分割部分是从该形状修改而来的。已修改形状由输入形状的子形状创建，并且通常重复其几何结构。

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.
已修改元素列表将仅包含那些对操作结果有贡献的元素。如果列表为空，则形状未被修改，需要检查其是否已被删除。

For example, after translation of the shape in any direction all its sub-shapes will be modified into their translated copies.
例如，在将形状向任意方向平移后，其所有子形状将被修改为平移后的副本。

Generated shapes

已生成形状

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.
如果结果形状中包含的形状是在操作期间生成的，并且与创建它们的形状具有不同的维度，则这些形状被视为从输入形状生成的。

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.
已生成元素列表将仅包含那些包含在操作结果中的元素。如果列表为空，则没有从该形状生成新形状。

For example, extrusion of the edge in some direction will create a face. This face will be generated from the edge.
例如，将边沿某个方向拉伸将创建一个面。该面将从边生成。

BRepTools_History

BRepTools_History

BRepTools_History is the general History tool intended for unification of the histories of different algorithms.
BRepTools_History 是通用的历史记录工具，用于统一不同算法的历史记录。

BRepTools_History can be created from any algorithm supporting the standard history methods (IsDeleted(), Modified() and Generated()):
BRepTools_History 可以从任何支持标准历史记录方法（IsDeleted()、Modified() 和 Generated()）的算法创建：

// The arguments of the operation
TopoDS_Shape aS = ...;
 
// 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();
 
// Create the translation history object
TopTools_ListOfShape anArguments;
anArguments.Append(aS);
BRepTools_History aHistory(anArguments, aTransformer);

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:
BRepTools_History 还允许合并历史记录。因此，如果有两个或更多后续操作，可以获取一个由这些操作的历史记录组合而成的最终历史记录：

Handle(BRepTools_History) aHist1 = ...; // History of first operation
Handle(BRepTools_History) aHist2 = ...; // History of second operation

// Merge the second history into the first one
aHist1->Merge(aHist2);

// Or create the new history keeping the two histories unmodified
Handle(BRepTools_History) aResHistory = new BRepTools_History;
aResHistory->Merge(aHist1);
aResHistory->Merge(aHist2);

The possibilities of Merging histories and history creation from the API algorithms allow providing easy History support for the new algorithms.
合并历史记录和从API算法创建历史记录的功能使得为新算法提供简单的历史记录支持成为可能。

DRAW history support

DRAW历史记录支持

DRAW History support for the algorithms is provided by three basic commands:
算法的DRAW历史记录支持由三个基本命令提供：

• isdeleted;
  isdeleted；
• modified;
  modified；
• generated.
  generated。

For more information on the Draw History mechanism, refer to the corresponding chapter in the Draw users guide - History commands.
有关Draw历史记录机制的更多信息，请参考《Draw用户指南》中的相应章节 - 历史记录命令。

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.
如果存在凹度，需要延伸和不需要延伸的曲面都会被处理。

Fillets

圆角

Fillet on shape

形状上的圆角

A fillet is a smooth face replacing a sharp edge.
圆角是替换尖锐边的光滑面。

BRepFilletAPI_MakeFillet class allows filleting a shape.
BRepFilletAPI_MakeFillet 类用于对形状进行圆角处理。

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.
要生成圆角，需要在类构造时定义圆角形状，并使用 Add 方法添加圆角描述。

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 smooth continuity with the original edge. It is not an error to add a fillet twice, the last description holds.
圆角描述包含一条边和一个半径。该边必须由两个面共享。圆角会自动延伸到与原始边光滑连续的所有边。两次添加圆角不算错误，最后一次描述有效。

Filleting two edges using radii r1 and r2.

使用半径 r1 和 r2 对两条边倒圆角

In the following example, a filleted box with dimensions a,b,c and radius r is created.
以下示例创建一个尺寸为 a,b,c 且半径为 r 的圆角盒子。

Constant radius

恒定半径

#include <TopoDS_Shape.hxx> 
#include <TopoDS.hxx> 
#include <BRepPrimAPI_MakeBox.hxx> 
#include <TopoDS_Solid.hxx> 
#include <BRepFilletAPI_MakeFillet.hxx> 
#include <TopExp_Explorer.hxx> 
 
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); 
 
    // 添加所有边以倒圆角 
    TopExp_Explorer ex(Box, TopAbs_EDGE); 
    while (ex.More()) 
    { 
        MF.Add(r, TopoDS::Edge(ex.Current())); 
        ex.Next(); 
    } 
    return MF.Shape(); 
}

Fillet with constant radius
恒定半径圆角

Changing radius

变半径

void CSampleTopologicalOperationsDoc::OnEvolvedblend1() 
{ 
    TopoDS_Shape theBox = BRepPrimAPI_MakeBox(200, 200, 200); 
 
    BRepFilletAPI_MakeFillet Rake(theBox); 
    ChFi3d_FilletShape FSh = ChFi3d_Rational; 
    Rake.SetFilletShape(FSh); 
 
    TColgp_Array1OfPnt2d ParAndRad(1, 6); 
    ParAndRad(1).SetCoord(0.,  10.); 
    ParAndRad(2).SetCoord(50.,  20.); 
    ParAndRad(3).SetCoord(70.,  20.); 
    ParAndRad(4).SetCoord(130.,  60.); 
    ParAndRad(5).SetCoord(160.,  30.); 
    ParAndRad(6).SetCoord(200.,  20.); 
 
    TopExp_Explorer ex(theBox, TopAbs_EDGE); 
    Rake.Add(ParAndRad, TopoDS::Edge(ex.Current())); 
    TopoDS_Shape evolvedBox = Rake.Shape(); 
}

Fillet with changing radius
变半径圆角

Chamfer

倒角

A chamfer is a rectilinear edge replacing a sharp vertex of the face.
倒角是替换面的尖锐顶点的直线边。

The use of BRepFilletAPI_MakeChamfer class is similar to the use of BRepFilletAPI_MakeFillet, except for the following:
BRepFilletAPI_MakeChamfer 类的用法与 BRepFilletAPI_MakeFillet 类似，但以下区别除外：

• 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 语法需要一个或两个距离、一条边和一个面（与边相邻）。

  Add(dist,  E, F) 
  Add(d1,  d2, E, F)  // d1 位于面 F 上
  

Chamfer
倒角

Fillet on a planar face

平面上的圆角

BRepFilletAPI_MakeFillet2d class allows constructing fillets and chamfers on planar faces. To create a fillet on a planar face: define it, indicate which vertex is to be deleted, and give the fillet radius with AddFillet method.
BRepFilletAPI_MakeFillet2d 类用于在平面上构建圆角和倒角。要在平面上创建圆角：定义平面，指定要删除的顶点，并使用 AddFillet 方法提供圆角半径。

A chamfer can be calculated with AddChamfer method. It can be described by:
倒角可通过 AddChamfer 方法计算，可通过以下方式描述：

• two edges and two distances
  两条边和两个距离
• one edge, one vertex, one distance and one angle
  一条边、一个顶点、一个距离和一个角度

Fillets and chamfers are calculated when addition is complete.
添加完成后计算圆角和倒角。

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:
如果面 F2 是由 2D 圆角和倒角构建器从面 F1 创建的，可重建构建器（构建器恢复删除前的状态），语法如下：

BRepFilletAPI_MakeFillet2d builder; 
builder.Init(F1, F2);