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

kicad_sch_api/core/component_bounds.py

@@ -382,21 +382,43 @@ def get_component_bounding_box(
     # Calculate symbol bounding box
     symbol_bbox = SymbolBoundingBoxCalculator.calculate_bounding_box(symbol, include_properties)
 
-    # Transform to world coordinates
-    # TODO: Handle component rotation in the future
-    # NOTE: Currently assumes 0° rotation. For rotated components, bounding box
-    # would need to be recalculated after applying rotation matrix. This is a
-    # known limitation but doesn't affect most use cases since components are
-    # typically placed without rotation, and routing avoids components regardless.
-    # Priority: LOW - Would improve accuracy for rotated component placement validation
+    # Transform to world coordinates with rotation
+    # Apply rotation matrix to bounding box corners, then find new min/max
+    import math
+
+    angle_rad = math.radians(component.rotation)
+    cos_a = math.cos(angle_rad)
+    sin_a = math.sin(angle_rad)
+
+    # Get all 4 corners of the symbol bounding box
+    corners = [
+        (symbol_bbox.min_x, symbol_bbox.min_y),  # Bottom-left
+        (symbol_bbox.max_x, symbol_bbox.min_y),  # Bottom-right
+        (symbol_bbox.max_x, symbol_bbox.max_y),  # Top-right
+        (symbol_bbox.min_x, symbol_bbox.max_y),  # Top-left
+    ]
+
+    # Rotate each corner using standard 2D rotation matrix
+    rotated_corners = []
+    for x, y in corners:
+        rotated_x = x * cos_a - y * sin_a
+        rotated_y = x * sin_a + y * cos_a
+        rotated_corners.append((rotated_x, rotated_y))
+
+    # Find min/max of rotated corners
+    rotated_xs = [x for x, y in rotated_corners]
+    rotated_ys = [y for x, y in rotated_corners]
+
     world_bbox = BoundingBox(
-        component.position.x + symbol_bbox.min_x,
-        component.position.y + symbol_bbox.min_y,
-        component.position.x + symbol_bbox.max_x,
-        component.position.y + symbol_bbox.max_y,
+        component.position.x + min(rotated_xs),
+        component.position.y + min(rotated_ys),
+        component.position.x + max(rotated_xs),
+        component.position.y + max(rotated_ys),
     )
 
-    logger.debug(f"Component {component.reference} world bbox: {world_bbox}")
+    logger.debug(
+        f"Component {component.reference} at {component.rotation}° world bbox: {world_bbox}"
+    )
     return world_bbox
 
 

kicad_sch_api/core/components.py

@@ -12,6 +12,7 @@ from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple, Union
 from ..library.cache import SymbolDefinition, get_symbol_cache
 from ..utils.validation import SchematicValidator, ValidationError, ValidationIssue
 from .collections import BaseCollection
+from .exceptions import LibraryError
 from .ic_manager import ICManager
 from .types import Point, SchematicPin, SchematicSymbol
 
@@ -106,8 +107,29 @@ class Component:
 
     @rotation.setter
     def rotation(self, value: float):
-        """Set component rotation."""
-        self._data.rotation = float(value) % 360
+        """Set component rotation (must be 0, 90, 180, or 270 degrees).
+
+        KiCad only supports these four rotation angles for components.
+
+        Args:
+            value: Rotation angle in degrees (0, 90, 180, or 270)
+
+        Raises:
+            ValueError: If rotation is not 0, 90, 180, or 270
+        """
+        # Normalize rotation to 0-360 range
+        normalized = float(value) % 360
+
+        # KiCad only accepts 0, 90, 180, or 270 degrees
+        VALID_ROTATIONS = {0, 90, 180, 270}
+        if normalized not in VALID_ROTATIONS:
+            raise ValueError(
+                f"Component rotation must be 0, 90, 180, or 270 degrees. "
+                f"Got {value}° (normalized to {normalized}°). "
+                f"KiCad does not support arbitrary rotation angles."
+            )
+
+        self._data.rotation = normalized
         self._collection._mark_modified()
 
     @property
@@ -273,12 +295,13 @@ class ComponentCollection(BaseCollection[Component]):
     Optimized for schematics with hundreds or thousands of components.
     """
 
-    def __init__(self, components: List[SchematicSymbol] = None):
+    def __init__(self, components: List[SchematicSymbol] = None, parent_schematic=None):
         """
         Initialize component collection.
 
         Args:
             components: Initial list of component data
+            parent_schematic: Reference to parent Schematic object (for hierarchy context)
         """
         # Initialize base collection
         super().__init__([], collection_name="components")
@@ -288,6 +311,9 @@ class ComponentCollection(BaseCollection[Component]):
         self._lib_id_index: Dict[str, List[Component]] = {}
         self._value_index: Dict[str, List[Component]] = {}
 
+        # Store reference to parent schematic for hierarchy context
+        self._parent_schematic = parent_schematic
+
         # Add initial components
         if components:
             for comp_data in components:
@@ -301,6 +327,7 @@ class ComponentCollection(BaseCollection[Component]):
         position: Optional[Union[Point, Tuple[float, float]]] = None,
         footprint: Optional[str] = None,
         unit: int = 1,
+        rotation: float = 0.0,
         component_uuid: Optional[str] = None,
         **properties,
     ) -> Component:
@@ -314,6 +341,7 @@ class ComponentCollection(BaseCollection[Component]):
             position: Component position (auto-placed if None)
             footprint: Component footprint
             unit: Unit number for multi-unit components (1-based)
+            rotation: Component rotation in degrees (0, 90, 180, 270)
             component_uuid: Specific UUID for component (auto-generated if None)
             **properties: Additional component properties
 
@@ -322,6 +350,7 @@ class ComponentCollection(BaseCollection[Component]):
 
         Raises:
             ValidationError: If component data is invalid
+            LibraryError: If the KiCAD symbol library is not found
         """
         # Validate lib_id
         validator = SchematicValidator()
@@ -356,6 +385,28 @@ class ComponentCollection(BaseCollection[Component]):
             f"Component {reference} position snapped to grid: ({position.x:.3f}, {position.y:.3f})"
         )
 
+        # Normalize and validate rotation
+        rotation = rotation % 360
+
+        # KiCad only accepts 0, 90, 180, or 270 degrees
+        VALID_ROTATIONS = {0, 90, 180, 270}
+        if rotation not in VALID_ROTATIONS:
+            raise ValidationError(
+                f"Component rotation must be 0, 90, 180, or 270 degrees. "
+                f"Got {rotation}°. KiCad does not support arbitrary rotation angles."
+            )
+
+        # Check if parent schematic has hierarchy context set
+        # If so, add hierarchy_path to properties for proper KiCad instance paths
+        if self._parent_schematic and hasattr(self._parent_schematic, '_hierarchy_path'):
+            if self._parent_schematic._hierarchy_path:
+                properties = dict(properties)  # Make a copy to avoid modifying caller's dict
+                properties['hierarchy_path'] = self._parent_schematic._hierarchy_path
+                logger.debug(
+                    f"Setting hierarchy_path for component {reference}: "
+                    f"{self._parent_schematic._hierarchy_path}"
+                )
+
         # Create component data
         component_data = SchematicSymbol(
             uuid=component_uuid if component_uuid else str(uuid.uuid4()),
@@ -365,14 +416,24 @@ class ComponentCollection(BaseCollection[Component]):
             value=value,
             footprint=footprint,
             unit=unit,
+            rotation=rotation,
             properties=properties,
         )
 
         # Get symbol definition and update pins
         symbol_cache = get_symbol_cache()
         symbol_def = symbol_cache.get_symbol(lib_id)
-        if symbol_def:
-            component_data.pins = symbol_def.pins.copy()
+        if not symbol_def:
+            # Provide helpful error message with library name
+            library_name = lib_id.split(":")[0] if ":" in lib_id else "unknown"
+            raise LibraryError(
+                f"Symbol '{lib_id}' not found in KiCAD libraries. "
+                f"Please verify the library name '{library_name}' and symbol name are correct. "
+                f"Common libraries include: Device, Connector_Generic, Regulator_Linear, RF_Module",
+                field="lib_id",
+                value=lib_id
+            )
+        component_data.pins = symbol_def.pins.copy()
 
         # Create component wrapper
         component = Component(component_data, self)
@@ -448,11 +509,25 @@ class ComponentCollection(BaseCollection[Component]):
         Remove component by reference.
 
         Args:
-            reference: Component reference to remove
+            reference: Component reference to remove (e.g., "R1")
 
         Returns:
-            True if component was removed
+            True if component was removed, False if not found
+
+        Raises:
+            TypeError: If reference is not a string
+
+        Examples:
+            sch.components.remove("R1")
+            sch.components.remove("C2")
+
+        Note:
+            For removing by UUID or component object, use remove_by_uuid() or remove_component()
+            respectively. This maintains a clear, simple API contract.
         """
+        if not isinstance(reference, str):
+            raise TypeError(f"reference must be a string, not {type(reference).__name__}")
+
         component = self._reference_index.get(reference)
         if not component:
             return False
@@ -466,6 +541,70 @@ class ComponentCollection(BaseCollection[Component]):
         logger.info(f"Removed component: {reference}")
         return True
 
+    def remove_by_uuid(self, component_uuid: str) -> bool:
+        """
+        Remove component by UUID.
+
+        Args:
+            component_uuid: Component UUID to remove
+
+        Returns:
+            True if component was removed, False if not found
+
+        Raises:
+            TypeError: If UUID is not a string
+        """
+        if not isinstance(component_uuid, str):
+            raise TypeError(f"component_uuid must be a string, not {type(component_uuid).__name__}")
+
+        if component_uuid not in self._uuid_index:
+            return False
+
+        component = self._items[self._uuid_index[component_uuid]]
+
+        # Remove from component-specific indexes
+        self._remove_from_indexes(component)
+
+        # Remove from base collection
+        super().remove(component_uuid)
+
+        logger.info(f"Removed component by UUID: {component_uuid}")
+        return True
+
+    def remove_component(self, component: "Component") -> bool:
+        """
+        Remove component by component object.
+
+        Args:
+            component: Component object to remove
+
+        Returns:
+            True if component was removed, False if not found
+
+        Raises:
+            TypeError: If component is not a Component instance
+
+        Examples:
+            comp = sch.components.get("R1")
+            sch.components.remove_component(comp)
+        """
+        if not isinstance(component, Component):
+            raise TypeError(
+                f"component must be a Component instance, not {type(component).__name__}"
+            )
+
+        if component.uuid not in self._uuid_index:
+            return False
+
+        # Remove from component-specific indexes
+        self._remove_from_indexes(component)
+
+        # Remove from base collection
+        super().remove(component.uuid)
+
+        logger.info(f"Removed component: {component.reference}")
+        return True
+
     def get(self, reference: str) -> Optional[Component]:
         """Get component by reference."""
         return self._reference_index.get(reference)

kicad_sch_api/core/config.py

@@ -174,35 +174,48 @@ class KiCADConfig:
         return name.lower() not in self.no_title_block_names
 
     def get_property_position(
-        self, property_name: str, component_pos: Tuple[float, float], offset_index: int = 0
+        self, property_name: str, component_pos: Tuple[float, float], offset_index: int = 0, component_rotation: float = 0
     ) -> Tuple[float, float, float]:
         """
-        Calculate property position relative to component.
+        Calculate property position relative to component, accounting for component rotation.
+
+        Args:
+            property_name: Name of the property (Reference, Value, etc.)
+            component_pos: (x, y) position of component
+            offset_index: Stacking offset for multiple properties
+            component_rotation: Rotation of the component in degrees (0, 90, 180, 270)
 
         Returns:
             Tuple of (x, y, rotation) for the property
         """
+        import math
+
         x, y = component_pos
 
+        # Get base offsets (for 0° rotation)
         if property_name == "Reference":
-            return (x + self.properties.reference_x, y + self.properties.reference_y, 0)
+            dx, dy = self.properties.reference_x, self.properties.reference_y
         elif property_name == "Value":
-            return (x + self.properties.value_x, y + self.properties.value_y, 0)
+            dx, dy = self.properties.value_x, self.properties.value_y
         elif property_name == "Footprint":
             # Footprint positioned to left of component, rotated 90 degrees
-            return (x - 1.778, y, self.properties.footprint_rotation)  # Exact match for reference
+            return (x - 1.778, y, self.properties.footprint_rotation)
         elif property_name in ["Datasheet", "Description"]:
             # Hidden properties at component center
             return (x, y, 0)
         else:
             # Other properties stacked vertically below
-            return (
-                x + self.properties.reference_x,
-                y
-                + self.properties.value_y
-                + (self.properties.hidden_property_offset * offset_index),
-                0,
-            )
+            dx = self.properties.reference_x
+            dy = self.properties.value_y + (self.properties.hidden_property_offset * offset_index)
+
+        # Apply rotation transform to offsets
+        # Text stays at 0° rotation (readable), but position rotates around component
+        # KiCad uses clockwise rotation, so negate the angle
+        rotation_rad = math.radians(-component_rotation)
+        dx_rotated = dx * math.cos(rotation_rad) - dy * math.sin(rotation_rad)
+        dy_rotated = dx * math.sin(rotation_rad) + dy * math.cos(rotation_rad)
+
+        return (x + dx_rotated, y + dy_rotated, 0)
 
 
 # Global configuration instance