linkcad.libgraph

用于多边形运算的高性能布尔几何引擎。它封装了原生 libgraph 库。

from linkcad.v1.libgraph import (
    ShapeProcessor, ShapeGroup, Operation, FillRule, HolesMode, Result,
    boolean_and, boolean_or, boolean_xor, boolean_difference,
    succeeded, failed,
)

便捷函数

对于简单的双多边形运算，可直接使用这些函数。每个函数都接受以 (x, y) 元组序列表示的顶点列表，并返回结果多边形列表（每个元素是 (x, y) 元组的列表）。运算失败时抛出 RuntimeError。

from linkcad.v1.libgraph import boolean_and, boolean_or, boolean_xor, boolean_difference

square   = [(0, 0), (10, 0), (10, 10), (0, 10)]
triangle = [(5, 5), (15, 5), (10, 15)]

result = boolean_and(square, triangle)          # intersection
result = boolean_or(square, triangle)           # union
result = boolean_xor(square, triangle)          # exclusive OR
result = boolean_difference(square, triangle)   # square minus triangle

函数	说明
`boolean_and(vtx1, vtx2, fill_rule=FillRule.EvenOdd)`	两个多边形的交集
`boolean_or(vtx1, vtx2, fill_rule=FillRule.EvenOdd)`	两个多边形的并集
`boolean_xor(vtx1, vtx2, fill_rule=FillRule.EvenOdd)`	两个多边形的对称差
`boolean_difference(vtx1, vtx2, fill_rule=FillRule.EvenOdd)`	差集——在 `vtx1` 中但不在 `vtx2` 中的区域

坐标为整数。如果你的几何图形已经是数据库单位，那就已经满足要求。

ShapeProcessor

对于多多边形运算，或需要控制填充规则和孔处理方式时，请使用 ShapeProcessor：

from linkcad.v1.libgraph import (
    FillRule, HolesMode, Operation, ShapeGroup, ShapeProcessor, succeeded,
)

sp = ShapeProcessor()
sp.add_polygon(ShapeGroup.A, [(0, 0), (10, 0), (10, 10), (0, 10)])
sp.add_polygon(ShapeGroup.B, [(5, 5), (15, 5), (10, 15)])

result = sp.execute(Operation.And, FillRule.NonZero, HolesMode.Link)
if not succeeded(result):
    raise RuntimeError(f"Boolean failed: {result}")

polygons = []
while sp.has_next_polygon():
    poly = sp.get_next_polygon()
    if poly is None:
        break
    polygons.append(poly)

属性 / 方法	说明
`ShapeProcessor(granularity=1)`	创建新的处理器
`sp.add_polygon(group, vertices, combine_with_previous=False)`	向组 A、B 或 AB 添加多边形。返回内部形状 ID
`sp.execute(operation, fill_mode=FillRule.NonZero, hole_mode=HolesMode.Link, process_vertically=False)`	执行运算；返回一个 `Result`
`sp.has_next_polygon()`	是否还有结果多边形
`sp.get_next_polygon()`	下一个结果多边形；取尽时返回 `None`
`sp.get_next_hole()`	当前多边形的下一个孔，或 `None`。仅在 `HolesMode.Extract` 下有意义
`sp.clear()`	丢弃所有多边形并为复用做准备
`sp.empty`	处理器中没有多边形时为 `True`
`sp.set_license(license)`	设置许可密钥；有效时返回 `True`

execute() 返回一个 Result；没有 sp.result 属性。请用模块级辅助函数判断：

函数	说明
`succeeded(result)`	结果为 `SuccessModified` 或 `SuccessNotModified` 时为 `True`
`failed(result)`	任何错误结果均为 `True`

在 add_polygon() 上设置 combine_with_previous=True，可把一条子路径——一个孔，或第二条轮廓——附加到紧邻其前添加的多边形上。

枚举

ShapeGroup

决定多边形属于哪个操作数。

值	说明
`ShapeGroup.A`	第一个操作数
`ShapeGroup.B`	第二个操作数
`ShapeGroup.AB`	同时属于两个操作数

Operation

要执行的布尔运算。

值	说明
`Operation.Or`	并集（A ∪ B）
`Operation.And`	交集（A ∩ B）
`Operation.Xor`	对称差（A △ B）
`Operation.AMinusB`	差集（A − B）
`Operation.BMinusA`	差集（B − A）
`Operation.SplitOnB`	沿 B 的边界分割 A 中的多边形
`Operation.Noop`	简化 A 中的多边形而不做合并
`Operation.KeepInternalEdges`	求并集但保留内部边
`Operation.OrNoMerge`	不合并内部边的并集
`Operation.AndNoMerge`	不合并内部边的交集
`Operation.XorNoMerge`	不合并内部边的 XOR
`Operation.AMinusBNoMerge`	不合并内部边的 A − B
`Operation.BMinusANoMerge`	不合并内部边的 B − A

FillRule

控制重叠的多边形边如何判定“内部”与“外部”。

值	说明
`FillRule.NonZero`	非零环绕规则
`FillRule.EvenOdd`	奇偶规则（最快）
`FillRule.NonZeroGroup`	按组应用的非零环绕规则
`FillRule.EvenOddGroup`	按组应用的奇偶规则
`FillRule.OuterGroup`	只填充最外层区域

HolesMode

控制输出多边形中孔的表示方式。

值	说明
`HolesMode.Extract`	通过 `get_next_hole()` 单独返回孔
`HolesMode.Link`	用零宽桥接把孔连到外轮廓
`HolesMode.Split`	把结果拆成没有孔的简单多边形
`HolesMode.Keep`	把孔保留为独立多边形

Result

ShapeProcessor.execute() 返回的状态。

值	说明
`Result.SuccessModified`	成功；几何图形发生了变化
`Result.SuccessNotModified`	成功；几何图形本已是所要求的形式
`Result.Failed`	运算失败
`Result.Cancelled`	运算被取消
`Result.NoLicense`	许可密钥无效
`Result.InvalidFillRule`	该运算不支持此填充规则
`Result.InvalidHolesMode`	该运算不支持此孔模式