Apertures in Gerbonara

Gerbonara maps all standard Gerber apertures to subclasses of the Aperture class. These subclasses: CircleAperture, RectangleAperture, ObroundAperture and PolygonAperture. Aperture macro instantiations get mapped to ApertureMacroInstance (also an Aperture subclass). The basic aperture shapes each support a central hole through their hole_dia attribute. This “hole” is just a cut-out in the aperture itself, and does not imply an actual drilled hole in the board. Drilled holes in the board are specified completely separately through an ExcellonFile.

Gerbonara is able to rotate any aperture. The Gerber standard does not support rotation for standard apertures in any widespread way, so Gerbolyze handles rotation by converting rotated standard apertures into aperture macros during export as necessary.

Aperture generalization

Gerbonara supports rotating both individual graphic objects and whole files. Alas, this was not a use case that was intended when the Gerber format was developed. We can rotate lines, arcs, and regions alright by simply rotating all of their points. Flashes are where things get tricky: Individual flashes cannot be rotated at all in any widely supported way. There are some newer additions to the standard, but I would be surprised if any of the cheap board houses understand those. The only way to rotate a flash is to rotate the aperture, not the flash. For cirlces, this is a no-op. For polygons, we simply change the angle parameter. However, for rectangles and obrounds this gets tricky: Neither one supports a rotation parameter. The only way to rotate these is to convert them to an aperture macro, then rotate that.

This behavior of using aperture macros for general rotated rectangles is common behavior among CAD tools. Gerbonara adds a non-standard RectangleAperture.rotation attribute to all apertures except CircleAperture and transparently converts rotated instances to the appropriate ApertureMacroInstance objects while it writes out the file. Be aware that this may mean that an object that in memory has a RectangleAperture might end up with an aperture macro instance in the output Gerber file.

Aperture classes

class gerbonara.apertures.Aperture

Base class for all apertures.

equivalent_width(unit=None)

Get the width of a line interpolated using this aperture in the given LengthUnit.

Return type:

float

flash(x, y, unit=None, polarity_dark=True)

Render this aperture into a list of GraphicPrimitive instances in the given unit. If no unit is given, use this aperture’s local unit.

Parameters:

  • x (float) – X coordinate of center of flash.

  • y (float) – Y coordinate of center of flash.

  • unit (LengthUnit) – Physical length unit to use for the returned primitives.

  • polarity_dark (bool) – Polarity of this flash. True renders this aperture as usual. False flips the polarity of all primitives.

Returns:

Rendered graphic primitivees.

Return type:

list(GraphicPrimitive)

to_gerber(settings=None)

Return the Gerber aperture definition for this aperture using the given FileSettings.

Return type:

str

to_macro()

Convert this Aperture into an ApertureMacro inside an ApertureMacroInstance.

property hole_shape

Get shape of hole based on hole_dia and hole_rect_h: “rect” or “circle” or None.

class gerbonara.apertures.CircleAperture(diameter: <gerbonara.apertures.Length object at 0x7fb71a82a7d0>, hole_dia: <gerbonara.apertures.Length object at 0x7fb71a82a830> = None, hole_rect_h: <gerbonara.apertures.Length object at 0x7fb71a82a890> = None, rotation: float = 0, unit: str = None, attrs: dict = <factory>, original_number: int = None)

Besides flashing circles or rings, CircleApertures are used to set the width of a Line or Arc.

equivalent_width(unit=None)

Get the width of a line interpolated using this aperture in the given LengthUnit.

Return type:

float

flash(x, y, unit=None, polarity_dark=True)

Render this aperture into a list of GraphicPrimitive instances in the given unit. If no unit is given, use this aperture’s local unit.

Parameters:

  • x (float) – X coordinate of center of flash.

  • y (float) – Y coordinate of center of flash.

  • unit (LengthUnit) – Physical length unit to use for the returned primitives.

  • polarity_dark (bool) – Polarity of this flash. True renders this aperture as usual. False flips the polarity of all primitives.

Returns:

Rendered graphic primitivees.

Return type:

list(GraphicPrimitive)

to_macro()

Convert this Aperture into an ApertureMacro inside an ApertureMacroInstance.

diameter: <gerbonara.apertures.Length object at 0x7fb71a82a7d0>

float with diameter of the circle in unit units.

hole_dia: <gerbonara.apertures.Length object at 0x7fb71a82a830> = None

float with the hole diameter of this aperture in unit units. 0 for no hole.

hole_rect_h: <gerbonara.apertures.Length object at 0x7fb71a82a890> = None

float or None. If not None, specifies a rectangular hole of size hole_dia * hole_rect_h instead of a round hole.

class gerbonara.apertures.RectangleAperture(w: <gerbonara.apertures.Length object at 0x7fb71a829f90>, h: <gerbonara.apertures.Length object at 0x7fb71a8298a0>, hole_dia: <gerbonara.apertures.Length object at 0x7fb71a82a410> = None, hole_rect_h: <gerbonara.apertures.Length object at 0x7fb71a82bf40> = None, rotation: float = 0, unit: str = None, attrs: dict = <factory>, original_number: int = None)

Gerber rectangle aperture. Can only be used for flashes, since the line width of an interpolation of a rectangle aperture is not well-defined and there is no tool that implements it in a geometrically correct way.

equivalent_width(unit=None)

Get the width of a line interpolated using this aperture in the given LengthUnit.

Return type:

float

flash(x, y, unit=None, polarity_dark=True)

Render this aperture into a list of GraphicPrimitive instances in the given unit. If no unit is given, use this aperture’s local unit.

Parameters:

  • x (float) – X coordinate of center of flash.

  • y (float) – Y coordinate of center of flash.

  • unit (LengthUnit) – Physical length unit to use for the returned primitives.

  • polarity_dark (bool) – Polarity of this flash. True renders this aperture as usual. False flips the polarity of all primitives.

Returns:

Rendered graphic primitivees.

Return type:

list(GraphicPrimitive)

to_macro(rotation=0)

Convert this Aperture into an ApertureMacro inside an ApertureMacroInstance.

h: <gerbonara.apertures.Length object at 0x7fb71a8298a0>

float with the height of the rectangle in unit units.

hole_dia: <gerbonara.apertures.Length object at 0x7fb71a82a410> = None

float with the hole diameter of this aperture in unit units. 0 for no hole.

hole_rect_h: <gerbonara.apertures.Length object at 0x7fb71a82bf40> = None

float or None. If not None, specifies a rectangular hole of size hole_dia * hole_rect_h instead of a round hole.

w: <gerbonara.apertures.Length object at 0x7fb71a829f90>

float with the width of the rectangle in unit units.

class gerbonara.apertures.ObroundAperture(w: <gerbonara.apertures.Length object at 0x7fb71a828040>, h: <gerbonara.apertures.Length object at 0x7fb71a828280>, hole_dia: <gerbonara.apertures.Length object at 0x7fb71a82a110> = None, hole_rect_h: <gerbonara.apertures.Length object at 0x7fb71a829d20> = None, rotation: float = 0, unit: str = None, attrs: dict = <factory>, original_number: int = None)

Aperture whose shape is the convex hull of two circles of equal radii.

Obrounds are specified through width and height of their bounding rectangle.. The smaller one of these will be the diameter of the obround’s ends. If w is larger, the result will be a landscape obround. If h is larger, it will be a portrait obround.

flash(x, y, unit=None, polarity_dark=True)

Render this aperture into a list of GraphicPrimitive instances in the given unit. If no unit is given, use this aperture’s local unit.

Parameters:

  • x (float) – X coordinate of center of flash.

  • y (float) – Y coordinate of center of flash.

  • unit (LengthUnit) – Physical length unit to use for the returned primitives.

  • polarity_dark (bool) – Polarity of this flash. True renders this aperture as usual. False flips the polarity of all primitives.

Returns:

Rendered graphic primitivees.

Return type:

list(GraphicPrimitive)

to_macro(rotation=0)

Convert this Aperture into an ApertureMacro inside an ApertureMacroInstance.

h: <gerbonara.apertures.Length object at 0x7fb71a828280>

float with the height of the bounding rectangle of this obround in unit units.

hole_dia: <gerbonara.apertures.Length object at 0x7fb71a82a110> = None

float with the hole diameter of this aperture in unit units. 0 for no hole.

hole_rect_h: <gerbonara.apertures.Length object at 0x7fb71a829d20> = None

float or None. If not None, specifies a rectangular hole of size hole_dia * hole_rect_h instead of a round hole.

rotation: float = 0

Rotation in radians. This rotates both the aperture and the rectangular hole if it has one.

w: <gerbonara.apertures.Length object at 0x7fb71a828040>

float with the width of the bounding rectangle of this obround in unit units.

class gerbonara.apertures.PolygonAperture(diameter: <gerbonara.apertures.Length object at 0x7fb71a82a080>, n_vertices: int, rotation: float = 0, hole_dia: <gerbonara.apertures.Length object at 0x7fb71a8284c0> = None, unit: str = None, attrs: dict = <factory>, original_number: int = None)

Aperture whose shape is a regular n-sided polygon (e.g. pentagon, hexagon etc.). Note that this only supports round holes.

flash(x, y, unit=None, polarity_dark=True)

Render this aperture into a list of GraphicPrimitive instances in the given unit. If no unit is given, use this aperture’s local unit.

Parameters:

  • x (float) – X coordinate of center of flash.

  • y (float) – Y coordinate of center of flash.

  • unit (LengthUnit) – Physical length unit to use for the returned primitives.

  • polarity_dark (bool) – Polarity of this flash. True renders this aperture as usual. False flips the polarity of all primitives.

Returns:

Rendered graphic primitivees.

Return type:

list(GraphicPrimitive)

to_macro()

Convert this Aperture into an ApertureMacro inside an ApertureMacroInstance.

diameter: <gerbonara.apertures.Length object at 0x7fb71a82a080>

Diameter of circumscribing circle, i.e. the circle that all the polygon’s corners lie on. In unit units.

hole_dia: <gerbonara.apertures.Length object at 0x7fb71a8284c0> = None

float with the hole diameter of this aperture in unit units. 0 for no hole.

n_vertices: int

Number of corners of this polygon. Three for a triangle, four for a square, five for a pentagon etc.

rotation: float = 0

Rotation in radians.

class gerbonara.apertures.ApertureMacroInstance(macro: object, parameters: list, rotation: float = 0, unit: str | None = None, attrs: dict = <factory>, original_number: int | None = None)

One instance of an aperture macro. An aperture macro defined with an AM statement can be instantiated by multiple AD aperture definition statements using different parameters. An ApertureMacroInstance is one such binding of a macro to a particular set of parameters. Note that you still need an ApertureMacroInstance even if your ApertureMacro has no parameters since an ApertureMacro is not an Aperture by itself.

to_macro(rotation=0)

Convert this Aperture into an ApertureMacro inside an ApertureMacroInstance.

macro: object

The ApertureMacro bound in this instance

parameters: list

The parameters to the ApertureMacro. All elements should be floats or ints. The first item in the list is parameter $1, the second is $2 etc.

rotation: float = 0

Aperture rotation in radians. When saving, a copy of the ApertureMacro is re-written with this rotation.