kicad-sch-api 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

kicad_sch_api/__init__.py

@@ -42,7 +42,7 @@ Advanced Usage:
         print(f"Found {len(issues)} validation issues")
 """
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 __author__ = "Circuit-Synth"
 __email__ = "info@circuit-synth.com"
 
@@ -55,7 +55,7 @@ from .library.cache import SymbolLibraryCache, get_symbol_cache
 from .utils.validation import ValidationError, ValidationIssue
 
 # Version info
-VERSION_INFO = (0, 3, 2)
+VERSION_INFO = (0, 3, 3)
 
 # Public API
 __all__ = [

kicad_sch_api/core/formatter.py

@@ -146,6 +146,9 @@ class ExactFormatter:
         self.rules["embedded_fonts"] = FormatRule(inline=True)
         self.rules["page"] = FormatRule(inline=True, quote_indices={1})
 
+        # Image element
+        self.rules["image"] = FormatRule(inline=False, custom_handler=self._format_image)
+
     def format(self, data: Any) -> str:
         """
         Format S-expression data with exact KiCAD formatting.
@@ -511,6 +514,34 @@ class ExactFormatter:
         result += f"\n{indent})"
         return result
 
+    def _format_image(self, lst: List[Any], indent_level: int) -> str:
+        """Format image elements with base64 data split across lines."""
+        indent = "\t" * indent_level
+        next_indent = "\t" * (indent_level + 1)
+
+        result = f"({lst[0]}"
+
+        # Process each element
+        for element in lst[1:]:
+            if isinstance(element, list):
+                tag = str(element[0]) if element else ""
+                if tag == "data":
+                    # Special handling for data element
+                    # First chunk on same line as (data, rest on subsequent lines
+                    if len(element) > 1:
+                        result += f'\n{next_indent}({element[0]} "{element[1]}"'
+                        for chunk in element[2:]:
+                            result += f'\n{next_indent}\t"{chunk}"'
+                        result += f"\n{next_indent})"
+                    else:
+                        result += f"\n{next_indent}({element[0]})"
+                else:
+                    # Regular element formatting
+                    result += f"\n{next_indent}{self._format_element(element, indent_level + 1)}"
+
+        result += f"\n{indent})"
+        return result
+
 
 class CompactFormatter(ExactFormatter):
     """Compact formatter for minimal output size."""

kicad_sch_api/core/parser.py

@@ -197,6 +197,7 @@ class SExpressionParser:
             "circles": [],
             "beziers": [],
             "rectangles": [],
+            "images": [],
             "nets": [],
             "lib_symbols": {},
             "sheet_instances": [],
@@ -282,6 +283,10 @@ class SExpressionParser:
                 rectangle = self._parse_rectangle(item)
                 if rectangle:
                     schematic_data["rectangles"].append(rectangle)
+            elif element_type == "image":
+                image = self._parse_image(item)
+                if image:
+                    schematic_data["images"].append(image)
             elif element_type == "lib_symbols":
                 schematic_data["lib_symbols"] = self._parse_lib_symbols(item)
             elif element_type == "sheet_instances":
@@ -357,6 +362,10 @@ class SExpressionParser:
         for graphic in schematic_data.get("graphics", []):
             sexp_data.append(self._graphic_to_sexp(graphic))
 
+        # Images
+        for image in schematic_data.get("images", []):
+            sexp_data.append(self._image_to_sexp(image))
+
         # Circles
         for circle in schematic_data.get("circles", []):
             sexp_data.append(self._circle_to_sexp(circle))
@@ -1108,6 +1117,37 @@ class SExpressionParser:
 
         return rectangle if rectangle else None
 
+    def _parse_image(self, item: List[Any]) -> Optional[Dict[str, Any]]:
+        """Parse an image element."""
+        # Format: (image (at x y) (uuid "...") (data "base64..."))
+        image = {
+            "position": {"x": 0, "y": 0},
+            "data": "",
+            "scale": 1.0,
+            "uuid": None
+        }
+
+        for elem in item[1:]:
+            if not isinstance(elem, list):
+                continue
+
+            elem_type = str(elem[0]) if isinstance(elem[0], sexpdata.Symbol) else None
+
+            if elem_type == "at" and len(elem) >= 3:
+                image["position"] = {"x": float(elem[1]), "y": float(elem[2])}
+            elif elem_type == "scale" and len(elem) >= 2:
+                image["scale"] = float(elem[1])
+            elif elem_type == "data" and len(elem) >= 2:
+                # The data can be spread across multiple string elements
+                data_parts = []
+                for data_elem in elem[1:]:
+                    data_parts.append(str(data_elem).strip('"'))
+                image["data"] = "".join(data_parts)
+            elif elem_type == "uuid" and len(elem) >= 2:
+                image["uuid"] = str(elem[1]).strip('"')
+
+        return image if image.get("uuid") and image.get("data") else None
+
     def _parse_lib_symbols(self, item: List[Any]) -> Dict[str, Any]:
         """Parse lib_symbols section."""
         # Implementation for lib_symbols parsing
@@ -1933,6 +1973,38 @@ class SExpressionParser:
 
         return sexp
 
+    def _image_to_sexp(self, image_data: Dict[str, Any]) -> List[Any]:
+        """Convert image element to S-expression."""
+        sexp = [sexpdata.Symbol("image")]
+
+        # Add position
+        position = image_data.get("position", {"x": 0, "y": 0})
+        pos_x, pos_y = position["x"], position["y"]
+        sexp.append([sexpdata.Symbol("at"), pos_x, pos_y])
+
+        # Add UUID
+        if "uuid" in image_data:
+            sexp.append([sexpdata.Symbol("uuid"), image_data["uuid"]])
+
+        # Add scale if not default
+        scale = image_data.get("scale", 1.0)
+        if scale != 1.0:
+            sexp.append([sexpdata.Symbol("scale"), scale])
+
+        # Add image data
+        # KiCad splits base64 data into multiple lines for readability
+        # Each line is roughly 76 characters (standard base64 line length)
+        data = image_data.get("data", "")
+        if data:
+            data_sexp = [sexpdata.Symbol("data")]
+            # Split the data into 76-character chunks
+            chunk_size = 76
+            for i in range(0, len(data), chunk_size):
+                data_sexp.append(data[i:i+chunk_size])
+            sexp.append(data_sexp)
+
+        return sexp
+
     def _lib_symbols_to_sexp(self, lib_symbols: Dict[str, Any]) -> List[Any]:
         """Convert lib_symbols to S-expression."""
         sexp = [sexpdata.Symbol("lib_symbols")]

kicad_sch_api/core/schematic.py

@@ -1138,6 +1138,55 @@ class Schematic:
         logger.debug(f"Added text box: '{text}' at {position} size {size}")
         return text_box.uuid
 
+    def add_image(
+        self,
+        position: Union[Point, Tuple[float, float]],
+        data: str,
+        scale: float = 1.0,
+        uuid: Optional[str] = None,
+    ) -> str:
+        """
+        Add an image element.
+
+        Args:
+            position: Image position
+            data: Base64-encoded image data
+            scale: Image scale factor (default 1.0)
+            uuid: Optional UUID (auto-generated if None)
+
+        Returns:
+            UUID of created image element
+        """
+        if isinstance(position, tuple):
+            position = Point(position[0], position[1])
+
+        from .types import Image
+
+        import uuid as uuid_module
+
+        image = Image(
+            uuid=uuid if uuid else str(uuid_module.uuid4()),
+            position=position,
+            data=data,
+            scale=scale,
+        )
+
+        if "images" not in self._data:
+            self._data["images"] = []
+
+        self._data["images"].append(
+            {
+                "uuid": image.uuid,
+                "position": {"x": image.position.x, "y": image.position.y},
+                "data": image.data,
+                "scale": image.scale,
+            }
+        )
+        self._modified = True
+
+        logger.debug(f"Added image at {position} with {len(data)} bytes of data")
+        return image.uuid
+
     def add_rectangle(
         self,
         start: Union[Point, Tuple[float, float]],
@@ -1592,9 +1641,7 @@ class Schematic:
                     break
 
         # Fix string/symbol conversion issues in pin definitions
-        print(f"🔧 DEBUG: Before fix - checking for pin definitions...")
         self._fix_symbol_strings_recursively(modified_data)
-        print(f"🔧 DEBUG: After fix - symbol strings fixed")
 
         return modified_data
 
@@ -1607,15 +1654,10 @@ class Schematic:
                 if isinstance(item, list):
                     # Check for pin definitions that need fixing
                     if len(item) >= 3 and item[0] == sexpdata.Symbol("pin"):
-                        print(
-                            f"🔧 DEBUG: Found pin definition: {item[:3]} - types: {[type(x) for x in item[:3]]}"
-                        )
                         # Fix pin type and shape - ensure they are symbols not strings
                         if isinstance(item[1], str):
-                            print(f"🔧 DEBUG: Converting pin type '{item[1]}' to symbol")
                             item[1] = sexpdata.Symbol(item[1])  # pin type: "passive" -> passive
                         if len(item) >= 3 and isinstance(item[2], str):
-                            print(f"🔧 DEBUG: Converting pin shape '{item[2]}' to symbol")
                             item[2] = sexpdata.Symbol(item[2])  # pin shape: "line" -> line
 
                     # Recursively process nested lists

kicad_sch_api/core/types.py

@@ -372,6 +372,20 @@ class SchematicRectangle:
         )
 
 
+@dataclass
+class Image:
+    """Image element in schematic."""
+
+    uuid: str
+    position: Point
+    data: str  # Base64-encoded image data
+    scale: float = 1.0
+
+    def __post_init__(self):
+        if not self.uuid:
+            self.uuid = str(uuid4())
+
+
 @dataclass
 class Net:
     """Electrical net connecting components."""

kicad_sch_api/geometry/__init__.py

@@ -0,0 +1,26 @@
+"""
+Geometry module for KiCad schematic symbol bounding box calculations.
+
+This module provides accurate bounding box calculations for KiCad symbols,
+including font metrics and symbol geometry analysis.
+
+Migrated from circuit-synth to kicad-sch-api for better architectural separation.
+"""
+
+from .font_metrics import (
+    DEFAULT_PIN_LENGTH,
+    DEFAULT_PIN_NAME_OFFSET,
+    DEFAULT_PIN_NUMBER_SIZE,
+    DEFAULT_PIN_TEXT_WIDTH_RATIO,
+    DEFAULT_TEXT_HEIGHT,
+)
+from .symbol_bbox import SymbolBoundingBoxCalculator
+
+__all__ = [
+    "SymbolBoundingBoxCalculator",
+    "DEFAULT_TEXT_HEIGHT",
+    "DEFAULT_PIN_LENGTH",
+    "DEFAULT_PIN_NAME_OFFSET",
+    "DEFAULT_PIN_NUMBER_SIZE",
+    "DEFAULT_PIN_TEXT_WIDTH_RATIO",
+]

kicad_sch_api/geometry/font_metrics.py

@@ -0,0 +1,20 @@
+"""
+Font metrics and text rendering constants for KiCad schematic text.
+
+These constants are used for accurate text bounding box calculations
+and symbol spacing in schematic layouts.
+"""
+
+# KiCad default text size in mm
+# Increased to better match actual KiCad rendering
+DEFAULT_TEXT_HEIGHT = 2.54  # 100 mils (doubled from 50 mils)
+
+# Default pin dimensions
+DEFAULT_PIN_LENGTH = 2.54  # 100 mils
+DEFAULT_PIN_NAME_OFFSET = 0.508  # 20 mils - offset from pin endpoint to label text
+DEFAULT_PIN_NUMBER_SIZE = 1.27  # 50 mils
+
+# Text width ratio for proportional font rendering
+# KiCad uses proportional fonts where average character width is ~0.65x height
+# This prevents label text from extending beyond calculated bounding boxes
+DEFAULT_PIN_TEXT_WIDTH_RATIO = 0.65  # Width to height ratio for pin text (proportional font average)

kicad_sch_api/geometry/symbol_bbox.py

@@ -0,0 +1,595 @@
+"""
+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")
+
+        import sys
+        # Reduced logging frequency - only log if DEBUG environment variable is set
+        debug_enabled = os.getenv("CIRCUIT_SYNTH_DEBUG", "").lower() == "true"
+        if debug_enabled:
+            print(f"\n=== CALCULATING BOUNDING BOX ===", file=sys.stderr, flush=True)
+            print(f"include_properties={include_properties}", file=sys.stderr, flush=True)
+
+        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", [])
+        print(f"Processing {len(shapes)} main shapes", file=sys.stderr, flush=True)
+        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", [])
+        print(f"Processing {len(pins)} main pins", file=sys.stderr, flush=True)
+        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")
+
+        print(f"After geometry processing: ({min_x:.2f}, {min_y:.2f}) to ({max_x:.2f}, {max_y:.2f})", file=sys.stderr, flush=True)
+        print(f"  Width: {max_x - min_x:.2f}, Height: {max_y - min_y:.2f}", file=sys.stderr, flush=True)
+
+        # 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})"
+        )
+
+        print(f"FINAL BBOX: ({min_x:.2f}, {min_y:.2f}) to ({max_x:.2f}, {max_y:.2f})", file=sys.stderr, flush=True)
+        print(f"  Width: {max_x - min_x:.2f}, Height: {max_y - min_y:.2f}", file=sys.stderr, flush=True)
+        print("=" * 50 + "\n", file=sys.stderr, flush=True)
+
+        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")
+
+        import sys
+        print(f"\n=== CALCULATING PLACEMENT BOUNDING BOX (NO PIN LABELS) ===", file=sys.stderr, flush=True)
+
+        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", [])
+        print(f"Processing {len(shapes)} main shapes", file=sys.stderr, flush=True)
+        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", [])
+        print(f"Processing {len(pins)} main pins (NO LABELS)", file=sys.stderr, flush=True)
+        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")
+
+        print(f"After geometry processing: ({min_x:.2f}, {min_y:.2f}) to ({max_x:.2f}, {max_y:.2f})", file=sys.stderr, flush=True)
+        print(f"  Width: {max_x - min_x:.2f}, Height: {max_y - min_y:.2f}", file=sys.stderr, flush=True)
+
+        # 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
+
+        print(f"FINAL PLACEMENT BBOX: ({min_x:.2f}, {min_y:.2f}) to ({max_x:.2f}, {max_y:.2f})", file=sys.stderr, flush=True)
+        print(f"  Width: {max_x - min_x:.2f}, Height: {max_y - min_y:.2f}", file=sys.stderr, flush=True)
+        print("=" * 50 + "\n", file=sys.stderr, flush=True)
+
+        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."""
+        import sys
+
+        # 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]
+            print(f"  PIN {pin_number}: ✅ USING NET '{label_text}' (len={len(label_text)}), at=({x:.2f}, {y:.2f}), angle={angle}", file=sys.stderr, flush=True)
+        else:
+            # No net match - use minimal size (3 chars) instead of potentially long pin name
+            label_text = "XXX"  # 3-character placeholder for unmatched pins
+            print(f"  PIN {pin_number}: ⚠️  NO MATCH, using minimal fallback (pin name was '{pin_name}'), at=({x:.2f}, {y:.2f})", file=sys.stderr, flush=True)
+
+        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
+
+            print(f"    label_width={name_width:.2f}, label_height={name_height:.2f} (len={len(label_text)})", file=sys.stderr, flush=True)
+
+            # 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
+                print(f"    Angle 0 (Right pin): min_x {min_x:.2f} -> {label_x:.2f} (offset={offset:.3f})", file=sys.stderr, flush=True)
+                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
+                print(f"    Angle 180 (Left pin): max_x {max_x:.2f} -> {label_x:.2f} (offset={offset:.3f})", file=sys.stderr, flush=True)
+                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
+                print(f"    Angle 90 (Up pin): min_y {min_y:.2f} -> {label_y:.2f} (offset={offset:.3f})", file=sys.stderr, flush=True)
+                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
+                print(f"    Angle 270 (Down pin): max_y {max_y:.2f} -> {label_y:.2f} (offset={offset:.3f})", file=sys.stderr, flush=True)
+                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
+
+        print(f"    Pin bounds: ({min_x:.2f}, {min_y:.2f}) to ({max_x:.2f}, {max_y:.2f})", file=sys.stderr, flush=True)
+        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."""
+        import sys
+
+        # 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-0.3.2.dist-info → kicad_sch_api-0.3.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kicad-sch-api
-Version: 0.3.2
+Version: 0.3.4
 Summary: Professional KiCAD schematic manipulation library with exact format preservation
 Author-email: Circuit-Synth <shane@circuit-synth.com>
 Maintainer-email: Circuit-Synth <shane@circuit-synth.com>

{kicad_sch_api-0.3.2.dist-info → kicad_sch_api-0.3.4.dist-info}/RECORD

@@ -1,31 +1,34 @@
-kicad_sch_api/__init__.py,sha256=6yDjQeaoOdZatCgDaIULVxwXqT1fjLSNjYU0yKRh9f4,2919
+kicad_sch_api/__init__.py,sha256=87qLx-VMQTBHDVq_CiXW-6wyKtvLFc3AsKQaoLKsIbs,2919
 kicad_sch_api/cli.py,sha256=ZzmwzfHEvPgGfCiQBU4G2LBAyRtMNiBRoY21pivJSYc,7621
 kicad_sch_api/py.typed,sha256=e4ldqxwpY7pNDG1olbvj4HSKr8sZ9vxgA_2ek8xXn-Q,70
 kicad_sch_api/core/__init__.py,sha256=ur_KeYBlGKl-e1hLpLdxAhGV2A-PCCGkcqd0r6KSeBA,566
 kicad_sch_api/core/component_bounds.py,sha256=BFYJYULyzs5it2hN7bHTimyS9Vet4dxsMklRStob-F4,17509
 kicad_sch_api/core/components.py,sha256=tXRL18GObl2u94wl5jP-1ID56s_UD9F1gQ_iRIyZ_Kw,25290
 kicad_sch_api/core/config.py,sha256=itw0j3DeIEHaFVf8p3mfAS1SP6jclBwvMv7NPdkThE4,4309
-kicad_sch_api/core/formatter.py,sha256=7kwM7WdbVjT8biirWSSFO44OMjeByvzYYr_-mpGiEA4,20862
+kicad_sch_api/core/formatter.py,sha256=zzZi0f06C1YWUy5l0WFS9G4KRTEzmAY3rFK3XGocvCo,22185
 kicad_sch_api/core/geometry.py,sha256=27SgN0padLbQuTi8MV6UUCp6Pyaiv8V9gmYDOhfwny8,2947
 kicad_sch_api/core/ic_manager.py,sha256=Kg0HIOMU-TGXiIkrnwcHFQ1Kfv_3rW2U1cwBKJsKopc,7219
 kicad_sch_api/core/junctions.py,sha256=Ay6BsWX_DLs-wB0eMA2CytKKq0N8Ja41ZubJWpAqNgM,6122
 kicad_sch_api/core/manhattan_routing.py,sha256=t_T2u0zsQB-a8dTijFmY-qFq-oDt2qDebYyXzD_pBWI,15989
-kicad_sch_api/core/parser.py,sha256=UMTpwrxtyFM5cjAkgLWts6vBJ254gc4Hvx-puZydkVQ,92209
+kicad_sch_api/core/parser.py,sha256=UY_GNX1yHd3xgTVqZ9TZe1u94q4YZBo-NibsSH8Jy44,94983
 kicad_sch_api/core/pin_utils.py,sha256=XGEow3HzBTyT8a0B_ZC8foMvwzYaENSaqTUwDW1rz24,5417
-kicad_sch_api/core/schematic.py,sha256=U9-wrhuGtgRqZJfc76Dj-g1_ZTjrT8R9LmfX-BIBH8w,61201
+kicad_sch_api/core/schematic.py,sha256=B2n0tf3HyyVzTJOPABpzJGVbd5yBAsI9CE5OVZnSCoI,62027
 kicad_sch_api/core/simple_manhattan.py,sha256=CvIHvwmfABPF-COzhblYxEgRoR_R_eD-lmBFHHjDuMI,7241
-kicad_sch_api/core/types.py,sha256=UmqIvEx_Pd3B9jhvtmgZxx4SAjHUeOZBOEc8VtRILZs,13716
+kicad_sch_api/core/types.py,sha256=D8VGvE7N2nj-xqnWSnTl98WaAbWh6JhQsn-pZCiLFfE,13974
 kicad_sch_api/core/wire_routing.py,sha256=G-C7S-ntQxwuu1z3OaaYlkURXwKE4r4xmhbbi6cvvaI,12830
 kicad_sch_api/core/wires.py,sha256=608t9oH4UzppdGgNgUd-ABK6T-ahyETZwhO_-CuKFO8,8319
 kicad_sch_api/discovery/__init__.py,sha256=qSuCsnC-hVtaLYE8fwd-Gea6JKwEVGPQ-hSNDNJYsIU,329
 kicad_sch_api/discovery/search_index.py,sha256=KgQT8ipT9OU6ktUwhDZ37Mao0Cba0fJOsxUk9m8ZKbY,15856
+kicad_sch_api/geometry/__init__.py,sha256=hTBXkn8mZZCjzDIrtPv67QsnCYB77L67JjthQgEIX7o,716
+kicad_sch_api/geometry/font_metrics.py,sha256=qqnfBuRqiLQDnGkk64rKzdyvuSNU0uBfdp0TKEgzXds,831
+kicad_sch_api/geometry/symbol_bbox.py,sha256=5oMVmmimyqF4ITj8wS9yeU3jXdpqG0XhCIvAHlYr9Rg,24688
 kicad_sch_api/library/__init__.py,sha256=NG9UTdcpn25Bl9tPsYs9ED7bvpaVPVdtLMbnxkQkOnU,250
 kicad_sch_api/library/cache.py,sha256=7na88grl465WHwUOGuOzYrrWwjsMBXhXVtxhnaJ9GBY,33208
 kicad_sch_api/utils/__init__.py,sha256=1V_yGgI7jro6MUc4Pviux_WIeJ1wmiYFID186SZwWLQ,277
 kicad_sch_api/utils/validation.py,sha256=XlWGRZJb3cOPYpU9sLQQgC_NASwbi6W-LCN7PzUmaPY,15626
-kicad_sch_api-0.3.2.dist-info/licenses/LICENSE,sha256=Em65Nvte1G9MHc0rHqtYuGkCPcshD588itTa358J6gs,1070
-kicad_sch_api-0.3.2.dist-info/METADATA,sha256=m8NfvoWy9m4AfShTSlHkn2AMUzy1cZkxiQXPnF3e0a0,17183
-kicad_sch_api-0.3.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kicad_sch_api-0.3.2.dist-info/entry_points.txt,sha256=VWKsFi2Jv7G_tmio3cNVhhIBfv_OZFaKa-T_ED84lc8,57
-kicad_sch_api-0.3.2.dist-info/top_level.txt,sha256=n0ex4gOJ1b_fARowcGqRzyOGZcHRhc5LZa6_vVgGxcI,14
-kicad_sch_api-0.3.2.dist-info/RECORD,,
+kicad_sch_api-0.3.4.dist-info/licenses/LICENSE,sha256=Em65Nvte1G9MHc0rHqtYuGkCPcshD588itTa358J6gs,1070
+kicad_sch_api-0.3.4.dist-info/METADATA,sha256=4RHjg7LWStLaT3wRrAkmDhBTLR5l-TRYoc2eXP5zZHs,17183
+kicad_sch_api-0.3.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kicad_sch_api-0.3.4.dist-info/entry_points.txt,sha256=VWKsFi2Jv7G_tmio3cNVhhIBfv_OZFaKa-T_ED84lc8,57
+kicad_sch_api-0.3.4.dist-info/top_level.txt,sha256=n0ex4gOJ1b_fARowcGqRzyOGZcHRhc5LZa6_vVgGxcI,14
+kicad_sch_api-0.3.4.dist-info/RECORD,,