opencascade 源码学习几何变换 BRepBuilderAPI-BRepBuilderAPI_Transform

---

1. 类概述

BRepBuilderAPI_Transform 是 OpenCASCADE 中用于对 TopoDS_Shape 进行几何变换的核心类，继承自 BRepBuilderAPI_Modify。它支持以下操作：
• 平移（Translation）
• 旋转（Rotation）
• 缩放（Scaling）
• 镜像（Mirror）
• 复合变换（Composition）

---

2. 核心方法

2.1 构造函数

BRepBuilderAPI_Transform(TopoDS_Shape* shape, 
                         const gp_Trsf& transformation);

• 参数：
• shape：待变换的原始形状（TopoDS_Shape*）
• transformation：变换矩阵（gp_Trsf）
• 功能：创建带有初始形状和变换矩阵的变换对象。

2.2 变换类型设置

通过 SetTransformation() 方法动态修改变换矩阵：

void SetTransformation(const gp_Trsf& transformation);

---

3. 典型变换示例

3.1 平移变换

// 创建平移向量（沿X轴移动5mm）
gp_Vec3d translationVector(5.0, 0.0, 0.0);
gp_Trsf translateTrsf = gp_Trsf(translationVector);

// 应用平移
BRepBuilderAPI_Transform transformer(shape, translateTrsf);
TopoDS_Shape translatedShape = transformer.Shape();

3.2 旋转变换

// 定义旋转轴（Z轴）和旋转角度（45度）
gp_Ax1 rotationAxis(gp_Pnt(0,0,0), gp_Dir(0,0,1));
double angle = 45.0 * M_PI / 180.0; // 弧度制

// 构建旋转变换矩阵
gp_Trsf rotateTrsf = gp_Trsf(rotationAxis, angle);

// 应用旋转
BRepBuilderAPI_Transform transformer(shape, rotateTrsf);
TopoDS_Shape rotatedShape = transformer.Shape();

3.3 缩放变换

// 定义缩放比例（X/Y/Z轴分别缩放2倍）
gp_Scalar scaleFactor(2.0);
gp_Trsf scaleTrsf = gp_Trsf(scaleFactor);

// 应用缩放
BRepBuilderAPI_Transform transformer(shape, scaleTrsf);
TopoDS_Shape scaledShape = transformer.Shape();

3.4 镜像变换

// 定义镜像平面（XY平面）
gp_Pln mirrorPlane(gp_Pnt(0,0,0), gp_Dir(0,0,1));

// 构建镜像变换矩阵
gp_Trsf mirrorTrsf = mirrorPlane.Mirror();

// 应用镜像
BRepBuilderAPI_Transform transformer(shape, mirrorTrsf);
TopoDS_Shape mirroredShape = transformer.Shape();

---

4. 高级用法

4.1 复合变换

通过组合多个变换矩阵实现复杂操作：

// 先旋转后平移
gp_Trsf rotateTrsf = ...; // 45度绕Z轴旋转
gp_Trsf translateTrsf = ...; // 沿X轴平移5mm

// 组合变换矩阵
gp_Trsf composedTrsf = rotateTrsf * translateTrsf;

// 应用复合变换
BRepBuilderAPI_Transform transformer(shape, composedTrsf);

4.2 局部变换

对形状的子部分（如面、边）应用变换：

// 获取形状的面迭代器
TopoDS_FaceIterator faceIter(shape, TopoDS_face);

while (faceIter.More()) {
    TopoDS_Face face = faceIter.Current();
    
    // 对单个面进行缩放
    BRepBuilderAPI_Transform localTransformer(face, scaleTrsf);
    TopoDS_Face scaledFace = localTransformer.Shape();
    
    // 更新原始形状（需使用BRep_Tool）
    BRep_Tool::Replace(face, scaledFace, shape);
    faceIter.Next();
}

---

5. 错误处理

5.1 异常类型

• Standard_NullObject：输入形状为空。
• Standard_TypeError：变换矩阵类型不兼容。
• Standard_ConstructionError：变换导致几何不一致。

5.2 验证变换结果

// 检查形状是否有效
if (shape.IsNull()) {
    throw std::runtime_error("变换后形状为空！");
}

// 计算变换后体积变化率（用于缩放验证）
double originalVolume = BRep_Tool::Volume(shape);
double transformedVolume = BRep_Tool::Volume(transformer.Shape());
double scaleFactor = std::sqrt(transformedVolume / originalVolume);

---

6. 性能优化

1. 批量变换：对多个形状使用同一变换矩阵时，复用 gp_Trsf 对象。
2. 延迟计算：BRepBuilderAPI_Transform 采用延迟渲染机制，适用于大规模几何操作。
3. 并行化：结合 OpenCASCADE 的多线程 API（如 Parallel_Worker）处理复杂变换。

---

7. 对比其他变换类

类别	BRepBuilderAPI_Transform	BRep_Tool::Copy()
目的	修改原始形状的几何位置/形态	创建形状的深拷贝
性能	O(1)（仅引用变换矩阵）	O(N)（复制所有顶点和边）
适用场景	动态修改几何位置（如装配体组装）	需要独立副本的场景
继承关系	继承自 BRepBuilderAPI_Modify	独立于 BRepBuilderAPI 框架

---

8. 完整代码示例

#include <BRepBuilderAPI_Transform.hxx>
#include <TopoDS_Shape.hxx>
#include <gp_Trsf.hxx>
#include <gp_Vec3d.hxx>
#include <gp_Ax1.hxx>

int main() {
    // 加载初始形状（假设已从STEP文件读取）
    TopoDS_Shape shape = ReadSTEPFile("input.step");

    try {
        // 平移+旋转复合变换
        gp_Vec3d transVec(10, 0, 0);      // 平移向量
        gp_Ax1 rotAxis(gp_Pnt(0,0,0), gp_Dir(0,1,0)); // Y轴
        double angle = 30.0 * M_PI / 180.0; // 30度

        gp_Trsf translateTrsf(transVec);
        gp_Trsf rotateTrsf(rotAxis, angle);
        gp_Trsf composedTrsf = rotateTrsf * translateTrsf;

        BRepBuilderAPI_Transform transformer(shape, composedTrsf);
        TopoDS_Shape resultShape = transformer.Shape();

        // 保存结果
        WriteSTEPFile(resultShape, "output_transformed.step");

    } catch (const Standardexception& ex) {
        std::cerr << "变换失败: " << ex.GetMessage() << std::endl;
        return 1;
    }

    return 0;
}

---

9. 最佳实践

1. 变换矩阵管理：复用 gp_Trsf 对象避免内存泄漏。
2. 异常捕获：在关键操作中捕获 Standardexception。
3. 几何验证：使用 BRep_Tool::IsClosed() 或 BRep_Tool::Volume() 验证变换后形状有效性。
4. 性能监控：对大型模型变换时，使用 OpenCASCADE::Timer 统计耗时。

---