Skip to content

gerber

The builder module provides a stable API for constructing Gerber code.

Construction is done by creating a GerberX3Builder object and using its methods to add elements to image. When the image is ready, call get_code() method to get the Gerber code.

Loc2D module-attribute 

Loc2D: TypeAlias = Tuple[float, float]

Type alias of tuple of two floats representing 2D location.

GerberX3Builder

Builder class for constructing Gerber ASTs.

Builder uses metric units (millimeters) and absolute coordinates. This default can not be changed. Use of imperial units and incremental coordinates in Gerber files is deprecated.

Code generated is compliant with The Gerber Layer Format Specification - Revision 2024.05.

new_pad 

new_pad() -> PadCreator

Create a new pad.

add_pad 

add_pad(
    pad: Pad,
    at: Loc2D | TraceDraw,
    *,
    rotation: float = 0.0,
    mirror_x: bool = False,
    mirror_y: bool = False,
    scale: float = 1.0
) -> PadDraw

Add pad in shape of a pad to image.

This corresponds to the flash with positive polarity in Gerber standard.

Parameters:

  • pad (Pad) –

    Previously defined pad object to be used for drawing.

  • at (Loc2D | TraceDraw) –

    Location to flash at. Can be a 2-tuple of floats or TraceDraw object returned from add_line_trace() or add_clockwise_arc_trace(), then the end location of that trace will be used.

  • rotation (float, default: 0.0 ) –

    Pad rotation (rotation around pad origin), by default 0.0

  • mirror_x (bool, default: False ) –

    Pad X mirroring (mirroring of pad orientation relative to pad origin X axis), by default False

  • mirror_y (bool, default: False ) –

    Pad Y mirroring (mirroring of pad orientation relative to pad origin Y axis), by default False

  • scale (float, default: 1.0 ) –

    Pad scaling (pad grows in all directions), by default 1.0

Returns:

  • PadDraw –

    Object which can be used to set attributes of the pad or use it as start point for another trace.

add_cutout_pad 

add_cutout_pad(
    pad: Pad,
    at: Loc2D | TraceDraw,
    *,
    rotation: float = 0.0,
    mirror_x: bool = False,
    mirror_y: bool = False,
    scale: float = 1.0
) -> PadDraw

Add cutout in shape of a pad to image.

This corresponds to the flash with negative polarity in Gerber standard. The result will be a hole in shape of a pad cut out of whatever was previously at the given location.

Parameters:

  • pad (Pad) –

    Previously defined pad object to be used for drawing.

  • at (Loc2D | TraceDraw) –

    Location to flash at. Can be a 2-tuple of floats or TraceDraw object returned from add_line_trace() or add_clockwise_arc_trace(), then the end location of that trace will be used.

  • rotation (float, default: 0.0 ) –

    Pad rotation (rotation around pad origin), by default 0.0

  • mirror_x (bool, default: False ) –

    Pad X mirroring (mirroring of pad orientation relative to pad origin X axis), by default False

  • mirror_y (bool, default: False ) –

    Pad Y mirroring (mirroring of pad orientation relative to pad origin Y axis), by default False

  • scale (float, default: 1.0 ) –

    Pad scaling (pad grows in all directions), by default 1.0

Returns:

  • PadDraw –

    Object which can be used to set attributes of the pad or use it as start point for trace.

add_line_trace 

add_line_trace(
    width: float,
    begin: Loc2D | PadDraw | TraceDraw,
    end: Loc2D | PadDraw | TraceDraw,
) -> TraceDraw

Add a trace to the image.

Parameters:

  • width (float) –

    Width of a trace.

  • begin (Loc2D | PadDraw | TraceDraw) –

    Begin point of the trace. When 2-tuple of floats is provided, it is interpreted as absolute coordinates. When PadDraw is provided, the location of the center of the pad is used. When TraceDraw is provided, the end location of the trace is used.

  • end (Loc2D | PadDraw | TraceDraw) –

    End point of the trace. When 2-tuple of floats is provided, it is interpreted as absolute coordinates. When PadDraw is provided, the location of the center of the pad is used. When TraceDraw is provided, the begin location of the trace is used.

Returns:

  • TraceDraw –

    Object which can be used to set attributes of the trace, as start point for another trace or a center of a pad.

add_clockwise_arc_trace 

add_clockwise_arc_trace(
    width: float,
    begin: Loc2D | PadDraw | TraceDraw,
    end: Loc2D | PadDraw | TraceDraw,
    center: Loc2D,
) -> TraceDraw

Add a clockwise arc trace to the image.

Parameters:

  • width (float) –

    Width of a trace.

  • begin (Loc2D | PadDraw | TraceDraw) –

    Begin point of the trace. When 2-tuple of floats is provided, it is interpreted as absolute coordinates. When PadDraw is provided, the location of the center of the pad is used. When TraceDraw is provided, the end location of the trace is used.

  • end (Loc2D | PadDraw | TraceDraw) –

    End point of the trace. When 2-tuple of floats is provided, it is interpreted as absolute coordinates. When PadDraw is provided, the location of the center of the pad is used. When TraceDraw is provided, the begin location of the trace is used.

  • center (Loc2D) –

    Center of the arc.

Returns:

  • TraceDraw –

    Object which can be used to set attributes of the trace, as start point for another trace or a center of a pad.

add_counter_clockwise_arc_trace 

add_counter_clockwise_arc_trace(
    width: float,
    begin: Loc2D | PadDraw | TraceDraw,
    end: Loc2D | PadDraw | TraceDraw,
    center: Loc2D,
) -> TraceDraw

Add a counter clockwise arc trace to the image.

Parameters:

  • width (float) –

    Width of a trace.

  • begin (Loc2D | PadDraw | TraceDraw) –

    Begin point of the trace. When 2-tuple of floats is provided, it is interpreted as absolute coordinates. When PadDraw is provided, the location of the center of the pad is used. When TraceDraw is provided, the end location of the trace is used.

  • end (Loc2D | PadDraw | TraceDraw) –

    End point of the trace. When 2-tuple of floats is provided, it is interpreted as absolute coordinates. When PadDraw is provided, the location of the center of the pad is used. When TraceDraw is provided, the begin location of the trace is used.

  • center (Loc2D) –

    Center of the arc.

Returns:

  • TraceDraw –

    Object which can be used to set attributes of the trace, as start point for another trace or a center of a pad.

new_region 

new_region(begin: Loc2D) -> RegionCreator

Return RegionCreator object ready for creating a region.

Parameters:

  • begin (Optional[Loc2D]) –

    Location to start the region outline.

Returns:

get_code 

get_code() -> GerberCode

Generate Gerber code created with builder until this point.

set_standard_attributes 

set_standard_attributes() -> None

Set standard attributes for the file.

GerberCode

Container for Gerber code produced by the builder.

raw property 

raw: File

Get raw abstract syntax tree of Gerber code.

dump 

dump(dst: TextIO) -> None

Dump the Gerber code to file or other buffer.

dumps 

dumps() -> str

Dump the Gerber code to string.

PadCreator

The PadCreator is responsible for managing creation of pads.

Do not directly instantiate this class, instead use new_pad() method of GerberX3Builder.

circle 

circle(
    diameter: float, hole_diameter: Optional[float] = None
) -> Pad

Create a circle pad.

For corresponding element of Gerber standard see section 4.4.2 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • diameter (float) –

    Circle diameter.

  • hole_diameter (Optional[float], default: None ) –

    Diameter circle shaped hole in aperture, by default None, meaning no hole.

Returns:

  • Pad –

    New pad object.

rectangle 

rectangle(
    width: float,
    height: float,
    hole_diameter: Optional[float] = None,
) -> Pad

Create a rectangle pad.

For corresponding element of Gerber standard see section 4.4.3 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • width (float) –

    Width (x dimension) of rectangle aperture.

  • height (float) –

    Height (y dimension) of rectangle aperture.

  • hole_diameter (Optional[float], default: None ) –

    Diameter circle shaped hole in aperture, by default None, meaning no hole.

Returns:

  • Pad –

    New pad object.

rounded_rectangle 

rounded_rectangle(
    width: float,
    height: float,
    hole_diameter: Optional[float] = None,
) -> Pad

Create a rounded rectangle pad.

For corresponding element of Gerber standard see section 4.4.4 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • width (float) –

    Width (x dimension) of rounded rectangle aperture.

  • height (float) –

    Height (y dimension) of rounded rectangle aperture.

  • hole_diameter (Optional[float], default: None ) –

    Diameter circle shaped hole in aperture, by default None, meaning no hole.

Returns:

  • Pad –

    New pad object.

regular_polygon 

regular_polygon(
    outer_diameter: float,
    number_of_vertices: int,
    base_rotation_degrees: float,
    hole_diameter: Optional[float] = None,
) -> Pad

Create a regular polygon pad.

For corresponding element of Gerber standard see section 4.4.5 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • outer_diameter (float) –

    Diameter of the circle circumscribed around the polygon.

  • number_of_vertices (int) –

    Number of vertices of the polygon.

  • base_rotation_degrees (float) –

    Rotation of the polygon in degrees.

  • hole_diameter (Optional[float], default: None ) –

    Diameter circle shaped hole in aperture, by default None, meaning no hole.

Returns:

  • Pad –

    New pad object.

custom 

custom() -> CustomPadCreator

Get an object for creating custom pads.

For corresponding element of Gerber standard see section 4.5 of The Gerber Layer Format Specification - Revision 2024.05.

Returns:

Pad

Bases: BaseModel

The Pad class represents a pad object created with PadCreator which can be added to the image managed by GerberX3Builder with use of add_pad() method.

Do not directly instantiate this class, use methods available on PadCreator class.

set_aperture_function 

set_aperture_function(
    aper_function: str | AperFunction,
) -> None

Set .AperFunction attribute for aperture.

For corresponding element of Gerber standard see section 5.6.10 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • aper_function (str | AperFunction) –

    Aperture function value. Can be an AperFunction enum value or a string conversable to it.

set_drill_tolerance 

set_drill_tolerance(plus: float, minus: float) -> None

Set .DrillTolerance attribute for aperture.

For corresponding element of Gerber standard see section 5.6.11 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • plus (float) –

    Plus tolerance of a drill hole.

  • minus (float) –

    Minus tolerance of a drill hole.

set_custom_attribute 

set_custom_attribute(name: str, *values: str) -> None

Add custom attribute to the pad.

For corresponding element of Gerber standard see section 5.1 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • name (str) –

    Name of custom attribute.

  • *values (str, default: () ) –

    Values of custom attribute.

CustomPadCreator

The CustomPadCreator is single use driver of process of creating custom pad.

Do not directly instantiate this class, instead use new_pad() method of GerberX3Builder.

create 

create() -> Pad

Finalize process of creating custom pad.

This method can be called only once. After calling this method, no more primitives can be added to the pad.

add_circle 

add_circle(
    diameter: float, center: Loc2D, rotation: float = 0.0
) -> Self

Add a circle to the custom pad.

For corresponding element of Gerber standard see section 4.5.1.3 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • diameter (float) –

    Circle diameter.

  • center (Loc2D) –

    Location of circle center relative to pad origin.

  • rotation (float, default: 0.0 ) –

    Rotation of the circle relative to the pad origin in degrees counterclockwise, by default 0.0

Returns:

  • Self –

    Same CustomPadCreator object for method chaining.

cut_circle 

cut_circle(
    diameter: float, center: Loc2D, rotation: float = 0.0
) -> Self

Add a cut out in a shape of a circle to the custom pad.

For corresponding element of Gerber standard see section 4.5.1.3 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • diameter (float) –

    Circle diameter.

  • center (Loc2D) –

    Location of circle center relative to pad origin.

  • rotation (float, default: 0.0 ) –

    Rotation of the circle relative to the pad origin in degrees counterclockwise, by default 0.0

Returns:

  • Self –

    Same CustomPadCreator object for method chaining.

add_vector_line 

add_vector_line(
    width: float,
    start: Loc2D,
    end: Loc2D,
    rotation: float = 0.0,
) -> Self

Add a vector line to the custom pad.

For corresponding element of Gerber standard see section 4.5.1.4 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • width (float) –

    Vector line width.

  • start (Loc2D) –

    Start point coordinates relative to origin of the pad.

  • end (Loc2D) –

    End point coordinates relative to origin of the pad.

  • rotation (float, default: 0.0 ) –

    Rotation of the vector line relative to the pad origin in degrees counterclockwise, by default 0.0

Returns:

  • Self –

    Same CustomPadCreator object for method chaining.

cut_vector_line 

cut_vector_line(
    width: float,
    start: Loc2D,
    end: Loc2D,
    rotation: float = 0.0,
) -> Self

Add a cut out in a shape of a vector line to the custom pad.

For corresponding element of Gerber standard see section 4.5.1.4 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • width (float) –

    Vector line width.

  • start (Loc2D) –

    Start point coordinates relative to origin of the pad.

  • end (Loc2D) –

    End point coordinates relative to origin of the pad.

  • rotation (float, default: 0.0 ) –

    Rotation of the vector line relative to the pad origin in degrees counterclockwise, by default 0.0

Returns:

  • Self –

    Same CustomPadCreator object for method chaining.

add_center_line 

add_center_line(
    width: float,
    height: float,
    center: Loc2D,
    rotation: float = 0.0,
) -> Self

Add a center line to the custom pad.

For corresponding element of Gerber standard see section 4.5.1.5 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • width (float) –

    Line width (x dimension).

  • height (float) –

    Line height (y dimension).

  • center (Loc2D) –

    Line center coordinates relative to origin of the pad.

  • rotation (float, default: 0.0 ) –

    Rotation of the center line relative to the pad origin in degrees counterclockwise, by default 0.0

Returns:

  • Self –

    Same CustomPadCreator object for method chaining.

cut_center_line 

cut_center_line(
    width: float,
    height: float,
    center: Loc2D,
    rotation: float = 0.0,
) -> Self

Add a cut out in a shape of a center line to the custom pad.

For corresponding element of Gerber standard see section 4.5.1.5 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • width (float) –

    Line width (x dimension).

  • height (float) –

    Line height (y dimension).

  • center (Loc2D) –

    Line center coordinates relative to origin of the pad.

  • rotation (float, default: 0.0 ) –

    Rotation of the center line relative to the pad origin in degrees counterclockwise, by default 0.0

Returns:

  • Self –

    Same CustomPadCreator object for method chaining.

add_outline 

add_outline(
    points: Sequence[Loc2D], rotation: float = 0.0
) -> Self

Add an outline to the custom pad.

For corresponding element of Gerber standard see section 4.5.1.6 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • points (Sequence[Loc2D]) –

    Points of the outline as coordinates relative to the center of the pad. First and last point are implicitly connected.

  • rotation (float, default: 0.0 ) –

    Rotation of the outline relative to the pad origin in degrees counterclockwise, by default 0.0

Returns:

  • Self –

    Same CustomPadCreator object for method chaining.

cut_outline 

cut_outline(
    points: Sequence[Loc2D], rotation: float = 0.0
) -> Self

Add a cut out in a shape of an outline to the custom pad.

For corresponding element of Gerber standard see section 4.5.1.6 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • points (Sequence[Loc2D]) –

    Points of the outline as coordinates relative to the center of the pad. First and last point are implicitly connected.

  • rotation (float, default: 0.0 ) –

    Rotation of the outline relative to the pad origin in degrees counterclockwise, by default 0.0

Returns:

  • Self –

    Same CustomPadCreator object for method chaining.

add_polygon 

add_polygon(
    vertex_count: int,
    center: Loc2D,
    outer_diameter: float,
    rotation: float = 0.0,
) -> Self

Add a regular polygon to the custom pad.

For corresponding element of Gerber standard see section 4.5.1.7 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • vertex_count (int) –

    Number of vertices of the polygon.

  • center (Loc2D) –

    Coordinates of center of the polygon relative to the pad origin.

  • outer_diameter (float) –

    Diameter of the circle circumscribed around the polygon.

  • rotation (float, default: 0.0 ) –

    Rotation of the polygon relative to the pad origin in degrees counterclockwise, by default 0.0

Returns:

  • Self –

    Same CustomPadCreator object for method chaining.

cut_polygon 

cut_polygon(
    vertex_count: int,
    center: Loc2D,
    outer_diameter: float,
    rotation: float = 0.0,
) -> Self

Add a regular polygon to the custom pad.

For corresponding element of Gerber standard see section 4.5.1.7 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • vertex_count (int) –

    Number of vertices of the polygon.

  • center (Loc2D) –

    Coordinates of center of the polygon relative to the pad origin.

  • outer_diameter (float) –

    Diameter of the circle circumscribed around the polygon.

  • rotation (float, default: 0.0 ) –

    Rotation of the polygon relative to the pad origin in degrees counterclockwise, by default 0.0

Returns:

  • Self –

    Same CustomPadCreator object for method chaining.

add_thermal 

add_thermal(
    center: Loc2D,
    outer_diameter: float,
    inner_diameter: float,
    gap_thickness: float,
    rotation: float = 0.0,
) -> Self

Add a thermal shape to the custom pad.

For corresponding element of Gerber standard see section 4.5.1.8 of The Gerber Layer Format Specification - Revision 2024.05.

Parameters:

  • center (Loc2D) –

    Center point coordinates.

  • outer_diameter (float) –

    Outer diameter > inner diameter

  • inner_diameter (float) –

    Inner diameter >= 0

  • gap_thickness (float) –

    Gap thickness < (outer diameter)/√2. Note that if the (gap thickness)*√2 ≥ (inner diameter) the inner circle disappears. This is not invalid. The gaps are on the X and Y axes through the center without rotation. They rotate with the primitive.

  • rotation (float, default: 0.0 ) –

    Rotation of the thermal relative to the pad origin in degrees counterclockwise, by default 0.0

Returns:

  • Self –

    Same CustomPadCreator object for method chaining.

RegionCreator

The RegionCreator is responsible for managing creation of regions.

Do not directly instantiate this class, instead use new_region() method of GerberX3Builder.

add_line 

add_line(to: tuple[float, float]) -> Self

Add a line to the region outline.

Parameters:

Returns:

  • Self –

    Same RegionCreator object for method chaining.

add_clockwise_arc 

add_clockwise_arc(
    to: tuple[float, float], center: tuple[float, float]
) -> Self

Add a clockwise arc to the region outline.

Parameters:

Returns:

  • Self –

    Same RegionCreator object for method chaining.

add_counterclockwise_arc 

add_counterclockwise_arc(
    to: tuple[float, float], center: tuple[float, float]
) -> Self

Add a counterclockwise arc to the region outline.

Parameters:

Returns:

  • Self –

    Same RegionCreator object for method chaining.

create 

create() -> Region

Finalize process of creating region and automatically add it to the image.

This method can be called only once. After calling this method, no more elements can be added to the region.

Draw

Bases: BaseModel

The Draw class is a base class for all drawing operations.

SimpleDraw

Bases: Draw

The Draw class represents any drawing operation with additional state updating commands and attributes.

PadDraw

Bases: SimpleDraw

The PadDraw represents a drawing operation of creating a pad.

TraceDraw

Bases: SimpleDraw

The TraceDraw represents a drawing operation of creating a trace.

ArcTraceDraw

Bases: TraceDraw

The ArcTraceDraw represents a drawing operation of creating an arc trace.

Region

Bases: Draw

The Region represents a drawing operation of creating a region.

GerberX3BuilderError

Bases: Exception

Base class for exceptions raised by GerberX3Builder.

NotAPadError

Bases: GerberX3BuilderError

Raised when a pad is expected but different object is provided.

InvalidRegionOutlineError

Bases: GerberX3BuilderError

Raised when a region outline is invalid.