gerberdiff 0.29.0__py3-none-any.whl

gerberdiff/types.py

@@ -0,0 +1,360 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal, TypeAlias
+
+if TYPE_CHECKING:
+    # MacroDef lives in parse/macro_parser.py (Phase 4).  Imported only for
+    # type-checking to avoid a runtime circular dependency.
+    from gerberdiff.parse.macro_parser import MacroDef
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+
+class ApertureType(StrEnum):
+    Circle = "circle"
+    Rectangle = "rectangle"
+    Obround = "obround"
+    Polygon = "polygon"
+    Macro = "macro"
+    Block = "block"
+
+
+class ApertureState(StrEnum):
+    Off = "off"
+    On = "on"
+    Flash = "flash"
+
+
+class InterpolationMode(StrEnum):
+    Linear = "linear"
+    ClockwiseCircular = "cw"
+    CounterClockwiseCircular = "ccw"
+
+
+class Polarity(StrEnum):
+    Dark = "dark"
+    Clear = "clear"
+
+
+class MirrorState(StrEnum):
+    # None_ avoids collision with the Python builtin None
+    None_ = "none"
+    FlipA = "flipA"
+    FlipB = "flipB"
+    FlipAB = "flipAB"
+
+
+class UnitType(StrEnum):
+    Inch = "inch"
+    Millimeter = "mm"
+
+
+class ZeroOmission(StrEnum):
+    Leading = "leading"  # leading zeros omitted (most common, RS-274X default)
+    Trailing = "trailing"  # trailing zeros omitted
+    Explicit = "explicit"  # all digits present (rare)
+
+
+class CoordinateMode(StrEnum):
+    Absolute = "absolute"
+    Incremental = "incremental"
+
+
+class DiagnosticSeverity(StrEnum):
+    Error = "error"  # abort: parse result is unusable
+    Warning = "warning"  # proceed: result may be degraded
+    Info = "info"  # informational, suppressed unless -v
+
+
+class LayerStatus(StrEnum):
+    Matched = "matched"
+    Added = "added"
+    Removed = "removed"
+
+
+class LayerType(StrEnum):
+    FCu = "FCu"
+    BCu = "BCu"
+    InCu = "InCu"
+    FMask = "FMask"
+    BMask = "BMask"
+    FPaste = "FPaste"
+    BPaste = "BPaste"
+    FSilk = "FSilk"
+    BSilk = "BSilk"
+    EdgeCuts = "EdgeCuts"
+    NPTH = "NPTH"
+    PTH = "PTH"
+    Drill = "Drill"
+    Unknown = "Unknown"
+
+
+# ---------------------------------------------------------------------------
+# Geometric primitives
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ArcSegment:
+    """Fully resolved arc geometry.  Angles in degrees."""
+
+    center_x: float
+    center_y: float
+    radius: float
+    start_angle_deg: float
+    end_angle_deg: float
+
+
+@dataclass
+class BoundingBox:
+    """Axis-aligned bounding box.  All values in inches.
+
+    Initialises to the sentinel state {+inf, +inf, -inf, -inf} so that the
+    first call to expand() sets the box correctly.  Check is_valid before use.
+    """
+
+    # math.inf is an immutable float constant -- field(default=...) is correct.
+    min_x: float = field(default=math.inf)
+    min_y: float = field(default=math.inf)
+    max_x: float = field(default=-math.inf)
+    max_y: float = field(default=-math.inf)
+
+    @property
+    def is_valid(self) -> bool:
+        """True if at least one point has been added."""
+        return math.isfinite(self.min_x)
+
+    def expand(self, x: float, y: float, radius: float = 0.0) -> None:
+        """Expand to include the point (x+/-radius, y+/-radius)."""
+        self.min_x = min(self.min_x, x - radius)
+        self.min_y = min(self.min_y, y - radius)
+        self.max_x = max(self.max_x, x + radius)
+        self.max_y = max(self.max_y, y + radius)
+
+
+# ---------------------------------------------------------------------------
+# Step-and-repeat / layer / net state
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class StepAndRepeat:
+    x: int = 1  # repeat count X (>=1)
+    y: int = 1  # repeat count Y (>=1)
+    dist_x: float = 0.0  # step distance X in inches
+    dist_y: float = 0.0  # step distance Y in inches
+
+
+@dataclass
+class LayerState:
+    polarity: Polarity = Polarity.Dark
+    rotation: float = 0.0
+    mirror: MirrorState = MirrorState.None_
+    scale: float = 1.0
+    step_and_repeat: StepAndRepeat = field(default_factory=StepAndRepeat)
+    name: str | None = None
+
+
+@dataclass
+class CoordState:
+    """Snapshot of global image-level state at the time a net was emitted.
+
+    ``unit`` is stored for diagnostic/display purposes only.  All coordinates
+    in DrawOp are already normalised to inches by convert_coordinate at parse
+    time.  The deprecated RS-274X image/axis commands (%MI%, %AS%, %OF%,
+    %SF%) are silently ignored by the parser; their fields have been removed
+    from this type.
+    """
+
+    unit: UnitType = UnitType.Inch
+
+
+@dataclass
+class DrawOp:
+    """A single drawing operation.  All coordinates in inches."""
+
+    start_x: float
+    start_y: float
+    stop_x: float
+    stop_y: float
+    aperture_index: int
+    aperture_state: ApertureState
+    interpolation: InterpolationMode
+    layer_index: int
+    net_state_index: int
+    arc_segment: ArcSegment | None = None
+    attributes: dict[str, str] | None = None  # %TO.* object attributes
+
+
+@dataclass
+class RegionFill:
+    """A filled region produced by a G36..G37 block.
+
+    ``segments`` are the ``DrawOp`` objects from inside the region (G36/G37
+    are not included).  All coordinates in inches.
+    """
+
+    layer_index: int
+    net_state_index: int
+    segments: list[DrawOp]
+
+
+@dataclass
+class Diagnostic:
+    severity: DiagnosticSeverity
+    message: str
+    line: int | None = None
+
+
+# ---------------------------------------------------------------------------
+# Aperture definitions
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CircleAperture:
+    aperture_type: Literal[ApertureType.Circle] = ApertureType.Circle
+    diameter: float = 0.0  # inches
+    hole_diameter: float | None = None
+
+
+@dataclass
+class RectangleAperture:
+    aperture_type: Literal[ApertureType.Rectangle] = ApertureType.Rectangle
+    width: float = 0.0
+    height: float = 0.0
+    hole_diameter: float | None = None
+
+
+@dataclass
+class ObroundAperture:
+    aperture_type: Literal[ApertureType.Obround] = ApertureType.Obround
+    width: float = 0.0
+    height: float = 0.0
+    hole_diameter: float | None = None
+
+
+@dataclass
+class PolygonAperture:
+    aperture_type: Literal[ApertureType.Polygon] = ApertureType.Polygon
+    outer_diameter: float = 0.0
+    num_vertices: int = 4
+    rotation: float = 0.0
+    hole_diameter: float | None = None
+
+
+@dataclass
+class MacroAperture:
+    aperture_type: Literal[ApertureType.Macro] = ApertureType.Macro
+    macro_def: MacroDef | None = None  # defined in parse/macro_parser.py (Phase 4)
+    params: list[float] = field(default_factory=list)
+    unit_scale: float = 1.0  # 1.0 for inch files; 1/25.4 for mm files
+
+
+@dataclass
+class BlockAperture:
+    aperture_type: Literal[ApertureType.Block] = ApertureType.Block
+    draw_ops: list[DrawOp | RegionFill] = field(default_factory=list)
+    apertures: dict[int, Aperture] = field(default_factory=dict)
+    layers: list[LayerState] = field(default_factory=list)
+    bounding_box: BoundingBox = field(default_factory=BoundingBox)
+
+
+# Union type alias -- used for aperture dict values and type-narrowing dispatch.
+Aperture: TypeAlias = (
+    CircleAperture
+    | RectangleAperture
+    | ObroundAperture
+    | PolygonAperture
+    | MacroAperture
+    | BlockAperture
+)
+
+
+# ---------------------------------------------------------------------------
+# Top-level IR output
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ParsedImage:
+    """The complete output of parsing one Gerber or Excellon file."""
+
+    draw_ops: list[DrawOp | RegionFill]
+    apertures: dict[int, Aperture]  # D-code -> aperture
+    layers: list[LayerState]
+    coord_states: list[CoordState]
+    bounding_box: BoundingBox
+    diagnostics: list[Diagnostic]
+    source_path: Path | None = None
+
+
+# ---------------------------------------------------------------------------
+# Diff result types
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Region:
+    """A contiguous changed area.  Coordinates in inches."""
+
+    id: int
+    centroid_x: float
+    centroid_y: float
+    bounding_box: BoundingBox  # consistent naming with ParsedImage, BlockAperture
+    pixel_count: int
+
+
+@dataclass
+class LayerDiffResult:
+    name: str
+    status: LayerStatus  # matched | added | removed
+    layer_type: LayerType
+    changed_pixel_count: int
+    total_pixel_count: int
+    regions: list[Region]
+
+    @property
+    def changed_fraction(self) -> float:
+        if self.total_pixel_count == 0:
+            return 0.0
+        return self.changed_pixel_count / self.total_pixel_count
+
+
+@dataclass
+class DiffResult:
+    layers: list[LayerDiffResult]
+
+    @property
+    def has_changes(self) -> bool:
+        """True when any layer was added, removed, or has changed pixels."""
+        return any(
+            lr.changed_pixel_count > 0 or lr.status != LayerStatus.Matched for lr in self.layers
+        )
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class GerberParseError(Exception):
+    """Raised by ``compute_full_diff`` when a fatal parse error is encountered.
+
+    Attributes
+    ----------
+    path : Path
+        The file that triggered the error.
+    """
+
+    def __init__(self, path: Path, message: str, line: int | None = None) -> None:
+        self.path = path
+        loc = f" (line {line})" if line is not None else ""
+        super().__init__(f"{path.name}: {message}{loc}")

gerberdiff-0.29.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: gerberdiff
+Version: 0.29.0
+Summary: Visual raster diff tool for Gerber/Excellon PCB design files
+Project-URL: Homepage, https://github.com/CameronBrooks11/gerberdiff
+Project-URL: Repository, https://github.com/CameronBrooks11/gerberdiff
+Project-URL: Changelog, https://github.com/CameronBrooks11/gerberdiff/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/CameronBrooks11/gerberdiff/issues
+Author-email: Cameron Brooks <cameronbrooks11@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: diff,eda,excellon,gerber,grbl,kicad,pcb
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cairocffi>=1.6
+Requires-Dist: click>=8
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: shapely>=2.0
+Provides-Extra: rich
+Requires-Dist: rich>=13; extra == 'rich'
+Description-Content-Type: text/markdown
+
+# gerberdiff
+
+[![CI](https://github.com/CameronBrooks11/gerberdiff/actions/workflows/ci.yml/badge.svg)](https://github.com/CameronBrooks11/gerberdiff/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/gerberdiff)](https://pypi.org/project/gerberdiff/)
+[![Python](https://img.shields.io/pypi/pyversions/gerberdiff)](https://pypi.org/project/gerberdiff/)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
+
+Diff tool for Gerber/Excellon PCB design files, with two complementary
+engines:
+
+- **Raster diff** (`diff`) -- visual overlay PNGs of changed pixels.
+- **Geometry diff** (`geomdiff`) -- resolution-independent, attributed
+  changes (`moved` / `resized` / `added` / `removed`) computed on the
+  parsed vector geometry, down to micrometre displacements.
+
+## Install
+
+```sh
+pip install gerberdiff
+```
+
+Requires Python >= 3.11. The raster engine needs the system Cairo library
+(`libcairo2` on Debian/Ubuntu, `cairo` via Homebrew); the geometry engine
+is Cairo-free.
+
+## Quick start
+
+```sh
+# Geometry diff: what moved, resized, was added or removed -- and by how much
+gerberdiff geomdiff before/ after/ --out-json report.json --out-svg overlays/
+
+# Raster diff: visual overlay PNGs
+gerberdiff diff before/ after/ --out-json report.json --out-png diffs/
+
+# Exit 1 if any changes detected (useful in CI)
+gerberdiff geomdiff before/ after/ --fail-on-diff
+```
+
+```python
+import gerberdiff
+from pathlib import Path
+
+result = gerberdiff.compute_geometry_diff(Path("before/"), Path("after/"))
+for layer in result.layers:
+    for change in layer.changes:
+        print(f"{layer.name}: {change.kind} {change.op_kind} "
+              f"dx={change.dx_mm} dy={change.dy_mm}")
+```
+
+## Docs
+
+| Topic                | File                                         |
+| -------------------- | -------------------------------------------- |
+| CLI reference        | [docs/cli.md](docs/cli.md)                   |
+| Python API           | [docs/api.md](docs/api.md)                   |
+| JSON report schemas  | [docs/schema.md](docs/schema.md)             |
+| Architecture         | [docs/architecture.md](docs/architecture.md) |
+| Geometry diff engine | [docs/geometry-diff.md](docs/geometry-diff.md) |
+
+## Known limitations
+
+- **Excellon rout mode:** only drill hits are processed; routing paths produce a
+  `Warning` diagnostic but no geometry.
+- **Deprecated RS-274X commands (`%MI%`, `%OF%`, `%SF%`, `%AS%`):** ignored with an
+  `Info` diagnostic.
+- **Rectangle/obround aperture strokes:** the raster engine strokes with
+  `max(width, height)`; the geometry engine computes the exact Minkowski sum
+  for linear strokes (see [docs/geometry-diff.md](docs/geometry-diff.md)).
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

gerberdiff-0.29.0.dist-info/RECORD

@@ -0,0 +1,38 @@
+gerberdiff/__init__.py,sha256=k4SXSMEbSXgIhrUEzQmCfqiJ28rjNbJ-VjVtVeXpQDc,2126
+gerberdiff/cli.py,sha256=i7aYlcYie7jnfJMPXIboeXWU-cQsVOXV0j0Nmc53bm4,18796
+gerberdiff/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gerberdiff/types.py,sha256=oH782FolWQepErTjjUR1yIN5Owum9ASkWAzkC0nhz5I,9710
+gerberdiff/diff/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gerberdiff/diff/diff_engine.py,sha256=lr0Ppw4N9Bf5gqpBIr3lu218ZPQzbPMRuhOhDCxBq7Q,14219
+gerberdiff/diff/layer_matcher.py,sha256=ygj1nYC6-8KiVfinNSR4OY_3POtAnzCInMn762UbImo,6732
+gerberdiff/export/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gerberdiff/export/json_report.py,sha256=RjVE2cGzgkLKYdPcdVZ2gwh_2G-EADMQEUDDlQuZHAM,6075
+gerberdiff/export/png_export.py,sha256=2WNb_Jfpj8G57kKsx6hMJzkNbgJrh5JMJp93SiM_2lw,3110
+gerberdiff/export/svg_export.py,sha256=npkFHTH9--ZXwKGLsQJ-s3wuUbawWadRtISr0xtC8w4,6302
+gerberdiff/geometry/__init__.py,sha256=K3uHr08lxQgEbTrRfvyTKAILVLDloV1lvj-IbizFNfo,929
+gerberdiff/geometry/attribute.py,sha256=M2yjYATNywovknHQmNh7Vw0cIDXWafcV-hN_DOsjS3g,7470
+gerberdiff/geometry/driver.py,sha256=SR3MM9JQOYrmnXyu8W0hvKYoUeEoQ7zlIg6vR6e4BFk,8042
+gerberdiff/geometry/expand.py,sha256=gLpXGjMJAXzepuuu09-sKn5fjwBtdNFjiLAkkrUNOgc,7818
+gerberdiff/geometry/geom_diff.py,sha256=5jIY5ybKskQYpq3H1St0gghPjxIvJhi9C6sZqidp-oc,5596
+gerberdiff/geometry/layer_geometry.py,sha256=RyAJnwW2yKVrQ99z0cN86TSgEEuP1aEOs9IHNpeGKmk,22165
+gerberdiff/geometry/macro_geom.py,sha256=TKiu-fH4SSMg2XwPzfMv_PKooZeTlO6sXZxsoAGyizI,7304
+gerberdiff/geometry/primitives.py,sha256=By8gdNQLqwb3pwoimjvM2gXrmaWGMcjmIAAWwt3rdQw,3675
+gerberdiff/geometry/types.py,sha256=DtTCZ2RTVokgos2DyfMzkAfrDnnysNA-JUnFMCLI25w,2667
+gerberdiff/parse/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gerberdiff/parse/arc_math.py,sha256=pwe6Hva6lwrZzX8VMu2Pd0XrUL1cPsc-p3571EWCpSQ,5379
+gerberdiff/parse/excellon_parser.py,sha256=pdRu7rAY3MzE9mIFLrkV7wGx86Ntff1ZmCzpEDRy5Io,10900
+gerberdiff/parse/gerber_parser.py,sha256=3HVX2Oz-Ng7C5KvKahkgYMvYD1sZGxsZhbThnsjMryw,7594
+gerberdiff/parse/gerber_state.py,sha256=e3XfM6hy3K8aQrkNdQ8wdjON_Ycv9RT5sXX9ir69ajo,28747
+gerberdiff/parse/macro_parser.py,sha256=WIEXtEzYeb5RwUoEhFMGUQGpcACleh3hIlzXOlOEWQU,19841
+gerberdiff/parse/tokenizer.py,sha256=6mhCv_VngFMKqVjMJ4KelHyWesgVbSFnn5EPXk2HzSs,4649
+gerberdiff/render/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gerberdiff/render/compiled_render.py,sha256=yyKeeYZsgFl4o4aNS5_G6Z0Y7b3JOtTX5b-g-pY0w28,7865
+gerberdiff/render/draw_ops.py,sha256=CeINqVED4btp-_ZorjmCj1PvGn842eMVZz0hEyr4laA,7033
+gerberdiff/render/macro_renderer.py,sha256=mCbwONgG2v2QSSzwZM4R8xyU18oEPtZPqst2002gIgY,10776
+gerberdiff/render/renderer.py,sha256=sNoG0xZFnwb-Y2WAw02ZdyXaVRqiL4JtXdf5Bblt_jQ,9657
+gerberdiff/render/viewport.py,sha256=Ym2iCFT4GkFEOp5Mtb6IGfy_LGI051VSM4TReWmzQxU,2520
+gerberdiff-0.29.0.dist-info/METADATA,sha256=NoejnAu3AVP2g7D_Gox9B_2zekpn43DasibWLAOsLW8,4180
+gerberdiff-0.29.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+gerberdiff-0.29.0.dist-info/entry_points.txt,sha256=0p8xVyTFlgL4mFCJwsKRrOPAIIF-X9HBut7jG16SbBE,50
+gerberdiff-0.29.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+gerberdiff-0.29.0.dist-info/RECORD,,

gerberdiff-0.29.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

gerberdiff-0.29.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gerberdiff = gerberdiff.cli:cli