gerberdiff 0.29.0__py3-none-any.whl

gerberdiff/__init__.py

@@ -0,0 +1,86 @@
+__version__ = "0.29.0"
+
+from typing import TYPE_CHECKING, Any
+
+from gerberdiff.diff.diff_engine import SingleLayerDiff, compute_diff, compute_full_diff
+from gerberdiff.diff.layer_matcher import LayerPair, match_layers
+from gerberdiff.geometry import (
+    GeometryChange,
+    GeometryDiffResult,
+    LayerGeometryDiff,
+    compute_geometry_diff,
+)
+from gerberdiff.parse.excellon_parser import parse_excellon
+from gerberdiff.parse.gerber_state import parse_gerber
+from gerberdiff.render.viewport import Viewport, compute_viewport
+from gerberdiff.types import (
+    BoundingBox,
+    Diagnostic,
+    DiagnosticSeverity,
+    DiffResult,
+    GerberParseError,
+    LayerDiffResult,
+    LayerStatus,
+    LayerType,
+    ParsedImage,
+    Region,
+    RegionFill,
+)
+
+if TYPE_CHECKING:
+    from gerberdiff.render.renderer import render_to_numpy, render_to_surface
+
+# The rasteriser requires the native cairo library; import it lazily so that
+# `import gerberdiff` -- and the Cairo-free parse/geometry pipelines -- work
+# on systems without it (PEP 562 module __getattr__).
+_LAZY_RENDER_ATTRS = ("render_to_numpy", "render_to_surface")
+
+
+def __getattr__(name: str) -> Any:
+    if name in _LAZY_RENDER_ATTRS:
+        from gerberdiff.render import renderer
+
+        return getattr(renderer, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "BoundingBox",
+    # Diagnostics
+    "Diagnostic",
+    # Enums
+    "DiagnosticSeverity",
+    # Diff result types
+    "DiffResult",
+    # Geometry diff
+    "GeometryChange",
+    "GeometryDiffResult",
+    # Exceptions
+    "GerberParseError",
+    "LayerDiffResult",
+    "LayerGeometryDiff",
+    "LayerPair",
+    "LayerStatus",
+    "LayerType",
+    # Core IR types
+    "ParsedImage",
+    "Region",
+    "RegionFill",
+    "SingleLayerDiff",
+    "Viewport",
+    # Version
+    "__version__",
+    # Diff
+    "compute_diff",
+    "compute_full_diff",
+    "compute_geometry_diff",
+    "compute_viewport",
+    # Layer matching
+    "match_layers",
+    "parse_excellon",
+    # Parse
+    "parse_gerber",
+    # Render
+    "render_to_numpy",
+    "render_to_surface",
+]

gerberdiff/cli.py

@@ -0,0 +1,527 @@
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+
+import click
+
+from gerberdiff import __version__
+from gerberdiff.diff.layer_matcher import EXCELLON_SUFFIXES
+from gerberdiff.types import Diagnostic, DiagnosticSeverity, LayerStatus
+
+_MEMORY_WARN_PIXELS = 16_777_216  # 4096^2
+
+
+@click.group()
+@click.version_option(__version__, prog_name="gerberdiff")
+def cli() -> None:
+    """Visual raster diff tool for Gerber/Excellon PCB design files."""
+
+
+@cli.command("parse")
+@click.argument("file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--dump-ir", is_flag=True, help="Print ParsedImage summary as JSON to stdout.")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress all output except errors.")
+@click.option("-v", "--verbose", is_flag=True, help="Print Info-level diagnostics.")
+def parse_cmd(file: Path, dump_ir: bool, quiet: bool, verbose: bool) -> None:
+    """Parse a Gerber or Excellon file and report diagnostics."""
+    from gerberdiff.parse.excellon_parser import parse_excellon
+    from gerberdiff.parse.gerber_state import parse_gerber
+
+    try:
+        content = file.read_text(errors="replace")
+    except OSError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+
+    if file.suffix.lower() in EXCELLON_SUFFIXES:
+        img = parse_excellon(content, source_path=file)
+    else:
+        img = parse_gerber(content, source_path=file)
+
+    has_errors = False
+    for diag in img.diagnostics:
+        loc = f" (line {diag.line})" if diag.line else ""
+        if diag.severity == DiagnosticSeverity.Error:
+            has_errors = True
+            click.echo(f"error: {diag.message}{loc}", err=True)
+        elif diag.severity == DiagnosticSeverity.Warning and not quiet:
+            click.echo(f"warning: {diag.message}{loc}", err=True)
+        elif diag.severity == DiagnosticSeverity.Info and verbose:
+            click.echo(f"info: {diag.message}", err=True)
+
+    if not quiet and not dump_ir:
+        click.echo(f"nets: {len(img.draw_ops)}")
+        click.echo(f"apertures: {len(img.apertures)}")
+        if img.bounding_box.is_valid:
+            bb = img.bounding_box
+            click.echo(
+                f"bbox: x=[{bb.min_x:.6f}, {bb.max_x:.6f}]"
+                f" y=[{bb.min_y:.6f}, {bb.max_y:.6f}] inches"
+            )
+        else:
+            click.echo("bbox: empty (no geometry)")
+
+    if dump_ir:
+        bb = img.bounding_box
+        ir: dict[str, object] = {
+            "source": str(file),
+            "net_count": len(img.draw_ops),
+            "aperture_count": len(img.apertures),
+            "layer_count": len(img.layers),
+            "bounding_box": {
+                "min_x": bb.min_x if bb.is_valid else None,
+                "min_y": bb.min_y if bb.is_valid else None,
+                "max_x": bb.max_x if bb.is_valid else None,
+                "max_y": bb.max_y if bb.is_valid else None,
+            },
+            "diagnostics": [
+                {"severity": d.severity.value, "message": d.message, "line": d.line}
+                for d in img.diagnostics
+            ],
+        }
+        click.echo(json.dumps(ir, indent=2))
+
+    sys.exit(2 if has_errors else 0)
+
+
+@cli.command("render")
+@click.argument("file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "--out-png",
+    required=True,
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="Output PNG path.",
+)
+@click.option("--width", default=2048, show_default=True, help="Canvas width in pixels.")
+@click.option("--height", default=2048, show_default=True, help="Canvas height in pixels.")
+@click.option("--overwrite", is_flag=True, help="Overwrite output file if it already exists.")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress all output except errors.")
+@click.option("-v", "--verbose", is_flag=True, help="Print render timing and diagnostic detail.")
+def render_cmd(
+    file: Path,
+    out_png: Path,
+    width: int,
+    height: int,
+    overwrite: bool,
+    quiet: bool,
+    verbose: bool,
+) -> None:
+    """Render a Gerber or Excellon file to a PNG image."""
+    from gerberdiff.parse.excellon_parser import parse_excellon
+    from gerberdiff.parse.gerber_state import parse_gerber
+    from gerberdiff.render.renderer import render_to_surface
+    from gerberdiff.render.viewport import compute_viewport
+
+    # Memory warning -- non-blocking.
+    total_pixels = width * height
+    if total_pixels > _MEMORY_WARN_PIXELS:
+        mb = (total_pixels * 4) / (1024 * 1024)
+        click.echo(
+            f"warning: canvas {width}x{height} = {total_pixels:,} pixels "
+            f"(~{mb:.0f} MB); reduce --width/--height if memory is limited.",
+            err=True,
+        )
+
+    if out_png.exists() and not overwrite:
+        click.echo(
+            f"error: output file already exists: {out_png}  (use --overwrite to replace)",
+            err=True,
+        )
+        sys.exit(1)
+
+    try:
+        content = file.read_text(errors="replace")
+    except OSError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+
+    if file.suffix.lower() in EXCELLON_SUFFIXES:
+        img = parse_excellon(content, source_path=file)
+    else:
+        img = parse_gerber(content, source_path=file)
+
+    has_errors = False
+    for diag in img.diagnostics:
+        loc = f" (line {diag.line})" if diag.line else ""
+        if diag.severity == DiagnosticSeverity.Error:
+            has_errors = True
+            click.echo(f"error: {diag.message}{loc}", err=True)
+        elif diag.severity == DiagnosticSeverity.Warning and not quiet:
+            click.echo(f"warning: {diag.message}{loc}", err=True)
+        elif diag.severity == DiagnosticSeverity.Info and verbose:
+            click.echo(f"info: {diag.message}", err=True)
+
+    if has_errors:
+        sys.exit(2)
+
+    vp = compute_viewport(img.bounding_box, width, height)
+
+    t0 = time.perf_counter()
+    surface = render_to_surface(img, vp)
+    elapsed = time.perf_counter() - t0
+
+    try:
+        out_png.parent.mkdir(parents=True, exist_ok=True)
+        surface.write_to_png(str(out_png))
+    except OSError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+
+    if not quiet:
+        click.echo(f"rendered {width}x{height} -> {out_png}")
+    if verbose:
+        click.echo(f"render time: {elapsed * 1000:.1f} ms")
+        click.echo(f"nets: {len(img.draw_ops)}  apertures: {len(img.apertures)}")
+
+
+# ---------------------------------------------------------------------------
+# diff subcommand
+# ---------------------------------------------------------------------------
+
+
+@cli.command("diff")
+@click.argument("before_dir", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.argument("after_dir", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option(
+    "--layer",
+    "layers",
+    multiple=True,
+    help="Restrict diff to this layer name (repeatable).",
+)
+@click.option("--width", default=2048, show_default=True, help="Canvas width in pixels.")
+@click.option("--height", default=2048, show_default=True, help="Canvas height in pixels.")
+@click.option(
+    "--min-pixels",
+    default=4,
+    show_default=True,
+    help="Minimum changed-pixel count to report a region.",
+)
+@click.option(
+    "--merge-tolerance", default=0.05, show_default=True, help="Region merge padding in inches."
+)
+@click.option(
+    "--out-json",
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="Write JSON report to this file.",
+)
+@click.option(
+    "--out-png",
+    "out_png_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    help="Write diff overlay PNG(s) to this directory.",
+)
+@click.option("--overwrite", is_flag=True, help="Allow overwriting existing output files.")
+@click.option(
+    "--png-show-common", is_flag=True, help="Include unchanged geometry as grey in PNG overlay."
+)
+@click.option(
+    "--align-offset",
+    default="0,0",
+    show_default=True,
+    help=(
+        "Shift image B by DX,DY inches before diffing. "
+        "Positive DX shifts right; positive DY shifts downward "
+        "(screen convention, i.e. negative Gerber Y). "
+        "Example: '--align-offset 0.5,0' compensates for B being 0.5 in to the right of A."
+    ),
+)
+@click.option("--fail-on-diff", is_flag=True, help="Exit with code 1 if any changes are detected.")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress all output except errors.")
+@click.option("-v", "--verbose", is_flag=True, help="Print per-layer and per-region detail.")
+def diff_cmd(
+    before_dir: Path,
+    after_dir: Path,
+    layers: tuple[str, ...],
+    width: int,
+    height: int,
+    min_pixels: int,
+    merge_tolerance: float,
+    out_json: Path | None,
+    out_png_dir: Path | None,
+    overwrite: bool,
+    png_show_common: bool,
+    align_offset: str,
+    fail_on_diff: bool,
+    quiet: bool,
+    verbose: bool,
+) -> None:
+    """Compare two directories of Gerber/Excellon layer files."""
+    from gerberdiff.diff.diff_engine import compute_full_diff
+    from gerberdiff.export.json_report import write_report
+    from gerberdiff.export.png_export import build_overlay_png
+    from gerberdiff.types import GerberParseError
+
+    # Parse --align-offset
+    try:
+        ox_str, oy_str = align_offset.split(",", 1)
+        alignment_offset: tuple[float, float] | None = (float(ox_str), float(oy_str))
+        if alignment_offset == (0.0, 0.0):
+            alignment_offset = None
+    except ValueError:
+        click.echo(
+            "error: --align-offset must be two comma-separated floats (e.g. '0.5,0')",
+            err=True,
+        )
+        sys.exit(2)
+
+    # Memory warning
+    total_pixels = width * height
+    if total_pixels > _MEMORY_WARN_PIXELS and not quiet:
+        mb = (total_pixels * 4) / (1024 * 1024)
+        click.echo(
+            f"warning: canvas {width}x{height} = {total_pixels:,} pixels (~{mb:.0f} MB)",
+            err=True,
+        )
+
+    def _overlay_cb(
+        layer_name: str,
+        arr_a: object,
+        arr_b: object,
+        xor: object,
+    ) -> None:
+        import numpy as _np
+
+        png_path = out_png_dir / f"{layer_name}_diff.png"  # type: ignore[operator]
+        build_overlay_png(
+            _np.asarray(arr_a),
+            _np.asarray(arr_b),
+            _np.asarray(xor),
+            png_path,
+            show_common=png_show_common,
+            overwrite=overwrite,
+        )
+
+    def _on_diagnostic(path: Path, diag: Diagnostic) -> None:
+        loc = f" (line {diag.line})" if diag.line else ""
+        if diag.severity == DiagnosticSeverity.Warning and not quiet:
+            click.echo(f"warning: {path.name}: {diag.message}{loc}", err=True)
+        elif diag.severity == DiagnosticSeverity.Info and verbose:
+            click.echo(f"info: {path.name}: {diag.message}", err=True)
+
+    t_start = time.perf_counter()
+
+    try:
+        diff_result = compute_full_diff(
+            before_dir,
+            after_dir,
+            width=width,
+            height=height,
+            layers=layers if layers else None,
+            alignment_offset=alignment_offset,
+            min_pixel_count=min_pixels,
+            merge_tolerance=merge_tolerance,
+            overlay_callback=_overlay_cb if out_png_dir is not None else None,
+            on_diagnostic=_on_diagnostic,
+        )
+    except GerberParseError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(2)
+    except FileExistsError as exc:
+        click.echo(f"error: {exc}  (use --overwrite to replace)", err=True)
+        sys.exit(1)
+    except OSError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+
+    elapsed_total = time.perf_counter() - t_start
+
+    # Verbose per-layer output
+    if verbose:
+        for lr in diff_result.layers:
+            click.echo(
+                f"  {lr.name}: {lr.changed_pixel_count} changed px, {len(lr.regions)} regions"
+            )
+            for region in lr.regions:
+                click.echo(
+                    f"    region {region.id}: {region.pixel_count} px  "
+                    f"centroid=({region.centroid_x:.4f}, {region.centroid_y:.4f})"
+                )
+
+    # JSON report
+    if out_json is not None:
+        try:
+            write_report(diff_result, out_json, overwrite=overwrite)
+        except FileExistsError as exc:
+            click.echo(f"error: {exc}  (use --overwrite to replace)", err=True)
+            sys.exit(1)
+
+    elapsed_ms = f"({elapsed_total * 1000:.0f} ms)"
+    if not quiet:
+        changed_layers = sum(
+            1
+            for lr in diff_result.layers
+            if lr.changed_pixel_count > 0 or lr.status != LayerStatus.Matched
+        )
+        click.echo(f"diff: {changed_layers}/{len(diff_result.layers)} layers changed  {elapsed_ms}")
+        if out_json:
+            click.echo(f"report: {out_json}")
+
+    sys.exit(1 if fail_on_diff and diff_result.has_changes else 0)
+
+
+# ---------------------------------------------------------------------------
+# geomdiff subcommand
+# ---------------------------------------------------------------------------
+
+
+@cli.command("geomdiff")
+@click.argument("before_dir", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.argument("after_dir", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option(
+    "--layer",
+    "layers",
+    multiple=True,
+    help="Restrict diff to this layer name (repeatable).",
+)
+@click.option(
+    "--move-tol",
+    default=0.005,
+    show_default=True,
+    help="Minimum displacement (mm) to report a matched object as moved.",
+)
+@click.option(
+    "--gate-radius",
+    default=0.2,
+    show_default=True,
+    help="Maximum distance (mm) at which two objects can pair as the same.",
+)
+@click.option(
+    "--area-tol",
+    default=0.01,
+    show_default=True,
+    help="Relative area delta still counted as same dimensions.",
+)
+@click.option(
+    "--dust-area",
+    default=1e-6,
+    show_default=True,
+    help="Drop boolean-diff components smaller than this area (mm^2).",
+)
+@click.option(
+    "--out-json",
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="Write geometry JSON report (schema v2) to this file.",
+)
+@click.option(
+    "--out-svg",
+    "out_svg_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    help="Write per-layer SVG overlays to this directory.",
+)
+@click.option("--overwrite", is_flag=True, help="Allow overwriting existing output files.")
+@click.option("--fail-on-diff", is_flag=True, help="Exit with code 1 if any changes are detected.")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress all output except errors.")
+@click.option("-v", "--verbose", is_flag=True, help="Print per-change detail.")
+def geomdiff_cmd(
+    before_dir: Path,
+    after_dir: Path,
+    layers: tuple[str, ...],
+    move_tol: float,
+    gate_radius: float,
+    area_tol: float,
+    dust_area: float,
+    out_json: Path | None,
+    out_svg_dir: Path | None,
+    overwrite: bool,
+    fail_on_diff: bool,
+    quiet: bool,
+    verbose: bool,
+) -> None:
+    """Geometry-aware diff: attributed, resolution-independent changes.
+
+    Compares two directories of Gerber/Excellon layer files on the parsed
+    vector geometry and classifies each change as added, removed, moved,
+    or resized -- including sub-pixel displacements invisible to the
+    raster diff.
+    """
+    from gerberdiff.export.json_report import write_geometry_report
+    from gerberdiff.export.svg_export import write_geometry_svg
+    from gerberdiff.geometry import compute_geometry_diff
+    from gerberdiff.types import GerberParseError
+
+    def _on_diagnostic(path: Path, diag: Diagnostic) -> None:
+        loc = f" (line {diag.line})" if diag.line else ""
+        if diag.severity == DiagnosticSeverity.Warning and not quiet:
+            click.echo(f"warning: {path.name}: {diag.message}{loc}", err=True)
+        elif diag.severity == DiagnosticSeverity.Info and verbose:
+            click.echo(f"info: {path.name}: {diag.message}", err=True)
+
+    t_start = time.perf_counter()
+    try:
+        result = compute_geometry_diff(
+            before_dir,
+            after_dir,
+            layers=layers if layers else None,
+            move_tol_mm=move_tol,
+            gate_radius_mm=gate_radius,
+            area_tol=area_tol,
+            dust_area_mm2=dust_area,
+            on_diagnostic=_on_diagnostic,
+        )
+    except GerberParseError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(2)
+    except OSError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+    elapsed_total = time.perf_counter() - t_start
+
+    if verbose:
+        for layer_diff in result.layers:
+            click.echo(
+                f"  {layer_diff.name}: {len(layer_diff.changes)} changes, "
+                f"{layer_diff.unchanged_count} unchanged, "
+                f"+{layer_diff.added_area_mm2:.3f}/-{layer_diff.removed_area_mm2:.3f} mm^2"
+            )
+            for c in layer_diff.changes:
+                detail = f"    {c.kind} {c.op_kind} at ({c.centroid_x:.4f}, {c.centroid_y:.4f})"
+                if c.kind in ("moved", "resized") and c.dx_mm is not None and c.dy_mm is not None:
+                    detail += f"  d=({c.dx_mm:+.4f}, {c.dy_mm:+.4f}) mm"
+                if c.net_name:
+                    detail += f"  net={c.net_name}"
+                click.echo(detail)
+
+    tolerances = {
+        "move_tol_mm": move_tol,
+        "gate_radius_mm": gate_radius,
+        "area_tol": area_tol,
+        "dust_area_mm2": dust_area,
+    }
+
+    if out_json is not None:
+        try:
+            write_geometry_report(result, out_json, tolerances=tolerances, overwrite=overwrite)
+        except FileExistsError as exc:
+            click.echo(f"error: {exc}  (use --overwrite to replace)", err=True)
+            sys.exit(1)
+
+    if out_svg_dir is not None:
+        try:
+            for layer_diff in result.layers:
+                write_geometry_svg(
+                    layer_diff,
+                    out_svg_dir / f"{layer_diff.name}_geomdiff.svg",
+                    overwrite=overwrite,
+                )
+        except FileExistsError as exc:
+            click.echo(f"error: {exc}  (use --overwrite to replace)", err=True)
+            sys.exit(1)
+
+    if not quiet:
+        changed_layers = sum(1 for layer_diff in result.layers if layer_diff.has_changes)
+        total_changes = sum(len(layer_diff.changes) for layer_diff in result.layers)
+        click.echo(
+            f"geomdiff: {changed_layers}/{len(result.layers)} layers changed, "
+            f"{total_changes} changes  ({elapsed_total * 1000:.0f} ms)"
+        )
+        if out_json:
+            click.echo(f"report: {out_json}")
+
+    sys.exit(1 if fail_on_diff and result.has_changes else 0)
+
+
+if __name__ == "__main__":
+    cli()