pcb-rnd - user manual

2. Model of the world

Pcb-rnd is designed to handle the geometric data of a PCB. This section describes how pcb-rnd represents reality (e.g. copper shapes) in memory.

2.1. Board

Each design pcb-rnd handles is a board. The board has global properties and hosts layers. Most drawing primitives (objects) are on layers. This section describes the most important global properties.

Raw board size is given as a width and a height. This is the size of the preferred drawing area on screen, but for rectangular boards this can be the real board size. More often final board dimensions are specified by drawing objects drawn on boundary layer groups within this area. If the board is not rectangular, the contour must be specified on boundary layers and the board size must be large enough that the outline fits in it.

Netlist is the list of logical connections to be realized in copper. A netlist is a list of named nets. Each net consists of a list of terminals (pins or pads) to connect. A terminal is given as refdes-pinname, e.g. U4-7 means "pin number 7 in subcircuit called U4".

Fonts are normally embedded in the design file in order to guarantee that the file can be ported and will look the same on different hosts.

Configuration: misc editor settings, such as grid size and offset, plugin settings.

Route styles.

2.2. Layers

The main use of pcb-rnd is to aide the user in the process of producing real pcbs composed of real physical layers. pcb-rnd also refers to layers to conceptualize this process, but pcb-rnd layers are different than the physical layers.

Unlike a physical layer, a pcb-rnd layer has no thickness. Any pcb-rnd layer is always part of a layer group. It is a 2 dimensional logical canvas, similar to layers in image manipulation software like GIMP. In pcb-rnd there are explicit, virtual or implicit layers. An explicit layer contains drawing primitives (objects) placed by the user. The user has full control over an explicit layer: objects can be added or removed or changed any time. A virtual or implicit layer has no such flexibility: pcb-rnd computes its content from explicit layers and there's no way for the user to change the result directly.

Pcb-rnd currently maintains some layers types as virtual layers for compatibility with the PCB package. In a pcb-rnd board design started from default configuration options, the mask, silk, and paste layers currently start out as virtual layers. The content for these layers is computed by pcb-rnd as for a virtual or explicit layer, until the user decides to use features that require user control over one or more of the layers in the group. At that point, the virtual layer is replaced with an explicit layer group.

For example, in pcb-rnd when using one of the gtk GUIs, if the user right clicks on a solder mask ('mask') layer and choose an option to 'insert new layer before this one', pcb-rnd replaces the virtual mask layer with an explicit mask layer group. The mask layer group can contain one to many pcb-rnd layers each with individual settings to control implicit generation, and additive or subtractive behavior when adding objects to the layers.

In CLI (e.g. action arguments), layers are referenced using layer addressing.

2.3. Layer Groups

One or more explicit layers form a layer group. All pcb-rnd layers of a layer group will end up on the same physical layer. The visibility of layers in a layer group are toggled together. Having more than one layer in a group may be useful to:

Since layer groups donate the physical layers, a board stack-up is built of layer groups. Substrates are layer groups without drawable layers in them. The mask, paste, silk layer groups behave the same and can host zero or more logical layers.

Each layer group has a main type. Main types are:

Each layer group has a location. Locations are:

Not all combination of type and location are supported: e.g. for a boundary layer group the location is always global. The table below lists whether a combination is supported or not.

Layer Combination Support
  top bottom intern global composite
copper yes yes yes no no
silk yes yes no no yes
mask yes yes no no yes
paste yes yes no no yes
boundary no no no yes no
mech yes yes yes yes maybe
doc yes yes yes yes maybe

Note: for some layer types whether compositing is allowed depends on the subtype (purpose).

Each layer group has a purpose field, which functions as a subtype. The value is a free form text for user defined groups, but pcb-rnd recognizes (and handles specially) the following combinations:

Layer purpose combinations recongized
main type purpose special meaning
boundary uroute unplated, routed bounary: routed outline of the board
boundary proute plated, routed bounary: routed outline of the board with copper plating
mech uroute unplated, routed inner cutout: unplated slots and small inner cutouts, done with drilling or routing or punch-through
mech proute plated, routed inner cutout: plated slots and small inner cutouts, done with drilling or routing or punch-through (typical for oval/rectanglar pins)

The following combinations are conventions many footprints and boards would follow:

Layer purpose combinations recommended
main type purpose location special meaning
boundary cut (global) unplated, straight line cuts at board outline
boundary vcut (global) unplated, straight line v-cuts (or grooves) at board outline
doc assy top or bottom assembly drawing (for populating the board)
doc fab top fab instructions (for board fabrication: cuts and drills)
doc ko.courtyard top or bottom keepout: component body above (or below) the board surface (polygons)
doc ko@lt respectively keepout: nothing shall be drawn on layer type lt that intersects objects on this layer; lt is location-type, e.g. top-copper, bottom-silk, etc.
doc placement any placement helpers, e.g. where board edge should be relative to a connector
mech adhesive top or bottom adhesive (glue) pattern printed on the board to keep parts in place during reflow
mech finish.gold top or bottom gold finish (typical for copper fingers intended for slots/connectors/contacts)
mech finish.carbon top or bottom carbon finish (typical for under rubber push buttons)

Layer group attributes interpreted by pcb-rnd core:

Layer group attributes
layer group attribute name description
thickness thickness of the physical layer, given with unit (e.g. 0.2mm or 200um or 50mil)
plugin::thickness overrides the above thickness value for a specific plugin, if the plugin supports it; for example openems::thickness will use a different layer group thickness for the given layer group when exporting to openems
dielectric Relative dielectric constant, typically for substrate layer groups, Er (unitless)

In CLI (e.g. action arguments), layers groups are referenced using layer group addressing.

2.4. Basic Drawing Objects

Pcb-rnd supports a small number of basic drawing objects, from which complex objects can be build. The following figure demonstrates all basic objects:

[Arc, Line, Polygon, Pin, Via]

Objects have flags that control their behavior. The following flags are common to all objects:

Object Flags
name description
selected selected by the user ("cyan")
found found as a galvanic connection in the last connection lookup ("green")
warn offending object e.g. in a short circuit ("orange")
lock locked by the user: can't be selected, moved or changed using the basic mouse/keyboard actions (still can be copied, selected by query() and edited by propedit())

2.4.1. Line Objects

Lines are round ended straight line segments with a width and a clearance. The above image shows 3 lines connected. Lines are mainly used to construct traces. A line is always on a specific layer. The user interface allows drawing lines aligned to 90 or 45 degree axes or lines with random angle.

A line is specified by its two endpoints, width and clearance:

[Line interacting with a polygon]

A clearance is the gap between a line and the surrounding polygon in the same layer group. The gap is made only if the surrounding polygon has the "clearpoly" flag set and the line has the "clearline" flag set. If either of these flags is not set, no gap is made - or in pcb-rnd terminology, the line is joined to the polygon.

Line Object Flags
name description
clearline clears polygons with the "clearpoly" flag in the same layer group

2.4.2. Arc Objects

Arcs are round ended circular arcs with trace width and clearance. They behave like lines in all respects.

[Arc interacting with a polygon]

Although the arc is described with its center, radius, start and end angles, the user interface may offer drawing arcs by endpoints.

Arc Object Flags
name description
clearline clears polygons with the "clearpoly" flag in the same layer group

2.4.3. Polygon Objects

Polygons are solid, filled copper areas with optional holes in them. Polygon contour consists of lines - when they look curvy, its really high resolution line approximation. There are two type of holes in a polygon: explicit, user drawn holes and clearance cutouts. User drawn holes are "negative" polygons drawn manually. To keep polygons simple, if an user drawn hole touches the contour of a polygon, the hole is removed and the contour is modified; if two holes touch, they are merged into one hole.

If the polygon has the "clearpoly" flag set (default), clearance cutouts are automatically inserted around objects on the same layer group:

Overlapping or touching polygons are not automatically merged. An object with the "clearline" flag set will clear all "clearpolys" it is over - if there are multiple such polygons overlapping under the objects (on the same layer group), all such polygons get the clearance cutout.

If a polygon has the "clearpolypoly" flag set, it clears any other polygon that does not have the "clearpolypoly" flag set but has the "clearpoly" set. In other words, a "clearpolypoly" polygon behaves the same as a line/arc that has the "clearline" flag.

If a polygon is cut into multiple islands, the behavior depends on the "fullpoly" flag of the polygon. If it is not set (default), only the largest island is kept, else all islands are kept. In the "fullpoly" mode islands will have no galvanic connection (unless the user adds vias and connect them on another layer), still the program will handle all islands as a single polygon. This is risky: the program will indicate connection between polygon islands that are not really connected, only because they are part of the same polygon!

Any polygon may have its enforce_clearance set to non-zero, in which case any object that has a clearance within the given polygon by flags will make a clearance at least as large as the polygon's enforce_clearance (but larger, if the object requested larger clearance than the polygon's enforce_clearance). Note: this applies only if the object has the clearline flag and the polygon has the clearpoly flag.

Polygon Object Flags
name description
clearpoly should have clearance around objects, if the objects have the appropriate flags too
fullpoly keep all islands, not only the largest

2.4.4. Text Objects

A text object is string and a series of symbols (pcb-rnd's terminology for glyph). Symbols are built of lines and are stored in the font. Each board can have its own font, but there can be only one font per board. When the string of the text is edited, the object is rendered again so that the new string appears.

Text objects can be placed on copper and silk layers. Each text object has a scale_x, a scale_y and a scale parameter that determine its size. If scale_x is non-zero, it is the width multiplier on the neutral font width; if scale_y is non-zero, it is the height multiplier on the normal font height. When any of the two is zero, it is replaced by scale/100.

Thus scale_x=1 and scale_y=1 means symbols are rendered in 1:1 size. Alternatively scale_x=0 and scale_y=0 and scale=100 means the same.

Text has a thickness field; if it is non-zero, it specifies the stroke (line and arc) thickness of symbols (glyphs); if it is zero, the thickness value is calculated from scale.

By default, the clearance around text is rendered as a round corner rectangular cutout. If the tight_clearance attribute on the text object is specified and the value is "yes" or "true" or "1", a more accurate clearance is calculated that follows the true shape of the text object. If the clearance field of the text object is not 0, it determines the clearance (gap) to polygon in thight_clearance mode (if the clearance happens, see flags, and the value not overridden from the polygon side).

The Y coordinates of a text object are mirrored if the ONSOLDER flag is set (which means the text is mirrored over the X axis). The X coordinates of a text object are mirrored if the mirror_x attribute is true (which means the text is mirrored over the Y axis). NOTE: the point of placement (which corner is placed at the specified X;Y coordinate) depends on mirroring.

Bug: copper text can not participate in short circuits, the galvanic connection checker code skips texts.

2.4.5. Subcircuits

A subc (subcircuit) is a group of objects with its own, local layer information. All layers of a subc are bound layers, that is, the user is free to choose on which actual board layer it is placed on. There is no limitation on what layers or objects a subc can contain.

The main uses of subc are: Subcircuits as footprints

A subcircuit may be an instance (copy) of a footprint. The subcircuit is placed on the board or loaded into a paste buffer (the footprint lives in the footprint library).

In the footprint form the construct is small and flexible. It describes all the physical parts, like pins, pads, silk lines. In the same time a footprint leaves many details blank, e.g. it doesn't specify exact layers, it doesn't have font and the refdes is random.

When the footprint is loaded, it becomes a subcircuit. The subcircuit inherits all the physical properties and the blank details are filled in with the data taken from the current board: the layer binding is done, all parts of the subcircuit lands on a specific board layer; the refdes is rendered using the font in the current board.

The footprint -> subcircuit instantiation is also a copy. Once the subcircuit is created from a footprint, the subcircuit is a self-containing object and does not have any direct reference to the footprint it was once derived from. Changes to the original footprint will not affect the subcircuits.

In other words, a footprint is an abstract recipe, part of a library, while a subcircuit is a land pattern already embedded in a specific design and describes actual copper and silk.

Currently a subcircuit or footprint can contain any object on any layer that a board can contain.

Commonly used subcircuit attributes:

Subcircuit attributes
subcircuit attribute name description
refdes unique identifier, e.g. "C42" - pcb-rnd code will use this when present
value informal value, e.g. "15 pF"
footprint informal footprint description, e.g. "1206"

When a subcircuit is a footprint, it normally has the refdes attribute set. Refdes is the name that identifies the part on the netlist. Some objects of a footprint will have the term attribute to turn those object into terminals (representing pins or pads). If multiple objects have the same term attribute value, they are all contributing to the same terminal.

When the terminal object is a single padstack, it is called a light terminal. When the terminal is built using multiple objects, it is called a heavy terminal.

A connection on the netlist is identified as refdes-term, e.g. U5-3 means "the object(s) whose term attribute is 3 within the subcircuit whose refdes attribute is 'U5'".

If its nonetlist flag is set, the subcircuit is not intended to be part of the netlist; that is, it will not cause shorts and will not be removed on a forward annotation (schematics/netlist import). Subcircuits as repetitive modules

If the repetitive module is specified as a refdes-named device on the schematics, it is really just a footprint. Else it is a non-footprint subcircuit.

Compared to subcircuits as footprint, a non-footprint subcircuit will not have a refdes attribute and will not have terminals. It will also have the nonetlist flag set. Subcircuit aux layer

A subcircuit needs to have an aux layer. The name of this layer is subc-aux, with type VIRTUAL and MISC, and is on top, bottom or intern. It hosts three objects placed when the subc was first created:

These objects specify the neutral state of the subcircuit. If the subcircuit goes through any transformation (rotation, translation/move, mirroring, etc.), these objects are also transformed (just like any other object in the subc). Looking at the current state of these objects and the location flag of the aux layer, the code can work out the net result of all transformations the subc suffered since creation. Subcircuit uid

Each subcircuit has a globally unique ID generated (using libminuid) when the subcircuit is first created from scratch. The uid field is retained through copies as it is used to identify the original source of a footprint even if the footprint had minor modifications. The user shall change the uid if a substantial modification is made to a footprint.

2.4.6. Pad stacks

A pad stack is a generic pin/pad/via object that may contain any combination of:

Pad stacks are flexible enough to cover the majority of the simple pin/pad/via cases. In a subcircuit, marked as a terminal, a pad stack is called a light terminal. This concept exist in parallel to the heavy terminal concept: a heavy terminal consists of multiple objects (e.g. polygons, lines, arcs, pad stacks), all tagged to the same terminal. When the pad stack model is not capable to describe a complicated pin or pad, the user should chose the heavy terminal model. A typical example is the center pad of a QFN footprint with vias for heat transfer and a specific pattern of paste. The strength of a pad stack is it's relative simplicity and that all objects on the vertical stack are bundled together; the strength of the heavy model is its flexibility: anything that can be drawn on board can be turned into a heavy terminal.

The optional hole of the pad stack is useful if the pad stack is to be used as a mounting hole, via or pin. The span of the hole is described by two integers: how far the hole starts and ends from the top or bottom copper layer group, counted in copper layer groups.

A simple all-way-thru hole's span is 0;0, which means it starts at the top copper group and ends on the bottom copper group. Or precisely, "starts 0 groups down from top copper group and spans until 0 groups up from the bottom group". That is, when hol span values are positive, the top of the hole is counted from the top copper group down and the bottom of the hole is counted from the bottom group up. If a span value is negative, it is counted from the other side, e.g. a 0;-3 means: "hole top is 0 groups down from top copper group, hole bottom is 3 groups down from the top copper group". Or in other words, the topmost four copper layer groups are connected by the via.

The plating of the hole is a boolean and is independent of any other parameter.

For each layer group type, the user may specify zero or one pad shape.

Pad stack layer group types
name remarks
top silk  
top paste  
top mask the first negative layer is used
top copper  
intern copper the same pad will be used on all internal copper groups
bottom copper  
bottom mask the first negative layer is used
bottom paste  
bottom silk  

Pad shapes
name description
fillcircle x;y offset of the center, diameter
line round or square cap, from x1;y1 to x2;y2 with the specified thickness
simple-polygon a simple polygon has a single outer contour and no holes
hshadow n/a

Pad shape hshadow is a special construct: when drawing a clearance around the shape, it pretends to be a copy of the hole or slot shape, but it never has any visible (positive) effect on the target layer. Typical use is inner layer clearance around a via that should not have a copper ring on that layer.

The pad stack has an origin, a 0;0 point where it is grabbed. If the pad stack features a hole, the origin is the center point of the hole. Pad shapes are all defined in a way that they do not have to be concentric with the hole or the origin. This allows asymmetric pads.

In case of blind/buried vias, the internal copper layer pads are applied only on layers with hole span. However, this does not apply to top/bottom shapes, those are always explicit. This means it is possible to use a pad stack as a pad-pair of an board edge connector, having a copper pad on the top layer and one on the bottom layer, even without having a (plated) hole in between. The code will assume connection between the pads only if the pad stack has a plated hole.

If the global clearance is set, it overrides the per layer type clearance and the padstack will have the same global clearance on all layer groups on which it has copper objects.

Typical pad stack examples
name description
rectangular smd pad no hole; square cap line or polygon on top copper, top mask and top paste
simple pin or via plated hole and the same filled circle on all copper layers; if pin, a slightly bigger circle on the mask layers
octagon pin or via plated hole and the same simple polygon (octagon shaped) on all copper layers; if pin, a slightly bigger polygon on the mask layers
'oblong' pin plated hole, a short round cap line segment on the bottom copper and mask layers, filled circle on all other copper layers and on the top mask layer
blind via plated hole and the same filled circle on internal and top copper layers - nothing on the bottom copper layer
power jack with slot n/a - can not be done with pad stack as the plated slots for the pins can not be represented as plated round holes - use heavy terminals instead

Pad stack prototypes (templates) are stored only once per pcb_data_t (only once per board for vias or per each subcircuit for terminals). The actual pad stacks placed on the board (or in subcircuit) are called pad stack references. A pad stack reference has its own x;y coordinate (within the board or subcircuit), a rotation angle and a mirror flag. This means if a TQFP chip has 48 pads along 4 sides, in the simplest setup there will be onlt one pad stack prototype and 48 pad stack references using the same prototype with different coordinates and rotations.

Each padstack reference has an optional global clearance; if it is non-zero, this value is used as clearance on all layers for this instance. When it is zero, the prototype's per shape clearance applies, which makes it possible to have different clearance for internal layers, for example.

Each padstack reference has a per board layer list of thermal relief types.

A thermal relief property is added to the copper rings of a via when it is connected to the surrounding polygon of any individual layer. Physical designs may use thermal reliefs to enable easy hand soldering, or reduce occurrence of tombstoning in automated production.

The following thermal relief options are available:

Pad/Pin/Via Thermal Relief
Thermal Relief Appearance   Thermal Relief Appearance
no connection unconnected via solid solid thermal
round x 90 Thermal relief arc style round x 45 Thermal relief arc style, 45deg
crossbar x 90 Thermal relief crossbar style, 90deg crossbar x 45 Thermal relief crossbar style, 45deg

2.4.7. Rat line Objects

A rat line represents a logical connection that is not yet realized in copper. It requires a loaded netlist for generation, and relies on calculations for any existing copper layers that connect terminals on the pcb-rnd board. Rat connections are straight line connections between the terminals of any two drawing primitives that aren't yet connected

2.4.8 Gfx objects

A gfx object is a layer object that hosts a rectangular custom graphics - typically pixel graphics. The raw graphics is rectangular ans has its own size (width and height), which is scaled to the rectangular size of the gfx object, the rotated and/or mirrored as requested by the gfx object.

Gfx objects are visible only on screen and will be ignored by most export plugins. The main purpose of the gfx object is GUI enhancement - for example breadboard support.

Gfx attributes intepreted by pcb-rnd:

Gfx attributes
gfx attribute name description
render_level if value is "under", render the gfx object before (under) other objects on the same layer, else after (above) other objects on the same layer

2.4.9 Netlists

A netlist is a list of named logical networks. Each network is a list of netlist terminals that should be connected. A netlist terminal is a pair of subcircuit-refdes and pin-number (or pad-number). Thus a typical netlist looks like the following:

The netlist assumes subcircuit refdes are unique. If a subcircuit has multiple instances of the same terminal number, the engine picks one randomly and assumes there's an invisible, internal connection within the subcircuit.

Rat lines can be regenerated from the current netlist for missing connections. Connections that are realized in copper but not present on the netlist, pcb-rnd gives a "short circuit" warning. Both happens when the net is "optimized" (upon user request).

The netlist is typically derived from a schematics by external tools (such as gnetlist). The netlist can be imported (updated) any time. This process is called "forward annotation".

It is also possible to make changes to the netlist from within pcb-rnd: terminals can be swapped, subcircuit footprint replaced using back annotation actions. Such actions will keep a list of intended netlist and subcircuit changes, called the netlist patch. Pcb-rnd will keep these changes even if a new version of the netlist is imported. It is possible to export the netlist patch that can be imported in the schematics editor to change the schematics - this process is called "back annotation". A new forward annotation from the schematics editor to pcb-rnd will then cancel the netlist/subcircuit changes as the new netlist import netlist matches the intended (changed) netlist.

2.5. Non-objects

The following objects are commonly used in the industry, but have no special implementation in pcb-rnd but are created by using the above objects.


A via is an electrically connected hole that connects copper rings to multiple layers. In pcb-rnd, a via is always implemented using a padstack.


A hole is a special case of a padstack: it has an unplated hole and typically does not have copper pad shapes but should have mask cutout shape.

Test points, test pads

A test point or test pad is a padstack that has copper shape only on one of the outer copper layer and a mask cutout shape over that layer.


A fiducial mark is a special case of a padstack very similar to the test point/pad.


A mark or target (e.g. for layer alignment) is usually realized as a subcircuit it has more complex graphics that doesn't fit in a padstack.

Using subcircuit instead of raw padstack

Holes, test points/pads and fiducials are often realized within a subcircuit , especially if they have a refdes and present on the schematics. However, the only way to implement a hole is using a padstack, so the resulting subcircuit for holes and test pins will always have at least one padstack.

2.6. Comparison of Physical world and pcb-rnd world terminology

Pcb-rnd Terminology
Physical board pcb-rnd Description
Layer Layer Group enables the user to design complex physical constructions
Copper layer Layer group of type copper  
Component/Top copper layer Layer group of type copper, location top  
Solder/bottom copper layer Layer group of type copper, location bottom  
Substrate, prepreg, core Layer group marked as substrate, hosting no logical layers pcb-rnd does not yet handle properties of physical substrate information
Contour of the board Boundary layer designed using standard pcb-rnd objects
Outline routing path Boundary layer designed using standard pcb-rnd objects
Polygon pour Polygon an object available for design in any layer group
Plane Polygon see above
Mask (solder mask) Layer group with implicit and potential explicit content design layers available: automatic, additive, subtractive
Silk Layer group with implicit and potential explicit content design layers available: automatic, additive, subtractive
Paste (paste stencil) Layer group with implicit and potential explicit content design layers available: automatic, additive, subtractive
  Rats assistive layer automatically generated with netlist and copper layer group connection data
Via Padstack a vertical construction that features a plated hole and copper pads around the hole
Pin Padstack a special via that is going to host a pin of a through-hole component soldered on the board
Pad Padstack a copper feature that is going to host a lead of a surface mount component
Hole, mounting hole Padstack special case of vias, with no plating or copper pads
Fiducial mark, test pad Padstack special case of pad
Element, module, part (on board) Subcircuit a placed instance of a library footprint
Footprint, land pattern Footprint reusable patterns stored in the footprint library