diff options
Diffstat (limited to 'gerbonara')
| -rw-r--r-- | gerbonara/apertures.py | 1 | ||||
| -rwxr-xr-x | gerbonara/excellon.py | 10 | ||||
| -rw-r--r-- | gerbonara/graphic_objects.py | 298 | ||||
| -rw-r--r-- | gerbonara/graphic_primitives.py | 4 | ||||
| -rw-r--r-- | gerbonara/rs274x.py | 11 |
5 files changed, 271 insertions, 53 deletions
diff --git a/gerbonara/apertures.py b/gerbonara/apertures.py index ab62077..086d5b1 100644 --- a/gerbonara/apertures.py +++ b/gerbonara/apertures.py @@ -95,6 +95,7 @@ class Aperture: @dataclass(unsafe_hash=True) class ExcellonTool(Aperture): + gerber_shape_code = 'C' human_readable_shape = 'drill' diameter : Length(float) plated : bool = None diff --git a/gerbonara/excellon.py b/gerbonara/excellon.py index 3382ffe..96a78be 100755 --- a/gerbonara/excellon.py +++ b/gerbonara/excellon.py @@ -197,6 +197,9 @@ class ExcellonFile(CamFile): else: self.objects.append(obj_or_comment) + def to_excellon(self): + return self + def to_gerber(self): apertures = {} out = GerberFile() @@ -292,7 +295,7 @@ class ExcellonFile(CamFile): yield 'M30' - def to_excellon(self, settings=None, drop_comments=True): + def generate_excellon(self, settings=None, drop_comments=True): ''' Export to Excellon format. This function always generates XNC, which is a well-defined subset of Excellon. ''' if settings is None: @@ -306,10 +309,11 @@ class ExcellonFile(CamFile): def save(self, filename, settings=None, drop_comments=True): with open(filename, 'w') as f: - f.write(self.to_excellon(settings, drop_comments=drop_comments)) + f.write(self.generate_excellon(settings, drop_comments=drop_comments)) def offset(self, x=0, y=0, unit=MM): - self.objects = [ obj.with_offset(x, y, unit) for obj in self.objects ] + for obj in self.objects: + obj.offset(x, y, unit) def rotate(self, angle, cx=0, cy=0, unit=MM): if math.isclose(angle % (2*math.pi), 0): diff --git a/gerbonara/graphic_objects.py b/gerbonara/graphic_objects.py index 1f475a6..99f990f 100644 --- a/gerbonara/graphic_objects.py +++ b/gerbonara/graphic_objects.py @@ -1,8 +1,9 @@ import math +import copy from dataclasses import dataclass, KW_ONLY, astuple, replace, field, fields -from .utils import MM, InterpMode +from .utils import MM, InterpMode, to_unit from . import graphic_primitives as gp @@ -18,27 +19,94 @@ class Length: def __init__(self, obj_type): self.type = obj_type + def __repr__(self): + # This makes the automatically generated method signatures in the Sphinx docs look nice + return 'float' + @dataclass -class GerberObject: +class GraphicObject: + """ Base class for the graphic objects that make up a :py:class:`gerbonara.rs274x.GerberFile` or + :py:class:`gerbonara.excellon.ExcellonFile`. """ _ : KW_ONLY + + #: bool representing the *color* of this feature: whether this is a *dark* or *clear* feature. Clear and dark are + #: meant in the sense that they are used in the Gerber spec and refer to whether the transparency film that this + #: file describes ends up black or clear at this spot. In a standard green PCB, a *polarity_dark=True* line will + #: show up as copper on the copper layer, white ink on the silkscreen layer, or an opening on the soldermask layer. + #: Clear features erase dark features, they are not transparent in the colloquial meaning. This property is ignored + #: for features of an :py:class:`gerbonara.excellon.ExcellonFile`. polarity_dark : bool = True + + #: :py:class:`gerbonara.utils.LengthUnit` used for all coordinate fields of this feature (such as `x` or `y`). unit : str = None + + + #: `dict` containing GerberX2 attributes attached to this feature. Note that this does not include file attributes, + #: which are stored in the :py:class:`gerbonara.rs274x.GerberFile` object instead. attrs : dict = field(default_factory=dict) def converted(self, unit): - return replace(self, - **{ f.name: self.unit.convert_to(unit, getattr(self, f.name)) - for f in fields(self) if type(f.type) is Length }) + """ Convert this gerber object to another :py:class:`gerbonara.utils.LengthUnit`. + + :param unit: Either a :py:class:`gerbonara.utils.LengthUnit` instance or one of the strings ``'mm'`` or ``'inch'``. + + :returns: A copy of this object using the new unit. + """ + copy = copy.copy(self) + copy.convert_to(unit) + + def convert_to(self, unit): + """ Convert this gerber object to another :py:class:`gerbonara.utils.LengthUnit` in-place. + + :param unit: Either a :py:class:`gerbonara.utils.LengthUnit` instance or one of the strings ``'mm'`` or ``'inch'``. + """ + + for f in fields(self): + if type(f.type) is Length: + setattr(self, f.name, self.unit.convert_to(unit, getattr(self, f.name))) + + self.unit = to_unit(unit) + + def offset(self, dx, dy, unit=MM): + """ 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. + + :param float dx: X offset, positive values move the object right. + :param float dy: 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. + """ - def with_offset(self, dx, dy, unit=MM): dx, dy = self.unit(dx, unit), self.unit(dy, unit) - return self._with_offset(dx, dy) + self._offset(dx, dy) def rotate(self, rotation, cx=0, cy=0, unit=MM): + """ 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. + + :param float rotation: rotation in radians clockwise. + :param float cx: X coordinate of center of rotation in *unit* units. + :param float cy: Y coordinate of center of rotation. (0,0) is at the bottom left of the image. + :param unit: :py:class:`gerbonara.utils.LengthUnit` or str with unit for *cx* and *cy* + """ + cx, cy = self.unit(cx, unit), self.unit(cy, unit) self._rotate(rotation, cx, cy) def bounding_box(self, 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)`` + + :param unit: :py:class:`gerbonara.utils.LengthUnit` or str with unit for return value. + + :returns: tuple of tuples of floats: ``(min_x, min_y), (max_x, max_y)`` + """ + bboxes = [ p.bounding_box() for p in self.to_primitives(unit) ] min_x = min(min_x for (min_x, _min_y), _ in bboxes) min_y = min(min_y for (_min_x, min_y), _ in bboxes) @@ -47,16 +115,62 @@ class GerberObject: return ((min_x, min_y), (max_x, max_y)) def to_primitives(self, unit=None): - raise NotImplementedError() + """ Render this object into low-level graphical primitives (subclasses of :py:class:`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``). + + :param unit: :py:class:`gerbonara.utils.LengthUnit` or str with unit for return value. + + :rtype: Iterator[:py:class:`GraphicPrimitive`] + """ + return self._to_primitives(unit) + + def _to_statements(self, gs): + """ Serialize this object into Gerber statements. + + :param gs: :py:class:`rs274x.GraphicsState` object containing current Gerber state (polarity, selected aperture, + interpolation mode etc.). + + :returns: Iterator yielding one string per line of output Gerber + :rtype: Iterator[str] + """ + self._to_statements(gs) + + def _to_xnc(self, ctx): + """ Serialize this object into XNC Excellon statements. + + :param ctx: :py:class:`excellon.ExcellonContext` object containing current Excellon state (selected tool, + interpolation mode etc.). + + :returns: Iterator yielding one string per line of output XNC code + :rtype: Iterator[str] + """ + self._to_xnc(ctx) + @dataclass -class Flash(GerberObject): +class Flash(GraphicObject): + """ A flash is what happens when you "stamp" a Gerber aperture at some location. The :py:attr:`polarity_dark` + attribute that Flash inherits from :py:class:`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 :py:class:`gerbonara.excellon.ExcellonFile`. In this case, + :py:attr:`aperture` should be an instance of :py:class:`ExcellonTool`. + """ + + #: float with X coordinate of the center of this flash. x : Length(float) + + #: float with Y coordinate of the center of this flash. y : Length(float) + + #: Flashed Aperture. must be a subclass of :py:class:`Aperture`. aperture : object @property def tool(self): + """ Alias for :py:attr:`aperture` for use inside an :py:class:`gerbonara.excellon.ExcellonFile`. """ return self.aperture @tool.setter @@ -65,19 +179,23 @@ class Flash(GerberObject): @property def plated(self): - return self.tool.plated + """ (Excellon only) Returns if this is a plated hole. ``True`` (plated), ``False`` (non-plated) or ``None`` + (plating undefined) + """ + return getattr(self.tool, 'plated', None) - def _with_offset(self, dx, dy): - return replace(self, x=self.x+dx, y=self.y+dy) + def __offset(self, dx, dy): + self.x += dx + self.y += dy def _rotate(self, rotation, cx=0, cy=0): self.x, self.y = gp.rotate_point(self.x, self.y, rotation, cx, cy) - def to_primitives(self, unit=None): + def _to_primitives(self, unit=None): conv = self.converted(unit) yield from self.aperture.flash(conv.x, conv.y, unit, self.polarity_dark) - def to_statements(self, gs): + def _to_statements(self, gs): yield from gs.set_polarity(self.polarity_dark) yield from gs.set_aperture(self.aperture) @@ -87,7 +205,7 @@ class Flash(GerberObject): gs.update_point(self.x, self.y, unit=self.unit) - def to_xnc(self, ctx): + def _to_xnc(self, ctx): yield from ctx.select_tool(self.tool) yield from ctx.drill_mode() @@ -97,11 +215,31 @@ class Flash(GerberObject): ctx.set_current_point(self.unit, self.x, self.y) + # internally used to compute Excellon file path length def curve_length(self, unit=MM): return 0 -class Region(GerberObject): +class Region(GraphicObject): + """ 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. + + :attr poly: :py:class:`graphic_primitives.ArcPoly` describing the actual outline of this Region. The coordinates of + this poly are in the unit of this instance's :py:attr:`unit` field. + """ + def __init__(self, outline=None, arc_centers=None, *, unit, polarity_dark): super().__init__(unit=unit, polarity_dark=polarity_dark) outline = [] if outline is None else outline @@ -114,11 +252,8 @@ class Region(GerberObject): def __bool__(self): return bool(self.poly) - def _with_offset(self, dx, dy): - return Region([ (x+dx, y+dy) for x, y in self.poly.outline ], - self.poly.arc_centers, - polarity_dark=self.polarity_dark, - unit=self.unit) + def _offset(self, dx, dy): + self.poly.outline = [ (x+dx, y+dy) for x, y in self.poly.outline ] def _rotate(self, angle, cx=0, cy=0): self.poly.outline = [ gp.rotate_point(x, y, angle, cx, cy) for x, y in self.poly.outline ] @@ -138,7 +273,7 @@ class Region(GerberObject): else: self.poly.arc_centers.append(None) - def to_primitives(self, unit=None): + def _to_primitives(self, unit=None): self.poly.polarity_dark = self.polarity_dark # FIXME: is this the right spot to do this? if unit == self.unit: yield self.poly @@ -188,17 +323,37 @@ class Region(GerberObject): yield 'G37*' @dataclass -class Line(GerberObject): - # Line with *round* end caps. +class Line(GraphicObject): + """ A line is what happens when you "drag" a Gerber :py:class:`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 :py:class:`CircleAperture` with :py:class:`Line` and :py:class:`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 :py:class:`Line`, it is okay to assume that it has round end caps and a defined width + as exceptions are really rare. + """ + #: X coordinate of start point x1 : Length(float) + #: Y coordinate of start point y1 : Length(float) + #: X coordinate of end point x2 : Length(float) + #: Y coordinate of end point y2 : Length(float) + #: Aperture for this line. Should be a subclass of :py:class:`CircleAperture`, whose diameter determines the line + #: width. aperture : object - def _with_offset(self, dx, dy): - return replace(self, x1=self.x1+dx, y1=self.y1+dy, x2=self.x2+dx, y2=self.y2+dy) + def _offset(self, dx, dy): + self.x1 += dx + self.y1 += dy + self.x2 += dx + self.y2 += dy def _rotate(self, rotation, cx=0, cy=0): self.x1, self.y1 = gp.rotate_point(self.x1, self.y1, rotation, cx, cy) @@ -206,18 +361,17 @@ class Line(GerberObject): @property def p1(self): + """ Convenience alias for ``(self.x1, self.y1)`` returning start point of the line. """ return self.x1, self.y1 @property def p2(self): + """ Convenience alias for ``(self.x2, self.y2)`` returning end point of the line. """ return self.x2, self.y2 @property - def end_point(self): - return self.p2 - - @property def tool(self): + """ Alias for :py:attr:`aperture` for use inside an :py:class:`gerbonara.excellon.ExcellonFile`. """ return self.aperture @tool.setter @@ -226,14 +380,17 @@ class Line(GerberObject): @property def plated(self): + """ (Excellon only) Returns if this is a plated hole. ``True`` (plated), ``False`` (non-plated) or ``None`` + (plating undefined) + """ return self.tool.plated - def to_primitives(self, unit=None): + def _to_primitives(self, unit=None): conv = self.converted(unit) w = self.aperture.equivalent_width(unit) if self.aperture else 0.1 # for debugging yield gp.Line(*conv.p1, *conv.p2, w, polarity_dark=self.polarity_dark) - def to_statements(self, gs): + def _to_statements(self, gs): yield from gs.set_polarity(self.polarity_dark) yield from gs.set_aperture(self.aperture) yield from gs.set_interpolation_mode(InterpMode.LINEAR) @@ -245,7 +402,7 @@ class Line(GerberObject): gs.update_point(*self.p2, unit=self.unit) - def to_xnc(self, ctx): + def _to_xnc(self, ctx): yield from ctx.select_tool(self.tool) yield from ctx.route_mode(self.unit, *self.p1) @@ -255,26 +412,61 @@ class Line(GerberObject): ctx.set_current_point(self.unit, *self.p2) + # internally used to compute Excellon file path length def curve_length(self, unit=MM): return self.unit.convert_to(unit, math.dist(self.p1, self.p2)) @dataclass -class Arc(GerberObject): +class Arc(GraphicObject): + """ Like :py:class:`Line`, but a circular arc. Has start ``(x1, y1)`` and end ``(x2, y2)`` attributes like a + :py:class:`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 :py:class:`Line` applies to :py:class:`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. + """ + #: X coordinate of start point x1 : Length(float) + #: Y coordinate of start point y1 : Length(float) + #: X coordinate of end point x2 : Length(float) + #: Y coordinate of end point y2 : Length(float) - # relative to (x1, x2) + #: X coordinate of arc center relative to ``x1`` cx : Length(float) + #: Y coordinate of arc center relative to ``x1`` cy : Length(float) + #: 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. clockwise : bool + #: Aperture for this arc. Should be a subclass of :py:class:`CircleAperture`, whose diameter determines the line + #: width. aperture : object - def _with_offset(self, dx, dy): - return replace(self, x1=self.x1+dx, y1=self.y1+dy, x2=self.x2+dx, y2=self.y2+dy) + def _offset(self, dx, dy): + self.x1 += dx + self.y1 += dy + self.x2 += dx + self.y2 += dy def numeric_error(self, 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. + + :rtype: float + """ + # This function is used internally to determine the right arc in multi-quadrant mode conv = self.converted(unit) cx, cy = conv.cx + conv.x1, conv.cy + conv.y1 r1 = math.dist((cx, cy), conv.p1) @@ -282,6 +474,11 @@ class Arc(GerberObject): return abs(r1 - r2) def sweep_angle(self): + """ Calculate absolute sweep angle of arc. This is always a positive number. + + :returns: Angle in clockwise radian between ``0`` and ``2*math.pi`` + :rtype: float + """ cx, cy = self.cx + self.x1, self.cy + self.y1 x1, y1 = self.x1 - cx, self.y1 - cy x2, y2 = self.x2 - cx, self.y2 - cy @@ -301,26 +498,35 @@ class Arc(GerberObject): @property def p1(self): + """ Convenience alias for ``(self.x1, self.y1)`` returning start point of the arc. """ return self.x1, self.y1 @property def p2(self): + """ Convenience alias for ``(self.x2, self.y2)`` returning end point of the arc. """ return self.x2, self.y2 @property def center(self): + """ Returns the center of the arc in **absolute** coordinates. + + :returns: ``(self.x1 + self.cx, self.y1 + self.cy)`` + :rtype: tuple(float) + """ return self.cx + self.x1, self.cy + self.y1 @property def center_relative(self): - return self.cx, self.cy + """ Returns the center of the arc in relative coordinates. - @property - def end_point(self): - return self.p2 + :returns: ``(self.cx, self.cy)`` + :rtype: tuple(float) + """ + return self.cx, self.cy @property def tool(self): + """ Alias for :py:attr:`aperture` for use inside an :py:class:`gerbonara.excellon.ExcellonFile`. """ return self.aperture @tool.setter @@ -329,6 +535,9 @@ class Arc(GerberObject): @property def plated(self): + """ (Excellon only) Returns if this is a plated hole. ``True`` (plated), ``False`` (non-plated) or ``None`` + (plating undefined) + """ return self.tool.plated def _rotate(self, rotation, cx=0, cy=0): @@ -338,7 +547,7 @@ class Arc(GerberObject): self.x2, self.y2 = gp.rotate_point(self.x2, self.y2, rotation, cx, cy) self.cx, self.cy = new_cx - self.x1, new_cy - self.y1 - def to_primitives(self, unit=None): + def _to_primitives(self, unit=None): conv = self.converted(unit) w = self.aperture.equivalent_width(unit) if self.aperture else 0.1 # for debugging yield gp.Arc(x1=conv.x1, y1=conv.y1, @@ -348,7 +557,7 @@ class Arc(GerberObject): width=w, polarity_dark=self.polarity_dark) - def to_statements(self, gs): + def _to_statements(self, gs): yield from gs.set_polarity(self.polarity_dark) yield from gs.set_aperture(self.aperture) # TODO is the following line correct? @@ -363,7 +572,7 @@ class Arc(GerberObject): gs.update_point(*self.p2, unit=self.unit) - def to_xnc(self, ctx): + def _to_xnc(self, ctx): yield from ctx.select_tool(self.tool) yield from ctx.route_mode(self.unit, self.x1, self.y1) code = 'G02' if self.clockwise else 'G03' @@ -376,6 +585,7 @@ class Arc(GerberObject): ctx.set_current_point(self.unit, self.x2, self.y2) + # internally used to compute Excellon file path length def curve_length(self, unit=MM): return self.unit.convert_to(unit, math.hypot(self.cx, self.cy) * self.sweep_angle) diff --git a/gerbonara/graphic_primitives.py b/gerbonara/graphic_primitives.py index 65aa28c..889aa92 100644 --- a/gerbonara/graphic_primitives.py +++ b/gerbonara/graphic_primitives.py @@ -201,10 +201,10 @@ class ArcPoly(GraphicPrimitive): # list of (x : float, y : float) tuples. Describes closed outline, i.e. first and last point are considered # connected. - outline : [(float,)] + outline : list # must be either None (all segments are straight lines) or same length as outline. # Straight line segments have None entry. - arc_centers : [(float,)] = None + arc_centers : list = None @property def segments(self): diff --git a/gerbonara/rs274x.py b/gerbonara/rs274x.py index 8bd622b..837440f 100644 --- a/gerbonara/rs274x.py +++ b/gerbonara/rs274x.py @@ -79,6 +79,9 @@ class GerberFile(CamFile): return ExcellonFile(objects=new_objs, comments=self.comments) + def to_gerber(self): + return + def merge(self, other): """ Merge other GerberFile into this one """ if other is None: @@ -222,9 +225,9 @@ class GerberFile(CamFile): def save(self, filename, settings=None, drop_comments=True): with open(filename, 'w', encoding='utf-8') as f: # Encoding is specified as UTF-8 by spec. - f.write(self.to_gerber(settings, drop_comments=drop_comments)) + f.write(self.generate_gerber(settings, drop_comments=drop_comments)) - def to_gerber(self, settings=None, drop_comments=True): + def generate_gerber(self, settings=None, drop_comments=True): # Use given settings, or use same settings as original file if not given, or use defaults if not imported from a # file if settings is None: @@ -245,8 +248,8 @@ class GerberFile(CamFile): def offset(self, dx=0, dy=0, unit=MM): # TODO round offset to file resolution - - self.objects = [ obj.with_offset(dx, dy, unit) for obj in self.objects ] + for obj in self.objects: + obj.with_offset(dx, dy, unit) def rotate(self, angle:'radian', center=(0,0), unit=MM): """ Rotate file contents around given point. |