PythonOCC 基础教程：几何建模与数据交换

PythonOCC 的基础教程，涵盖环境配置、基础形状创建、布尔运算与几何变换、数据交换（STEP/IGES）以及 PyQt5 图形界面开发。内容包含详细的代码示例，展示了如何使用 PythonOCC 进行三维建模、文件读写及简单的 CAD 应用开发。

刀狂发布于 2026/3/28更新于 2026/4/178 浏览

环境配置

# OCC 7.5.1 conda create --name=pyoccenv python=3.7 source activate pyoccenv conda install -c conda-forge pythonocc-core=7.5.1
# OCC 7.7.0 conda create --name=pyoccenv python=3.9 activate pyoccenv conda install -c conda-forge pythonocc-core=7.7.0

版本号	推荐 Python 版本

from OCC.Display.SimpleGui import init_display
from OCC.Core.BRepPrimAPI import BRepPrimAPI_MakeBox

# 初始化显示窗口
display, start_display, _, _ = init_display()

# 创建一个长 10、宽 20、高 30 的立方体
box = BRepPrimAPI_MakeBox(10,20,30).Shape()

# 显示这个立方体
display.DisplayShape(box, update=True)
start_display()

操作类别	核心 API 类	代码示例（核心部分）	关键说明
创建点	`gp_Pnt`	`p = gp_Pnt(x, y, z)`	定义 3D 空间中的位置
创建线	`BRepBuilderAPI_MakeEdge`	`edge = BRepBuilderAPI_MakeEdge(p1, p2).Edge()`	两点确定一条线段
创建立方体	`BRepPrimAPI_MakeBox`	`box = BRepPrimAPI_MakeBox(dx, dy, dz).Shape()`	指定长宽高
创建球体	`BRepPrimAPI_MakeSphere`	`sphere = BRepPrimAPI_MakeSphere(radius).Shape()`	指定半径
创建圆柱体	`BRepPrimAPI_MakeCylinder`	`cylinder = BRepPrimAPI_MakeCylinder(radius, height).Shape()`	指定半径和高度

""" PythonOCC 基础形状演示 各物体沿 X 轴拉开间距，便于观察 """
from OCC.Display.SimpleGui import init_display
from OCC.Core.gp import gp_Pnt, gp_Ax2, gp_Dir
from OCC.Core.BRepBuilderAPI import BRepBuilderAPI_MakeEdge, BRepBuilderAPI_MakeVertex
from OCC.Core.BRepPrimAPI import BRepPrimAPI_MakeBox, BRepPrimAPI_MakeSphere, BRepPrimAPI_MakeCylinder

# 初始化显示窗口
display, start_display, _, _ = init_display()

# 定义 X 方向上的偏移量，使各物体依次排列
offset_x = 0

# 1. 点：位于原点
p = gp_Pnt(offset_x,0,0)
vertex = BRepBuilderAPI_MakeVertex(p).Vertex()
display.DisplayShape(vertex, color="RED")
offset_x += 35 # 留出间距

# 2. 线：两点确定一条线段，整体偏移
p1 = gp_Pnt(offset_x,0,0)
p2 = gp_Pnt(offset_x +20,10,0)
edge = BRepBuilderAPI_MakeEdge(p1, p2).Edge()
display.DisplayShape(edge, color="GREEN", transparency=False)
offset_x += 45 # 线段长度约 20，再加间距

# 3. 立方体：长 10，宽 20，高 30，使其中心位于 offset_x 处
# 注意：BRepPrimAPI_MakeBox(gp_Ax2, dx, dy, dz) 以 Ax2 原点为角点，沿 X、Y、Z 正向延伸
# 我们通过设置角点位置来控制中心位置（角点 = 中心 - (dx/2, dy/2, dz/2)）
box_dx, box_dy, box_dz = 10,20,30
box_corner = gp_Pnt(offset_x - box_dx/2,-box_dy/2,-box_dz/2)
box_axis = gp_Ax2(box_corner, gp_Dir(0,0,1))
box = BRepPrimAPI_MakeBox(box_axis, box_dx, box_dy, box_dz).Shape()
display.DisplayShape(box, color="BLUE", transparency=0.5)
offset_x += 40 # 立方体 X 方向跨度 10，再加间距

# 4. 球体：半径 15，使其中心位于 offset_x
sphere_radius = 15
sphere_center = gp_Pnt(offset_x,0,0)
sphere = BRepPrimAPI_MakeSphere(sphere_center, sphere_radius).Shape()
display.DisplayShape(sphere, color="YELLOW", transparency=0.3)
offset_x += 40 # 球体直径 30，再加间距

# 5. 圆柱体：半径 10，高 40，使其底部中心位于 offset_x
cylinder_radius = 10
cylinder_height = 40
cylinder_pos = gp_Pnt(offset_x,0,0)
cylinder_axis = gp_Ax2(cylinder_pos, gp_Dir(0,0,1))
# 底部中心在 pos，沿 Z 轴向上
cylinder = BRepPrimAPI_MakeCylinder(cylinder_axis, cylinder_radius, cylinder_height).Shape()
display.DisplayShape(cylinder, color="MAGENTA", transparency=0.4)

# 调整视图并显示
display.FitAll()
start_display()

操作	类	效果	应用场景
融合 (Union)	`BRepAlgoAPI_Fuse`	合并两个形状，得到它们的并集	将多个零件组合成一个整体
切割 (Cut)	`BRepAlgoAPI_Cut`	从第一个形状中减去第二个形状	打孔、开槽、切除多余部分
交集 (Common)	`BRepAlgoAPI_Common`	保留两个形状重叠的部分	提取交集体积，用于装配干涉检测

""" 布尔运算示例：融合、切割、交集 使用一个立方体（蓝色）和一个球体（黄色）演示 结果分别显示在三个区域 """
from OCC.Display.SimpleGui import init_display
from OCC.Core.gp import gp_Pnt, gp_Vec, gp_Trsf
from OCC.Core.BRepPrimAPI import BRepPrimAPI_MakeBox, BRepPrimAPI_MakeSphere
from OCC.Core.BRepAlgoAPI import BRepAlgoAPI_Fuse, BRepAlgoAPI_Cut, BRepAlgoAPI_Common
from OCC.Core.BRepBuilderAPI import BRepBuilderAPI_Transform

# 初始化显示窗口
display, start_display, _, _ = init_display()

# ---------- 1. 创建基本形状 ----------
# 立方体：边长 10，中心位于原点
box = BRepPrimAPI_MakeBox(10,10,10).Shape()
# 球体：半径 5，中心位于 (2, 0, 0)（部分与立方体重叠）
sphere_center = gp_Pnt(2,0,0)
sphere = BRepPrimAPI_MakeSphere(sphere_center,5).Shape()

# ---------- 2. 布尔运算 ----------
# 融合 (Union)
fuse = BRepAlgoAPI_Fuse(box, sphere).Shape()
# 切割 (Cut): 立方体减去球体
cut = BRepAlgoAPI_Cut(box, sphere).Shape()
# 交集 (Common)
common = BRepAlgoAPI_Common(box, sphere).Shape()

# ---------- 3. 将三个结果沿 X 轴排开 ----------
# 平移距离（确保不重叠）
offset_x = 20

# 将融合结果放置在 x = -offset_x 处
trsf_fuse = gp_Trsf()
trsf_fuse.SetTranslation(gp_Vec(-offset_x,0,0))
fuse_trans = BRepBuilderAPI_Transform(fuse, trsf_fuse,True).Shape()
display.DisplayShape(fuse_trans, color="GREEN", transparency=0.3)

# 切割结果放置在原点
display.DisplayShape(cut, color="RED", transparency=0.3)

# 交集结果放置在 x = offset_x 处
trsf_common = gp_Trsf()
trsf_common.SetTranslation(gp_Vec(offset_x,0,0))
common_trans = BRepBuilderAPI_Transform(common, trsf_common,True).Shape()
display.DisplayShape(common_trans, color="BLUE", transparency=0.3)

# 可选：显示原始立方体和球体作为参考（半透明）
# 为了清晰，不在此显示，以免干扰

# 调整视图并显示
display.FitAll()
start_display()

""" 几何变换演示（使用 Quantity_Color 精确设置颜色） """
from OCC.Display.SimpleGui import init_display
from OCC.Core.gp import gp_Trsf, gp_Vec, gp_Ax1, gp_Pnt, gp_Dir, gp_Ax2
from OCC.Core.BRepPrimAPI import BRepPrimAPI_MakeBox
from OCC.Core.BRepBuilderAPI import BRepBuilderAPI_Transform
from OCC.Core.Quantity import Quantity_Color, Quantity_TOC_RGB
import math

display, start_display, _, _ = init_display()

# 辅助函数：根据 RGB 创建颜色对象
def rgb_color(r, g, b):
    return Quantity_Color(r, g, b, Quantity_TOC_RGB)

# 原始立方体（白色）
original_box = BRepPrimAPI_MakeBox(10,10,10).Shape()
display.DisplayShape(original_box, color=rgb_color(1.0,1.0,1.0), transparency=0.0)

# 平移（红色）
trsf_trans = gp_Trsf()
trsf_trans.SetTranslation(gp_Vec(15,0,0))
trans_box = BRepBuilderAPI_Transform(original_box, trsf_trans,True).Shape()
display.DisplayShape(trans_box, color=rgb_color(1.0,0.0,0.0), transparency=0.3)

# 旋转（绿色）
trsf_rot = gp_Trsf()
trsf_rot.SetRotation(gp_Ax1(gp_Pnt(0,0,0), gp_Dir(0,1,0)), math.radians(45))
rot_box = BRepBuilderAPI_Transform(original_box, trsf_rot,True).Shape()
trsf_move = gp_Trsf()
trsf_move.SetTranslation(gp_Vec(-15,0,0))
rot_box_moved = BRepBuilderAPI_Transform(rot_box, trsf_move,True).Shape()
display.DisplayShape(rot_box_moved, color=rgb_color(0.0,1.0,0.0), transparency=0.3)

# 缩放（蓝色）
trsf_scale = gp_Trsf()
trsf_scale.SetScale(gp_Pnt(0,0,0),1.5)
scale_box = BRepBuilderAPI_Transform(original_box, trsf_scale,True).Shape()
trsf_move2 = gp_Trsf()
trsf_move2.SetTranslation(gp_Vec(0,15,0))
scale_box_moved = BRepBuilderAPI_Transform(scale_box, trsf_move2,True).Shape()
display.DisplayShape(scale_box_moved, color=rgb_color(0.0,0.0,1.0), transparency=0.3)

# 镜像（洋红色）
plane_ax2 = gp_Ax2(gp_Pnt(0,0,0), gp_Dir(0,0,1))
trsf_mirror = gp_Trsf()
trsf_mirror.SetMirror(plane_ax2)
mirror_box = BRepBuilderAPI_Transform(original_box, trsf_mirror,True).Shape()
trsf_move3 = gp_Trsf()
trsf_move3.SetTranslation(gp_Vec(0,-15,0))
mirror_box_moved = BRepBuilderAPI_Transform(mirror_box, trsf_move3,True).Shape()
display.DisplayShape(mirror_box_moved, color=rgb_color(1.0,0.0,1.0), transparency=0.3)

# 组合变换（青色）
trsf_trans2 = gp_Trsf()
trsf_trans2.SetTranslation(gp_Vec(10,10,0))
trsf_rot2 = gp_Trsf()
trsf_rot2.SetRotation(gp_Ax1(gp_Pnt(0,0,0), gp_Dir(0,0,1)), math.radians(45))
combined = trsf_rot2 * trsf_trans2
combined_box = BRepBuilderAPI_Transform(original_box, combined,True).Shape()
display.DisplayShape(combined_box, color=rgb_color(0.0,1.0,1.0), transparency=0.3)

display.FitAll()
start_display()

""" 数据交换示例：读取 STEP 文件并显示（直接指定文件路径） """
from OCC.Display.SimpleGui import init_display
from OCC.Core.STEPControl import STEPControl_Reader
from OCC.Core.IFSelect import IFSelect_RetDone

def load_and_display_step(filename):
    # 读取文件
    reader = STEPControl_Reader()
    status = reader.ReadFile(filename)
    if status != IFSelect_RetDone:
        print(f"读取文件失败：{ filename}")
        return
    reader.TransferRoots()
    shape = reader.OneShape() # 获取第一个形状
    
    # 显示
    display, start_display, _, _ = init_display()
    display.DisplayShape(shape, color="BLUE", transparency=0.2)
    display.FitAll()
    start_display()

if __name__ == "__main__":
    # 直接指定要加载的 STEP 文件路径
    # 注意：如果路径包含反斜杠，请使用原始字符串 r"..." 或双反斜杠
    step_file = r"path/to/your/file.step"
    load_and_display_step(step_file)

""" 数据交换示例：读取 IGES 文件并显示（直接指定文件路径） 支持多实体文件，自动将所有形状显示在场景中 """
from OCC.Display.SimpleGui import init_display
from OCC.Core.IGESControl import IGESControl_Reader

def load_and_display_iges(filename):
    # 创建 IGES 读取器
    reader = IGESControl_Reader()
    status = reader.ReadFile(filename)
    # 正确的状态检查：返回值 >0 表示成功，<=0 表示失败
    if status <= 0:
        print(f"读取文件失败，返回码：{ status}")
        return
    print(f"成功读取 { status} 个实体")
    
    # 将所有根实体转换为形状
    reader.TransferRoots()
    nb_shapes = reader.NbShapes()
    print(f"转换得到 { nb_shapes} 个形状")
    
    # 初始化显示
    display, start_display, _, _ = init_display()
    
    # 如果只有一个形状，直接显示
    if nb_shapes == 1:
        shape = reader.OneShape()
        display.DisplayShape(shape, color="GREEN", transparency=0.2)
    else:
        # 多个形状，分别显示并分配不同颜色
        for i in range(nb_shapes):
            shape = reader.Shape(i+1) # 索引从 1 开始
            color = ["BLUE","RED","YELLOW","MAGENTA","CYAN"][i % 5]
            display.DisplayShape(shape, color=color, transparency=0.2)
    
    display.FitAll()
    start_display()

if __name__ == "__main__":
    # 直接指定要加载的 IGES 文件路径
    iges_file = r"path/to/your/file.igs"
    load_and_display_iges(iges_file)

import sys
from OCC.Core.STEPControl import STEPControl_Reader
from OCC.Core.IGESControl import IGESControl_Writer
from OCC.Core.IFSelect import IFSelect_RetDone

def step_to_iges(input_step_file, output_iges_file):
    """ 将 STEP 文件转换为 IGES 文件 """
    # 1. 读取 STEP 文件
    step_reader = STEPControl_Reader()
    status = step_reader.ReadFile(input_step_file)
    if status != IFSelect_RetDone:
        print(f"错误：无法读取 STEP 文件 '{ input_step_file}'")
        return False
    
    # 执行转换并获取形状
    step_reader.TransferRoot()
    shape = step_reader.Shape()
    
    # 2. 写入 IGES 文件
    iges_writer = IGESControl_Writer()
    iges_writer.AddShape(shape)
    iges_writer.Write(output_iges_file)
    print(f"成功：已将 '{ input_step_file}' 转换为 '{ output_iges_file}'")
    return True

# 使用示例
if __name__ == "__main__":
    step_to_iges("1.step","1.igs")

pip install pyqt5

""" 简易 CAD 查看器：支持加载/保存 STEP，显示模型信息 修正：显式加载 Qt 后端 """
import sys
from PyQt5.QtWidgets import(QApplication, QMainWindow, QVBoxLayout, QHBoxLayout, QWidget, QPushButton, QFileDialog, QLabel, QStatusBar, QMessageBox)
from PyQt5.QtCore import Qt

# 重要：先加载 Qt 后端，然后再导入 qtDisplay
from OCC.Display.backend import load_backend
load_backend("pyqt5") # 必须在导入 qtDisplay 之前调用

from OCC.Display.qtDisplay import qtViewer3d
from OCC.Core.STEPControl import STEPControl_Reader, STEPControl_Writer
from OCC.Core.IFSelect import IFSelect_RetDone
from OCC.Core.TopExp import TopExp_Explorer
from OCC.Core.TopAbs import TopAbs_FACE, TopAbs_EDGE, TopAbs_VERTEX

class CADViewer(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("简易 CAD 查看器")
        self.setGeometry(100,100,1200,800)
        central = QWidget()
        self.setCentralWidget(central)
        layout = QVBoxLayout(central)
        
        # 3D 视图
        self.viewer = qtViewer3d(self)
        layout.addWidget(self.viewer)
        
        # 按钮栏
        btn_layout = QHBoxLayout()
        load_btn = QPushButton("加载 STEP")
        load_btn.clicked.connect(self.load_step)
        save_btn = QPushButton("保存 STEP")
        save_btn.clicked.connect(self.save_step)
        clear_btn = QPushButton("清除")
        clear_btn.clicked.connect(self.clear_view)
        info_btn = QPushButton("模型信息")
        info_btn.clicked.connect(self.show_info)
        btn_layout.addWidget(load_btn)
        btn_layout.addWidget(save_btn)
        btn_layout.addWidget(clear_btn)
        btn_layout.addWidget(info_btn)
        layout.addLayout(btn_layout)
        
        # 状态栏
        self.status_bar = QStatusBar()
        self.setStatusBar(self.status_bar)
        self.status_bar.showMessage("就绪")
        
        self.shape = None
        self.current_file = None

    def load_step(self):
        filename, _ = QFileDialog.getOpenFileName(self,"打开 STEP 文件","","STEP Files (*.step *.stp)")
        if not filename:
            return
        reader = STEPControl_Reader()
        status = reader.ReadFile(filename)
        if status != IFSelect_RetDone:
            self.status_bar.showMessage("读取失败")
            return
        reader.TransferRoots()
        self.shape = reader.OneShape()
        self.current_file = filename
        # 显示
        self.viewer._display.Context.RemoveAll(True)
        self.viewer._display.DisplayShape(self.shape, color="LIGHTBLUE", transparency=0.2)
        self.viewer._display.FitAll()
        self.status_bar.showMessage(f"已加载：{ filename}")

    def save_step(self):
        if self.shape is None:
            self.status_bar.showMessage("没有可保存的形状")
            return
        filename, _ = QFileDialog.getSaveFileName(self,"保存 STEP 文件","","STEP Files (*.step)")
        if not filename:
            return
        writer = STEPControl_Writer()
        writer.Transfer(self.shape, STEPControl_AsIs)
        writer.Write(filename)
        self.status_bar.showMessage(f"已保存到：{ filename}")

    def clear_view(self):
        self.viewer._display.Context.RemoveAll(True)
        self.viewer._display.FitAll()
        self.shape = None
        self.current_file = None
        self.status_bar.showMessage("场景已清空")

    def show_info(self):
        if self.shape is None:
            self.status_bar.showMessage("无模型")
            return
        face_count = 0
        edge_count = 0
        vertex_count = 0
        exp = TopExp_Explorer()
        exp.Init(self.shape, TopAbs_FACE)
        while exp.More():
            face_count += 1
            exp.Next()
        exp.Init(self.shape, TopAbs_EDGE)
        while exp.More():
            edge_count += 1
            exp.Next()
        exp.Init(self.shape, TopAbs_VERTEX)
        while exp.More():
            vertex_count += 1
            exp.Next()
        info = f"文件：{ self.current_file}\n面数：{ face_count}\n边数：{ edge_count}\n顶点数：{ vertex_count}"
        QMessageBox.information(self,"模型信息", info)

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = CADViewer()
    window.show()
    sys.exit(app.exec_())

import math
from OCC.Core.gp import gp_Pnt, gp_Ax1, gp_Dir, gp_Trsf, gp_Vec
from OCC.Core.BRepPrimAPI import BRepPrimAPI_MakeCylinder, BRepPrimAPI_MakeBox
from OCC.Core.BRepBuilderAPI import BRepBuilderAPI_Transform
from OCC.Core.BRepAlgoAPI import BRepAlgoAPI_Cut, BRepAlgoAPI_Fuse
from OCC.Display.SimpleGui import init_display

# ========== 1. 参数定义（可轻松修改） ==========
flange_outer_radius = 60.0 # 法兰外径
flange_inner_radius = 20.0 # 内孔半径
flange_thickness = 10.0 # 厚度
bolt_circle_radius = 45.0 # 螺栓孔分布圆半径

7.8.1.1	3.9 - 3.11	OCCT 7.8.x	当前最新稳定版，支持在 Jupyter 中使用
7.8.1	3.9 - 3.11	OCCT 7.8.x	于 2024 年 6 月发布
7.7.2	3.9 - 3.10	OCCT 7.7.x	7.7 系列的小幅更新
7.7.0	3.9	OCCT 7.7.0	你最初提到的版本
7.6.2	3.8 - 3.10	OCCT 7.6.2	于 2022 年 8 月发布，非常稳定的版本
7.5.1	3.7 - 3.9	OCCT 7.5.1	你最初提到的版本
7.5.0rc1	3.7 - 3.9	OCCT 7.5.0	7.5.0 的预发布候选版
7.4.1	3.7 - 3.8	OCCT 7.4.0	7.4 系列的小幅更新
7.4.0	3.7 - 3.8	OCCT 7.4.0	首个基于官方 OCCT 的版本之一
0.18.2	2.7, 3.5 - 3.7	OCE 0.18	旧版，基于社区版 OCE 内核
0.18.1	2.7, 3.4 - 3.6	OCE 0.18
0.18	2.7, 3.4 - 3.6	OCE 0.18
0.17.x	2.7, 3.4	OCE 0.17	更早期的版本系列

PythonOCC 基础教程：几何建模与数据交换

环境配置

基础形状的创建

布尔运算与几何变换

1. 布尔运算

2. 几何变换

数据交换与 GUI 开发

1. 数据交换：读写 STEP 和 IGES 文件

2. 图形界面开发：将 PythonOCC 嵌入 PyQt5

参数化建模

更多推荐文章

相关免费在线工具

PythonOCC 基础教程：几何建模与数据交换

环境配置

基础形状的创建

布尔运算与几何变换

1. 布尔运算

2. 几何变换

数据交换与 GUI 开发

1. 数据交换：读写 STEP 和 IGES 文件

2. 图形界面开发：将 PythonOCC 嵌入 PyQt5

参数化建模

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具