Graphic Objects¶

Graphic objects are the lego blocks a gerbonara GerberFile or ExcellonFile is built from. They are stored in the file’s objects attribute of a GerberFile. You can directly manipulate that list from code.

There are four graphic object types: Flash, Line, Arc, and Region . All of them are derived from GraphicObject.

class gerbonara.graphic_objects.GraphicObject¶

Base class for the graphic objects that make up a GerberFile or ExcellonFile.

bounding_box(unit=None)¶

Return axis-aligned bounding box of this object in given unit. If no unit is given, return the bounding box in the object’s local unit (self.unit).

Note

This method returns bounding boxes in a different format than legacy pcb-tools, which used (min_x, max_x), (min_y, max_y)

Parameters:: unit – LengthUnit or str with unit for return value.
Returns:: tuple of tuples of floats: (min_x, min_y), (max_x, max_y)

convert_to(unit)¶

Convert this gerber object to another LengthUnit in-place.

Parameters:: unit – Either a LengthUnit instance or one of the strings 'mm' or 'inch'.

converted(unit)¶

Convert this gerber object to another LengthUnit.

Parameters:: unit – Either a LengthUnit instance or one of the strings 'mm' or 'inch'.
Returns:: A copy of this object using the new unit.

offset(dx, dy, unit=<LengthUnit millimeter>)¶

Add an offset to the location of this feature. The location can be given in either unit, and is automatically converted into this object’s local unit.

Parameters:

dx (float) – X offset, positive values move the object right.
dy (float) – Y offset, positive values move the object up. This is the opposite of the normal screen coordinate system used in SVG and other computer graphics APIs.

rotate(rotation, cx=0, cy=0, unit=<LengthUnit millimeter>)¶

Rotate this object. The center of rotation can be given in either unit, and is automatically converted into this object’s local unit.

Note

The center’s Y coordinate as well as the angle’s polarity are flipped compared to computer graphics convention since Gerber uses a bottom-to-top Y axis.

Note

If this object references an aperture, this aperture is not modified. You will have to transform this aperture yourself.

Parameters:

rotation (float) – rotation in radians clockwise.
cx (float) – X coordinate of center of rotation in unit units.
cy (float) – Y coordinate of center of rotation. (0,0) is at the bottom left of the image.
unit – LengthUnit or str with unit for cx and cy

scale(factor, unit=<LengthUnit millimeter>)¶

Scale this feature in both its dimensions and location.

Note

The scale factor is a scalar, and the unit argument is irrelevant, but is kept for API consistency.

Note

If this object references an aperture, this aperture is not modified. You will have to transform this aperture yourself.

Parameters:: factor (float) – Scale factor, 1 to keep the object as is, larger values to enlarge, smaller values to shrink. Negative values are permitted.

to_primitives(unit=None)¶

Render this object into low-level graphical primitives (subclasses of GraphicPrimitive). This computes out all coordinates in case aperture macros are involved, and resolves units. The output primitives are converted into the given unit, and will be stripped of unit information. If no unit is given, use this object’s native unit (self.unit).

Parameters:: unit – LengthUnit or str with unit for return value.
Return type:: Iterator[GraphicPrimitive]

to_statements(gs)¶

Serialize this object into Gerber statements.

Parameters:: gs – GraphicsState object containing current Gerber state (polarity, selected aperture, interpolation mode etc.).
Returns:: Iterator yielding one string per line of output Gerber
Return type:: Iterator[str]

to_xnc(ctx)¶

Serialize this object into XNC Excellon statements.

Parameters:: ctx – ExcellonContext object containing current Excellon state (selected tool, interpolation mode etc.).
Returns:: Iterator yielding one string per line of output XNC code
Return type:: Iterator[str]

class gerbonara.graphic_objects.Flash(x: float, y: float, aperture: object, polarity_dark: bool = True, unit: str | None = None, attrs: dict = <factory>)¶

A flash is what happens when you “stamp” a Gerber aperture at some location. The polarity_dark attribute that Flash inherits from GraphicObject is True for normal flashes. If you set a Flash’s polarity_dark to False, you invert the polarity of all of its features.

Flashes are also used to represent drilled holes in an ExcellonFile. In this case, aperture should be an instance of ExcellonTool.

to_primitives(unit=None)¶

Parameters:: unit – LengthUnit or str with unit for return value.
Return type:: Iterator[GraphicPrimitive]

to_statements(gs)¶

Serialize this object into Gerber statements.

Parameters:: gs – GraphicsState object containing current Gerber state (polarity, selected aperture, interpolation mode etc.).
Returns:: Iterator yielding one string per line of output Gerber
Return type:: Iterator[str]

to_xnc(ctx)¶

Serialize this object into XNC Excellon statements.

Parameters:: ctx – ExcellonContext object containing current Excellon state (selected tool, interpolation mode etc.).
Returns:: Iterator yielding one string per line of output XNC code
Return type:: Iterator[str]

aperture: object¶: Flashed Aperture. must be a subclass of Aperture.

property plated¶: (Excellon only) Returns if this is a plated hole. True (plated), False (non-plated) or None (plating undefined)

property tool¶: Alias for aperture for use inside an ExcellonFile.

x: float¶: float with X coordinate of the center of this flash.

y: float¶: float with Y coordinate of the center of this flash.

class gerbonara.graphic_objects.Line(x1: float, y1: float, x2: float, y2: float, aperture: object, polarity_dark: bool = True, unit: str | None = None, attrs: dict = <factory>)¶

A line is what happens when you “drag” a Gerber Aperture from one point to another. Note that Gerber lines are substantially funkier than normal lines as we know them from modern computer graphics such as SVG. A Gerber line is defined as the area that is covered when you drag its aperture along. This means that for a rectangular aperture, a horizontal line and a vertical line using the same aperture will have different widths.

Warning

Try to only ever use CircleAperture with Line and Arc since other aperture types are not widely supported by renderers / photoplotters even though they are part of the spec.

Note

If you manipulate a Line, it is okay to assume that it has round end caps and a defined width as exceptions are really rare.

to_primitives(unit=None)¶

Parameters:: unit – LengthUnit or str with unit for return value.
Return type:: Iterator[GraphicPrimitive]

to_statements(gs)¶

Serialize this object into Gerber statements.

Parameters:: gs – GraphicsState object containing current Gerber state (polarity, selected aperture, interpolation mode etc.).
Returns:: Iterator yielding one string per line of output Gerber
Return type:: Iterator[str]

to_xnc(ctx)¶

Serialize this object into XNC Excellon statements.

Parameters:: ctx – ExcellonContext object containing current Excellon state (selected tool, interpolation mode etc.).
Returns:: Iterator yielding one string per line of output XNC code
Return type:: Iterator[str]

aperture: object¶: Aperture for this line. Should be a subclass of CircleAperture, whose diameter determines the line width.

property p1¶: Convenience alias for (self.x1, self.y1) returning start point of the line.

property p2¶: Convenience alias for (self.x2, self.y2) returning end point of the line.

property plated¶: (Excellon only) Returns if this is a plated hole. True (plated), False (non-plated) or None (plating undefined)

property tool¶: Alias for aperture for use inside an ExcellonFile.

x1: float¶: X coordinate of start point

x2: float¶: X coordinate of end point

y1: float¶: Y coordinate of start point

y2: float¶: Y coordinate of end point

class gerbonara.graphic_objects.Arc(x1: float, y1: float, x2: float, y2: float, cx: float, cy: float, clockwise: bool, aperture: object, polarity_dark: bool = True, unit: str | None = None, attrs: dict = <factory>)¶

Like Line, but a circular arc. Has start (x1, y1) and end (x2, y2) attributes like a Line, but additionally has a center (cx, cy) specified relative to the start point (x1, y1), as well as a clockwise attribute indicating the arc’s direction.

Note

The same warning on apertures that applies to Line applies to Arc, too.

Warning

When creating your own circles, you have to take care yourself that the center is actually the center of a circle that goes through both (x1,y1) and (x2,y2). Elliptical arcs are not supported by either us or the Gerber standard.

approximate(max_error=0.01, unit=<LengthUnit millimeter>, clip_max_error=True)¶

Approximate this Arc using a list of multiple Line instances to the given precision.

Parameters:

max_error (float) – Maximum approximation error in unit units.
unit – Either a LengthUnit instance or one of the strings 'mm' or 'inch'.
clip_max_error (bool) – Clip max error such that at least a square is always rendered.

Returns:

list of Line instances.

Return type:

list

numeric_error(unit=None)¶

Gerber arcs are sligtly over-determined. Since we have not just a radius, but center X and Y coordinates, an “impossible” arc can be specified, where the start and end points do not lie on a circle around its center. This function returns the absolute difference between the two radii (start - center) and (end - center) as an indication on how bad this arc is.

Note

For arcs read from a Gerber file, this value can easily be in the order of magnitude of 1e-4. Gerber files have very limited numerical resolution, and rounding errors will necessarily lead to numerical accuracy issues with arcs.

Return type:: float

sweep_angle()¶

Calculate absolute sweep angle of arc. This is always a positive number.

Returns:: Angle in clockwise radian between 0 and 2*math.pi
Return type:: float

to_primitives(unit=None)¶

Parameters:: unit – LengthUnit or str with unit for return value.
Return type:: Iterator[GraphicPrimitive]

to_statements(gs)¶

Serialize this object into Gerber statements.

Parameters:: gs – GraphicsState object containing current Gerber state (polarity, selected aperture, interpolation mode etc.).
Returns:: Iterator yielding one string per line of output Gerber
Return type:: Iterator[str]

to_xnc(ctx)¶

Serialize this object into XNC Excellon statements.

Parameters:: ctx – ExcellonContext object containing current Excellon state (selected tool, interpolation mode etc.).
Returns:: Iterator yielding one string per line of output XNC code
Return type:: Iterator[str]

aperture: object¶: Aperture for this arc. Should be a subclass of CircleAperture, whose diameter determines the line width.

property center¶

Returns the center of the arc in absolute coordinates.

Returns:: (self.x1 + self.cx, self.y1 + self.cy)
Return type:: tuple(float)

property center_relative¶

Returns the center of the arc in relative coordinates.

Returns:: (self.cx, self.cy)
Return type:: tuple(float)

clockwise: bool¶: Direction of arc. True means clockwise. For a given center coordinate and endpoints there are always two possible arcs, the large one and the small one. Flipping this switches between them.

cx: float¶: X coordinate of arc center relative to x1

cy: float¶: Y coordinate of arc center relative to x1

property p1¶: Convenience alias for (self.x1, self.y1) returning start point of the arc.

property p2¶: Convenience alias for (self.x2, self.y2) returning end point of the arc.

property plated¶: (Excellon only) Returns if this is a plated hole. True (plated), False (non-plated) or None (plating undefined)

property tool¶: Alias for aperture for use inside an ExcellonFile.

x1: float¶: X coordinate of start point

x2: float¶: X coordinate of end point

y1: float¶: Y coordinate of start point

y2: float¶: Y coordinate of end point

class gerbonara.graphic_objects.Region(outline=None, arc_centers=None, *, unit=<LengthUnit millimeter>, polarity_dark=True)¶

Gerber “region”, roughly equivalent to what in computer graphics you would call a polygon. A region is a single filled area defined by a list of coordinates on its contour. A region’s polarity is its “fill”. A region does not have a “stroke”, and thus does not have an aperture field. Note that regions are a strict subset of what modern computer graphics considers a polygon or path. Be careful when converting shapes from somewhere else into Gerber regions. For arbitrary shapes (e.g. SVG paths) this is non-trivial, and I recommend you hava look at Gerbolyze / svg-flatten. Here’s a list of special features of Gerber regions:

A region’s outline consists of straigt line segments and circular arcs and must always be closed.

A region is always exactly one connected component.

A region must not overlap itself anywhere.

A region cannot have holes.

There is one exception from the last two rules: To emulate a region with a hole in it, cut-ins are allowed. At a cut-in, the region is allowed to touch (but never overlap!) itself.

to_primitives(unit=None)¶

Parameters:: unit – LengthUnit or str with unit for return value.
Return type:: Iterator[GraphicPrimitive]

to_statements(gs)¶

Serialize this object into Gerber statements.

Parameters:: gs – GraphicsState object containing current Gerber state (polarity, selected aperture, interpolation mode etc.).
Returns:: Iterator yielding one string per line of output Gerber
Return type:: Iterator[str]

Graphic Objects¶

gerbonara

Navigation

Related Topics