Physical units

Gerbonara tracks length units using the LengthUnit class. LengthUnit contains a number of conventient conversion functions. Everywhere where Gerbonara accepts units as a method argument, it automatically converts a string 'mm' or 'inch' to the corresponding LengthUnit.

class gerbonara.utils.LengthUnit(**kwargs)

Convenience length unit class. Used in GraphicObject and Aperture to store lenght information. Provides a number of useful unit conversion functions.

Singleton, use only global instances utils.MM and utils.Inch.

convert_bounds_from(unit, value)

LengthUnit.convert_from() but for ((min_x, min_y), (max_x, max_y)) bounding box tuples.

convert_bounds_to(unit, value)

LengthUnit.convert_to() but for ((min_x, min_y), (max_x, max_y)) bounding box tuples.

convert_from(unit, value)

Convert value from unit into this unit.

  • unitMM, Inch or one of the strings "mm" or "inch"

  • value (float) –

Return type:


convert_to(unit, value)

LengthUnit.convert_from() but in reverse.


Return a human-readdable string representing value in this unit.


value (float) –


something like “3mm”

Return type:


Format settings

When reading or writing Gerber or Excellon, Gerbonara stores information about file format options such as zero suppression or number of decimal places in a FileSettings instance. When you are writing a Gerber file, Gerbonara picks reasonable defaults, but allows you to specify your own FileSettings to override these defaults.

class gerbonara.cam.FileSettings(notation: str = 'absolute', unit: LengthUnit = None, angle_unit: str = 'degree', zeros: bool = None, number_format: tuple = (None, None), calculate_out_all_aperture_macros: bool = True)

Format settings for Gerber/Excellon import/export.


Format and zero suppression are configurable. Note that the Excellon and Gerber formats use opposite terminology with respect to leading and trailing zeros. The Gerber format specifies which zeros are suppressed, while the Excellon format specifies which zeros are included. This function uses the Gerber-file convention, so an Excellon file in LZ (leading zeros) mode would use zeros='trailing'


Create a deep copy of this FileSettings

classmethod defaults()

Return a set of good default settings that will work for all gerber or excellon files. These default settings are metric units, 4 integer digits (for up to 10 m by 10 m size), 5 fractional digits (for 10 µm resolution) and None zero suppression, meaning that explicit decimal points are going to be used.


Parse a numeric string in gerber format using this file’s settings.


Convert a given numeric string or a given float from file units into radians.

write_excellon_value(value, unit=None)

Convert a floating point number to an Excellon-formatted string.

write_gerber_value(value, unit=None)

Convert a floating point number to a Gerber-formatted string.

angle_unit: str = 'degree'

Angle unit. Should be 'degree' unless you really know what you’re doing.

calculate_out_all_aperture_macros: bool = True

At least the aperture macro implementations of gerbv and whatever JLCPCB uses are severely broken and simply ignore parentheses in numeric expressions without throwing an error or a warning, leading to broken rendering. To avoid trouble with severely broken software like this, we just calculate out all macros by default. If you want to export the macros with their original formulaic expressions (which is completely fine by the Gerber standard, btw), set this parameter to False before exporting.

property is_inch

Return true if this FileSettings has a defined unit, and that unit is Inch

property is_metric

Return true if this FileSettings has a defined unit, and that unit is MM

notation: str = 'absolute'

Coordinate notation. 'absolute' or 'incremental'. Absolute mode is universally used today. Incremental (relative) mode is technically still supported, but exceedingly rare in the wild.

number_format: tuple = (None, None)

Number format. (integer, decimal) tuple of number of integer and decimal digits. At most (6,7) by spec.

unit: LengthUnit = None

Export unit. MM or Inch

zeros: bool = None

Zero suppression settings. Must be one of None, 'leading' or 'trailing'. See note at FileSettings for meaning in Excellon files. None will produce explicit decimal points, which should work for most tools. For Gerber files, the other settings are fine, but for Excellon files, which lack a standardized way to indicate number format, explicit decimal points are the best way to avoid mis-parsing.