gerberdiff 0.29.0__py3-none-any.whl

gerberdiff/export/json_report.py

@@ -0,0 +1,184 @@
+"""Export diff results as a versioned JSON report.
+
+Schemas
+-------
+- Version 1: raster pixel diff (``DiffResult``).
+- Version 2: geometry diff (``GeometryDiffResult``), ``"mode": "geometry"``.
+
+See ``docs/schema.md`` for canonical documentation.
+
+Coordinate values are in **inches**; geometry areas are in **mm^2** and
+displacements in **mm** (see ``gerberdiff/geometry/types.py``).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from gerberdiff.geometry.types import GeometryChange, GeometryDiffResult, LayerGeometryDiff
+from gerberdiff.types import DiffResult, LayerDiffResult, LayerStatus, Region
+
+_SCHEMA_VERSION = 1
+_GEOMETRY_SCHEMA_VERSION = 2
+_GENERATOR = "gerberdiff"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def build_report(diff_result: DiffResult) -> dict[str, Any]:
+    """Serialize *diff_result* to a JSON-compatible dictionary.
+
+    The returned dict can be passed directly to ``json.dumps`` / ``json.dump``.
+    """
+    changed_layers = sum(
+        1
+        for lr in diff_result.layers
+        if lr.changed_pixel_count > 0 or lr.status != LayerStatus.Matched
+    )
+    total_regions = sum(len(lr.regions) for lr in diff_result.layers)
+
+    return {
+        "version": _SCHEMA_VERSION,
+        "generator": _GENERATOR,
+        "summary": {
+            "changed_layers": changed_layers,
+            "total_regions": total_regions,
+            "has_changes": diff_result.has_changes,
+        },
+        "layers": [_serialize_layer(lr) for lr in diff_result.layers],
+    }
+
+
+def write_report(diff_result: DiffResult, output_path: Path, overwrite: bool = False) -> None:
+    """Write the JSON report to *output_path*.
+
+    Raises
+    ------
+    FileExistsError
+        If *output_path* already exists and *overwrite* is ``False``.
+    """
+    if output_path.exists() and not overwrite:
+        raise FileExistsError(f"output file already exists: {output_path}")
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    report = build_report(diff_result)
+    output_path.write_text(json.dumps(report, indent=2), encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Geometry report (schema version 2)
+# ---------------------------------------------------------------------------
+
+
+def build_geometry_report(
+    result: GeometryDiffResult,
+    tolerances: dict[str, float] | None = None,
+) -> dict[str, Any]:
+    """Serialize a geometry diff result to a JSON-compatible dictionary.
+
+    *tolerances* (optional) records the classification thresholds used, for
+    reproducibility (keys: ``move_tol_mm``, ``gate_radius_mm``, ``area_tol``,
+    ``dust_area_mm2``).
+    """
+    report: dict[str, Any] = {
+        "version": _GEOMETRY_SCHEMA_VERSION,
+        "generator": _GENERATOR,
+        "mode": "geometry",
+        "summary": {
+            "changed_layers": sum(1 for layer in result.layers if layer.has_changes),
+            "total_changes": sum(len(layer.changes) for layer in result.layers),
+            "has_changes": result.has_changes,
+        },
+        "layers": [_serialize_geometry_layer(layer) for layer in result.layers],
+    }
+    if tolerances is not None:
+        report["tolerances"] = tolerances
+    return report
+
+
+def write_geometry_report(
+    result: GeometryDiffResult,
+    output_path: Path,
+    tolerances: dict[str, float] | None = None,
+    overwrite: bool = False,
+) -> None:
+    """Write the geometry JSON report to *output_path*.
+
+    Raises
+    ------
+    FileExistsError
+        If *output_path* already exists and *overwrite* is ``False``.
+    """
+    if output_path.exists() and not overwrite:
+        raise FileExistsError(f"output file already exists: {output_path}")
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    report = build_geometry_report(result, tolerances)
+    output_path.write_text(json.dumps(report, indent=2), encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _serialize_geometry_layer(layer: LayerGeometryDiff) -> dict[str, Any]:
+    return {
+        "name": layer.name,
+        "status": layer.status,
+        "layer_type": layer.layer_type,
+        "unchanged_count": layer.unchanged_count,
+        "added_area_mm2": round(layer.added_area_mm2, 6),
+        "removed_area_mm2": round(layer.removed_area_mm2, 6),
+        "counts": {
+            "added": layer.count("added"),
+            "removed": layer.count("removed"),
+            "moved": layer.count("moved"),
+            "resized": layer.count("resized"),
+        },
+        "changes": [_serialize_geometry_change(c) for c in layer.changes],
+    }
+
+
+def _serialize_geometry_change(c: GeometryChange) -> dict[str, Any]:
+    return {
+        "kind": c.kind,
+        "op_kind": c.op_kind,
+        "centroid_x": c.centroid_x,
+        "centroid_y": c.centroid_y,
+        "area_mm2": round(c.area_mm2, 6),
+        "dx_mm": round(c.dx_mm, 6) if c.dx_mm is not None else None,
+        "dy_mm": round(c.dy_mm, 6) if c.dy_mm is not None else None,
+        "net": c.net_name,
+    }
+
+
+def _serialize_layer(lr: LayerDiffResult) -> dict[str, Any]:
+    return {
+        "name": lr.name,
+        "status": lr.status,
+        "layer_type": lr.layer_type,
+        "changed_pixel_count": lr.changed_pixel_count,
+        "total_pixel_count": lr.total_pixel_count,
+        "changed_fraction": round(lr.changed_fraction, 8),
+        "regions": [_serialize_region(r) for r in lr.regions],
+    }
+
+
+def _serialize_region(r: Region) -> dict[str, Any]:
+    bb = r.bounding_box
+    return {
+        "id": r.id,
+        "centroid_x": r.centroid_x,
+        "centroid_y": r.centroid_y,
+        "bbox": {
+            "min_x": bb.min_x,
+            "min_y": bb.min_y,
+            "max_x": bb.max_x,
+            "max_y": bb.max_y,
+        },
+        "pixel_count": r.pixel_count,
+    }

gerberdiff/export/png_export.py

@@ -0,0 +1,92 @@
+"""Export a diff overlay PNG using cairocffi surfaces and numpy.
+
+Colour scheme
+-------------
+- **Red:**   pixels present in image A but not B (geometry removed)
+- **Green:** pixels present in image B but not A (geometry added)
+- **Grey:**  unchanged geometry from image A (only when *show_common=True*)
+- **Black:** background (fully transparent in ARGB32)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import cairocffi as cairo
+import numpy as np
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def build_overlay_png(
+    arr_a: np.ndarray,
+    arr_b: np.ndarray,
+    xor: np.ndarray,
+    output_path: Path,
+    show_common: bool = False,
+    overwrite: bool = False,
+) -> None:
+    """Composite a red/green diff overlay and write it to *output_path*.
+
+    Parameters
+    ----------
+    arr_a:
+        Rendered image A, shape ``(H, W, 4)`` uint8 BGRA (Cairo ARGB32 LE).
+    arr_b:
+        Rendered image B, shape ``(H, W, 4)`` uint8.
+    xor:
+        Channel-wise XOR of *arr_a* and *arr_b* (from ``SingleLayerDiff.xor``).
+    output_path:
+        Destination PNG file path.  Parent directories are created if needed.
+    show_common:
+        When ``True``, unchanged geometry (present in both A and B) is drawn
+        in grey (128, 128, 128) in the output image.
+    overwrite:
+        When ``False`` (default), raises ``FileExistsError`` if *output_path*
+        already exists.
+
+    Raises
+    ------
+    FileExistsError
+        If *output_path* exists and *overwrite* is ``False``.
+    """
+    if output_path.exists() and not overwrite:
+        raise FileExistsError(f"output file already exists: {output_path}")
+
+    height, width = arr_a.shape[:2]
+
+    # --- build boolean masks ------------------------------------------------
+    # Changed wherever any of the first three channels of XOR is non-zero.
+    xor_mask: np.ndarray = np.any(xor[..., :3] > 0, axis=-1)
+
+    # Alpha channels: pixel is "lit" in A or B when alpha > 0.
+    alpha_a: np.ndarray = arr_a[..., 3] > 0
+    alpha_b: np.ndarray = arr_b[..., 3] > 0
+
+    removed = xor_mask & alpha_a & ~alpha_b  # in A, not in B
+    added = xor_mask & alpha_b & ~alpha_a  # in B, not in A
+    if show_common:
+        common = alpha_a & alpha_b & ~xor_mask
+
+    # --- build BGRA output buffer -------------------------------------------
+    out = np.zeros((height, width, 4), dtype=np.uint8)
+
+    # Removed -> red   (B=0, G=0, R=255, A=255  ->  BGRA: [0, 0, 255, 255])
+    out[removed] = [0, 0, 255, 255]
+    # Added   -> green (B=0, G=255, R=0, A=255  ->  BGRA: [0, 255, 0, 255])
+    out[added] = [0, 255, 0, 255]
+    if show_common:
+        out[common] = [128, 128, 128, 255]
+
+    # --- write via cairocffi ImageSurface -----------------------------------
+    surface = cairo.ImageSurface.create_for_data(
+        out,
+        cairo.FORMAT_ARGB32,
+        width,
+        height,
+        width * 4,
+    )
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    surface.write_to_png(str(output_path))

gerberdiff/export/svg_export.py

@@ -0,0 +1,187 @@
+"""Export a geometry diff overlay as an SVG (Cairo-free).
+
+Colour semantics:
+
+- **red** -- removed material (before-state of ``removed`` changes)
+- **green** -- added material (after-state of ``added`` changes)
+- **blue** -- ``moved`` objects: after-state fill plus a displacement line
+  from the before-centroid to the after-centroid
+- **orange** -- ``resized`` objects: after-state fill, before-state outline
+
+Y axis is flipped (Gerber +Y up -> SVG +Y down).  Polygon interiors (holes)
+are preserved via even-odd fill paths.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+from shapely.geometry import MultiPolygon, Polygon
+from shapely.geometry.base import BaseGeometry
+
+from gerberdiff.geometry.types import GeometryChange, LayerGeometryDiff
+
+_Sx = Callable[[float], float]
+
+_COLOR_REMOVED = "#cc0000"
+_COLOR_ADDED = "#00aa00"
+_COLOR_MOVED = "#0066cc"
+_COLOR_RESIZED = "#cc6600"
+
+_FILL_OPACITY = 0.85
+_PAD_FRACTION = 0.05
+
+
+def write_geometry_svg(
+    layer: LayerGeometryDiff,
+    output_path: Path,
+    *,
+    canvas_px: int = 1600,
+    overwrite: bool = False,
+) -> None:
+    """Write an SVG overlay of *layer*'s changes to *output_path*.
+
+    Raises
+    ------
+    FileExistsError
+        If *output_path* already exists and *overwrite* is ``False``.
+    """
+    if output_path.exists() and not overwrite:
+        raise FileExistsError(f"output file already exists: {output_path}")
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(render_geometry_svg(layer, canvas_px=canvas_px), encoding="utf-8")
+
+
+def render_geometry_svg(layer: LayerGeometryDiff, *, canvas_px: int = 1600) -> str:
+    """Render *layer*'s changes to an SVG document string."""
+    geoms: list[BaseGeometry] = []
+    for c in layer.changes:
+        if c.before_geom is not None:
+            geoms.append(c.before_geom)
+        if c.after_geom is not None:
+            geoms.append(c.after_geom)
+
+    if not geoms:
+        return (
+            "<svg xmlns='http://www.w3.org/2000/svg' width='64' height='64'>"
+            f"<title>{_escape(layer.name)}: no changes</title></svg>"
+        )
+
+    min_x = min(g.bounds[0] for g in geoms)
+    min_y = min(g.bounds[1] for g in geoms)
+    max_x = max(g.bounds[2] for g in geoms)
+    max_y = max(g.bounds[3] for g in geoms)
+    span = max(max_x - min_x, max_y - min_y, 1e-6)
+    pad = span * _PAD_FRACTION
+    min_x -= pad
+    min_y -= pad
+    max_x += pad
+    max_y += pad
+
+    scale = canvas_px / max(max_x - min_x, max_y - min_y)
+    width = (max_x - min_x) * scale
+    height = (max_y - min_y) * scale
+
+    def sx(x: float) -> float:
+        return (x - min_x) * scale
+
+    def sy(y: float) -> float:  # Gerber +Y up -> SVG +Y down
+        return (max_y - y) * scale
+
+    parts: list[str] = [
+        f"<svg xmlns='http://www.w3.org/2000/svg' width='{width:.0f}' "
+        f"height='{height:.0f}' viewBox='0 0 {width:.0f} {height:.0f}'>",
+        f"<title>{_escape(layer.name)}</title>",
+        f"<rect width='{width:.0f}' height='{height:.0f}' fill='white'/>",
+    ]
+    for c in layer.changes:
+        parts.extend(_change_svg(c, sx, sy))
+    parts.append(_legend())
+    parts.append("</svg>")
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _change_svg(c: GeometryChange, sx: _Sx, sy: _Sx) -> list[str]:
+    parts: list[str] = []
+    if c.kind == "removed" and c.before_geom is not None:
+        parts.append(_geom_path(c.before_geom, _COLOR_REMOVED, _FILL_OPACITY, sx, sy))
+    elif c.kind == "added" and c.after_geom is not None:
+        parts.append(_geom_path(c.after_geom, _COLOR_ADDED, _FILL_OPACITY, sx, sy))
+    elif c.kind == "moved" and c.after_geom is not None:
+        parts.append(_geom_path(c.after_geom, _COLOR_MOVED, _FILL_OPACITY, sx, sy))
+        if c.before_geom is not None:
+            bc = c.before_geom.centroid
+            ac = c.after_geom.centroid
+            parts.append(
+                f"<line x1='{sx(bc.x):.1f}' y1='{sy(bc.y):.1f}' "
+                f"x2='{sx(ac.x):.1f}' y2='{sy(ac.y):.1f}' "
+                f"stroke='{_COLOR_MOVED}' stroke-width='1.5'/>"
+            )
+    elif c.kind == "resized":
+        if c.after_geom is not None:
+            parts.append(_geom_path(c.after_geom, _COLOR_RESIZED, _FILL_OPACITY, sx, sy))
+        if c.before_geom is not None:
+            parts.append(_geom_path(c.before_geom, "none", 0.0, sx, sy, stroke=_COLOR_RESIZED))
+    return [p for p in parts if p]
+
+
+def _geom_path(
+    geom: BaseGeometry,
+    fill: str,
+    opacity: float,
+    sx: _Sx,
+    sy: _Sx,
+    stroke: str | None = None,
+) -> str:
+    """One even-odd <path> for all polygon rings (exteriors + holes)."""
+    polys: list[Polygon]
+    if isinstance(geom, Polygon):
+        polys = [geom]
+    elif isinstance(geom, MultiPolygon):
+        polys = list(geom.geoms)
+    else:
+        polys = [g for g in getattr(geom, "geoms", []) if isinstance(g, Polygon)]
+
+    d_parts: list[str] = []
+    for poly in polys:
+        if poly.is_empty:
+            continue
+        rings = [poly.exterior, *poly.interiors]
+        for ring in rings:
+            coords = " L ".join(f"{sx(x):.2f},{sy(y):.2f}" for x, y in ring.coords)
+            d_parts.append(f"M {coords} Z")
+    if not d_parts:
+        return ""
+    stroke_attr = f" stroke='{stroke}' stroke-width='1'" if stroke else " stroke='none'"
+    return (
+        f"<path d='{' '.join(d_parts)}' fill='{fill}' fill-opacity='{opacity}' "
+        f"fill-rule='evenodd'{stroke_attr}/>"
+    )
+
+
+def _legend() -> str:
+    rows = [
+        (_COLOR_REMOVED, "removed"),
+        (_COLOR_ADDED, "added"),
+        (_COLOR_MOVED, "moved"),
+        (_COLOR_RESIZED, "resized"),
+    ]
+    items = [
+        "<g font-family='sans-serif' font-size='16'>",
+        "<rect x='8' y='8' width='120' height='98' fill='white' stroke='#888'/>",
+    ]
+    for i, (color, label) in enumerate(rows):
+        y = 30 + i * 22
+        items.append(f"<text x='20' y='{y}' fill='{color}'>{label}</text>")
+    items.append("</g>")
+    return "".join(items)
+
+
+def _escape(text: str) -> str:
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")

gerberdiff/geometry/__init__.py

@@ -0,0 +1,37 @@
+"""Geometry-aware diff engine: resolution-independent, attributed changes.
+
+Public surface:
+
+- :func:`compute_geometry_diff` -- directory-vs-directory geometry diff.
+- :class:`GeometryChange`, :class:`LayerGeometryDiff`,
+  :class:`GeometryDiffResult` -- result types.
+
+The geometry pipeline operates on the parsed IR and is Cairo-free; see
+``docs/geometry-diff.md`` for the design.
+"""
+
+from gerberdiff.geometry.driver import (
+    DEFAULT_AREA_TOL,
+    DEFAULT_DUST_AREA_MM2,
+    DEFAULT_GATE_RADIUS_MM,
+    DEFAULT_MOVE_TOL_MM,
+    compute_geometry_diff,
+)
+from gerberdiff.geometry.types import (
+    ChangeKind,
+    GeometryChange,
+    GeometryDiffResult,
+    LayerGeometryDiff,
+)
+
+__all__ = [
+    "DEFAULT_AREA_TOL",
+    "DEFAULT_DUST_AREA_MM2",
+    "DEFAULT_GATE_RADIUS_MM",
+    "DEFAULT_MOVE_TOL_MM",
+    "ChangeKind",
+    "GeometryChange",
+    "GeometryDiffResult",
+    "LayerGeometryDiff",
+    "compute_geometry_diff",
+]