Format Decorators

The @format_reader() and @format_writer() decorators register classes as custom import/export formats in LinkCAD.

@format_reader()

Signature

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

Parameters

Parameter	Type	Default	Description
name	str	required	Format display name
extensions	list[str]	required	File patterns (e.g. ["*.gds", "*.gdsii"])
description	str	""	Format description

FormatReader Base Class

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

The DrawingContext provides a builder API for constructing the drawing:

def read(self, path: Path, drawing: DrawingContext) -> None:
    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)

---

@format_writer()

Signature

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

Parameters

Parameter	Type	Default	Description
name	str	required	Format display name
extensions	list[str]	required	File patterns
description	str	""	Format description

FormatWriter Base Class

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

The WriterContext provides read access to the drawing:

def write(self, path: Path, drawing: WriterContext) -> None:
    with open(path, "w") as f:
        for shape in drawing.shapes():
            f.write(f"{shape.layer_name}: {len(shape.vertices)} vertices\n")

---

FormatInfo

Both decorators create a FormatInfo object attached to the class:

Field	Description
name	Format display name
extensions	List of file patterns
description	Format description

---

Registration

Registered formats automatically appear in LinkCAD's Open/Save dialogs:

• Readers are listed in the File → Open format dropdown
• Writers are listed in the File → Save As format dropdown

The extensions list determines file type association. For example:

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

This adds "My Format (.myf, .myfx)" to the Open dialog.