CadQuery CQGI接口详解：脚本执行与交互式建模指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00681/article/details/148552969

CadQuery CQGI接口详解：脚本执行与交互式建模指南

cadquery A python parametric CAD scripting framework based on OCCT 项目地址: https://gitcode.com/gh_mirrors/ca/cadquery

什么是CQGI

CadQuery Gateway Interface（CQGI）是CadQuery提供的一套标准化接口规范，它定义了脚本执行环境与CadQuery脚本之间的交互方式。作为一款参数化CAD建模库，CadQuery主要通过编程方式创建3D模型，而CQGI则为各种执行环境（如IDE、文档系统等）提供了统一的脚本执行框架。

CQGI的核心价值

传统CAD建模工具通常采用图形界面交互方式，而CadQuery则通过代码实现建模过程。CQGI在这两者之间架起了桥梁，使得：

开发者可以创建各种前端界面来执行CadQuery脚本
用户可以通过更友好的方式与参数化模型交互
教学文档能够实时展示代码与模型的对应关系

脚本编写规范

在CQGI兼容环境中编写脚本时，需要遵循以下约定：

基本结构

脚本无需显式导入cadquery模块（已自动导入为cq），但必须至少调用一次show_object()方法来输出模型。典型结构如下：

# 创建基础几何体
base = cq.Workplane("XY").box(10, 20, 5)

# 添加特征
with_hole = base.faces(">Z").workplane().hole(3)

# 输出最终模型
show_object(with_hole)

调试输出

CQGI提供了debug()方法用于输出中间建模状态，这对复杂模型的调试非常有帮助：

# 创建初始工作平面
wp = cq.Workplane("XY")

# 调试输出工作平面（黄色显示）
debug(wp, {"color": "yellow"})

# 创建草图
rect = wp.rect(5, 10)

# 调试输出草图（红色显示）
debug(rect, {"color": "red"})

# 拉伸并输出最终模型
show_object(rect.extrude(2))

调试信息通常会在执行环境中以不同颜色或图层显示，帮助开发者理解建模过程。

参数化设计

CQGI支持通过外部参数控制模型，这是实现参数化设计的关键：

脚本中的参数定义

# 这些顶层变量将被识别为可调整参数
length = 10.0
width = 5.0
thickness = 2.0
has_hole = True

# 使用参数构建模型
result = cq.Workplane("XY").box(length, width, thickness)

if has_hole:
    result = result.faces(">Z").workplane().hole(1.5)

show_object(result)

参数类型系统

CQGI自动识别参数类型并提供了丰富的元数据支持：

数值类型（int/float）：可设置范围约束
布尔类型：自动转换为复选框控件
字符串：支持枚举值限制

执行环境集成

开发执行环境（如自定义CAD工具）时，可以通过以下方式集成CQGI：

基本执行流程

from cadquery import cqgi

# 解析用户脚本
script_content = open("model.py").read()
model = cqgi.parse(script_content)

# 获取脚本参数信息
parameters = model.metadata.parameters
for name, param in parameters.items():
    print(f"参数 {name}: 类型 {param.paramType}, 默认值 {param.default_value}")

# 使用自定义参数执行脚本
build_result = model.build(build_parameters={
    "length": 15.0,
    "has_hole": False
})

# 处理结果
if build_result.success:
    for i, result in enumerate(build_result.results):
        print(f"获取到模型 {i}")
else:
    print(f"执行失败: {build_result.exception}")

高级控制选项

build()方法支持多种构建选项：

build_result = model.build(
    build_parameters={"param1": "new_value"},
    build_options={
        "timeout": 30,  # 超时设置(秒)
        "tessellation_tolerance": 0.1,  # 曲面细分精度
        "angular_tolerance": 0.1  # 角度公差(弧度)
    }
)

典型应用场景

1. 自动化模型导出

import cadquery as cq
import cadquery.cqgi as cqgi

# 加载并执行脚本
model = cqgi.parse(open("parametric_design.py").read())
result = model.build()

# 导出所有结果模型
if result.success:
    for i, obj in enumerate(result.results):
        cq.exporters.export(obj.shape, f"output_{i}.step")
        print(f"成功导出模型 {i}")
else:
    print("执行错误:", result.exception)