summaryrefslogtreecommitdiff
path: root/gerbonara/cam.py
blob: 49c2df3f45127f7fed5e5cb4c4ebc3ef157dd9eb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
#! /usr/bin/env python
# -*- coding: utf-8 -*-
#
# Copyright 2014 Hamilton Kibbe <ham@hamiltonkib.be>
# Copyright 2022 Jan Sebastian Götte <gerbonara@jaseg.de>
#
# 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 math
from dataclasses import dataclass
from copy import deepcopy
from enum import Enum
import string
import shutil
from pathlib import Path
from functools import cached_property

from .utils import LengthUnit, MM, Inch, Tag, sum_bounds, setup_svg
from . import graphic_primitives as gp
from . import graphic_objects as go

@dataclass
class FileSettings:
    ''' Format settings for Gerber/Excellon import/export.

    .. note::
        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'``
    '''
    #: Coordinate notation. ``'absolute'`` or ``'incremental'``. Absolute mode is universally used today. Incremental
    #: (relative) mode is technically still supported, but exceedingly rare in the wild.
    notation : str = 'absolute'
    #: Export unit. :py:attr:`~.utilities.MM` or :py:attr:`~.utilities.Inch`
    unit : LengthUnit = None
    #: Angle unit. Should be ``'degree'`` unless you really know what you're doing.
    angle_unit : str = 'degree'
    #: Zero suppression settings. Must be one of ``None``, ``'leading'`` or ``'trailing'``. See note at
    #: :py:class:`.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.
    zeros : bool = None
    #: Number format. ``(integer, decimal)`` tuple of number of integer and decimal digits. At most ``(6,7)`` by spec.
    number_format : tuple = (None, None)

    # input validation
    def __setattr__(self, name, value):
        if name == 'unit' and value not in [None, MM, Inch]:
            raise ValueError(f'Unit must be either Inch or MM, not {value}')
        elif name == 'notation' and value not in ['absolute', 'incremental']:
            raise ValueError(f'Notation must be either "absolute" or "incremental", not {value}')
        elif name == 'angle_unit' and value not in ('degree', 'radian'):
            raise ValueError(f'Angle unit may be "degree" or "radian", not {value}')
        elif name == 'zeros' and value not in [None, 'leading', 'trailing']:
            raise ValueError(f'zeros must be either "leading" or "trailing" or None, not {value}')
        elif name == 'number_format':
            if len(value) != 2:
                raise ValueError(f'Number format must be a (integer, fractional) tuple of integers, not {value}')

            if value != (None, None) and (value[0] > 6 or value[1] > 7):
                raise ValueError(f'Requested precision of {value} is too high. Only up to 6.7 digits are supported by spec.')

        super().__setattr__(name, value)

        if name in ('zeros', 'number_format'):
            num = self.number_format[1 if self.zeros == 'leading' else 0] or 0
            self._pad = '0'*num

    @classmethod
    def defaults(kls):
        """ 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 :py:obj:`None` zero suppression, meaning that explicit decimal points are going to be used."""
        return FileSettings(unit=MM, number_format=(4,5), zeros=None)

    def to_radian(self, value):
        """ Convert a given numeric string or a given float from file units into radians. """
        value = float(value)
        return math.radians(value) if self.angle_unit == 'degree' else value

    def parse_ipc_length(self, value, default=None):
        if value is None or not str(value).strip():
            return default

        if isinstance(value, str) and value[0].isalpha():
            value = value[1:]

        value = int(value)
        value *= 0.0001 if self.is_inch else 0.001
        return value

    def format_ipc_number(self, value, digits, key='', sign=False):
        if value is None:
            return ' ' * (digits + int(bool(sign)) + len(key))

        if isinstance(value, Enum):
            value = value.value
        num = format(round(value), f'{"+" if sign else ""}0{digits+int(bool(sign))}d')

        if len(num) > digits + int(bool(sign)):
            raise ValueError('Error: Number {num} to wide for IPC-356 field of width {digits}')

        return key + num

    def format_ipc_length(self, value, digits, key='', unit=None, sign=False):
        if value is not None:
            value = self.unit(value, unit)
            value /= 0.0001 if self.is_inch else  0.001

        return self.format_ipc_number(value, digits, key, sign=sign)

    @property
    def is_metric(self):
        """ Return true if this :py:class:`.FileSettings` has a defined unit, and that unit is :py:attr:`~.utilities.MM` """
        return self.unit == MM

    @property
    def is_inch(self):
        """ Return true if this :py:class:`.FileSettings` has a defined unit, and that unit is :py:attr:`~.utilities.Inch` """
        return self.unit == Inch

    def copy(self):
        """ Create a deep copy of this FileSettings """
        return deepcopy(self)

    def __str__(self):
        notation = f'notation={self.notation} ' if self.notation != 'absolute' else ''
        return f'<File settings: unit={self.unit}/{self.angle_unit} {notation}zeros={self.zeros} number_format={self.number_format}>'

    @property
    def is_incremental(self):
        return self.notation == 'incremental'

    @property
    def is_absolute(self):
        return not self.is_incremental # default to absolute

    def parse_gerber_value(self, value):
        """ Parse a numeric string in gerber format using this file's settings. """
        if not value:
            return None

        if '.' in value or value == '00':
            return float(value)
 
        integer_digits, decimal_digits = self.number_format or (2, 5)

        if self.zeros == 'leading':
            value = self._pad + value # pad with zeros to ensure we have enough decimals
            return float(value[:-decimal_digits] + '.' + value[-decimal_digits:])

        else: # no or trailing zero suppression
            value = value + self._pad
            return float(value[:integer_digits] + '.' + value[integer_digits:])

    def write_gerber_value(self, value, unit=None):
        """ Convert a floating point number to a Gerber-formatted string.  """

        if unit is not None:
            value = self.unit(value, unit)
        
        integer_digits, decimal_digits = self.number_format or (2, 5)
        if integer_digits is None:
            integer_digits = 3
        if decimal_digits is None:
            decimal_digits = 3

        # negative sign affects padding, so deal with it at the end...
        sign = '-' if value < 0 else ''

        # FIXME never use exponential notation here
        num = format(abs(value), f'0{integer_digits+decimal_digits+1}.{decimal_digits}f').replace('.', '')

        # Suppression...
        if self.zeros == 'trailing':
            num = num.rstrip('0')

        elif self.zeros == 'leading':
            num = num.lstrip('0')

        # Edge case. Per Gerber spec if the value is 0 we should return a single '0' in all cases, see page 77.
        elif not num.strip('0'):
            num = '0'

        return sign + (num or '0')

    def write_excellon_value(self, value, unit=None):
        """ Convert a floating point number to an Excellon-formatted string.  """
        if unit is not None:
            value = self.unit(value, unit)
        
        integer_digits, decimal_digits = self.number_format or (2, 5)
        if integer_digits is None:
            integer_digits = 2
        if decimal_digits is None:
            decimal_digits = 6

        return format(value, f'0{integer_digits+decimal_digits+1}.{decimal_digits}f')


class Polyline:
    """ Class that is internally used to generate compact SVG renderings. Collectes a number of subsequent
    :py:class:`~.graphic_objects.Line` and :py:class:`~.graphic_objects.Arc` instances into one SVG <path>. """

    def __init__(self, *lines):
        self.coords = []
        self.polarity_dark = None
        self.width = None

        for line in lines:
            self.append(line)

    def append(self, line):
        assert isinstance(line, gp.Line)
        if not self.coords:
            self.coords.append((line.x1, line.y1))
            self.coords.append((line.x2, line.y2))
            self.polarity_dark = line.polarity_dark
            self.width = line.width
            return True

        else:
            x, y = self.coords[-1]
            if self.polarity_dark == line.polarity_dark and self.width == line.width \
                    and math.isclose(line.x1, x) and math.isclose(line.y1, y):
                self.coords.append((line.x2, line.y2))
                return True

            else:
                return False

    def to_svg(self, fg='black', bg='white', tag=Tag):
        color = fg if self.polarity_dark else bg
        if not self.coords:
            return None

        (x0, y0), *rest = self.coords
        d = f'M {float(x0):.6} {float(y0):.6} ' + ' '.join(f'L {float(x):.6} {float(y):.6}' for x, y in rest)
        width = f'{self.width:.6}' if not math.isclose(self.width, 0) else '0.01mm'
        return tag('path', d=d, style=f'fill: none; stroke: {color}; stroke-width: {float(width):.6}; stroke-linejoin: round; stroke-linecap: round')


class CamFile:
    """ Base class for all layer classes (:py:class:`.GerberFile`, :py:class:`.ExcellonFile`, and :py:class:`.Netlist`).

    Provides some common functions such as :py:meth:`~.CamFile.to_svg`.
    """
    def __init__(self, original_path=None, layer_name=None, import_settings=None):
        self.original_path = original_path
        self.layer_name = layer_name
        self.import_settings = import_settings

    @property
    def is_lazy(self):
        return False

    @property
    def instance(self):
        return self

    def to_svg(self, margin=0, arg_unit=MM, svg_unit=MM, force_bounds=None, fg='black', bg='white', tag=Tag):
        if force_bounds:
            bounds = svg_unit.convert_bounds_from(arg_unit, force_bounds)
        else:
            bounds = self.bounding_box(svg_unit, default=((0, 0), (0, 0)))

        tags = list(self.svg_objects(svg_unit=svg_unit, tag=tag, fg=fg, bg=bg))

        # setup viewport transform flipping y axis
        (content_min_x, content_min_y), (content_max_x, content_max_y) = bounds
        content_min_x, content_min_y = float(content_min_x), float(content_min_y)
        content_max_x, content_max_y = float(content_max_x), float(content_max_y)
        content_w, content_h = content_max_x - content_min_x, content_max_y - content_min_y
        xform = f'translate({float(content_min_x):.6} {float(content_min_y+content_h):.6}) scale(1 -1) translate({-float(content_min_x):.6} {-float(content_min_y):.6})'
        tags = [tag('g', tags, transform=xform)]

        return setup_svg(tags, bounds, margin=margin, arg_unit=arg_unit, svg_unit=svg_unit,
                pagecolor=bg, tag=tag)

    def svg_objects(self, svg_unit=MM, fg='black', bg='white', tag=Tag):
        pl = None
        for i, obj in enumerate(self.objects):
            #if isinstance(obj, go.Flash):
            #    if pl:
            #        tags.append(pl.to_svg(tag, fg, bg))
            #        pl = None

            #    mask_tags = [ prim.to_svg(tag, 'white', 'black') for prim in obj.to_primitives(unit=svg_unit) ]
            #    mask_tags.insert(0, tag('rect', width='100%', height='100%', fill='black'))
            #    mask_id = f'mask{i}'
            #    tag('mask', mask_tags, id=mask_id)
            #    tag('rect', width='100%', height='100%', mask='url(#{mask_id})', fill=fg)

            #else:
                for primitive in obj.to_primitives(unit=svg_unit):
                    if isinstance(primitive, gp.Line):
                        if not pl:
                            pl = Polyline(primitive)
                        else:
                            if not pl.append(primitive):
                                yield pl.to_svg(fg, bg, tag=tag)
                                pl = Polyline(primitive)
                    else:
                        if pl:
                            yield pl.to_svg(fg, bg, tag=tag)
                            pl = None
                        yield primitive.to_svg(fg, bg, tag=tag)
        if pl:
            yield pl.to_svg(fg, bg, tag=tag)

    def size(self, unit=MM):
        """ Get the dimensions of the file's axis-aligned bounding box, i.e. the difference in x- and y-direction
        between the minimum x and y coordinates and the maximum x and y coordinates.

        :param unit: :py:class:`.LengthUnit` or str (``'mm'`` or ``'inch'``). Which unit to return results in. Default: mm
        :returns: ``(w, h)`` tuple of floats.
        :rtype: tuple
        """

        (x0, y0), (x1, y1) = self.bounding_box(unit, default=((0, 0), (0, 0)))
        return (x1 - x0, y1 - y0)

    def bounding_box(self, unit=MM, default=None):
        """ Calculate the axis-aligned bounding box of file. Returns value given by the ``default`` argument when the
        file is empty. This file calculates the accurate bounding box, even for features such as arcs.

        .. note:: Gerbonara returns bounding boxes as a ``(bottom_left, top_right)`` tuple of points, not in the
                  ``((min_x, max_x), (min_y, max_y))`` format used by pcb-tools.

        :param unit: :py:class:`.LengthUnit` or str (``'mm'`` or ``'inch'``). Which unit to return results in. Default: mm
        :returns: ``((x_min, y_min), (x_max, y_max))`` tuple of floats.
        :rtype: tuple
        """

        return sum_bounds(( p.bounding_box(unit) for p in self.objects ), default=default)

    def to_excellon(self):
        """ Convert to a :py:class:`.ExcellonFile`. Returns ``self`` if it already is one. """
        raise NotImplementedError()

    def to_gerber(self):
        """ Convert to a :py:class:`.GerberFile`. Returns ``self`` if it already is one. """
        raise NotImplementedError()

    def merge(self, other):
        """ Merge ``other`` into ``self``, i.e. add all objects that are in ``other`` to ``self``. This resets
        :py:attr:`.import_settings` and :py:attr:`~.CamFile.generator`. Units and other file-specific settings are
        handled automatically.
        """
        raise NotImplementedError()

    @property
    def generator(self):
        """ Return our best guess as to which software produced this file.

        :returns: a str like ``'kicad'`` or ``'allegro'``
        """
        raise NotImplementedError()

    def offset(self, x=0, y=0, unit=MM):
        """ Add a coordinate offset to this file. The offset is given in Gerber/Excellon coordinates, so the Y axis
        points upwards. Gerbonara does not use the poorly-supported Gerber file offset options, but instead actually
        changes the coordinates of every object in the file. This means that you can load the generated file with any
        Gerber viewer, and things should just work.

        :param float x: X offset
        :param float y: Y offset
        :param unit: :py:class:`.LengthUnit` or str (``'mm'`` or ``'inch'``). Unit ``x`` and ``y`` are passed in. Default: mm
        """
        raise NotImplementedError()

    def rotate(self, angle, cx=0, cy=0, unit=MM):
        """ Apply a rotation to this file. The center of rotation is given in Gerber/Excellon coordinates, so the Y axis
        points upwards. Gerbonara does not use the poorly-supported Gerber file rotation options, but instead actually
        changes the coordinates and rotation of every object in the file. This means that you can load the generated
        file with any Gerber viewer, and things should just work.

        Note that when rotating certain apertures, they will be automatically converted to aperture macros during export
        since the standard apertures do not support rotation by spec. This is the same way most CAD packages deal with
        this issue so it should work with most Gerber viewers.
    
        :param float angle: Rotation angle in radians, *clockwise*.
        :param float cx: Center of rotation X coordinate
        :param float cy: Center of rotation Y coordinate
        :param unit: :py:class:`.LengthUnit` or str (``'mm'`` or ``'inch'``). Unit ``cx`` and ``cy`` are passed in. Default: mm
        """
        raise NotImplementedError()

    def scale(self, factor, unit=MM):
        """ Scale all objects in this file by the given factor. Only uniform scaling using a single factor in both
        directions is supported as for both Gerber and Excellon files, nonuniform scaling would distort circular
        flashes, which would lead to garbage results.

        :param float factor: Scale factor
        :param unit: :py:class:`.LengthUnit` or str (``'mm'`` or ``'inch'``). Unit ``cx`` and ``cy`` are passed in. Default: mm
        """
        raise NotImplementedError()

    @property
    def is_empty(self):
        """ Check if there are any objects in this file. """
        return not bool(list(self.objects))

    def __len__(self):
        """ Return the number of objects in this file. Note that a e.g. a long trace or a long slot consisting of
        multiple segments is counted as one object per segment. Gerber regions are counted as only one object. """
        raise NotImplementedError()

    def __bool__(self):
        """ Test if this file contains any objects """
        return not self.is_empty

class LazyCamFile:
    """ Helper class for :py:class:`~.layers.LayerStack` that holds a path to an input file without loading it right
    away. This class'es :py:method:`save` method will just copy the input file instead of parsing and re-serializing
    it."""
    def __init__(self, klass, path, *args, **kwargs):
        self._class = klass
        self.original_path = Path(path)
        self._args = args
        self._kwargs = kwargs

    @cached_property
    def instance(self):
        """ Load the input file if necessary, and return the loaded object. Will only load the file once, and cache the
        result. """
        return self._class.open(self.original_path, *self._args, **self._kwargs)

    @property
    def is_lazy(self):
        return True

    def save(self, filename, *args, **kwargs):
        """ Copy this Gerber file to the new path. """
        if 'instance' in self.__dict__: # instance has been loaded, and might have been modified
            self.instance.save(filename, *args, **kwargs)
        else:
            shutil.copy(self.original_path, filename)