linkcad.db

数据库模块提供对 LinkCAD 内存中图纸数据库的访问。所有数据库对象都由 C++ 实现提供后端，以保证性能。

from linkcad.db import (
    Drawing, Cell, Layer, Object, Shape, Polygon, Polyline,
    Ref, Color, Property, ReadLock, WriteLock, Transaction, Unit
)

类

Drawing

所有版图数据的顶层容器。

from linkcad.db import Drawing

dwg = Drawing.current()  # Get the active drawing

属性 / 方法	说明
`Drawing.current()`	类方法——获取当前活动图纸实例
`drawing.name`	图纸名称（只读）
`drawing.units`	数据库单位——一个 `Unit` 枚举值（只读）
`drawing.main_cell`	获取或设置主（顶层）单元
`drawing.cells()`	迭代所有单元
`drawing.layers()`	迭代所有图层
`drawing.delete_layer(layer)`	删除图层

Cell

形状和单元引用的命名容器。

from linkcad.db import Cell

# Create
cell = Cell.create_instance(drawing, "MY_CELL")

# Look up
cell = Cell.lookup(drawing, "MY_CELL")  # returns None if not found

属性 / 方法	说明
`Cell.create_instance(drawing, name)`	类方法——创建新单元
`Cell.lookup(drawing, name)`	类方法——按名称查找单元；未找到时返回 `None`
`cell.name`	单元名称（只读）
`cell.shapes()`	迭代此单元中的形状
`cell.cell_objects()`	迭代此单元中的所有对象（形状 + 引用）

Layer

带显示属性的命名图层。

属性 / 方法	说明
`layer.name`	图层名称
`layer.number`	图层编号（由 GDSII 使用）
`layer.datatype`	图层数据类型（由 GDSII 使用）
`layer.visible`	图层是否可见
`layer.color`	图层显示颜色（`Color`）

Object

所有可存在于单元中的对象（形状、单元引用等）的基类。

属性 / 方法	说明
`obj.layer`	此对象所属的图层（对于引用可能为 `None`）
`obj.destroy()`	移除并销毁此对象

Shape

几何形状（多边形、折线以及圆等细分基元）的基类。

属性 / 方法	说明
`shape.layer()`	获取形状的 `Layer`
`shape.vertices()`	以 `(x, y)` 元组迭代顶点坐标
`shape.closed`	如果形状闭合（类似多边形），则为 `True`
`shape.area()`	形状的有符号面积
`shape.bounds()`	边界框（`Bounds`）
`shape.destroy()`	移除并销毁此形状

Polygon

闭合的填充形状。扩展 Shape。

from linkcad.db import Polygon

属性 / 方法	说明
`polygon.vertices()`	以 `(x, y)` 元组迭代顶点
`polygon.area()`	有符号面积
`polygon.layer()`	所属图层
`polygon.destroy()`	移除并销毁

Polyline

带可选宽度的开放或闭合路径。扩展 Shape。

from linkcad.db import Polyline

属性 / 方法	说明
`polyline.vertices()`	以 `(x, y)` 元组迭代顶点
`polyline.width`	以数据库单位表示的路径宽度
`polyline.closed`	如果路径闭合，则为 `True`
`polyline.layer()`	所属图层
`polyline.destroy()`	移除并销毁

Ref

另一个单元的放置实例，带有关联的变换。

from linkcad.db import Ref
from linkcad.geom import Transformation

xform = Transformation()
xform.rotate(45.0)
xform.translate(1000, 2000)
Ref.create_instance(cell=parent_cell, transformation=xform, ref_cell=child_cell)

属性 / 方法	说明
`Ref.create_instance(cell, transformation, ref_cell)`	类方法——创建单元引用
`ref.ref_cell`	被引用的 `Cell`
`ref.transformation`	已应用的 `Transformation`
`ref.destroy()`	移除并销毁此引用

Color

附加到图层的 RGB 颜色值。

属性	说明
`color.red`	红色通道（0–255）
`color.green`	绿色通道（0–255）
`color.blue`	蓝色通道（0–255）

Property

附加到数据库对象的命名字符串属性。

属性	说明
`prop.name`	属性名称
`prop.value`	属性值

Unit

数据库坐标单位的枚举。由 drawing.units 返回。

值	说明
`Unit.Nanometer`	每个数据库单位为 1 nm
`Unit.Micrometer`	每个数据库单位为 1 µm
`Unit.Millimeter`	每个数据库单位为 1 mm
`Unit.Centimeter`	每个数据库单位为 1 cm
`Unit.Meter`	每个数据库单位为 1 m
`Unit.Mil`	每个数据库单位为 1 mil（0.001 inch）
`Unit.Inch`	每个数据库单位为 1 inch

锁定

锁定要求取决于执行上下文。

插件上下文（`@tool`、`@format_reader`、`@format_writer`）

框架会在调用 run()、read() 或 write() 之前持有相应的锁。读取操作不需要显式加锁。 应可撤销的写入操作需要使用 Transaction：

from linkcad.db import Cell, Ref, Transaction
from linkcad.geom import Transformation

def run(self, drawing) -> None:
    # Read access — no lock needed
    for cell in drawing.cells():
        print(cell.name)

    # Write access — wrap in Transaction for undo support
    with Transaction(drawing, "My Operation"):
        new_cell = Cell.create_instance(drawing, "RESULT")
        # ... build geometry ...
        # auto-commits on exit; rolls back on exception

独立脚本（`linkcad --python-script`）

在插件框架之外运行的脚本必须显式获取锁：

from linkcad.db import Drawing, ReadLock, WriteLock

dwg = Drawing.current()

# Read access
with ReadLock():
    for cell in dwg.cells():
        print(cell.name)

# Write access (no undo support)
with WriteLock():
    for layer in list(dwg.layers()):
        if layer.name.startswith("TEMP_"):
            dwg.delete_layer(layer)

ReadLock

用于独立脚本中只读访问的上下文管理器。

from linkcad.db import ReadLock

with ReadLock():
    main = dwg.main_cell
    for shape in main.shapes():
        print(shape.bounds())

WriteLock

用于独立脚本中写访问的上下文管理器。不会创建撤销条目。

from linkcad.db import WriteLock

with WriteLock():
    for cell in dwg.cells():
        for obj in list(cell.cell_objects()):
            if obj.layer and obj.layer.name == "SCRATCH":
                obj.destroy()

Transaction

用于写访问的上下文管理器，会在撤销历史中创建单个可撤销条目。请在工具插件中使用。接受一个显示在 Edit 菜单中的描述字符串。

from linkcad.db import Transaction

with Transaction(drawing, "Create Panel"):
    cell = Cell.create_instance(drawing, "PANEL")
    # ... build content ...
    # auto-commits on clean exit; rolls back on exception