gerberdiff 0.29.0__py3-none-any.whl

gerberdiff/parse/gerber_state.py

@@ -0,0 +1,780 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from gerberdiff.parse.arc_math import (
+    arc_bounding_box,
+    compute_arc_multi_quadrant,
+    compute_arc_single_quadrant,
+)
+from gerberdiff.parse.gerber_parser import (
+    FormatStatement,
+    convert_coordinate,
+    parse_aperture_definition,
+    parse_format_statement,
+)
+from gerberdiff.parse.macro_parser import MacroDef, parse_macro_body
+from gerberdiff.parse.tokenizer import TokenType, tokenize_gerber
+from gerberdiff.types import (
+    Aperture,
+    ApertureState,
+    BlockAperture,
+    BoundingBox,
+    CircleAperture,
+    CoordinateMode,
+    CoordState,
+    Diagnostic,
+    DiagnosticSeverity,
+    DrawOp,
+    InterpolationMode,
+    LayerState,
+    MirrorState,
+    ObroundAperture,
+    ParsedImage,
+    Polarity,
+    PolygonAperture,
+    RectangleAperture,
+    RegionFill,
+    StepAndRepeat,
+    UnitType,
+    ZeroOmission,
+)
+
+# Default format statement used when no %FS...% is present in the file.
+# FSLAX25Y25 is the most common real-world default.
+_DEFAULT_FORMAT = FormatStatement(
+    zero_omission=ZeroOmission.Leading,
+    coordinate_mode=CoordinateMode.Absolute,
+    x_integer=2,
+    x_decimal=5,
+    y_integer=2,
+    y_decimal=5,
+)
+
+# Two-character prefix strings that begin a top-level extended command.
+# Any EXTENDED token whose prefix is NOT in this set, when we're inside a
+# macro definition, is treated as a macro body line.
+_COMMAND_PREFIXES: frozenset[str] = frozenset(
+    [
+        "FS",
+        "MO",
+        "AD",
+        "AM",
+        "LP",
+        "LM",
+        "LR",
+        "LS",
+        "LN",
+        "SR",
+        "AB",
+        "TO",
+        "TA",
+        "TD",
+        "TF",
+        "IA",
+        "AS",
+        "MI",
+        "OF",
+        "SF",
+    ]
+)
+
+
+@dataclass
+class _BlockFrame:
+    """Saved state for a single level of block-aperture nesting."""
+
+    d_code: int
+    block_ap: BlockAperture
+    saved_nets: list[DrawOp | RegionFill]
+    saved_layers: list[LayerState]
+    saved_apertures: dict[int, Aperture]
+    saved_bbox: BoundingBox
+    saved_layer_idx: int
+    saved_net_state_idx: int
+    saved_current_aperture: int
+    saved_aperture_state: ApertureState
+    saved_interpolation: InterpolationMode
+    saved_multi_quadrant: bool
+    saved_unit: UnitType
+    saved_macro_map: dict[str, MacroDef]
+
+
+# ---------------------------------------------------------------------------
+# Internal parser class
+# ---------------------------------------------------------------------------
+
+
+class _GerberParser:
+    """Stateful RS-274X parser.  Instantiate once per file; call parse()."""
+
+    def __init__(self, source_path: Path | None) -> None:
+        # ---- accumulated output ----
+        self._fmt: FormatStatement = _DEFAULT_FORMAT
+        self._fmt_seen: bool = False
+        self._apertures: dict[int, Aperture] = {}
+        self._nets: list[DrawOp | RegionFill] = []
+        self._layers: list[LayerState] = [LayerState()]
+        self._net_states: list[CoordState] = [CoordState()]
+        self._bbox: BoundingBox = BoundingBox()
+        self._diagnostics: list[Diagnostic] = []
+        self._source_path = source_path
+
+        # ---- drawing cursor ----
+        self._prev_x: float = 0.0
+        self._prev_y: float = 0.0
+
+        # per-block raw coordinate storage (reset each END_OF_BLOCK)
+        self._raw_x_int: int = 0
+        self._raw_x_str: str = "0"
+        self._raw_y_int: int = 0
+        self._raw_y_str: str = "0"
+        self._raw_i_int: int = 0
+        self._raw_i_str: str = "0"
+        self._raw_j_int: int = 0
+        self._raw_j_str: str = "0"
+        self._x_in_block: bool = False
+        self._y_in_block: bool = False
+        self._i_in_block: bool = False
+        self._j_in_block: bool = False
+        self._coord_changed: bool = False
+
+        # ---- drawing state ----
+        self._current_aperture: int = 0
+        self._aperture_state: ApertureState = ApertureState.Off
+        self._interpolation: InterpolationMode = InterpolationMode.Linear
+        self._multi_quadrant: bool = False
+        self._in_region_fill: bool = False
+        self._region_start_layer_idx: int = 0
+        self._region_start_net_state_idx: int = 0
+        self._region_segments: list[DrawOp] = []
+        self._current_layer_idx: int = 0
+        self._current_net_state_idx: int = 0
+        self._unit: UnitType = UnitType.Inch
+        self._done: bool = False
+
+        # ---- macro assembly ----
+        self._macro_map: dict[str, MacroDef] = {}
+        self._macro_name: str | None = None
+        self._macro_lines: list[str] = []
+
+        # ---- object / aperture attributes ----
+        self._net_attrs: dict[str, str] = {}
+        self._aperture_attrs: dict[str, str] = {}
+
+        # ---- block aperture stack ----
+        # Each frame saves state so that when %AB*% closes the block the
+        # parent drawing context is fully restored.
+        self._block_stack: list[_BlockFrame] = []
+
+    # ------------------------------------------------------------------
+    # Small helpers
+    # ------------------------------------------------------------------
+
+    def _warn(self, msg: str, line: int | None = None) -> None:
+        self._diagnostics.append(Diagnostic(DiagnosticSeverity.Warning, msg, line))
+
+    def _error(self, msg: str, line: int | None = None) -> None:
+        self._diagnostics.append(Diagnostic(DiagnosticSeverity.Error, msg, line))
+
+    def _info(self, msg: str, line: int | None = None) -> None:
+        self._diagnostics.append(Diagnostic(DiagnosticSeverity.Info, msg, line))
+
+    def _current_layer(self) -> LayerState:
+        return self._layers[self._current_layer_idx]
+
+    def _convert_x(self, raw_int: int, raw_str: str) -> float:
+        return convert_coordinate(
+            raw_int,
+            raw_str,
+            self._fmt.x_integer,
+            self._fmt.x_decimal,
+            self._fmt.zero_omission,
+            self._unit,
+        )
+
+    def _convert_y(self, raw_int: int, raw_str: str) -> float:
+        return convert_coordinate(
+            raw_int,
+            raw_str,
+            self._fmt.y_integer,
+            self._fmt.y_decimal,
+            self._fmt.zero_omission,
+            self._unit,
+        )
+
+    def _aperture_radius(self) -> float:
+        ap = self._apertures.get(self._current_aperture)
+        if ap is None:
+            return 0.0
+        if isinstance(ap, CircleAperture):
+            return ap.diameter / 2.0
+        if isinstance(ap, (RectangleAperture, ObroundAperture)):
+            return max(ap.width, ap.height) / 2.0
+        if isinstance(ap, PolygonAperture):
+            return ap.outer_diameter / 2.0
+        # MacroAperture, BlockAperture: conservative -- renderer computes exact bbox
+        return 0.0
+
+    def _flush_macro(self) -> None:
+        if self._macro_name is None:
+            return
+        body = "*".join(self._macro_lines)
+        try:
+            mdef = parse_macro_body(self._macro_name, body)
+            self._macro_map[self._macro_name] = mdef
+        except Exception as exc:
+            self._error(f"Macro parse failed for {self._macro_name!r}: {exc}")
+        self._macro_name = None
+        self._macro_lines = []
+
+    def _reset_block(self) -> None:
+        """Reset per-block state after END_OF_BLOCK."""
+        self._x_in_block = False
+        self._y_in_block = False
+        self._i_in_block = False
+        self._j_in_block = False
+        self._coord_changed = False
+
+    # ------------------------------------------------------------------
+    # Net emission
+    # ------------------------------------------------------------------
+
+    def _emit_net(self) -> None:
+        fmt = self._fmt
+
+        # Resolve stop position (use prev if coordinate not updated this block)
+        if self._x_in_block:
+            stop_x = self._convert_x(self._raw_x_int, self._raw_x_str)
+            if fmt.coordinate_mode == CoordinateMode.Incremental:
+                stop_x += self._prev_x
+        else:
+            stop_x = self._prev_x
+
+        if self._y_in_block:
+            stop_y = self._convert_y(self._raw_y_int, self._raw_y_str)
+            if fmt.coordinate_mode == CoordinateMode.Incremental:
+                stop_y += self._prev_y
+        else:
+            stop_y = self._prev_y
+
+        # Arc centre offsets (I uses X format, J uses Y format per RS-274X spec)
+        arc_i = self._convert_x(self._raw_i_int, self._raw_i_str) if self._i_in_block else 0.0
+        arc_j = self._convert_y(self._raw_j_int, self._raw_j_str) if self._j_in_block else 0.0
+
+        # Compute arc geometry when drawing in arc mode
+        arc_segment = None
+        if self._aperture_state == ApertureState.On and self._interpolation in (
+            InterpolationMode.ClockwiseCircular,
+            InterpolationMode.CounterClockwiseCircular,
+        ):
+            clockwise = self._interpolation == InterpolationMode.ClockwiseCircular
+            if self._multi_quadrant:
+                arc_segment = compute_arc_multi_quadrant(
+                    self._prev_x,
+                    self._prev_y,
+                    stop_x,
+                    stop_y,
+                    arc_i,
+                    arc_j,
+                    clockwise,
+                )
+            else:
+                arc_segment = compute_arc_single_quadrant(
+                    self._prev_x,
+                    self._prev_y,
+                    stop_x,
+                    stop_y,
+                    arc_i,
+                    arc_j,
+                    clockwise,
+                )
+
+        net = DrawOp(
+            start_x=self._prev_x,
+            start_y=self._prev_y,
+            stop_x=stop_x,
+            stop_y=stop_y,
+            aperture_index=self._current_aperture,
+            aperture_state=self._aperture_state,
+            interpolation=self._interpolation,
+            layer_index=self._current_layer_idx,
+            net_state_index=self._current_net_state_idx,
+            arc_segment=arc_segment,
+            attributes=dict(self._net_attrs) if self._net_attrs else None,
+        )
+        if self._in_region_fill:
+            self._region_segments.append(net)
+        else:
+            self._nets.append(net)
+
+        # Expand bounding box
+        r = self._aperture_radius()
+        if arc_segment is not None:
+            ab = arc_bounding_box(arc_segment, r)
+            self._bbox.expand(ab.min_x, ab.min_y)
+            self._bbox.expand(ab.max_x, ab.max_y)
+        else:
+            self._bbox.expand(stop_x, stop_y, r)
+            if self._aperture_state == ApertureState.On:
+                self._bbox.expand(self._prev_x, self._prev_y, r)
+
+        # Also expand for all step-and-repeat instances of the current layer.
+        sr = self._current_layer().step_and_repeat
+        if sr.x > 1 or sr.y > 1:
+            for ix in range(sr.x):
+                for iy in range(sr.y):
+                    if ix == 0 and iy == 0:
+                        continue  # already handled above
+                    ox, oy = ix * sr.dist_x, iy * sr.dist_y
+                    self._bbox.expand(stop_x + ox, stop_y + oy, r)
+                    if self._aperture_state == ApertureState.On:
+                        self._bbox.expand(self._prev_x + ox, self._prev_y + oy, r)
+
+        self._prev_x = stop_x
+        self._prev_y = stop_y
+
+    # ------------------------------------------------------------------
+    # Token handlers
+    # ------------------------------------------------------------------
+
+    def _handle_g_code(self, value: int, line: int) -> None:
+        if value == 1:
+            self._interpolation = InterpolationMode.Linear
+        elif value == 2:
+            self._interpolation = InterpolationMode.ClockwiseCircular
+        elif value == 3:
+            self._interpolation = InterpolationMode.CounterClockwiseCircular
+        elif value == 36:
+            self._in_region_fill = True
+            self._region_start_layer_idx = self._current_layer_idx
+            self._region_start_net_state_idx = self._current_net_state_idx
+            self._region_segments = []
+        elif value == 37:
+            self._in_region_fill = False
+            self._nets.append(
+                RegionFill(
+                    layer_index=self._region_start_layer_idx,
+                    net_state_index=self._region_start_net_state_idx,
+                    segments=self._region_segments,
+                )
+            )
+            self._region_segments = []
+        elif value in (54, 55, 70, 71):
+            # 54/55: deprecated aperture select/flash -- ignore
+            # 70/71: deprecated inch/mm (should use MO instead) -- update unit
+            if value == 70:
+                self._unit = UnitType.Inch
+            elif value == 71:
+                self._unit = UnitType.Millimeter
+        elif value == 74:
+            self._multi_quadrant = False
+        elif value == 75:
+            self._multi_quadrant = True
+        elif value == 90:
+            self._fmt = FormatStatement(
+                zero_omission=self._fmt.zero_omission,
+                coordinate_mode=CoordinateMode.Absolute,
+                x_integer=self._fmt.x_integer,
+                x_decimal=self._fmt.x_decimal,
+                y_integer=self._fmt.y_integer,
+                y_decimal=self._fmt.y_decimal,
+            )
+        elif value == 91:
+            self._fmt = FormatStatement(
+                zero_omission=self._fmt.zero_omission,
+                coordinate_mode=CoordinateMode.Incremental,
+                x_integer=self._fmt.x_integer,
+                x_decimal=self._fmt.x_decimal,
+                y_integer=self._fmt.y_integer,
+                y_decimal=self._fmt.y_decimal,
+            )
+        else:
+            self._warn(f"Unknown G code G{value:02d}", line)
+
+    def _handle_d_code(self, value: int, line: int) -> None:
+        if value == 1:
+            self._aperture_state = ApertureState.On
+            self._coord_changed = True
+        elif value == 2:
+            self._aperture_state = ApertureState.Off
+            self._coord_changed = True
+        elif value == 3:
+            self._aperture_state = ApertureState.Flash
+            self._coord_changed = True
+        elif value >= 10:
+            self._current_aperture = value
+        else:
+            self._warn(f"Unknown D code D{value:02d}", line)
+
+    def _handle_extended(self, body: str, line: int) -> None:
+        prefix = body[:2].upper()
+
+        # When accumulating a macro body, all unrecognised token bodies are
+        # macro primitive / assignment lines.  Any top-level command ends it.
+        if self._macro_name is not None:
+            if prefix not in _COMMAND_PREFIXES:
+                self._macro_lines.append(body)
+                return
+            # Recognised command -- flush macro first, then dispatch normally
+            self._flush_macro()
+
+        if prefix == "FS":
+            fs = parse_format_statement(body)
+            if fs is None:
+                self._warn(f"Could not parse format statement: {body!r}", line)
+            else:
+                self._fmt = fs
+                self._fmt_seen = True
+
+        elif prefix == "MO":
+            code = body[2:4].upper()
+            if code == "IN":
+                self._unit = UnitType.Inch
+            elif code == "MM":
+                self._unit = UnitType.Millimeter
+            # Push a NetState capturing the unit change
+            self._net_states.append(CoordState(unit=self._unit))
+            self._current_net_state_idx = len(self._net_states) - 1
+
+        elif prefix == "AD":
+            result = parse_aperture_definition(body, self._unit, self._macro_map)
+            if result is None:
+                self._warn(f"Could not parse aperture definition: {body!r}", line)
+            elif isinstance(result, str):
+                # result == "MACRO_NOT_FOUND:<name>" -- the aperture is permanently absent
+                macro_name = result.split(":", 1)[1] if ":" in result else result
+                self._error(f"Aperture definition references undefined macro {macro_name!r}", line)
+            else:
+                d_code, aperture = result
+                self._apertures[d_code] = aperture
+                self._aperture_attrs = {}  # aperture attributes consumed
+
+        elif prefix == "AM":
+            # Start a new macro definition
+            name = body[2:].strip()
+            if name:
+                self._macro_name = name
+                self._macro_lines = []
+
+        elif prefix == "LP":
+            code = body[2:3].upper()
+            polarity = Polarity.Clear if code == "C" else Polarity.Dark
+            prev = self._current_layer()
+            new_layer = LayerState(
+                polarity=polarity,
+                rotation=prev.rotation,
+                mirror=prev.mirror,
+                scale=prev.scale,
+                name=prev.name,
+            )
+            self._layers.append(new_layer)
+            self._current_layer_idx = len(self._layers) - 1
+
+        elif prefix == "LM":
+            code = body[2:].strip().upper()
+            mirror = {
+                "N": MirrorState.None_,
+                "X": MirrorState.FlipA,
+                "Y": MirrorState.FlipB,
+                "XY": MirrorState.FlipAB,
+            }.get(code, MirrorState.None_)
+            self._current_layer().mirror = mirror
+
+        elif prefix == "LR":
+            try:
+                self._current_layer().rotation = float(body[2:])
+            except ValueError:
+                self._warn(f"Invalid LR value: {body!r}", line)
+
+        elif prefix == "LS":
+            try:
+                self._current_layer().scale = float(body[2:])
+            except ValueError:
+                self._warn(f"Invalid LS value: {body!r}", line)
+
+        elif prefix == "LN":
+            self._current_layer().name = body[2:]
+
+        elif prefix == "SR":
+            self._handle_sr(body[2:], line)
+
+        elif prefix == "AB":
+            self._handle_ab(body[2:], line)
+
+        elif prefix == "TO":
+            # Object attribute: %TO.<name>,<value>*%
+            rest = body[2:]
+            if rest.startswith("."):
+                comma = rest.find(",")
+                if comma > 0:
+                    self._net_attrs[rest[1:comma]] = rest[comma + 1 :]
+
+        elif prefix == "TA":
+            # Aperture attribute
+            rest = body[2:]
+            if rest.startswith("."):
+                comma = rest.find(",")
+                if comma > 0:
+                    self._aperture_attrs[rest[1:comma]] = rest[comma + 1 :]
+
+        elif prefix == "TD":
+            # Delete attribute(s)
+            name = body[2:].strip()
+            if name:
+                self._net_attrs.pop(name.lstrip("."), None)
+                self._aperture_attrs.pop(name.lstrip("."), None)
+            else:
+                self._net_attrs.clear()
+                self._aperture_attrs.clear()
+
+        elif prefix == "TF":
+            pass  # File attribute -- informational, ignored
+
+        elif prefix in ("IA", "AS", "MI", "OF", "SF"):
+            self._info(f"Deprecated RS-274X command {prefix!r} ignored; transforms not applied")
+
+        else:
+            self._warn(f"Unknown extended command prefix {prefix!r}", line)
+
+    def _handle_ab(self, params: str, line: int) -> None:
+        """Open or close a block aperture definition.
+
+        ``%ABD<n>*%`` opens a block for D-code *n*; ``%AB*%`` closes it.
+        Nesting is supported up to depth 10 (matches the reference tool).
+        """
+        body = params.strip()
+        if body:
+            # Open: %ABD<n>*%
+            if not body.upper().startswith("D"):
+                self._warn(f"Invalid aperture block spec: {body!r}", line)
+                return
+            try:
+                d_code = int(body[1:])
+            except ValueError:
+                self._warn(f"Invalid aperture block D-code: {body!r}", line)
+                return
+            if d_code < 10:
+                self._warn(f"Invalid aperture block D-code: D{d_code} (must be >=10)", line)
+                return
+            if len(self._block_stack) >= 10:
+                self._warn("Aperture block nesting too deep (max 10)", line)
+                return
+
+            block_ap = BlockAperture()
+
+            # Save parent state and redirect emission into the block.
+            self._block_stack.append(
+                _BlockFrame(
+                    d_code=d_code,
+                    block_ap=block_ap,
+                    saved_nets=self._nets,
+                    saved_layers=self._layers,
+                    saved_apertures=self._apertures,
+                    saved_bbox=self._bbox,
+                    saved_layer_idx=self._current_layer_idx,
+                    saved_net_state_idx=self._current_net_state_idx,
+                    saved_current_aperture=self._current_aperture,
+                    saved_aperture_state=self._aperture_state,
+                    saved_interpolation=self._interpolation,
+                    saved_multi_quadrant=self._multi_quadrant,
+                    saved_unit=self._unit,
+                    saved_macro_map=self._macro_map,
+                )
+            )
+
+            # Block gets a fresh single-layer state and an empty bbox.
+            block_ap.layers.append(LayerState())
+            self._nets = block_ap.draw_ops
+            self._layers = block_ap.layers
+            self._current_layer_idx = 0
+            # Copy parent apertures so the block can reference them.
+            self._apertures = dict(self._apertures)
+            self._bbox = BoundingBox()
+            # Reset drawing cursor state to safe defaults inside the block.
+            self._current_aperture = 0
+            self._aperture_state = ApertureState.Off
+            self._interpolation = InterpolationMode.Linear
+            self._multi_quadrant = False
+            # Block gets a copy of the macro map; new macros defined inside
+            # the block do not leak back to the parent.
+            self._macro_map = dict(self._macro_map)
+
+        else:
+            # Close: %AB*%
+            if not self._block_stack:
+                self._warn("Unexpected AB close without matching open", line)
+                return
+            frame = self._block_stack.pop()
+
+            # Capture the block's accumulated state.
+            frame.block_ap.apertures = self._apertures
+            frame.block_ap.bounding_box = self._bbox
+
+            # Restore parent state.
+            self._nets = frame.saved_nets
+            self._layers = frame.saved_layers
+            self._apertures = frame.saved_apertures
+            self._bbox = frame.saved_bbox
+            self._current_layer_idx = frame.saved_layer_idx
+            self._current_net_state_idx = frame.saved_net_state_idx
+            self._current_aperture = frame.saved_current_aperture
+            self._aperture_state = frame.saved_aperture_state
+            self._interpolation = frame.saved_interpolation
+            self._multi_quadrant = frame.saved_multi_quadrant
+            self._unit = frame.saved_unit
+            self._macro_map = frame.saved_macro_map
+
+            # Register the completed block aperture in the parent aperture dict.
+            self._apertures[frame.d_code] = frame.block_ap
+
+    def _handle_sr(self, params: str, line: int) -> None:
+        """Handle the SR body after stripping the 'SR' prefix."""
+        if not params.strip():
+            # Close SR block -- push a new layer that copies the parent's
+            # polarity/rotation/mirror/scale/name but resets step_and_repeat.
+            prev = self._current_layer()
+            new_layer = LayerState(
+                polarity=prev.polarity,
+                rotation=prev.rotation,
+                mirror=prev.mirror,
+                scale=prev.scale,
+                name=prev.name,
+                # step_and_repeat intentionally left at default (1, 1, 0, 0)
+            )
+            self._layers.append(new_layer)
+            self._current_layer_idx = len(self._layers) - 1
+            return
+
+        # Parse SRX<count>Y<count>I<step>J<step>
+        x_count = y_count = 1
+        step_x = step_y = 0.0
+        s = params.strip()
+        pos = 0
+        while pos < len(s):
+            letter = s[pos].upper()
+            if letter not in "XYIJ":
+                pos += 1
+                continue
+            pos += 1
+            j = pos
+            while j < len(s) and s[j] not in "XYIJxyij":
+                j += 1
+            try:
+                val = float(s[pos:j])
+                if letter == "X":
+                    x_count = max(1, int(val))
+                elif letter == "Y":
+                    y_count = max(1, int(val))
+                elif letter == "I":
+                    step_x = val / 25.4 if self._unit == UnitType.Millimeter else val
+                elif letter == "J":
+                    step_y = val / 25.4 if self._unit == UnitType.Millimeter else val
+            except ValueError:
+                self._warn(f"Invalid SR parameter {letter}={s[pos:j]!r}", line)
+            pos = j
+
+        self._current_layer().step_and_repeat = StepAndRepeat(
+            x=x_count,
+            y=y_count,
+            dist_x=step_x,
+            dist_y=step_y,
+        )
+
+    # ------------------------------------------------------------------
+    # Main parse loop
+    # ------------------------------------------------------------------
+
+    def parse(self, content: str) -> ParsedImage:
+        for token in tokenize_gerber(content):
+            if self._done:
+                break
+            tt = token.type
+            line = token.line
+
+            if tt == TokenType.G:
+                if isinstance(token.value, int):
+                    self._handle_g_code(token.value, line)
+
+            elif tt == TokenType.D:
+                if isinstance(token.value, int):
+                    self._handle_d_code(token.value, line)
+
+            elif tt == TokenType.M:
+                if isinstance(token.value, int) and token.value == 2:
+                    if self._in_region_fill:
+                        self._warn("Region fill not closed at end of file", line)
+                    self._done = True
+                    break
+
+            elif tt == TokenType.X:
+                if isinstance(token.value, int):
+                    self._raw_x_int = token.value
+                    self._raw_x_str = token.raw or str(token.value)
+                    self._x_in_block = True
+                    self._coord_changed = True
+
+            elif tt == TokenType.Y:
+                if isinstance(token.value, int):
+                    self._raw_y_int = token.value
+                    self._raw_y_str = token.raw or str(token.value)
+                    self._y_in_block = True
+                    self._coord_changed = True
+
+            elif tt == TokenType.I:
+                if isinstance(token.value, int):
+                    self._raw_i_int = token.value
+                    self._raw_i_str = token.raw or str(token.value)
+                    self._i_in_block = True
+
+            elif tt == TokenType.J:
+                if isinstance(token.value, int):
+                    self._raw_j_int = token.value
+                    self._raw_j_str = token.raw or str(token.value)
+                    self._j_in_block = True
+
+            elif tt == TokenType.END_OF_BLOCK:
+                if self._coord_changed:
+                    self._emit_net()
+                self._reset_block()
+
+            elif tt == TokenType.EXTENDED:
+                if isinstance(token.value, str):
+                    self._handle_extended(token.value, line)
+
+            elif tt == TokenType.EOF:
+                if self._in_region_fill:
+                    self._warn("Region fill not closed at end of file", line)
+                break
+
+        # Final cleanup
+        self._flush_macro()
+
+        if not self._fmt_seen:
+            self._info("No format statement found; using default FSLAX25Y25")
+
+        return ParsedImage(
+            draw_ops=self._nets,
+            apertures=self._apertures,
+            layers=self._layers,
+            coord_states=self._net_states,
+            bounding_box=self._bbox,
+            diagnostics=self._diagnostics,
+            source_path=self._source_path,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def parse_gerber(content: str, source_path: Path | None = None) -> ParsedImage:
+    """Parse a Gerber RS-274X file string into a ParsedImage.
+
+    All diagnostics (errors, warnings, info) are collected on
+    ``image.diagnostics``.  This function never raises for parse-level
+    problems; only genuine Python-level exceptions (e.g. MemoryError) propagate.
+    """
+    return _GerberParser(source_path).parse(content)