格式装饰器

@format_reader() 和 @format_writer() 装饰器把类注册为 LinkCAD 中的自定义导入/导出格式。

@format_reader()

签名

@format_reader(
    name: str,
    extensions: list[str],
    description: str = "",
)
class MyReader(FormatReader):
    def read(self, path: Path, drawing: DrawingContext) -> None:
        ...

参数

参数	类型	默认值	说明
`name`	`str`	必填	格式显示名称
`extensions`	`list[str]`	必填	文件模式（例如 `[".gds", ".gdsii"]`）
`description`	`str`	`""`	格式描述

FormatReader 基类

class FormatReader:
    def read(self, path: Path, drawing: DrawingContext) -> None:
        """Override to implement file import logic."""
        ...

    def post_process(self, phase, drawing, resolution) -> bool:
        """Optional. Take part in the phases LinkCAD runs after parsing."""
        return True

DrawingContext 提供用于构建图纸的构建器 API。只需声明一次工作单位，LinkCAD 就会转换你传入的一切——读取器不应自带缩放表：

def read(self, path: Path, drawing: DrawingContext) -> None:
    drawing.units = "um"                # coordinates below are microns
    with drawing.cell("main", main=True) as cell:
        with cell.layer("metal1") as layer:
            layer.polygon([(0, 0), (100, 0), (100, 100), (0, 100)])
            layer.polyline(10, [(0, 0), (200, 200)], closed=False)
            layer.circle((500, 500), 200)

可接受的单位有 nm、um、mil、mm、cm、inch 和 m，以及 micron、millimetre 等别名。不设置 units 时使用原始数据库单位。名称未知，或图纸未声明其数据库单位时，会抛出 ValidationError。

post_process()

post_process() 是可选的——与内置原生读取器使用的钩子相同。它在解析之后按阶段各调用一次，运行在与 read() 相同的实例上，因此在那里记录的内容仍然可用。返回 False 会中止导入。

from linkcad.v1.plugin import Phase

class MyReader(FormatReader):
    def post_process(self, phase, drawing, resolution) -> bool:
        if phase == Phase.ResolvedRefs:
            ...            # every reference now points at a real cell
        return True

阶段	到达时机
`Phase.ParsedFile`	一个输入文件解析完成
`Phase.ParsedAll`	所有输入文件解析完成
`Phase.ClosedOpenCells`	解析器留下的未关闭单元已被关闭
`Phase.ResolvedRefs`	每个引用都指向真实存在的单元
`Phase.SelectedMainCell`	主单元已选定
`Phase.ResolvedLayersByBlock`	`ByBlock` 图层继承已解析
`Phase.AutoNumberedZ`	图层 Z 顺序已分配

@format_writer()

签名

@format_writer(
    name: str,
    extensions: list[str],
    description: str = "",
)
class MyWriter(FormatWriter):
    def write(self, path: Path, drawing: WriterContext) -> None:
        ...

参数

参数	类型	默认值	说明
`name`	`str`	必填	格式显示名称
`extensions`	`list[str]`	必填	文件模式
`description`	`str`	`""`	格式描述

FormatWriter 基类

class FormatWriter:
    def write(self, path: Path, drawing: WriterContext) -> None:
        """Override to implement file export logic."""
        ...

WriterContext 提供对图纸的读取访问。与读取器一样，声明工作单位之后，几何图形到达时已完成换算：

def write(self, path: Path, drawing: WriterContext) -> None:
    drawing.units = "mm"                # coordinates below are millimetres
    drawing.flatten = True              # resolve cell references into placed shapes
    with open(path, "w") as f:
        for shape in drawing.shapes():
            f.write(f"{shape.layer_name}: {len(shape.vertices)} vertices\n")

shapes() 是遍历几何图形的唯一入口。请在迭代前设置 flatten：flatten = False 时你得到每个单元自身的形状并自行处理引用；flatten = True 时宿主渲染层次结构、应用变换栈并沿途细分曲线。

FormatInfo

两个装饰器都会在类上附加一个 FormatInfo 对象，并把 info() 替换为返回该对象的静态方法：

字段	说明
`name`	格式显示名称
`extensions`	文件模式列表
`description`	格式描述
`options`	从类中收集到的 `Option` 属性

注册

已注册的格式会自动出现在 LinkCAD 的“打开/保存”对话框中：

读取器出现在 File → Open 的格式下拉列表中
写入器出现在 File → Save As 的格式下拉列表中

extensions 列表决定文件类型关联。例如：

@format_reader(name="My Format", extensions=["*.myf", "*.myfx"])

这会把“My Format (*.myf, *.myfx)”添加到“打开”对话框中。