gerberdiff 0.29.0__py3-none-any.whl

gerberdiff/render/macro_renderer.py

@@ -0,0 +1,343 @@
+from __future__ import annotations
+
+import math
+import warnings
+
+import cairocffi as cairo
+
+from gerberdiff.parse.macro_parser import (
+    EvaluatedCircle,
+    EvaluatedLineCenter,
+    EvaluatedLineVector,
+    EvaluatedMoire,
+    EvaluatedOutline,
+    EvaluatedPolygon,
+    EvaluatedThermal,
+    evaluate_macro_primitives,
+)
+from gerberdiff.types import MacroAperture
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def draw_macro_flash(
+    ctx: cairo.Context,
+    x: float,
+    y: float,
+    aperture: MacroAperture,
+) -> None:
+    """Draw a macro aperture flash at world position (x, y).
+
+    Evaluates all primitives in the macro definition and draws each using
+    cairocffi path operations.  Primitive exposure 0 -> DEST_OUT (erase);
+    exposure 1 -> OPERATOR_OVER (add).  All dimensions are scaled by
+    ``aperture.unit_scale``.
+    """
+    if aperture.macro_def is None:
+        return
+    try:
+        primitives = evaluate_macro_primitives(aperture.macro_def, aperture.params)
+    except Exception as exc:
+        warnings.warn(
+            f"Macro '{aperture.macro_def.name}' evaluation failed: {exc}",
+            UserWarning,
+            stacklevel=2,
+        )
+        return
+
+    scale = aperture.unit_scale
+    for p in primitives:
+        match p:
+            case EvaluatedCircle():
+                _draw_circle(ctx, x, y, p, scale)
+            case EvaluatedLineVector():
+                _draw_line_vector(ctx, x, y, p, scale)
+            case EvaluatedLineCenter():
+                _draw_line_center(ctx, x, y, p, scale)
+            case EvaluatedOutline():
+                _draw_outline(ctx, x, y, p, scale)
+            case EvaluatedPolygon():
+                _draw_polygon(ctx, x, y, p, scale)
+            case EvaluatedMoire():
+                _draw_moire(ctx, x, y, p, scale)
+            case EvaluatedThermal():
+                _draw_thermal(ctx, x, y, p, scale)
+
+
+def compute_macro_bounding_radius(aperture: MacroAperture) -> float:
+    """Estimate the bounding radius of a macro aperture in world units.
+
+    Returns the maximum reach from the origin across all evaluated primitives,
+    multiplied by ``aperture.unit_scale``.  Returns 0.0 if the macro cannot
+    be evaluated.
+    """
+    if aperture.macro_def is None:
+        return 0.0
+    try:
+        primitives = evaluate_macro_primitives(aperture.macro_def, aperture.params)
+    except Exception:  # pragma: no cover
+        return 0.0
+
+    max_r = 0.0
+    for p in primitives:
+        r: float = 0.0
+        match p:
+            case EvaluatedCircle():
+                r = math.hypot(p.center_x, p.center_y) + p.diameter / 2.0
+            case EvaluatedPolygon():
+                r = math.hypot(p.center_x, p.center_y) + p.diameter / 2.0
+            case EvaluatedLineVector():
+                r = (
+                    max(
+                        math.hypot(p.start_x, p.start_y),
+                        math.hypot(p.end_x, p.end_y),
+                    )
+                    + p.width / 2.0
+                )
+            case EvaluatedLineCenter():
+                r = math.hypot(p.center_x, p.center_y) + math.hypot(p.width / 2.0, p.height / 2.0)
+            case EvaluatedMoire():
+                r = math.hypot(p.center_x, p.center_y) + p.outer_diameter / 2.0
+            case EvaluatedThermal():
+                r = math.hypot(p.center_x, p.center_y) + p.outer_diameter / 2.0
+            case EvaluatedOutline():
+                verts = p.vertices
+                if len(verts) >= 2:
+                    r = max(math.hypot(verts[i], verts[i + 1]) for i in range(0, len(verts) - 1, 2))
+        if r > max_r:
+            max_r = r
+
+    return max_r * aperture.unit_scale
+
+
+# ---------------------------------------------------------------------------
+# Exposure helper
+# ---------------------------------------------------------------------------
+
+
+def _apply_exposure(ctx: cairo.Context, exposure: float) -> None:
+    if exposure == 0.0:
+        ctx.set_operator(cairo.OPERATOR_DEST_OUT)
+    else:
+        ctx.set_operator(cairo.OPERATOR_OVER)
+
+
+# ---------------------------------------------------------------------------
+# Per-primitive drawing helpers
+# ---------------------------------------------------------------------------
+
+
+def _draw_circle(ctx: cairo.Context, x: float, y: float, p: EvaluatedCircle, scale: float) -> None:
+    cx = x + p.center_x * scale
+    cy = y + p.center_y * scale
+    r = (p.diameter / 2.0) * scale
+    if r <= 0.0:
+        return
+    ctx.save()
+    _apply_exposure(ctx, p.exposure)
+    ctx.new_path()
+    ctx.arc(cx, cy, r, 0.0, 2.0 * math.pi)
+    ctx.fill()
+    ctx.restore()
+
+
+def _draw_line_vector(
+    ctx: cairo.Context, x: float, y: float, p: EvaluatedLineVector, scale: float
+) -> None:
+    """Rotated rectangle spanning start->end with width p.width."""
+    sx = x + p.start_x * scale
+    sy = y + p.start_y * scale
+    ex = x + p.end_x * scale
+    ey = y + p.end_y * scale
+    w2 = (p.width / 2.0) * scale
+    dx = ex - sx
+    dy = ey - sy
+    length = math.hypot(dx, dy)
+    if length == 0.0:
+        return
+    # Perpendicular unit vector scaled to half-width
+    nx = -dy / length * w2
+    ny = dx / length * w2
+    # Overall primitive rotation applied around the flash origin (x, y)
+    rot = math.radians(p.rotation)
+    cos_r = math.cos(rot)
+    sin_r = math.sin(rot)
+
+    def _rot(px: float, py: float) -> tuple[float, float]:
+        rx = x + cos_r * (px - x) - sin_r * (py - y)
+        ry = y + sin_r * (px - x) + cos_r * (py - y)
+        return rx, ry
+
+    corners = [
+        _rot(sx + nx, sy + ny),
+        _rot(sx - nx, sy - ny),
+        _rot(ex - nx, ey - ny),
+        _rot(ex + nx, ey + ny),
+    ]
+    ctx.save()
+    _apply_exposure(ctx, p.exposure)
+    ctx.new_path()
+    ctx.move_to(*corners[0])
+    for corner_x, corner_y in corners[1:]:
+        ctx.line_to(corner_x, corner_y)
+    ctx.close_path()
+    ctx.fill()
+    ctx.restore()
+
+
+def _draw_line_center(
+    ctx: cairo.Context, x: float, y: float, p: EvaluatedLineCenter, scale: float
+) -> None:
+    """Centred rectangle, optionally rotated."""
+    center_x = x + p.center_x * scale
+    center_y = y + p.center_y * scale
+    w2 = (p.width / 2.0) * scale
+    h2 = (p.height / 2.0) * scale
+    ctx.save()
+    _apply_exposure(ctx, p.exposure)
+    ctx.translate(center_x, center_y)
+    ctx.rotate(math.radians(p.rotation))
+    ctx.new_path()
+    ctx.rectangle(-w2, -h2, p.width * scale, p.height * scale)
+    ctx.fill()
+    ctx.restore()
+
+
+def _draw_outline(
+    ctx: cairo.Context, x: float, y: float, p: EvaluatedOutline, scale: float
+) -> None:
+    """Arbitrary polygon from flat vertex list [x0, y0, x1, y1, ...]."""
+    if len(p.vertices) < 4:
+        return
+    verts = [v * scale for v in p.vertices]
+    ctx.save()
+    _apply_exposure(ctx, p.exposure)
+    ctx.translate(x, y)
+    ctx.rotate(math.radians(p.rotation))
+    ctx.new_path()
+    for i in range(0, len(verts) - 1, 2):
+        vx, vy = verts[i], verts[i + 1]
+        if i == 0:
+            ctx.move_to(vx, vy)
+        else:
+            ctx.line_to(vx, vy)
+    ctx.close_path()
+    ctx.fill()
+    ctx.restore()
+
+
+def _draw_polygon(
+    ctx: cairo.Context, x: float, y: float, p: EvaluatedPolygon, scale: float
+) -> None:
+    """Regular n-sided polygon."""
+    center_x = x + p.center_x * scale
+    center_y = y + p.center_y * scale
+    r = (p.diameter / 2.0) * scale
+    if r <= 0.0 or p.num_vertices < 3:
+        return
+    rot = math.radians(p.rotation)
+    ctx.save()
+    _apply_exposure(ctx, p.exposure)
+    ctx.new_path()
+    for i in range(p.num_vertices):
+        angle = rot + 2.0 * math.pi * i / p.num_vertices
+        vx = center_x + r * math.cos(angle)
+        vy = center_y + r * math.sin(angle)
+        if i == 0:
+            ctx.move_to(vx, vy)
+        else:
+            ctx.line_to(vx, vy)
+    ctx.close_path()
+    ctx.fill()
+    ctx.restore()
+
+
+def _draw_moire(ctx: cairo.Context, x: float, y: float, p: EvaluatedMoire, scale: float) -> None:
+    """Concentric rings plus crosshair."""
+    cx = x + p.center_x * scale
+    cy = y + p.center_y * scale
+    outer_r = (p.outer_diameter / 2.0) * scale
+    gap = p.ring_gap * scale
+    thickness = p.ring_thickness * scale
+    rot = math.radians(p.rotation)
+
+    max_rings = p.max_rings if p.max_rings > 0 else 100
+    for i in range(max_rings):
+        r_outer = outer_r - i * (thickness + gap)
+        r_inner = r_outer - thickness
+        if r_outer <= 0.0:
+            break
+        ctx.save()
+        ctx.set_operator(cairo.OPERATOR_OVER)
+        ctx.new_path()
+        ctx.arc(cx, cy, r_outer, 0.0, 2.0 * math.pi)
+        ctx.fill()
+        ctx.restore()
+        if r_inner > 0.0:
+            ctx.save()
+            ctx.set_operator(cairo.OPERATOR_DEST_OUT)
+            ctx.new_path()
+            ctx.arc(cx, cy, r_inner, 0.0, 2.0 * math.pi)
+            ctx.fill()
+            ctx.restore()
+
+    # Crosshair: two perpendicular bars
+    cl = (p.crosshair_length / 2.0) * scale
+    ct = (p.crosshair_thickness / 2.0) * scale
+    if cl > 0.0 and ct > 0.0:
+        for bar_rot in (rot, rot + math.pi / 2.0):
+            ctx.save()
+            ctx.set_operator(cairo.OPERATOR_OVER)
+            ctx.translate(cx, cy)
+            ctx.rotate(bar_rot)
+            ctx.new_path()
+            ctx.rectangle(-cl, -ct, cl * 2.0, ct * 2.0)
+            ctx.fill()
+            ctx.restore()
+
+
+def _draw_thermal(
+    ctx: cairo.Context, x: float, y: float, p: EvaluatedThermal, scale: float
+) -> None:
+    """Annulus (ring) with four rectangular anti-pad gaps."""
+    cx = x + p.center_x * scale
+    cy = y + p.center_y * scale
+    r_outer = (p.outer_diameter / 2.0) * scale
+    r_inner = (p.inner_diameter / 2.0) * scale
+    gap_w = (p.gap / 2.0) * scale
+    rot = math.radians(p.rotation)
+
+    if r_outer <= 0.0:
+        return
+
+    # 1. Filled outer circle
+    ctx.save()
+    ctx.set_operator(cairo.OPERATOR_OVER)
+    ctx.new_path()
+    ctx.arc(cx, cy, r_outer, 0.0, 2.0 * math.pi)
+    ctx.fill()
+    ctx.restore()
+
+    # 2. Cut inner circle -> leaves the ring
+    if r_inner > 0.0:
+        ctx.save()
+        ctx.set_operator(cairo.OPERATOR_DEST_OUT)
+        ctx.new_path()
+        ctx.arc(cx, cy, r_inner, 0.0, 2.0 * math.pi)
+        ctx.fill()
+        ctx.restore()
+
+    # 3. Cut 4 rectangular gaps at 0deg, 90deg, 180deg, 270deg + rotation
+    if gap_w > 0.0:
+        for i in range(4):
+            angle = rot + i * math.pi / 2.0
+            ctx.save()
+            ctx.set_operator(cairo.OPERATOR_DEST_OUT)
+            ctx.translate(cx, cy)
+            ctx.rotate(angle)
+            ctx.new_path()
+            ctx.rectangle(-r_outer, -gap_w, r_outer * 2.0, gap_w * 2.0)
+            ctx.fill()
+            ctx.restore()

gerberdiff/render/renderer.py

@@ -0,0 +1,283 @@
+"""Two-pass rasteriser: compile ParsedImage -> render to a Cairo surface.
+
+Usage
+-----
+>>> from gerberdiff.render.renderer import render_to_surface, render_to_numpy
+>>> from gerberdiff.render.viewport import compute_viewport
+>>> vp = compute_viewport(parsed.bounding_box, width=1024, height=1024)
+>>> surface = render_to_surface(parsed, vp)
+>>> arr = render_to_numpy(parsed, vp)   # shape (H, W, 4) uint8 BGRA
+
+Polarity
+--------
+Layers with ``Polarity.Dark`` are composited with OPERATOR_OVER.
+Layers with ``Polarity.Clear`` are composited with OPERATOR_DEST_OUT, which
+punches holes into previously drawn content.
+"""
+
+from __future__ import annotations
+
+import math
+import weakref
+
+import cairocffi as cairo
+import numpy as np
+
+from gerberdiff.render.compiled_render import (
+    BlockFlash,
+    CompiledGroup,
+    CompiledLayer,
+    CompiledRender,
+    FlashBatch,
+    HoledFlash,
+    MacroFlash,
+    RegionGroup,
+    StrokeBatch,
+)
+from gerberdiff.render.compiled_render import (
+    compile_render as compile_render,
+)
+from gerberdiff.render.draw_ops import (
+    draw_flash,
+    draw_net_as_stroke,
+    draw_net_segment_in_region,
+)
+from gerberdiff.render.macro_renderer import draw_macro_flash
+from gerberdiff.render.viewport import Viewport
+from gerberdiff.types import (
+    Aperture,
+    BlockAperture,
+    CoordState,
+    MacroAperture,
+    MirrorState,
+    ParsedImage,
+    Polarity,
+)
+
+# Default draw colour: bright green (matches reference tool palette).
+_DEFAULT_COLOR: tuple[float, float, float, float] = (0.0, 1.0, 0.533, 1.0)
+
+# Cache of CompiledRender objects for BlockAperture instances.  Keyed by
+# id(block_ap).  A weakref finalizer removes each entry automatically when
+# its BlockAperture is garbage-collected, so stale ids cannot cause hits.
+_block_compile_cache: dict[int, CompiledRender] = {}
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def render_to_surface(
+    parsed_image: ParsedImage,
+    viewport: Viewport,
+    draw_color: tuple[float, float, float, float] = _DEFAULT_COLOR,
+    coordinate_offset: tuple[float, float] | None = None,
+) -> cairo.ImageSurface:
+    """Render *parsed_image* into a new ``cairo.ImageSurface``.
+
+    The surface uses ``FORMAT_ARGB32`` (premultiplied alpha).  Transparent
+    pixels represent the PCB substrate / background.
+
+    *coordinate_offset* shifts the board in world-space (inches) before
+    rendering.  Used by ``compute_diff`` to align two boards with different
+    origins.
+    """
+    surface = cairo.ImageSurface(cairo.FORMAT_ARGB32, viewport.width, viewport.height)
+    ctx = cairo.Context(surface)
+
+    # Start with a fully transparent canvas.
+    ctx.set_operator(cairo.OPERATOR_CLEAR)
+    ctx.paint()
+    ctx.set_operator(cairo.OPERATOR_OVER)
+
+    # Apply viewport transform: pan, then Y-flip + zoom so Gerber's
+    # mathematical Y-up coordinate system maps to screen Y-down.
+    ctx.save()
+    ctx.translate(viewport.pan_x, viewport.pan_y)
+    ctx.scale(viewport.zoom, -viewport.zoom)
+    if coordinate_offset is not None:
+        ctx.translate(coordinate_offset[0], -coordinate_offset[1])
+    # Global draw style.
+    ctx.set_source_rgba(*draw_color)
+    ctx.set_line_join(cairo.LINE_JOIN_ROUND)
+    ctx.set_line_cap(cairo.LINE_CAP_ROUND)
+
+    cr = compile_render(parsed_image)
+    for layer in cr.layers:
+        _render_layer(ctx, layer, parsed_image.apertures)
+
+    ctx.restore()
+    return surface
+
+
+def render_to_numpy(
+    parsed_image: ParsedImage,
+    viewport: Viewport,
+    draw_color: tuple[float, float, float, float] = _DEFAULT_COLOR,
+    coordinate_offset: tuple[float, float] | None = None,
+) -> np.ndarray:
+    """Render to a ``numpy`` array of shape ``(H, W, 4)`` with dtype ``uint8``.
+
+    Channel order is BGRA (Cairo's native ARGB32 little-endian layout).
+    """
+    surface = render_to_surface(parsed_image, viewport, draw_color, coordinate_offset)
+    surface.flush()
+    buf = surface.get_data()
+    arr = np.frombuffer(buf, dtype=np.uint8)
+    # copy() transfers ownership away from the cairo surface buffer so the
+    # returned array remains valid after the surface is garbage-collected.
+    return arr.reshape(viewport.height, viewport.width, 4).copy()
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _render_layer(
+    ctx: cairo.Context,
+    layer: CompiledLayer,
+    apertures: dict[int, Aperture],
+    depth: int = 0,
+) -> None:
+    """Render one compiled layer, applying polarity, transforms, and SR."""
+    ctx.save()
+
+    # Polarity: clear layers punch holes via DEST_OUT.
+    if layer.polarity == Polarity.Clear:
+        ctx.set_operator(cairo.OPERATOR_DEST_OUT)
+
+    # Optional layer-level transforms.
+    # Cairo post-multiplies each call into the CTM, so the last call in code
+    # is the FIRST transform applied to coordinates.  RS-274X sec.4.9 specifies
+    # that coordinates are transformed as: scale -> rotation -> mirror.
+    # Code order must therefore be the reverse: mirror -> rotation -> scale.
+    if layer.mirror != MirrorState.None_:
+        sx = -1.0 if layer.mirror in (MirrorState.FlipA, MirrorState.FlipAB) else 1.0
+        sy = -1.0 if layer.mirror in (MirrorState.FlipB, MirrorState.FlipAB) else 1.0
+        ctx.scale(sx, sy)
+    if layer.rotation != 0.0:
+        ctx.rotate(math.radians(layer.rotation))
+    if layer.scale != 1.0:
+        ctx.scale(layer.scale, layer.scale)
+
+    # Step-and-repeat: only loop when SR counts exceed 1.
+    sr = layer.step_and_repeat
+    if sr.x > 1 or sr.y > 1:
+        for ix in range(sr.x):
+            for iy in range(sr.y):
+                ctx.save()
+                ctx.translate(ix * sr.dist_x, iy * sr.dist_y)
+                _render_groups(ctx, layer.groups, apertures, depth)
+                ctx.restore()
+    else:
+        _render_groups(ctx, layer.groups, apertures, depth)
+
+    ctx.restore()
+
+
+def _render_groups(
+    ctx: cairo.Context,
+    groups: list[CompiledGroup],
+    apertures: dict[int, Aperture],
+    depth: int = 0,
+) -> None:
+    """Execute each compiled group against *ctx*."""
+    for group in groups:
+        match group:
+            case FlashBatch():
+                ap = apertures.get(group.aperture_code)
+                for net in group.nets:
+                    draw_flash(ctx, net, ap)
+
+            case StrokeBatch():
+                ap = apertures.get(group.aperture_code)
+                for net in group.nets:
+                    draw_net_as_stroke(ctx, net, ap)
+
+            case RegionGroup():
+                ctx.save()
+                ctx.set_fill_rule(cairo.FILL_RULE_EVEN_ODD)
+                ctx.new_path()
+                for net in group.nets:
+                    draw_net_segment_in_region(ctx, net)
+                ctx.close_path()
+                ctx.fill()
+                ctx.restore()
+
+            case HoledFlash():
+                if group.net is not None:
+                    ap = apertures.get(group.aperture_code)
+                    draw_flash(ctx, group.net, ap)
+
+            case MacroFlash():
+                if group.net is not None:
+                    ap = apertures.get(group.aperture_code)
+                    if isinstance(ap, MacroAperture):
+                        draw_macro_flash(
+                            ctx,
+                            group.net.stop_x,
+                            group.net.stop_y,
+                            ap,
+                        )
+
+            case BlockFlash():
+                if group.net is not None:
+                    ap = apertures.get(group.aperture_code)
+                    if isinstance(ap, BlockAperture):
+                        _draw_block_flash(
+                            ctx,
+                            group.net.stop_x,
+                            group.net.stop_y,
+                            ap,
+                            depth + 1,
+                        )
+
+
+def _draw_block_flash(
+    ctx: cairo.Context,
+    x: float,
+    y: float,
+    block_ap: BlockAperture,
+    depth: int = 0,
+) -> None:
+    """Render a block aperture flash by recursively compiling and drawing it.
+
+    The block's nets are in its own coordinate system.  Translating by
+    ``(x, y)`` stamps the block at the flash position.
+
+    *depth* tracks the block-nesting level.  Rendering is silently skipped
+    when ``depth >= 10``, matching the parser's nesting limit and preventing
+    unbounded recursion on malformed input.
+    """
+    if depth >= 10:
+        return
+    if not block_ap.draw_ops:
+        return
+
+    # Build a minimal synthetic ParsedImage so compile_render can be reused.
+    # Layer states come from the block's own captured layers (at least one).
+    layers = block_ap.layers if block_ap.layers else []
+    synthetic = ParsedImage(
+        draw_ops=block_ap.draw_ops,
+        apertures=block_ap.apertures,
+        layers=layers,
+        coord_states=[CoordState()],
+        bounding_box=block_ap.bounding_box,
+        diagnostics=[],
+    )
+
+    ctx.save()
+    ctx.translate(x, y)
+    cache_key = id(block_ap)
+    cr = _block_compile_cache.get(cache_key)
+    if cr is None:
+        cr = compile_render(synthetic)
+        _block_compile_cache[cache_key] = cr
+        # Evict the entry automatically when block_ap is garbage-collected so
+        # a future object that reuses the same id cannot get a stale hit.
+        weakref.finalize(block_ap, _block_compile_cache.pop, cache_key, None)
+    for layer in cr.layers:
+        _render_layer(ctx, layer, block_ap.apertures, depth)
+    ctx.restore()

gerberdiff/render/viewport.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from gerberdiff.types import BoundingBox
+
+
+@dataclass
+class Viewport:
+    """Canvas viewport parameters derived from a board's bounding box.
+
+    Coordinate convention:
+        screen_x = pan_x + world_x * zoom
+        screen_y = pan_y - world_y * zoom   (Y-flipped: Gerber +Y is screen up)
+    """
+
+    width: int
+    height: int
+    pan_x: float  # canvas X of the world origin
+    pan_y: float  # canvas Y of the world origin (after Y-flip)
+    zoom: float  # world units -> pixels
+
+
+def compute_viewport(bbox: BoundingBox, width: int, height: int) -> Viewport:
+    """Fit *bbox* into a *width* x *height* canvas with a 10% margin.
+
+    Returns a default viewport (zoom=100, centred) when the bbox is invalid
+    or has zero extent in either axis.
+    """
+    if not bbox.is_valid:
+        return Viewport(
+            width=width,
+            height=height,
+            pan_x=width / 2.0,
+            pan_y=height / 2.0,
+            zoom=100.0,
+        )
+
+    bbox_w = bbox.max_x - bbox.min_x
+    bbox_h = bbox.max_y - bbox.min_y
+
+    if bbox_w <= 0.0 or bbox_h <= 0.0:
+        return Viewport(
+            width=width,
+            height=height,
+            pan_x=width / 2.0,
+            pan_y=height / 2.0,
+            zoom=100.0,
+        )
+
+    zoom = min(width / bbox_w, height / bbox_h) * 0.9
+    center_x = bbox.min_x + bbox_w / 2.0
+    center_y = bbox.min_y + bbox_h / 2.0
+    pan_x = width / 2.0 - center_x * zoom
+    pan_y = height / 2.0 + center_y * zoom  # Y-flip
+
+    return Viewport(width=width, height=height, pan_x=pan_x, pan_y=pan_y, zoom=zoom)
+
+
+def merge_bounding_boxes(a: BoundingBox, b: BoundingBox) -> BoundingBox:
+    """Return the axis-aligned union of two BoundingBoxes.
+
+    If one box is invalid (empty) the other is returned unchanged.
+    If both are invalid the result is also invalid.
+    """
+    result = BoundingBox()
+    if a.is_valid:
+        result.expand(a.min_x, a.min_y)
+        result.expand(a.max_x, a.max_y)
+    if b.is_valid:
+        result.expand(b.min_x, b.min_y)
+        result.expand(b.max_x, b.max_y)
+    return result
+
+
+def screen_to_world(px: float, py: float, vp: Viewport) -> tuple[float, float]:
+    """Convert pixel coordinates back to world (inch) coordinates.
+
+    Inverts the transform:
+        screen_x = pan_x + world_x * zoom
+        screen_y = pan_y - world_y * zoom
+    """
+    world_x = (px - vp.pan_x) / vp.zoom
+    world_y = -(py - vp.pan_y) / vp.zoom
+    return world_x, world_y