kicad-sch-api 0.3.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

kicad_sch_api/geometry/symbol_bbox.py

@@ -0,0 +1,608 @@
+"""
+symbol_bbox.py
+
+Calculate accurate bounding boxes for KiCad symbols based on their graphical elements.
+This ensures proper spacing and collision detection in schematic layouts.
+
+Migrated from circuit-synth to kicad-sch-api for better architectural separation.
+"""
+
+import logging
+import math
+import os
+from typing import Any, Dict, List, Optional, Tuple
+
+from .font_metrics import (
+    DEFAULT_PIN_LENGTH,
+    DEFAULT_PIN_NAME_OFFSET,
+    DEFAULT_PIN_NUMBER_SIZE,
+    DEFAULT_PIN_TEXT_WIDTH_RATIO,
+    DEFAULT_TEXT_HEIGHT,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SymbolBoundingBoxCalculator:
+    """Calculate the actual bounding box of a symbol from its graphical elements."""
+
+    # Re-export font metrics as class constants for backward compatibility
+    DEFAULT_TEXT_HEIGHT = DEFAULT_TEXT_HEIGHT
+    DEFAULT_PIN_LENGTH = DEFAULT_PIN_LENGTH
+    DEFAULT_PIN_NAME_OFFSET = DEFAULT_PIN_NAME_OFFSET
+    DEFAULT_PIN_NUMBER_SIZE = DEFAULT_PIN_NUMBER_SIZE
+    DEFAULT_PIN_TEXT_WIDTH_RATIO = DEFAULT_PIN_TEXT_WIDTH_RATIO
+
+    @classmethod
+    def calculate_bounding_box(
+        cls,
+        symbol_data: Dict[str, Any],
+        include_properties: bool = True,
+        hierarchical_labels: Optional[List[Dict[str, Any]]] = None,
+        pin_net_map: Optional[Dict[str, str]] = None,
+    ) -> Tuple[float, float, float, float]:
+        """
+        Calculate the actual bounding box of a symbol from its graphical elements.
+
+        Args:
+            symbol_data: Dictionary containing symbol definition from KiCad library
+            include_properties: Whether to include space for Reference/Value labels
+            hierarchical_labels: List of hierarchical labels attached to this symbol
+            pin_net_map: Optional mapping of pin numbers to net names (for accurate label sizing)
+
+        Returns:
+            Tuple of (min_x, min_y, max_x, max_y) in mm
+
+        Raises:
+            ValueError: If symbol data is invalid or bounding box cannot be calculated
+        """
+        if not symbol_data:
+            raise ValueError("Symbol data is None or empty")
+
+        # Use proper logging instead of print statements
+        logger.debug("=== CALCULATING BOUNDING BOX ===")
+        logger.debug(f"include_properties={include_properties}")
+
+        min_x = float("inf")
+        min_y = float("inf")
+        max_x = float("-inf")
+        max_y = float("-inf")
+
+        # Process main symbol shapes (handle both 'shapes' and 'graphics' keys)
+        shapes = symbol_data.get("shapes", []) or symbol_data.get("graphics", [])
+        logger.debug(f"Processing {len(shapes)} main shapes")
+        for shape in shapes:
+            shape_bounds = cls._get_shape_bounds(shape)
+            if shape_bounds:
+                s_min_x, s_min_y, s_max_x, s_max_y = shape_bounds
+                min_x = min(min_x, s_min_x)
+                min_y = min(min_y, s_min_y)
+                max_x = max(max_x, s_max_x)
+                max_y = max(max_y, s_max_y)
+
+        # Process pins (including their labels)
+        pins = symbol_data.get("pins", [])
+        logger.debug(f"Processing {len(pins)} main pins")
+        for pin in pins:
+            pin_bounds = cls._get_pin_bounds(pin, pin_net_map)
+            if pin_bounds:
+                p_min_x, p_min_y, p_max_x, p_max_y = pin_bounds
+                min_x = min(min_x, p_min_x)
+                min_y = min(min_y, p_min_y)
+                max_x = max(max_x, p_max_x)
+                max_y = max(max_y, p_max_y)
+
+        # Process sub-symbols
+        sub_symbols = symbol_data.get("sub_symbols", [])
+        for sub in sub_symbols:
+            # Sub-symbols can have their own shapes and pins (handle both 'shapes' and 'graphics' keys)
+            sub_shapes = sub.get("shapes", []) or sub.get("graphics", [])
+            for shape in sub_shapes:
+                shape_bounds = cls._get_shape_bounds(shape)
+                if shape_bounds:
+                    s_min_x, s_min_y, s_max_x, s_max_y = shape_bounds
+                    min_x = min(min_x, s_min_x)
+                    min_y = min(min_y, s_min_y)
+                    max_x = max(max_x, s_max_x)
+                    max_y = max(max_y, s_max_y)
+
+            sub_pins = sub.get("pins", [])
+            for pin in sub_pins:
+                pin_bounds = cls._get_pin_bounds(pin, pin_net_map)
+                if pin_bounds:
+                    p_min_x, p_min_y, p_max_x, p_max_y = pin_bounds
+                    min_x = min(min_x, p_min_x)
+                    min_y = min(min_y, p_min_y)
+                    max_x = max(max_x, p_max_x)
+                    max_y = max(max_y, p_max_y)
+
+        # Check if we found any geometry
+        if min_x == float("inf") or max_x == float("-inf"):
+            raise ValueError(f"No valid geometry found in symbol data")
+
+        logger.debug(
+            f"After geometry processing: ({min_x:.2f}, {min_y:.2f}) to ({max_x:.2f}, {max_y:.2f})"
+        )
+        logger.debug(f"  Width: {max_x - min_x:.2f}, Height: {max_y - min_y:.2f}")
+
+        # Add small margin for text that might extend beyond shapes
+        margin = 0.254  # 10 mils
+        min_x -= margin
+        min_y -= margin
+        max_x += margin
+        max_y += margin
+
+        # Include space for component properties (Reference, Value, Footprint)
+        if include_properties:
+            # Use adaptive spacing based on component dimensions
+            component_width = max_x - min_x
+            component_height = max_y - min_y
+
+            # Adaptive property width: minimum 10mm or 80% of component width
+            property_width = max(10.0, component_width * 0.8)
+            property_height = cls.DEFAULT_TEXT_HEIGHT
+
+            # Adaptive vertical spacing: minimum 5mm or 10% of component height
+            vertical_spacing_above = max(5.0, component_height * 0.1)
+            vertical_spacing_below = max(10.0, component_height * 0.15)
+
+            # Reference label above
+            min_y -= vertical_spacing_above + property_height
+
+            # Value and Footprint labels below
+            max_y += vertical_spacing_below + property_height
+
+            # Extend horizontally for property text
+            center_x = (min_x + max_x) / 2
+            min_x = min(min_x, center_x - property_width / 2)
+            max_x = max(max_x, center_x + property_width / 2)
+
+        logger.debug(
+            f"Calculated bounding box: ({min_x:.2f}, {min_y:.2f}) to ({max_x:.2f}, {max_y:.2f})"
+        )
+
+        logger.debug(f"FINAL BBOX: ({min_x:.2f}, {min_y:.2f}) to ({max_x:.2f}, {max_y:.2f})")
+        logger.debug(f"  Width: {max_x - min_x:.2f}, Height: {max_y - min_y:.2f}")
+        logger.debug("=" * 50)
+
+        return (min_x, min_y, max_x, max_y)
+
+    @classmethod
+    def calculate_placement_bounding_box(
+        cls,
+        symbol_data: Dict[str, Any],
+    ) -> Tuple[float, float, float, float]:
+        """
+        Calculate bounding box for PLACEMENT purposes - excludes pin labels.
+
+        This method calculates a tighter bounding box that only includes:
+        - Component body (shapes/graphics)
+        - Pin endpoints (without label text)
+        - Small margin for component properties
+
+        Pin label text is excluded because it extends arbitrarily far based on
+        text length and would cause incorrect spacing in text-flow placement.
+
+        Args:
+            symbol_data: Dictionary containing symbol definition from KiCad library
+
+        Returns:
+            Tuple of (min_x, min_y, max_x, max_y) in mm
+
+        Raises:
+            ValueError: If symbol data is invalid or bounding box cannot be calculated
+        """
+        if not symbol_data:
+            raise ValueError("Symbol data is None or empty")
+
+        logger.debug("=== CALCULATING PLACEMENT BOUNDING BOX (NO PIN LABELS) ===")
+
+        min_x = float("inf")
+        min_y = float("inf")
+        max_x = float("-inf")
+        max_y = float("-inf")
+
+        # Process main symbol shapes (handle both 'shapes' and 'graphics' keys)
+        shapes = symbol_data.get("shapes", []) or symbol_data.get("graphics", [])
+        logger.debug(f"Processing {len(shapes)} main shapes")
+        for shape in shapes:
+            shape_bounds = cls._get_shape_bounds(shape)
+            if shape_bounds:
+                s_min_x, s_min_y, s_max_x, s_max_y = shape_bounds
+                min_x = min(min_x, s_min_x)
+                min_y = min(min_y, s_min_y)
+                max_x = max(max_x, s_max_x)
+                max_y = max(max_y, s_max_y)
+
+        # Process pins WITHOUT labels (just pin endpoints)
+        pins = symbol_data.get("pins", [])
+        logger.debug(f"Processing {len(pins)} main pins (NO LABELS)")
+        for pin in pins:
+            pin_bounds = cls._get_pin_bounds_no_labels(pin)
+            if pin_bounds:
+                p_min_x, p_min_y, p_max_x, p_max_y = pin_bounds
+                min_x = min(min_x, p_min_x)
+                min_y = min(min_y, p_min_y)
+                max_x = max(max_x, p_max_x)
+                max_y = max(max_y, p_max_y)
+
+        # Process sub-symbols
+        sub_symbols = symbol_data.get("sub_symbols", [])
+        for sub in sub_symbols:
+            # Sub-symbols can have their own shapes and pins
+            sub_shapes = sub.get("shapes", []) or sub.get("graphics", [])
+            for shape in sub_shapes:
+                shape_bounds = cls._get_shape_bounds(shape)
+                if shape_bounds:
+                    s_min_x, s_min_y, s_max_x, s_max_y = shape_bounds
+                    min_x = min(min_x, s_min_x)
+                    min_y = min(min_y, s_min_y)
+                    max_x = max(max_x, s_max_x)
+                    max_y = max(max_y, s_max_y)
+
+            sub_pins = sub.get("pins", [])
+            for pin in sub_pins:
+                pin_bounds = cls._get_pin_bounds_no_labels(pin)
+                if pin_bounds:
+                    p_min_x, p_min_y, p_max_x, p_max_y = pin_bounds
+                    min_x = min(min_x, p_min_x)
+                    min_y = min(min_y, p_min_y)
+                    max_x = max(max_x, p_max_x)
+                    max_y = max(max_y, p_max_y)
+
+        # Check if we found any geometry
+        if min_x == float("inf") or max_x == float("-inf"):
+            raise ValueError(f"No valid geometry found in symbol data")
+
+        logger.debug(
+            f"After geometry processing: ({min_x:.2f}, {min_y:.2f}) to ({max_x:.2f}, {max_y:.2f})"
+        )
+        logger.debug(f"  Width: {max_x - min_x:.2f}, Height: {max_y - min_y:.2f}")
+
+        # Add small margin for visual spacing
+        margin = 0.635  # 25mil margin (reduced from 50mil)
+        min_x -= margin
+        min_y -= margin
+        max_x += margin
+        max_y += margin
+
+        # Add minimal space for component properties (Reference above, Value below)
+        # Use adaptive spacing based on component height for better visual hierarchy
+        component_height = max_y - min_y
+        property_spacing = max(
+            3.0, component_height * 0.15
+        )  # Adaptive: minimum 3mm or 15% of height
+        property_height = 1.27  # Reduced from 2.54mm
+        min_y -= property_spacing + property_height  # Reference above
+        max_y += property_spacing + property_height  # Value below
+
+        logger.debug(
+            f"FINAL PLACEMENT BBOX: ({min_x:.2f}, {min_y:.2f}) to ({max_x:.2f}, {max_y:.2f})"
+        )
+        logger.debug(f"  Width: {max_x - min_x:.2f}, Height: {max_y - min_y:.2f}")
+        logger.debug("=" * 50)
+
+        return (min_x, min_y, max_x, max_y)
+
+    @classmethod
+    def calculate_visual_bounding_box(
+        cls, symbol_data: Dict[str, Any], pin_net_map: Optional[Dict[str, str]] = None
+    ) -> Tuple[float, float, float, float]:
+        """
+        Calculate bounding box for visual/debug drawing (includes pin labels, no property spacing).
+
+        This shows the actual component geometry including pin labels.
+        Use this for drawing bounding boxes on schematics.
+
+        Args:
+            symbol_data: Dictionary containing symbol definition
+            pin_net_map: Optional mapping of pin numbers to net names (for accurate label sizing)
+
+        Returns:
+            Tuple of (min_x, min_y, max_x, max_y) in mm
+        """
+        # Initialize bounds
+        min_x = float("inf")
+        min_y = float("inf")
+        max_x = float("-inf")
+        max_y = float("-inf")
+
+        # Process main symbol shapes
+        shapes = symbol_data.get("shapes", []) or symbol_data.get("graphics", [])
+        for shape in shapes:
+            shape_bounds = cls._get_shape_bounds(shape)
+            if shape_bounds:
+                s_min_x, s_min_y, s_max_x, s_max_y = shape_bounds
+                min_x = min(min_x, s_min_x)
+                min_y = min(min_y, s_min_y)
+                max_x = max(max_x, s_max_x)
+                max_y = max(max_y, s_max_y)
+
+        # Process pins WITH labels to get accurate visual bounds
+        pins = symbol_data.get("pins", [])
+        for pin in pins:
+            pin_bounds = cls._get_pin_bounds(pin, pin_net_map)
+            if pin_bounds:
+                p_min_x, p_min_y, p_max_x, p_max_y = pin_bounds
+                min_x = min(min_x, p_min_x)
+                min_y = min(min_y, p_min_y)
+                max_x = max(max_x, p_max_x)
+                max_y = max(max_y, p_max_y)
+
+        # Process sub-symbols
+        sub_symbols = symbol_data.get("sub_symbols", [])
+        for sub in sub_symbols:
+            sub_shapes = sub.get("shapes", []) or sub.get("graphics", [])
+            for shape in sub_shapes:
+                shape_bounds = cls._get_shape_bounds(shape)
+                if shape_bounds:
+                    s_min_x, s_min_y, s_max_x, s_max_y = shape_bounds
+                    min_x = min(min_x, s_min_x)
+                    min_y = min(min_y, s_min_y)
+                    max_x = max(max_x, s_max_x)
+                    max_y = max(max_y, s_max_y)
+
+            sub_pins = sub.get("pins", [])
+            for pin in sub_pins:
+                pin_bounds = cls._get_pin_bounds(pin, pin_net_map)
+                if pin_bounds:
+                    p_min_x, p_min_y, p_max_x, p_max_y = pin_bounds
+                    min_x = min(min_x, p_min_x)
+                    min_y = min(min_y, p_min_y)
+                    max_x = max(max_x, p_max_x)
+                    max_y = max(max_y, p_max_y)
+
+        # Check if we found any geometry
+        if min_x == float("inf") or max_x == float("-inf"):
+            raise ValueError(f"No valid geometry found in symbol data")
+
+        # Add only a tiny margin for visibility (no property spacing)
+        margin = 0.254  # 10mil minimal margin
+        min_x -= margin
+        min_y -= margin
+        max_x += margin
+        max_y += margin
+
+        return (min_x, min_y, max_x, max_y)
+
+    @classmethod
+    def get_symbol_dimensions(
+        cls,
+        symbol_data: Dict[str, Any],
+        include_properties: bool = True,
+        pin_net_map: Optional[Dict[str, str]] = None,
+    ) -> Tuple[float, float]:
+        """
+        Get the width and height of a symbol.
+
+        Args:
+            symbol_data: Dictionary containing symbol definition
+            include_properties: Whether to include space for Reference/Value labels
+            pin_net_map: Optional mapping of pin numbers to net names
+
+        Returns:
+            Tuple of (width, height) in mm
+        """
+        min_x, min_y, max_x, max_y = cls.calculate_bounding_box(
+            symbol_data, include_properties, pin_net_map=pin_net_map
+        )
+        width = max_x - min_x
+        height = max_y - min_y
+        return (width, height)
+
+    @classmethod
+    def _get_shape_bounds(
+        cls, shape: Dict[str, Any]
+    ) -> Optional[Tuple[float, float, float, float]]:
+        """Get bounding box for a graphical shape."""
+        shape_type = shape.get("shape_type", "")
+
+        if shape_type == "rectangle":
+            start = shape.get("start", [0, 0])
+            end = shape.get("end", [0, 0])
+            return (
+                min(start[0], end[0]),
+                min(start[1], end[1]),
+                max(start[0], end[0]),
+                max(start[1], end[1]),
+            )
+
+        elif shape_type == "circle":
+            center = shape.get("center", [0, 0])
+            radius = shape.get("radius", 0)
+            return (
+                center[0] - radius,
+                center[1] - radius,
+                center[0] + radius,
+                center[1] + radius,
+            )
+
+        elif shape_type == "arc":
+            # For arcs, we need to consider start, mid, and end points
+            start = shape.get("start", [0, 0])
+            mid = shape.get("mid", [0, 0])
+            end = shape.get("end", [0, 0])
+
+            # Simple approach: use bounding box of all three points
+            # More accurate would be to calculate the actual arc bounds
+            min_x = min(start[0], mid[0], end[0])
+            min_y = min(start[1], mid[1], end[1])
+            max_x = max(start[0], mid[0], end[0])
+            max_y = max(start[1], mid[1], end[1])
+
+            return (min_x, min_y, max_x, max_y)
+
+        elif shape_type == "polyline":
+            points = shape.get("points", [])
+            if not points:
+                return None
+
+            min_x = min(p[0] for p in points)
+            min_y = min(p[1] for p in points)
+            max_x = max(p[0] for p in points)
+            max_y = max(p[1] for p in points)
+
+            return (min_x, min_y, max_x, max_y)
+
+        elif shape_type == "text":
+            # Text bounding box estimation
+            at = shape.get("at", [0, 0])
+            text = shape.get("text", "")
+            # Rough estimation: each character is about 1.27mm wide
+            text_width = len(text) * cls.DEFAULT_TEXT_HEIGHT * 0.6
+            text_height = cls.DEFAULT_TEXT_HEIGHT
+
+            return (
+                at[0] - text_width / 2,
+                at[1] - text_height / 2,
+                at[0] + text_width / 2,
+                at[1] + text_height / 2,
+            )
+
+        return None
+
+    @classmethod
+    def _get_pin_bounds(
+        cls, pin: Dict[str, Any], pin_net_map: Optional[Dict[str, str]] = None
+    ) -> Optional[Tuple[float, float, float, float]]:
+        """Get bounding box for a pin including its labels."""
+
+        # Handle both formats: 'at' array or separate x/y/orientation
+        if "at" in pin:
+            at = pin.get("at", [0, 0])
+            x, y = at[0], at[1]
+            angle = at[2] if len(at) > 2 else 0
+        else:
+            # Handle the format from symbol cache
+            x = pin.get("x", 0)
+            y = pin.get("y", 0)
+            angle = pin.get("orientation", 0)
+
+        length = pin.get("length", cls.DEFAULT_PIN_LENGTH)
+
+        # Calculate pin endpoint based on angle
+        angle_rad = math.radians(angle)
+        end_x = x + length * math.cos(angle_rad)
+        end_y = y + length * math.sin(angle_rad)
+
+        # Start with pin line bounds
+        min_x = min(x, end_x)
+        min_y = min(y, end_y)
+        max_x = max(x, end_x)
+        max_y = max(y, end_y)
+
+        # Add space for pin name and number
+        pin_name = pin.get("name", "")
+        pin_number = pin.get("number", "")
+
+        # Use net name for label sizing if available (hierarchical labels show net names, not pin names)
+        # If no net name match, use minimal fallback to avoid oversized bounding boxes
+        if pin_net_map and pin_number in pin_net_map:
+            label_text = pin_net_map[pin_number]
+            logger.debug(
+                f"  PIN {pin_number}: ✅ USING NET '{label_text}' (len={len(label_text)}), at=({x:.2f}, {y:.2f}), angle={angle}"
+            )
+        else:
+            # No net match - use minimal size (3 chars) instead of potentially long pin name
+            label_text = "XXX"  # 3-character placeholder for unmatched pins
+            logger.debug(
+                f"  PIN {pin_number}: ⚠️  NO MATCH, using minimal fallback (pin name was '{pin_name}'), at=({x:.2f}, {y:.2f})"
+            )
+
+        if label_text and label_text != "~":  # ~ means no name
+            # Calculate text dimensions
+            # For horizontal text: width = char_count * char_width
+            name_width = (
+                len(label_text) * cls.DEFAULT_TEXT_HEIGHT * cls.DEFAULT_PIN_TEXT_WIDTH_RATIO
+            )
+            # For vertical text: height = char_count * char_height (characters stack vertically)
+            name_height = len(label_text) * cls.DEFAULT_TEXT_HEIGHT
+
+            logger.debug(
+                f"    label_width={name_width:.2f}, label_height={name_height:.2f} (len={len(label_text)})"
+            )
+
+            # Adjust bounds based on pin orientation
+            # Labels are placed at PIN ENDPOINT with offset, extending AWAY from the component
+            # Pin angle indicates where the pin points (into component)
+            # Apply KiCad's standard pin name offset (0.508mm / 20 mils)
+            offset = cls.DEFAULT_PIN_NAME_OFFSET
+
+            if angle == 0:  # Pin points right - label extends LEFT from endpoint
+                label_x = end_x - offset - name_width
+                logger.debug(
+                    f"    Angle 0 (Right pin): min_x {min_x:.2f} -> {label_x:.2f} (offset={offset:.3f})"
+                )
+                min_x = min(min_x, label_x)
+            elif angle == 180:  # Pin points left - label extends RIGHT from endpoint
+                label_x = end_x + offset + name_width
+                logger.debug(
+                    f"    Angle 180 (Left pin): max_x {max_x:.2f} -> {label_x:.2f} (offset={offset:.3f})"
+                )
+                max_x = max(max_x, label_x)
+            elif angle == 90:  # Pin points up - label extends DOWN from endpoint
+                label_y = end_y - offset - name_height
+                logger.debug(
+                    f"    Angle 90 (Up pin): min_y {min_y:.2f} -> {label_y:.2f} (offset={offset:.3f})"
+                )
+                min_y = min(min_y, label_y)
+            elif angle == 270:  # Pin points down - label extends UP from endpoint
+                label_y = end_y + offset + name_height
+                logger.debug(
+                    f"    Angle 270 (Down pin): max_y {max_y:.2f} -> {label_y:.2f} (offset={offset:.3f})"
+                )
+                max_y = max(max_y, label_y)
+
+        # Pin numbers are typically placed near the component body
+        if pin_number:
+            num_width = (
+                len(pin_number) * cls.DEFAULT_PIN_NUMBER_SIZE * cls.DEFAULT_PIN_TEXT_WIDTH_RATIO
+            )
+            # Add some space for the pin number
+            margin = cls.DEFAULT_PIN_NUMBER_SIZE * 1.5  # Increase margin for better spacing
+            min_x -= margin
+            min_y -= margin
+            max_x += margin
+            max_y += margin
+
+        logger.debug(f"    Pin bounds: ({min_x:.2f}, {min_y:.2f}) to ({max_x:.2f}, {max_y:.2f})")
+        return (min_x, min_y, max_x, max_y)
+
+    @classmethod
+    def _get_pin_bounds_no_labels(
+        cls, pin: Dict[str, Any]
+    ) -> Optional[Tuple[float, float, float, float]]:
+        """Get bounding box for a pin WITHOUT labels - for placement calculations only."""
+
+        # Handle both formats: 'at' array or separate x/y/orientation
+        if "at" in pin:
+            at = pin.get("at", [0, 0])
+            x, y = at[0], at[1]
+            angle = at[2] if len(at) > 2 else 0
+        else:
+            # Handle the format from symbol cache
+            x = pin.get("x", 0)
+            y = pin.get("y", 0)
+            angle = pin.get("orientation", 0)
+
+        length = pin.get("length", cls.DEFAULT_PIN_LENGTH)
+
+        # Calculate pin endpoint based on angle
+        angle_rad = math.radians(angle)
+        end_x = x + length * math.cos(angle_rad)
+        end_y = y + length * math.sin(angle_rad)
+
+        # Only include the pin line itself - NO labels
+        min_x = min(x, end_x)
+        min_y = min(y, end_y)
+        max_x = max(x, end_x)
+        max_y = max(y, end_y)
+
+        # Add small margin for pin graphics (circles, etc)
+        margin = 0.5  # Small margin for pin endpoint graphics
+        min_x -= margin
+        min_y -= margin
+        max_x += margin
+        max_y += margin
+
+        return (min_x, min_y, max_x, max_y)

kicad_sch_api/interfaces/__init__.py

@@ -0,0 +1,17 @@
+"""
+Core interfaces for KiCAD schematic API.
+
+This module provides abstract interfaces for the main components of the system,
+enabling better separation of concerns and testability.
+"""
+
+from .parser import IElementParser, ISchematicParser
+from .repository import ISchematicRepository
+from .resolver import ISymbolResolver
+
+__all__ = [
+    "IElementParser",
+    "ISchematicParser",
+    "ISchematicRepository",
+    "ISymbolResolver",
+]

kicad_sch_api/interfaces/parser.py

@@ -0,0 +1,76 @@
+"""
+Parser interfaces for S-expression elements.
+
+These interfaces define the contract for parsing different types of KiCAD
+S-expression elements, enabling modular and testable parsing.
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Protocol, Union
+
+
+class IElementParser(Protocol):
+    """Interface for parsing individual S-expression elements."""
+
+    def can_parse(self, element: List[Any]) -> bool:
+        """
+        Check if this parser can handle the given S-expression element.
+
+        Args:
+            element: S-expression element (list with type as first item)
+
+        Returns:
+            True if this parser can handle the element type
+        """
+        ...
+
+    def parse(self, element: List[Any]) -> Optional[Dict[str, Any]]:
+        """
+        Parse an S-expression element into a dictionary representation.
+
+        Args:
+            element: S-expression element to parse
+
+        Returns:
+            Parsed element as dictionary, or None if parsing failed
+
+        Raises:
+            ParseError: If element is malformed or cannot be parsed
+        """
+        ...
+
+
+class ISchematicParser(Protocol):
+    """Interface for high-level schematic parsing operations."""
+
+    def parse_file(self, filepath: Union[str, Path]) -> Dict[str, Any]:
+        """
+        Parse a complete KiCAD schematic file.
+
+        Args:
+            filepath: Path to the .kicad_sch file
+
+        Returns:
+            Complete schematic data structure
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ParseError: If file format is invalid
+        """
+        ...
+
+    def parse_string(self, content: str) -> Dict[str, Any]:
+        """
+        Parse schematic content from a string.
+
+        Args:
+            content: S-expression content as string
+
+        Returns:
+            Complete schematic data structure
+
+        Raises:
+            ParseError: If content format is invalid
+        """
+        ...