linkcad.db

The database module provides access to LinkCAD’s in-memory drawing database. All database objects are backed by native implementations for performance.

Use the stable linkcad.v1.db namespace in scripts and plugins. The top-level linkcad.db module exposes the same current API for compatibility.

from linkcad.v1.db import (
    Drawing, Cell, Layer, Object, Shape, Polygon, Polyline,
    Arc, Ellipse, Donut, Nurbs, Text, Ref,
    Color, Property, ReadLock, WriteLock, Transaction, Unit,
    EndCap, FillRule, BooleanOperation, MergeLayerPolarityResult,
    TextStyle, TextStyleMask,
)

Classes

Drawing

The top-level container for all layout data.

from linkcad.v1.db import Drawing

dwg = Drawing("scratch")

Property / Method	Description
Drawing(name="")	Create a drawing. If name is omitted, LinkCAD assigns a unique Python drawing name
drawing.name	Drawing name
drawing.units	Database unit scale
drawing.main_cell	Get or set the main (top) cell
drawing.cell(name)	Find a cell by name; returns None if not found
drawing.layer(name)	Find a layer by name; returns None if not found
drawing.cells()	Return all cells
drawing.layers()	Return all layers
drawing.destroy_layer_by_name(name)	Delete a layer by name; returns True if it existed
drawing.rename_layer(from_name, to_name)	Rename a layer; returns True on success
drawing.boolean_layers_by_name(op, result_layer, operand_layer, maximum_error=100, minimum_facets=16)	Boolean two layers by name; result_layer is operand A and receives the result
drawing.merge_layer_polarity_group(group_name, maximum_error=100, minimum_facets=16, progress_from=0, progress_to=100)	Merge one deferred-polarity layer group
drawing.merge_all_polarity_groups(maximum_error=100, minimum_facets=16, progress_from=0, progress_to=100)	Merge every deferred-polarity layer group
drawing.destroy()	Destroy the drawing and its contents
Drawing.memory_usage()	Return native database memory usage in bytes
Drawing.locked(by_any_thread=True)	Check whether the database is locked

Layer helper methods that mutate the drawing create their own undoable transaction.

from linkcad.v1.db import BooleanOperation, Drawing, MergeLayerPolarityResult

dwg = Drawing("example")

ok = dwg.boolean_layers_by_name(
    BooleanOperation.Or,
    result_layer="metal",
    operand_layer="vias",
)

result = dwg.merge_all_polarity_groups()
if result is not MergeLayerPolarityResult.Success:
    raise RuntimeError("Polarity merge failed")

Cell

A named container of shapes and cell references.

from linkcad.v1.db import Cell

cell = Cell.create_instance(drawing, "TOP")
cell = Cell.lookup(drawing, "TOP")  # returns None if not found

Property / Method	Description
Cell.create_instance(drawing, name)	Create a new cell
Cell.lookup(drawing, name)	Find a cell by name; returns None if not found
cell.name	Cell name
cell.shapes()	Iterate shapes in this cell
cell.cell_objects()	Iterate all objects in this cell

Layer

A named layer with display properties.

Property / Method	Description
Layer.create_instance(drawing, name)	Create a new layer
Layer.lookup(drawing, name)	Find a layer by name; returns None if not found
layer.name	Layer name
layer.number	Layer number used by formats that support numeric layers
layer.datatype	Layer datatype used by formats such as GDSII
layer.visible	Whether the layer is visible
layer.color	Layer display color (Color)

Object

Base class for all objects that can live in a cell, including shapes and cell references.

Property / Method	Description
obj.layer	The layer this object belongs to, when applicable
obj.destroy()	Remove and destroy this object

Shape

Base class for geometric shapes: polygons, polylines, arcs, ellipses, donuts, NURBS, and text.

Property / Method	Description
shape.layer()	Get the shape’s Layer
shape.vertices()	Iterate vertex coordinates when the shape exposes vertices
shape.closed	True if the shape is closed
shape.area()	Signed area of the shape
shape.bounds()	Bounding box (Bounds)
shape.destroy()	Remove and destroy this shape

Polygon

A closed filled shape. Extends Shape.

Property / Method	Description
polygon.vertices()	Iterate vertices
polygon.area()	Signed area
polygon.layer()	Owning layer
polygon.destroy()	Remove and destroy

Polyline

An open or closed path with an optional width. Extends Shape.

Property / Method	Description
polyline.vertices()	Iterate vertices
polyline.width	Path width in database units
polyline.closed	True if the path is closed
polyline.layer()	Owning layer
polyline.destroy()	Remove and destroy

Arc

A circular arc. Extends Shape.

from linkcad.v1.db import Arc
from linkcad.v1.geom import Angle, Point

arc = Arc.create(
    cell,
    layer,
    center=Point(0, 0),
    radius=10_000,
    width=500,
    start_angle=Angle.from_degrees(0),
    end_angle=Angle.from_degrees(90),
)

Method	Description
Arc.create(cell, layer, center, radius, width=None, start_angle=None, end_angle=None)	Create an arc in a cell and layer
arc.center() / arc.set_center(point)	Get or set the center point
arc.radius() / arc.set_radius(radius)	Get or set radius in database units
arc.width() / arc.set_width(width)	Get or set stroke width
arc.start_angle()	Start angle as an Angle
arc.end_angle()	End angle as an Angle

Ellipse

A circular ellipse primitive. Extends Shape.

Method	Description
Ellipse.create(cell, layer, center, diameter)	Create an ellipse in a cell and layer
ellipse.center() / ellipse.set_center(point)	Get or set the center point
ellipse.diameter() / ellipse.set_diameter(diameter)	Get or set diameter in database units
ellipse.radius()	Radius, equal to diameter / 2

Donut

A ring/annulus primitive. Extends Shape.

Method	Description
Donut.create(cell, layer, center, mean_diameter, width)	Create a donut in a cell and layer
donut.center() / donut.set_center(point)	Get or set the center point
donut.mean_diameter() / donut.set_mean_diameter(diameter)	Get or set mean diameter
donut.width() / donut.set_width(width)	Get or set ring width
donut.outer_diameter() / donut.inner_diameter()	Outer and inner diameters
donut.mean_radius() / donut.outer_radius() / donut.inner_radius()	Derived radii

Nurbs

A non-uniform B-spline curve. Extends Shape.

from linkcad.v1.db import Nurbs
from linkcad.v1.geom import Point

nurbs = Nurbs.create(
    cell,
    layer,
    width=5,
    degree=3,
    knots=[0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0],
    vertices=[Point(0, 0), Point(10, 20), Point(20, 20), Point(30, 0)],
)

Method	Description
Nurbs.create(cell, layer, width, degree, knots, vertices, weights=None, periodic=False)	Create a NURBS curve; degree must be 1, 2, 3, or 5
nurbs.width() / nurbs.set_width(width)	Get or set stroke width
nurbs.degree()	Curve degree
nurbs.knots() / nurbs.knot_count()	Knot vector and count
nurbs.vertices() / nurbs.control_points()	Control points as Point objects
nurbs.control_point_count()	Number of control points
nurbs.weights()	Weight vector
nurbs.periodic() / nurbs.close(do_close=True)	Get or set periodic/closed state
nurbs.rational()	True when weights are present

Text

Formatted text geometry. Extends Shape.

from linkcad.v1.db import Text
from linkcad.v1.geom import Point

label = Text.create(
    cell,
    layer,
    content="Hello LinkCAD",
    position=Point(100, 200),
    height=12.5,
    font="simplex.shx",
)

Method	Description
Text.create(cell, layer, content, position, height=1.0, font="")	Create text in a cell and layer
text.content() / text.text()	Formatted text content
text.set_content(content) / text.set_text(content)	Set formatted text content
text.font() / text.set_font(font)	Get or set font name
text.position() / text.set_position(point)	Get or set attachment point
text.height() / text.set_height(height)	Get or set text height
text.line_spacing() / text.set_line_spacing(spacing)	Get or set line spacing
text.box_width() / text.set_box_width(width)	Get or set wrapping width
text.rotation() / text.set_rotation(angle, absolute=False)	Get or set rotation
text.width_factor() / text.set_width_factor(factor)	Get or set horizontal scaling
text.stroke_width() / text.set_stroke_width(width)	Get or set stroke width
Text.escape(content)	Escape plain text for formatted-text storage

Ref

A placed instance of another cell, with an associated transformation.

from linkcad.v1.db import Ref
from linkcad.v1.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)

Property / Method	Description
Ref.create_instance(cell, transformation, ref_cell)	Create a cell reference
ref.ref_cell	The referenced Cell
ref.transformation	Applied Transformation
ref.destroy()	Remove and destroy this reference

Color

An RGB color value attached to layers.

Property	Description
color.red	Red channel (0-255)
color.green	Green channel (0-255)
color.blue	Blue channel (0-255)

Property

A named string property attached to a database object.

Property	Description
prop.name	Property name
prop.value	Property value

Enums

Unit

Enum of database coordinate units. Returned by drawing.units.

Value	Description
Unit.Nanometer	1 nm per database unit
Unit.Micron	1 micrometer per database unit
Unit.Millimeter	1 mm per database unit
Unit.Centimeter	1 cm per database unit
Unit.Meter	1 m per database unit
Unit.Mil	1 mil (0.001 inch) per database unit
Unit.Inch	1 inch per database unit
Unit.Feet	1 foot per database unit
Unit.Picometer	1 pm per database unit
Unit.Database	Native database units

EndCap

Polyline and arc end-cap style. Also re-exported from linkcad.v1.plugin.

Value	Description
EndCap.Round	Round cap
EndCap.SquareExtended	Square cap extended past the endpoint
EndCap.SquareFlat	Square cap ending at the endpoint

FillRule

Polygon fill rule. Also re-exported from linkcad.v1.plugin for writer APIs.

Value	Description
FillRule.NonZero	Non-zero winding rule
FillRule.EvenOdd	Even-odd fill rule

BooleanOperation

Layer-level boolean operation for Drawing.boolean_layers_by_name().

Value	Description
BooleanOperation.Or	Union operand layer into result layer
BooleanOperation.AMinusB	Subtract operand layer from result layer

MergeLayerPolarityResult

Result from deferred-polarity merge helpers.

Value	Description
MergeLayerPolarityResult.Success	Merge completed successfully
MergeLayerPolarityResult.Cancelled	Merge was cancelled
MergeLayerPolarityResult.Failure	Merge failed

TextStyle and TextStyleMask

TextStyle contains bit flags for text alignment, orientation, and line spacing. TextStyleMask selects which groups of style bits are changed by DrawingBuilder.set_text_style().

Enum	Common values
TextStyle	Default, AlignHLeft, AlignHCenter, AlignHRight, AlignVBaseline, AlignVBottom, AlignVMiddle, AlignVMiddleAscent, AlignVTop, OrientH, OrientV, LineSpacingExact, LineSpacingCompact
TextStyleMask	None_, AlignH, AlignV, Orient, LineSpacing

Locking

The locking requirement depends on the execution context.

Plugin context (@tool, @format_reader, @format_writer)

The framework holds the appropriate lock before calling run(), read(), or write(). No explicit lock is needed for read operations. Write operations that should be undoable require a Transaction:

from linkcad.v1.db import Cell, Transaction

def run(self, drawing) -> None:
    for cell in drawing.cells():
        print(cell.name)

    with Transaction(drawing, "My Operation"):
        new_cell = Cell.create_instance(drawing, "RESULT")
        # Build geometry here.

Standalone scripts (linkcad --python-script)

Scripts run outside the plugin framework must acquire locks explicitly:

from linkcad.v1.db import Drawing, ReadLock, WriteLock

dwg = Drawing("scratch")

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

with WriteLock():
    for layer in list(dwg.layers()):
        if layer.name.startswith("TEMP_"):
            dwg.destroy_layer_by_name(layer.name)

ReadLock

Context manager for read-only access in standalone scripts.

from linkcad.v1.db import ReadLock

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

WriteLock

Context manager for write access in standalone scripts. Does not create an undo entry.

from linkcad.v1.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

Context manager for write access that creates a single undoable entry in the undo history. Use in tool plugins. Takes a description string shown in the Edit menu.

from linkcad.v1.db import Cell, Transaction

with Transaction(drawing, "Create Panel"):
    cell = Cell.create_instance(drawing, "PANEL")
    # Build content here.

Caution

In standalone scripts, always use ReadLock or WriteLock around every database access. In plugin run() / read() / write() methods, the framework holds a read lock — use Transaction only when you need to write.