Skip to content

Gerber code generation

Overview

This section describes how to generate Gerber code with use of the pygerber.builder.gerber module.

All of the code building functionality is provided within GerberX3Builder class available in that module.

For reference of tools available in that module check out this reference page.

Creating pads

To generate Gerber code first you have to create an instance of GerberX3Builder class. Then you can use PadCreator object returned by new_pad() method to create a pad brush / pad template (in Gerber format it is called aperture) describing the shape of the pad. You can choose one of the predefined shapes (circle, rectangle, rounded_rectangle , polygon) or create a custom shape composed from predefined elements (with custom() method). To add actual pad to a image you have to pass Pad object, representing pad brush, to the add_pad() method you can add actual pads to the image.

Info

You can use same Pad object to create multiple pads in the image. To do that, simply pass it to multiple add_pad() calls.

In a example below, we create a circle aperture with new_pad().circle() call chain. It returns a Pad object which we will store in a variable d10. Then we can pass this variable to add_pad() method to add two pads to the image, first at location (1, 1), second at (2, 1).

example.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from pygerber.builder.gerber import GerberX3Builder


builder = GerberX3Builder()

d10 = builder.new_pad().circle(diameter=0.5)
builder.add_pad(d10, (1, 1))
builder.add_pad(d10, (2, 1))

code = builder.get_code()
print(code.dumps())
$ python example.py
%FSLAX46Y46*%
%MOMM*%
%ADD10C,0.5*%
G75*
D10*
X1000000Y1000000D03*
X2000000Y1000000D03*
M02*

Gerber code generated with the example above results in following image when rendered with PyGerber:

Embedded Image

Warning

Do not use Pad objects created with one instance of GerberX3Builder with another instance of GerberX3Builder. This will result in an error or invalid Gerber code being generated.

For full reference of shapes available in PadCreator check out this reference page.

Adding traces

GerberX3Builder class also provides means to add traces to the Gerber image. You can use new_trace() and add_clockwise_arc_trace() methods to do that. Fist one creates a straight lines, second one creates arcs. You don't need to create pads to add traces, but you have to provide width of the trace as first argument.

Info

New trace can, but doesn't have to be connected to previous trace or pad (differently than in Gerber format, there you have to explicitly change starting point of consecutive disconnected trace). It is recommended however that, if you have a series of traces that are starting from the end of previous trace, you should create them directly one after another, instead of jumping. This will result in smaller Gerber files.

example.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from pygerber.builder.gerber import GerberX3Builder


builder = GerberX3Builder()

d10 = builder.new_pad().circle(diameter=0.5)
builder.add_pad(d10, (2, 1))
builder.add_line_trace(0.1, (0, 0), (0, 1))
builder.add_line_trace(0.1, (0, 1), (2, 1))

code = builder.get_code()
print(code.dumps())
$ python example.py
%FSLAX46Y46*%
%MOMM*%
%ADD10C,0.5*%
%ADD11C,0.1*%
G75*
D10*
X2000000Y1000000D03*
D11*
G01*
X0Y0D02*
X0Y1000000D01*
X2000000Y1000000D01*
M02*

Gerber code generated with the example above results in following image when rendered with PyGerber:

Embedded Image

Using objects as locations

Commands creating graphical elements, like add_pad() or add_line_trace() return special Draw objects (PadDraw or TraceDraw respectively) which can be used as locations for new_pad() or new_trace() method calls. This way you don not have to retype coordinates for draws which are connected to previous objects.

Warning

When passing TraceDraw to new_trace() method, when you pass a trace as first parameter (begin) its end location will be used, but when you pass it as second parameter (end), its begin location will be used. So passing TraceDraw as both parameters will result in a trace going opposite direction than the original trace.

This is helpful when starting a new trace from the end of the previous trace or connecting it to the end of existing trace, but can be confusing when you want to connect traces in different way.

example.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
from pygerber.builder.gerber import GerberX3Builder


builder = GerberX3Builder()

d10 = builder.new_pad().circle(diameter=0.5)

pad_0 = builder.add_pad(d10, (0, 0))
pad_1 = builder.add_pad(d10, (2, 1))

trace_0 = builder.add_line_trace(0.1, pad_0, (0, 1))
builder.add_line_trace(0.1, trace_0, pad_1)


code = builder.get_code()
print(code.dumps())
$ python example.py
%FSLAX46Y46*%
%MOMM*%
%ADD10C,0.5*%
%ADD11C,0.1*%
G75*
D10*
X0Y0D03*
X2000000Y1000000D03*
D11*
G01*
X0Y0D02*
X0Y1000000D01*
X2000000Y1000000D01*
M02*

Gerber code generated with the example above results in following image when rendered with PyGerber:

Embedded Image

Creating custom pads

You can create custom pads shapes by using custom() method of PadCreator returned by new_pad() method. Custom pads are composed of predefined shapes added to pad with use of methods available on CustomPadCreator returned by custom(). Method calls can (and should) be chained. When you are done adding elements to the pad, you should call create() method to finish the modification of custom pad and create concrete object representing it. After calling create(), you cannot and new elements to that custom pad.

Warning

Coordinates used during creation are local (relative to (0, 0) point of pad canvas), not global. During custom pad creation elements added to the pad are not placed in global image space. They are added to image (canvas) dedicated for that pad. When pad is added to the main image with add_pad() (0, 0) point of that "canvas" is placed at the location where the pad is added. All the pad elements are translated relatively to that point.

Tip

You can add cutouts in different shapes to the custom pad by using cut_* methods. Those cutouts are made locally to the pad, but they will not create cutouts in the main image after adding the pad to it (they will not remove content below the pad), they will simply be transparent.

Custom pad is used in the same way as any other pad, to add it to the image you should use add_pad() method.

custom_pad_example.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
from pygerber.builder.gerber import GerberX3Builder


builder = GerberX3Builder()

d10 = (
    builder.new_pad()
    .custom()
    # Top right corner
    .add_vector_line(0.1, (0.5, 1.5), (1.5, 1.5))
    .add_vector_line(0.1, (1.5, 1.5), (1.5, 0.5))
    .add_circle(0.1, (1.5, 1.5))  # Corner
    # Bottom right corner
    .add_vector_line(0.1, (0.5, -1.5), (1.5, -1.5))
    .add_vector_line(0.1, (1.5, -1.5), (1.5, -0.5))
    .add_circle(0.1, (1.5, -1.5))  # Corner
    # Bottom left corner
    .add_vector_line(0.1, (-0.5, -1.5), (-1.5, -1.5))
    .add_vector_line(0.1, (-1.5, -1.5), (-1.5, -0.5))
    .add_circle(0.1, (-1.5, -1.5))
    # Top left corner
    .add_vector_line(0.1, (-0.5, 1.5), (-1.5, 1.5))
    .add_vector_line(0.1, (-1.5, 1.5), (-1.5, 0.5))
    .add_circle(0.1, (-1.5, 1.5))  # Corner
    .create()
)
builder.add_pad(d10, (0, 0))
builder.add_pad(d10, (4, 0))
builder.add_pad(d10, (8, 0))

code = builder.get_code()
print(code.dumps())
$ python custom_pad_example.py
%FSLAX46Y46*%
%MOMM*%
%AMM0*
20,1.0,0.1,0.5,1.5,1.5,1.5,0.0*
20,1.0,0.1,1.5,1.5,1.5,0.5,0.0*
1,1.0,0.1,1.5,1.5,0.0*
20,1.0,0.1,0.5,-1.5,1.5,-1.5,0.0*
20,1.0,0.1,1.5,-1.5,1.5,-0.5,0.0*
1,1.0,0.1,1.5,-1.5,0.0*
20,1.0,0.1,-0.5,-1.5,-1.5,-1.5,0.0*
20,1.0,0.1,-1.5,-1.5,-1.5,-0.5,0.0*
1,1.0,0.1,-1.5,-1.5,0.0*
20,1.0,0.1,-0.5,1.5,-1.5,1.5,0.0*
20,1.0,0.1,-1.5,1.5,-1.5,0.5,0.0*
1,1.0,0.1,-1.5,1.5,0.0*%
%ADD10M0*%
G75*
D10*
X0Y0D03*
X4000000Y0D03*
X8000000Y0D03*
M02*

Gerber code generated with the example above results in following image when rendered with PyGerber:

Embedded Image

Creating regions

Process of creating regions (copper pours / fills) is managed by RegionCreator class instances which can be obtained by calling new_region() method on GerberX3Builder.

Regions are defined by their outline made out of series of lines and / or arcs. Outline starts at point specified in new_region() call and it is always continuous series of lines / arcs. Each line / arc start at the end of previous arc / line. If end of last line / arc does not overlap with first point, last and first point are connected with straight line.

Region is added automatically to the image after calling create() method. After create() method is called you can no longer modify the region.

custom_pad_example.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
from pygerber.builder.gerber import GerberX3Builder


builder = GerberX3Builder()

region = (
    builder.new_region((-2, 0))
    .add_line((-2, 2))
    .add_line((0, 2))
    .add_line((1, 1))
    .add_line((0, 0))
    .create()
)

code = builder.get_code()
print(code.dumps())
$ python custom_pad_example.py
%FSLAX46Y46*%
%MOMM*%
%ADD10C,1.0*%
G75*
D10*
G36*
X-2000000Y0D02*
G01*
X-2000000Y2000000D01*
X0Y2000000D01*
X1000000Y1000000D01*
X0Y0D01*
X-2000000Y0D01*
G37*
X-2000000Y0D02*
M02*

Gerber code generated with the example above results in following image when rendered with PyGerber:

Embedded Image

Warning

Region outline can not self intersect and there must be at least 3 points in the outline.

There are also few restrictions implied by Gerber format regarding regions with cut-ins:

Cut-ins are subject to strict requirements:

  • they must consist of two fully-coincident linear segments; a pair of linear segments are said to be fully coincident if the segments coincide, with the second segment starting where the first one ends

  • cut-ins must be either horizontal or vertical

  • all cut-ins in a contour must have the same direction, either horizontal or vertical;

  • cut-ins can only touch or overlap the contour in their start and end points.