Python Scripting

LinkCAD includes an embedded Python interpreter for custom automation, tool development, and format plugin creation. Python scripts can access the drawing database, geometry API, and the linkcad.v1 plugin framework.

Features

• Custom Tools — create menu items that process drawing geometry
• Format Plugins — add import/export formats with FormatReader, FormatWriter, DrawingBuilder, and WriterController
• Interactive Console — explore and manipulate drawings live
• Script Editor — write and run scripts from within LinkCAD

The Python API remains in the stable linkcad.v1 namespace. Current format-plugin and database additions are part of v1; there is no v2 migration path to apply. The package also ships type stubs, so an editor gives you completion and type checking for linkcad.* out of the box — see Setup & Requirements.

Getting Started

1. Setup & Requirements — Python environment and prerequisites
2. Your First Script — “Hello World” in the Python console
3. Writing a Tool Plugin — create a menu-integrated tool
4. Writing a Format Plugin — add a new file format
5. Panel Assembly Tutorial — complete real-world example

API Reference

• Option Types — integer, real, boolean, string, choice, path, color, table, cell_choice
• Tool Decorator — @tool() decorator and Tool base class
• Format Decorators — @format_reader(), @format_writer(), and base classes
• API Modules — all modules: linkcad.v1.plugin, linkcad.v1.db, linkcad.v1.geom, linkcad.v1.edit, linkcad.v1.env, linkcad.v1.conv, linkcad.v1.libgraph, linkcad.v1.controller

Quick Example

A simple tool that counts shapes per layer:

from collections import Counter

from linkcad.v1.plugin import tool, Tool

@tool(
    name="Layer Statistics",
    menu="Tools/Analysis",
    tooltip="Count shapes per layer",
)
class LayerStats(Tool):
    def run(self, drawing) -> dict:
        counts = Counter(
            shape.layer.name
            for cell in drawing.cells
            for shape in cell.shapes
            if shape.layer is not None
        )
        return {
            "layers": dict(counts),
            "summary": f"{len(counts)} layers, {sum(counts.values())} shapes",
        }

drawing.cells and cell.shapes are properties, not methods. Throughout the API a noun is a property and a verb is a method, a getter/setter pair is one read-write property, and geometry is created by the object that will own it — drawing.add_cell(name), cell.add_polygon(layer, vertices).

linkcad and linkcad.v1 publish the API’s modules, not their contents, so import the module you need: from linkcad.v1 import db, then db.Drawing.