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(*, unit: LengthUnit = None, attrs: tuple = None, original_number: int = None, _bounding_box: tuple = None)

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.

class gerbonara.apertures.CircleAperture(diameter: <gerbonara.apertures.Length object at 0x7fddb4a3edd0>, hole_dia: <gerbonara.apertures.Length object at 0x7fddb4a3eb50> = None, *, unit: ~gerbonara.utils.LengthUnit = None, attrs: tuple = None, original_number: int = None, _bounding_box: tuple = 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(rotation=0)

Convert this Aperture into an ApertureMacro inside an ApertureMacroInstance.

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

float with diameter of the circle in unit units.

hole_dia: <gerbonara.apertures.Length object at 0x7fddb4a3eb50>

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

class gerbonara.apertures.RectangleAperture(w: <gerbonara.apertures.Length object at 0x7fddb4a3f150>, h: <gerbonara.apertures.Length object at 0x7fddb4a3efd0>, hole_dia: <gerbonara.apertures.Length object at 0x7fddb4a3f210> = None, *, unit: ~gerbonara.utils.LengthUnit = None, attrs: tuple = None, original_number: int = None, _bounding_box: tuple = 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 0x7fddb4a3efd0>

float with the height of the rectangle in unit units.

hole_dia: <gerbonara.apertures.Length object at 0x7fddb4a3f210>

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

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

float with the width of the rectangle in unit units.

class gerbonara.apertures.ObroundAperture(w: <gerbonara.apertures.Length object at 0x7fddb4b2c410>, h: <gerbonara.apertures.Length object at 0x7fddb4a3f290>, hole_dia: <gerbonara.apertures.Length object at 0x7fddb4a3c0d0> = None, *, unit: ~gerbonara.utils.LengthUnit = None, attrs: tuple = None, original_number: int = None, _bounding_box: tuple = 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 0x7fddb4a3f290>

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

hole_dia: <gerbonara.apertures.Length object at 0x7fddb4a3c0d0>

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

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

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

class gerbonara.apertures.PolygonAperture(diameter: <gerbonara.apertures.Length object at 0x7fddb4a3ff50>, n_vertices: int, rotation: float = 0, hole_dia: <gerbonara.apertures.Length object at 0x7fddb4a3fad0> = None, *, unit: ~gerbonara.utils.LengthUnit = None, attrs: tuple = None, original_number: int = None, _bounding_box: tuple = 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 0x7fddb4a3ff50>

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 0x7fddb4a3fad0>

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

Rotation in radians.

class gerbonara.apertures.ApertureMacroInstance(macro: object, parameters: tuple = (), *, unit: LengthUnit = None, attrs: tuple = None, original_number: int = None, _bounding_box: tuple = 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.0)

Convert this Aperture into an ApertureMacro inside an ApertureMacroInstance.

macro: object

The ApertureMacro bound in this instance

parameters: tuple

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.