#!/usr/bin/env python # -*- coding: utf-8 -*- # # Copyright 2022 Jan Sebastian Götte # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # import warnings import math from dataclasses import dataclass, replace, field, fields, InitVar, KW_ONLY from functools import lru_cache from .aperture_macros.parse import GenericMacros from .utils import LengthUnit, MM, Inch, sum_bounds from . import graphic_primitives as gp def _flash_hole(self, x, y, unit=None, polarity_dark=True): if self.hole_dia is not None: return [*self._primitives(x, y, unit, polarity_dark), gp.Circle(x, y, self.unit.convert_to(unit, self.hole_dia/2), polarity_dark=(not polarity_dark))] else: return self._primitives(x, y, unit, polarity_dark) def _strip_right(*args): args = list(args) while args and args[-1] is None: args.pop() return tuple(args) def _none_close(a, b): if a is None and b is None: return True elif a is not None and b is not None: return math.isclose(a, b) else: return False class Length: """ Marker indicating that a dataclass field of an :py:class:`.Aperture` contains a physical length or coordinate measured in the :py:class:`.Aperture`'s native unit from :py:attr:`.Aperture.unit`. """ def __init__(self, obj_type): self.type = obj_type @dataclass(frozen=True, slots=True) class Aperture: """ Base class for all apertures. """ _ : KW_ONLY unit: LengthUnit = None attrs: tuple = None original_number: int = field(default=None, hash=False, compare=False) _bounding_box: tuple = field(default=None, hash=False, compare=False) def _params(self, unit=None): out = [] for f in fields(self): if f.kw_only: continue val = getattr(self, f.name) if isinstance(f.type, Length): val = self.unit.convert_to(unit, val) out.append(val) return out def flash(self, x, y, unit=None, polarity_dark=True): """ Render this aperture into a ``list`` of :py:class:`.GraphicPrimitive` instances in the given unit. If no unit is given, use this aperture's local unit. :param float x: X coordinate of center of flash. :param float y: Y coordinate of center of flash. :param LengthUnit unit: Physical length unit to use for the returned primitives. :param bool polarity_dark: Polarity of this flash. ``True`` renders this aperture as usual. ``False`` flips the polarity of all primitives. :returns: Rendered graphic primitivees. :rtype: list(:py:class:`.GraphicPrimitive`) """ return self._primitives(x, y, unit, polarity_dark) def bounding_box(self, unit=None): if self._bounding_box is None: object.__setattr__(self, '_bounding_box', sum_bounds((prim.bounding_box() for prim in self.flash(0, 0, MM, True)))) return MM.convert_bounds_to(unit, self._bounding_box) def equivalent_width(self, unit=None): """ Get the width of a line interpolated using this aperture in the given :py:class:`~.LengthUnit`. :rtype: float """ raise ValueError('Non-circular aperture used in interpolation statement, line width is not properly defined.') def to_gerber(self, settings=None): """ Return the Gerber aperture definition for this aperture using the given :py:class:`.FileSettings`. :rtype: str """ unit = settings.unit if settings else None params = 'X'.join(f'{float(par):.4}' for par in self._params(unit) if par is not None) if params: return f'{self._gerber_shape_code},{params}' else: return self._gerber_shape_code def to_macro(self): """ Convert this :py:class:`.Aperture` into an :py:class:`.ApertureMacro` inside an :py:class:`.ApertureMacroInstance`. """ raise NotImplementedError() @dataclass(frozen=True, slots=True) class ExcellonTool(Aperture): """ Special Aperture_ subclass for use in :py:class:`.ExcellonFile`. Similar to :py:class:`.CircleAperture`, but does not have :py:attr:`.CircleAperture.hole_dia`, and has the additional :py:attr:`plated` attribute. """ _gerber_shape_code = 'C' _human_readable_shape = 'drill' #: float with diameter of this tool in :py:attr:`unit` units. diameter : Length(float) #: bool or ``None`` for "unknown", indicating whether this tool creates plated (``True``) or non-plated (``False``) #: holes. plated : bool = None def _primitives(self, x, y, unit=None, polarity_dark=True): return [ gp.Circle(x, y, self.unit.convert_to(unit, self.diameter/2), polarity_dark=polarity_dark) ] def to_xnc(self, settings): return 'C' + settings.write_excellon_value(self.diameter, self.unit) def __str__(self): plated = '' if self.plated is None else (' plated' if self.plated else ' non-plated') return f'' def equivalent_width(self, unit=MM): return unit(self.diameter, self.unit) # Internal use, for layer dilation. def dilated(self, offset, unit=MM): offset = unit(offset, self.unit) if math.isclose(offset, 0, abs_tol=1e-6): return self return replace(self, diameter=self.diameter+2*offset) @lru_cache() def rotated(self, angle=0): return self def to_macro(self, rotation=0): return ApertureMacroInstance(GenericMacros.circle, self._params(unit=MM)) def _params(self, unit=None): return (self.unit.convert_to(unit, self.diameter),) @dataclass(frozen=True, slots=True) class CircleAperture(Aperture): """ Besides flashing circles or rings, CircleApertures are used to set the width of a :py:class:`~.graphic_objects.Line` or :py:class:`~.graphic_objects.Arc`. """ _gerber_shape_code = 'C' _human_readable_shape = 'circle' #: float with diameter of the circle in :py:attr:`unit` units. diameter : Length(float) #: float with the hole diameter of this aperture in :py:attr:`unit` units. ``0`` for no hole. hole_dia : Length(float) = None def _primitives(self, x, y, unit=None, polarity_dark=True): return [ gp.Circle(x, y, self.unit.convert_to(unit, self.diameter/2), polarity_dark=polarity_dark) ] def __str__(self): return f'' flash = _flash_hole def equivalent_width(self, unit=None): return self.unit.convert_to(unit, self.diameter) def dilated(self, offset, unit=MM): offset = self.unit(offset, unit) if math.isclose(offset, 0, abs_tol=1e-6): return self return replace(self, diameter=self.diameter+2*offset, hole_dia=None) @lru_cache() def rotated(self, angle=0): return self def scaled(self, scale): return replace(self, diameter=self.diameter*scale, hole_dia=None if self.hole_dia is None else self.hole_dia*scale) def to_macro(self, rotation=0): return ApertureMacroInstance(GenericMacros.circle, self._params(unit=MM)) def _params(self, unit=None): return _strip_right( self.unit.convert_to(unit, self.diameter), self.unit.convert_to(unit, self.hole_dia)) @dataclass(frozen=True, slots=True) class RectangleAperture(Aperture): """ 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. """ _gerber_shape_code = 'R' _human_readable_shape = 'rect' #: float with the width of the rectangle in :py:attr:`unit` units. w : Length(float) #: float with the height of the rectangle in :py:attr:`unit` units. h : Length(float) #: float with the hole diameter of this aperture in :py:attr:`unit` units. ``0`` for no hole. hole_dia : Length(float) = None def _primitives(self, x, y, unit=None, polarity_dark=True): return [ gp.Rectangle(x, y, self.unit.convert_to(unit, self.w), self.unit.convert_to(unit, self.h), rotation=0, polarity_dark=polarity_dark) ] def __str__(self): return f'' flash = _flash_hole def equivalent_width(self, unit=None): return self.unit.convert_to(unit, math.sqrt(self.w**2 + self.h**2)) def dilated(self, offset, unit=MM): offset = self.unit(offset, unit) if math.isclose(offset, 0, abs_tol=1e-6): return self return replace(self, w=self.w+2*offset, h=self.h+2*offset, hole_dia=None) @lru_cache() def rotated(self, angle=0): if math.isclose(angle % math.pi, 0, abs_tol=1e-6): return self elif math.isclose(angle % math.pi, math.pi/2, abs_tol=1e-6): return replace(self, w=self.h, h=self.w, hole_dia=self.hole_dia) else: # odd angle return self.to_macro(angle) def scaled(self, scale): return replace(self, w=self.w*scale, h=self.h*scale, hole_dia=None if self.hole_dia is None else self.hole_dia*scale) def to_macro(self, rotation=0): return ApertureMacroInstance(GenericMacros.rect, (MM(self.w, self.unit), MM(self.h, self.unit), MM(self.hole_dia, self.unit) or 0, 0, rotation)) def _params(self, unit=None): return _strip_right( self.unit.convert_to(unit, self.w), self.unit.convert_to(unit, self.h), self.unit.convert_to(unit, self.hole_dia)) @dataclass(frozen=True, slots=True) class ObroundAperture(Aperture): """ 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 :py:attr:`w` is larger, the result will be a landscape obround. If :py:attr:`h` is larger, it will be a portrait obround. """ _gerber_shape_code = 'O' _human_readable_shape = 'obround' #: float with the width of the bounding rectangle of this obround in :py:attr:`unit` units. w : Length(float) #: float with the height of the bounding rectangle of this obround in :py:attr:`unit` units. h : Length(float) #: float with the hole diameter of this aperture in :py:attr:`unit` units. ``0`` for no hole. hole_dia : Length(float) = None def _primitives(self, x, y, unit=None, polarity_dark=True): return [ gp.Line.from_obround(x, y, self.unit.convert_to(unit, self.w), self.unit.convert_to(unit, self.h), polarity_dark=polarity_dark) ] def __str__(self): return f'' flash = _flash_hole def dilated(self, offset, unit=MM): offset = self.unit(offset, unit) if math.isclose(offset, 0, abs_tol=1e-6): return self return replace(self, w=self.w+2*offset, h=self.h+2*offset, hole_dia=None) @lru_cache() def rotated(self, angle=0): if math.isclose(angle % math.pi, 0, abs_tol=1e-6): return self elif math.isclose(angle % math.pi, math.pi/2, abs_tol=1e-6): return replace(self, w=self.h, h=self.w, hole_dia=self.hole_dia) else: return self.to_macro(angle) def scaled(self, scale): return replace(self, w=self.w*scale, h=self.h*scale, hole_dia=None if self.hole_dia is None else self.hole_dia*scale) def to_macro(self, rotation=0): # generic macro only supports w > h so flip x/y if h > w if self.w > self.h: inst = self else: rotation -= -math.pi/2 inst = replace(self, w=self.h, h=self.w, hole_dia=self.hole_dia) return ApertureMacroInstance(GenericMacros.obround, (MM(inst.w, self.unit), MM(inst.h, self.unit), MM(inst.hole_dia, self.unit) or 0, 0, rotation)) def _params(self, unit=None): return _strip_right( self.unit.convert_to(unit, self.w), self.unit.convert_to(unit, self.h), self.unit.convert_to(unit, self.hole_dia)) @dataclass(frozen=True, slots=True) class PolygonAperture(Aperture): """ Aperture whose shape is a regular n-sided polygon (e.g. pentagon, hexagon etc.). Note that this only supports round holes. """ _gerber_shape_code = 'P' #: Diameter of circumscribing circle, i.e. the circle that all the polygon's corners lie on. In #: :py:attr:`unit` units. diameter : Length(float) #: Number of corners of this polygon. Three for a triangle, four for a square, five for a pentagon etc. n_vertices : int #: Rotation in radians. rotation : float = 0 #: float with the hole diameter of this aperture in :py:attr:`unit` units. ``0`` for no hole. hole_dia : Length(float) = None def __post_init__(self): object.__setattr__(self, 'n_vertices', int(self.n_vertices)) def _primitives(self, x, y, unit=None, polarity_dark=True): return [ gp.ArcPoly.from_regular_polygon(x, y, self.unit.convert_to(unit, self.diameter)/2, self.n_vertices, rotation=self.rotation, polarity_dark=polarity_dark) ] def __str__(self): return f'<{self.n_vertices}-gon aperture d={self.diameter:.3} [{self.unit}]>' def dilated(self, offset, unit=MM): offset = self.unit(offset, unit) if math.isclose(offset, 0, abs_tol=1e-6): return self return replace(self, diameter=self.diameter+2*offset, hole_dia=None) flash = _flash_hole @lru_cache() def rotated(self, angle=0): if angle != 0: return replace(self, rotation=self.rotation + angle) else: return self def scaled(self, scale): return replace(self, diameter=self.diameter*scale, hole_dia=None if self.hole_dia is None else self.hole_dia*scale) def to_macro(self): return ApertureMacroInstance(GenericMacros.polygon, self._params(MM)) def _params(self, unit=None): rotation = self.rotation % (2*math.pi / self.n_vertices) if math.isclose(rotation, 0, abs_tol=1e-6): rotation = None if self.hole_dia is not None: return self.unit.convert_to(unit, self.diameter), self.n_vertices, rotation, self.unit.convert_to(unit, self.hole_dia) elif rotation is not None and not math.isclose(rotation, 0, abs_tol=1e-6): return self.unit.convert_to(unit, self.diameter), self.n_vertices, rotation else: return self.unit.convert_to(unit, self.diameter), self.n_vertices @dataclass(frozen=True, slots=True) class ApertureMacroInstance(Aperture): """ 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 :py:class:`.ApertureMacroInstance` is one such binding of a macro to a particular set of parameters. Note that you still need an :py:class:`.ApertureMacroInstance` even if your :py:class:`.ApertureMacro` has no parameters since an :py:class:`.ApertureMacro` is not an :py:class:`.Aperture` by itself. """ #: The :py:class:`.ApertureMacro` bound in this instance macro : object #: The parameters to the :py:class:`.ApertureMacro`. All elements should be floats or ints. The first item in the #: list is parameter ``$1``, the second is ``$2`` etc. parameters : tuple = () @property def _gerber_shape_code(self): return self.macro.name def _primitives(self, x, y, unit=None, polarity_dark=True): out = list(self.macro.to_graphic_primitives( offset=(x, y), rotation=0, parameters=self.parameters, unit=unit, polarity_dark=polarity_dark)) return out def dilated(self, offset, unit=MM): if math.isclose(offset, 0, abs_tol=1e-6): return self return replace(self, macro=self.macro.dilated(offset, unit)) @lru_cache() def rotated(self, angle=0.0): if math.isclose(angle % (2*math.pi), 0, abs_tol=1e-6): return self else: return self.to_macro(angle) def to_macro(self, rotation=0.0): return replace(self, macro=self.macro.rotated(rotation)) def scaled(self, scale): return replace(self, macro=self.macro.scaled(scale)) def calculate_out(self, unit=None, macro_name=None): return replace(self, parameters=tuple(), macro=self.macro.substitute_params(self._params(unit), unit, macro_name)) def _params(self, unit=None): # We ignore "unit" here as we convert the actual macro, not this instantiation. # We do this because here we do not have information about which parameter has which physical units. parameters = self.parameters if len(parameters) > self.macro.num_parameters: warnings.warn('Aperture definition using macro {self.macro.name} has more parameters than the macro uses.') parameters = parameters[:self.macro.num_parameters] return tuple(parameters)