CadQuery 网关接口

CadQuery 首先被设计为一个库，可以用作任何项目的一部分。在这种情况下，不需要标准脚本格式或网关 API。

虽然嵌入式使用案例最为常见，但也有一些工具可以代表用户运行 cadquery 脚本，然后以可视化方式呈现脚本结果。

这些执行环境 (EE) 通常接受脚本和用户输入的脚本参数值，然后以可视方式向用户显示生成的对象。

目前，存在三种执行环境：

• CQ-editor，它在 CadQuery IDE 内运行脚本，并在显示窗口中显示对象，还包括调试等功能。

• cq-directive，用于在 sphinx-doc 内执行脚本，生成的文档示例包括脚本和结果对象的 SVG 表示。。

CQGI 随 CadQuery 一起发布，它规范了执行环境与 CadQuery 脚本之间的接口。

脚本方面

CQGI 容器为脚本提供执行环境。环境包括：

• cadquery 库会自动导入为 "cq"。

• cadquery.cqgi.ScriptCallback.show_object()方法用于将形状输出到执行环境中

• cadquery.cqgi.ScriptCallBack.debug()可以使用该方法在执行期间调试模型输出。

脚本必须至少调用一次 show_object。多次调用 show_object 会向容器发送多个对象。如果脚本没有使用 show_object() 方法返回对象，则会发生错误。

该脚本符合 CQGI 标准，可生成一个顶部有圆的立方体，并显示工作平面和中间圆作为调试输出：

base_cube = cq.Workplane("XY").rect(1.0, 1.0).extrude(1.0)
top_of_cube_plane = base_cube.faces(">Z").workplane()
debug(
    top_of_cube_plane,
    {
        "color": "yellow",
    },
)
debug(top_of_cube_plane.center, {"color": "blue"})

circle = top_of_cube_plane.circle(0.5)
debug(circle, {"color": "red"})

show_object(circle.extrude(1.0))

注意：debug 暂时不支持选项参数

请注意，不需要导入 cadquery。本脚本结束时，除了一个工作平面、一个点和一个圆之外，还将显示一个对象

未来的增强功能将包括其他几种方法，用于为执行环境提供更多元数据：

• cadquery.cqgi.ScriptCallback.add_error(), 表示输入参数有错误

• cadquery.cqgi.ScriptCallback.describe_parameter()，提供有关脚本中参数的额外信息，

执行环境端

CQGI 可以轻松地以标准方式运行 cadquery 脚本。要从执行环境运行脚本，请运行如下代码：

from cadquery import cqgi

user_script = ...
build_result = cqgi.parse(user_script).build()

该cadquery.cqgi.parse()方法返回一个cadquery.cqgi.CQModel对象。

该对象的 metadata 属性包含一个cadquery.cqgi.ScriptMetaData对象，可用于发现可用的用户参数。如果执行环境想要提供 GUI 以允许用户更改模型参数，则这非常有用。通常情况下，在收集新值后，环境将在 build() 方法中提供这些值。

此代码将返回模型文本 SCRIPT的参数值字典：
parameters = cqgi.parse(SCRIPT).metadata.parameters

返回的字典是一个映射，其中 key 是参数名称，value 是一个 InputParameter 对象，该对象有名称、类型和默认值。

类型是一个扩展了 ParameterType 的对象，您可以用它来确定要渲染哪种 widget（例如，布尔型的复选框）。

如果用户使用 describe_parameter() 方法提供了参数描述、有效值、最小值和最大值，那么参数对象也有这些描述、有效值、最小值和最大值。

调用cadquery.cqgi.CQModel.build()返回一个cadquery.cqgi.BuildResult对象，其中包括脚本执行时间和成功标志。

如果脚本运行成功，结果属性将包括脚本返回的结果列表，以及脚本产生的所有调试信息

如果脚本运行失败，异常属性中将包含异常对象。

如果有办法从用户那里获取输入，就可以用新的值覆盖用户脚本中定义的任何常量：

from cadquery import cqgi

user_script = ...
build_result = cqgi.parse(user_script).build(
    build_parameters={"param": 2}, build_options={}
)

如果模型中定义了一个名为 "param "的参数，那么在脚本运行前，它将被赋值为 2。如果提供的值未在模型中定义，或提供的值无法分配给给定名称的变量，则会发生错误。

build_options 用于设置服务器端设置，例如超时、细分容差以及有关如何构建模型的其他详细信息。

有关脚本变量的更多信息

CQGI 使用以下规则来查找脚本的输入变量：

• 仅考虑顶层语句

• 仅考虑将常量值分配给本地名称。

例如，在以下脚本中：

h = 1.0
w = 2.0
foo = "bar"


def some_function():
    x = 1

h、w 和 foo 将是可重写的脚本变量，但 x 不是。

您可以使用 parse 方法的返回值列出模型中定义的变量：

model = cqgi.parse(user_script)

# a dictionary of InputParameter objects
parameters = model.metadata.parameters

字典的键是一个 string ，值是一个cadquery.cqgi.InputParameter对象 有关更多详细信息，请参阅 CQGI API 文档。

未来的增强功能将包括更安全的沙箱以防止恶意脚本。

自动导出到 STL

CQGI 的一个常见用例是将 cadquery 代码自动处理为几何图形，通过 CQGI 而不是脚本本身中的导出行来执行此操作会导致更加整洁的环境；您可能需要将其作为自动化工作流程、批量转换、导出到另一个软件进行装配或在生成的实体上运行应力模拟的一部分。

以下 Python 脚本演示了如何从任何有效的 cadquery 脚本打开、处理和导出 STL 文件：

# Load CQGI
import cadquery.cqgi as cqgi
import cadquery as cq

# load the cadquery script
model = cqgi.parse(open("example.py").read())

# run the script and store the result (from the show_object call in the script)
build_result = model.build()

# test to ensure the process worked.
if build_result.success:
    # loop through all the shapes returned and export to STL
    for i, result in enumerate(build_result.results):
        cq.exporters.export(result.shape, f"example_output{i}.stl")
else:
    print(f"BUILD FAILED: {build_result.exception}")

重要的 CQGI 方法

这些是 CQGI 最重要的方法和类

完整的 CQGI API

CadQuery 网关接口。提供用于执行 CadQuery 脚本的类和工具

执行 CadQuery 脚本的结果。success 属性包含执行是否成功。

如果成功，结果属性将包含所有结果的列表，而 first_result 属性则包含第一个结果。

如果不成功，异常属性将包含对发生的堆栈跟踪的引用。

构建完成后，元数据属性包含一个 ScriptMetaData 对象，该对象更详细地描述了模型，可用于检索模型定义的参数。

构建方法可用于生成 3D 模型

执行脚本，使用可选参数覆盖模型中的参数

Parameters

• build_parameters – 变量字典。变量必须可分配给基础变量类型。这些变量会覆盖脚本中的默认值

• build_options – 有关如何构建模型的构建选项。构建选项包括超时、曲面细分容差等

Raises
无异常。如果出现异常，则会出现在结果的异常属性中。有了这个接口，我们就可以返回结果的其他信息，例如构建时间

Returns
一个 BuildResult 对象，其中包括结果的状态，以及结果形状或异常情况

• params – 参数字典

为 cadquery 脚本构建执行环境。该环境包括内置方法以及脚本需要的其他方法。

定义模型执行时可提供的参数。

Name、varType 和 default_value 始终可用，因为它们是通过变量赋值代码行计算得出的：

当试图提供一个无法分配给模型的新参数值时发生该故障

当脚本未执行 show_object()方法返回实体时发生该错误。

Parameters

• shape – 查询对象

• options – 将提供给执行环境的选项字典

如果您希望在不构建模型的情况下访问底层模型，例如检查其可用参数，请构建一个 CQModel 对象。

Parameters

• script_source – 要运行的脚本。必须是有效的 cadquery 脚本

Returns
定义脚本并允许执行的 CQModel 对象