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

kicad_sch_api/core/geometry.py

@@ -7,7 +7,7 @@ migrated from circuit-synth for improved maintainability.
 
 import logging
 import math
-from typing import Optional, Tuple
+from typing import Optional, Tuple, Union
 
 from .types import Point
 
@@ -71,20 +71,29 @@ def apply_transformation(
 
     Migrated from circuit-synth for accurate pin position calculation.
 
+    CRITICAL: Symbol coordinates use normal Y-axis (+Y is up), but schematic
+    coordinates use inverted Y-axis (+Y is down). We must negate Y from symbol
+    space before applying transformations.
+
     Args:
-        point: Point to transform (x, y) relative to origin
-        origin: Component origin point
+        point: Point to transform (x, y) relative to origin in SYMBOL space
+        origin: Component origin point in SCHEMATIC space
         rotation: Rotation in degrees (0, 90, 180, 270)
         mirror: Mirror axis ("x" or "y" or None)
 
     Returns:
-        Transformed absolute position (x, y)
+        Transformed absolute position (x, y) in SCHEMATIC space
     """
     x, y = point
 
     logger.debug(f"Transforming point ({x}, {y}) with rotation={rotation}°, mirror={mirror}")
 
-    # Apply mirroring first
+    # CRITICAL: Negate Y to convert from symbol space (normal Y) to schematic space (inverted Y)
+    # This must happen BEFORE rotation/mirroring
+    y = -y
+    logger.debug(f"After Y-axis inversion (symbol→schematic): ({x}, {y})")
+
+    # Apply mirroring
     if mirror == "x":
         x = -x
         logger.debug(f"After X mirror: ({x}, {y})")
@@ -109,3 +118,83 @@ def apply_transformation(
 
     logger.debug(f"Final absolute position: ({final_x}, {final_y})")
     return (final_x, final_y)
+
+
+def calculate_position_for_pin(
+    pin_local_position: Union[Point, Tuple[float, float]],
+    desired_pin_position: Union[Point, Tuple[float, float]],
+    rotation: float = 0.0,
+    mirror: Optional[str] = None,
+    grid_size: float = 1.27,
+) -> Point:
+    """
+    Calculate component position needed to place a specific pin at a desired location.
+
+    This is the inverse of get_pin_position() - given where you want a pin to be,
+    it calculates where the component center needs to be placed.
+
+    Useful for aligning components by their pins rather than their centers, which
+    is essential for clean horizontal signal flows without unnecessary wire jogs.
+
+    Args:
+        pin_local_position: Pin position in symbol space (from symbol definition)
+        desired_pin_position: Where you want the pin to be in schematic space
+        rotation: Component rotation in degrees (0, 90, 180, 270)
+        mirror: Mirror axis ("x" or "y" or None) - currently unused
+        grid_size: Grid size for snapping result (default 1.27mm = 50mil)
+
+    Returns:
+        Component position that will place the pin at desired_pin_position
+
+    Example:
+        >>> # Place resistor so pin 2 is at (150, 100)
+        >>> pin_pos = Point(0, -3.81)  # Pin 2 local position from symbol
+        >>> comp_pos = calculate_position_for_pin(pin_pos, (150, 100))
+        >>> # Now add component at comp_pos, and pin 2 will be at (150, 100)
+
+    Note:
+        The result is automatically snapped to the KiCAD grid for proper connectivity.
+        This function matches the behavior of SchematicSymbol.get_pin_position().
+    """
+    # Convert inputs to proper types
+    if isinstance(pin_local_position, Point):
+        pin_x, pin_y = pin_local_position.x, pin_local_position.y
+    else:
+        pin_x, pin_y = pin_local_position
+
+    if isinstance(desired_pin_position, Point):
+        target_x, target_y = desired_pin_position.x, desired_pin_position.y
+    else:
+        target_x, target_y = desired_pin_position
+
+    logger.debug(
+        f"Calculating component position for pin at local ({pin_x}, {pin_y}) "
+        f"to reach target ({target_x}, {target_y}) with rotation={rotation}°"
+    )
+
+    # Apply the same transformation that get_pin_position() uses
+    # This is a standard 2D rotation matrix (NO Y-axis inversion)
+    angle_rad = math.radians(rotation)
+    cos_a = math.cos(angle_rad)
+    sin_a = math.sin(angle_rad)
+
+    # Calculate rotated offset (same as get_pin_position)
+    rotated_x = pin_x * cos_a - pin_y * sin_a
+    rotated_y = pin_x * sin_a + pin_y * cos_a
+
+    logger.debug(f"Pin offset after rotation: ({rotated_x:.3f}, {rotated_y:.3f})")
+
+    # Calculate component origin
+    # Since: target = component + rotated_offset
+    # Therefore: component = target - rotated_offset
+    component_x = target_x - rotated_x
+    component_y = target_y - rotated_y
+
+    logger.debug(f"Calculated component position (before grid snap): ({component_x:.3f}, {component_y:.3f})")
+
+    # Snap to grid for proper KiCAD connectivity
+    snapped_x, snapped_y = snap_to_grid((component_x, component_y), grid_size=grid_size)
+
+    logger.debug(f"Final component position (after grid snap): ({snapped_x:.3f}, {snapped_y:.3f})")
+
+    return Point(snapped_x, snapped_y)

kicad_sch_api/core/junctions.py

@@ -9,55 +9,34 @@ import logging
 import uuid as uuid_module
 from typing import Any, Dict, List, Optional, Tuple, Union
 
+from .collections import BaseCollection
 from .types import Junction, Point
 
 logger = logging.getLogger(__name__)
 
 
-class JunctionCollection:
+class JunctionCollection(BaseCollection[Junction]):
     """
     Professional junction collection with enhanced management features.
 
+    Inherits from BaseCollection for standard operations and adds junction-specific
+    functionality.
+
     Features:
-    - Fast UUID-based lookup and indexing
+    - Fast UUID-based lookup and indexing (inherited)
     - Position-based junction queries
-    - Bulk operations for performance
+    - Bulk operations for performance (inherited)
     - Validation and conflict detection
     """
 
-    def __init__(self, junctions: Optional[List[Junction]] = None):
+    def __init__(self, junctions: Optional[List[Junction]] = None) -> None:
         """
         Initialize junction collection.
 
         Args:
             junctions: Initial list of junctions
         """
-        self._junctions: List[Junction] = junctions or []
-        self._uuid_index: Dict[str, int] = {}
-        self._modified = False
-
-        # Build UUID index
-        self._rebuild_index()
-
-        logger.debug(f"JunctionCollection initialized with {len(self._junctions)} junctions")
-
-    def _rebuild_index(self):
-        """Rebuild UUID index for fast lookups."""
-        self._uuid_index = {junction.uuid: i for i, junction in enumerate(self._junctions)}
-
-    def __len__(self) -> int:
-        """Number of junctions in collection."""
-        return len(self._junctions)
-
-    def __iter__(self):
-        """Iterate over junctions."""
-        return iter(self._junctions)
-
-    def __getitem__(self, uuid: str) -> Junction:
-        """Get junction by UUID."""
-        if uuid not in self._uuid_index:
-            raise KeyError(f"Junction with UUID '{uuid}' not found")
-        return self._junctions[self._uuid_index[uuid]]
+        super().__init__(junctions, collection_name="junctions")
 
     def add(
         self,
@@ -94,35 +73,12 @@ class JunctionCollection:
         # Create junction
         junction = Junction(uuid=uuid, position=position, diameter=diameter, color=color)
 
-        # Add to collection
-        self._junctions.append(junction)
-        self._uuid_index[uuid] = len(self._junctions) - 1
-        self._modified = True
+        # Add to collection using base class method
+        self._add_item(junction)
 
         logger.debug(f"Added junction at {position}, UUID={uuid}")
         return uuid
 
-    def remove(self, uuid: str) -> bool:
-        """
-        Remove junction by UUID.
-
-        Args:
-            uuid: Junction UUID to remove
-
-        Returns:
-            True if junction was removed, False if not found
-        """
-        if uuid not in self._uuid_index:
-            return False
-
-        index = self._uuid_index[uuid]
-        del self._junctions[index]
-        self._rebuild_index()
-        self._modified = True
-
-        logger.debug(f"Removed junction: {uuid}")
-        return True
-
     def get_at_position(
         self, position: Union[Point, Tuple[float, float]], tolerance: float = 0.01
     ) -> Optional[Junction]:
@@ -139,7 +95,7 @@ class JunctionCollection:
         if isinstance(position, tuple):
             position = Point(position[0], position[1])
 
-        for junction in self._junctions:
+        for junction in self._items:
             if junction.position.distance_to(position) <= tolerance:
                 return junction
 
@@ -162,40 +118,35 @@ class JunctionCollection:
             point = Point(point[0], point[1])
 
         matching_junctions = []
-        for junction in self._junctions:
+        for junction in self._items:
             if junction.position.distance_to(point) <= tolerance:
                 matching_junctions.append(junction)
 
         return matching_junctions
 
     def get_statistics(self) -> Dict[str, Any]:
-        """Get junction collection statistics."""
-        if not self._junctions:
-            return {"total_junctions": 0, "avg_diameter": 0, "positions": []}
+        """Get junction collection statistics (extends base statistics)."""
+        base_stats = super().get_statistics()
+        if not self._items:
+            return {**base_stats, "total_junctions": 0, "avg_diameter": 0, "positions": []}
 
-        avg_diameter = sum(j.diameter for j in self._junctions) / len(self._junctions)
-        positions = [(j.position.x, j.position.y) for j in self._junctions]
+        avg_diameter = sum(j.diameter for j in self._items) / len(self._items)
+        positions = [(j.position.x, j.position.y) for j in self._items]
 
         return {
-            "total_junctions": len(self._junctions),
+            **base_stats,
+            "total_junctions": len(self._items),
             "avg_diameter": avg_diameter,
             "positions": positions,
-            "unique_diameters": len(set(j.diameter for j in self._junctions)),
-            "unique_colors": len(set(j.color for j in self._junctions)),
+            "unique_diameters": len(set(j.diameter for j in self._items)),
+            "unique_colors": len(set(j.color for j in self._items)),
         }
 
-    def clear(self):
-        """Remove all junctions from collection."""
-        self._junctions.clear()
-        self._uuid_index.clear()
-        self._modified = True
-        logger.debug("Cleared all junctions")
-
     @property
     def modified(self) -> bool:
         """Check if collection has been modified."""
-        return self._modified
+        return self.is_modified()
 
-    def mark_saved(self):
+    def mark_saved(self) -> None:
         """Mark collection as saved (reset modified flag)."""
-        self._modified = False
+        self.reset_modified_flag()

kicad_sch_api/core/labels.py

@@ -0,0 +1,324 @@
+"""
+Label element management for KiCAD schematics.
+
+This module provides collection classes for managing label elements,
+featuring fast lookup, bulk operations, and validation.
+"""
+
+import logging
+import uuid
+from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple, Union
+
+from ..utils.validation import SchematicValidator, ValidationError, ValidationIssue
+from .collections import BaseCollection
+from .types import Label, Point
+
+logger = logging.getLogger(__name__)
+
+
+class LabelElement:
+    """
+    Enhanced wrapper for schematic label elements with modern API.
+
+    Provides intuitive access to label properties and operations
+    while maintaining exact format preservation.
+    """
+
+    def __init__(self, label_data: Label, parent_collection: "LabelCollection"):
+        """
+        Initialize label element wrapper.
+
+        Args:
+            label_data: Underlying label data
+            parent_collection: Parent collection for updates
+        """
+        self._data = label_data
+        self._collection = parent_collection
+        self._validator = SchematicValidator()
+
+    # Core properties with validation
+    @property
+    def uuid(self) -> str:
+        """Label element UUID."""
+        return self._data.uuid
+
+    @property
+    def text(self) -> str:
+        """Label text (net name)."""
+        return self._data.text
+
+    @text.setter
+    def text(self, value: str):
+        """Set label text with validation."""
+        if not isinstance(value, str) or not value.strip():
+            raise ValidationError("Label text cannot be empty")
+        old_text = self._data.text
+        self._data.text = value.strip()
+        self._collection._update_text_index(old_text, self)
+        self._collection._mark_modified()
+
+    @property
+    def position(self) -> Point:
+        """Label position."""
+        return self._data.position
+
+    @position.setter
+    def position(self, value: Union[Point, Tuple[float, float]]):
+        """Set label position."""
+        if isinstance(value, tuple):
+            value = Point(value[0], value[1])
+        elif not isinstance(value, Point):
+            raise ValidationError(f"Position must be Point or tuple, got {type(value)}")
+        self._data.position = value
+        self._collection._mark_modified()
+
+    @property
+    def rotation(self) -> float:
+        """Label rotation in degrees."""
+        return self._data.rotation
+
+    @rotation.setter
+    def rotation(self, value: float):
+        """Set label rotation."""
+        self._data.rotation = float(value)
+        self._collection._mark_modified()
+
+    @property
+    def size(self) -> float:
+        """Label text size."""
+        return self._data.size
+
+    @size.setter
+    def size(self, value: float):
+        """Set label size with validation."""
+        if value <= 0:
+            raise ValidationError(f"Label size must be positive, got {value}")
+        self._data.size = float(value)
+        self._collection._mark_modified()
+
+    def validate(self) -> List[ValidationIssue]:
+        """Validate this label element."""
+        return self._validator.validate_label(self._data.__dict__)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert label element to dictionary representation."""
+        return {
+            "uuid": self.uuid,
+            "text": self.text,
+            "position": {"x": self.position.x, "y": self.position.y},
+            "rotation": self.rotation,
+            "size": self.size,
+        }
+
+    def __str__(self) -> str:
+        """String representation."""
+        return f"<Label '{self.text}' @ {self.position}>"
+
+
+class LabelCollection(BaseCollection[LabelElement]):
+    """
+    Collection class for efficient label element management.
+
+    Inherits from BaseCollection for standard operations and adds label-specific
+    functionality including text-based indexing.
+
+    Provides fast lookup, filtering, and bulk operations for schematic label elements.
+    """
+
+    def __init__(self, labels: List[Label] = None):
+        """
+        Initialize label collection.
+
+        Args:
+            labels: Initial list of label data
+        """
+        # Initialize base collection
+        super().__init__([], collection_name="labels")
+
+        # Additional label-specific index
+        self._text_index: Dict[str, List[LabelElement]] = {}
+
+        # Add initial labels
+        if labels:
+            for label_data in labels:
+                self._add_to_indexes(LabelElement(label_data, self))
+
+    def add(
+        self,
+        text: str,
+        position: Union[Point, Tuple[float, float]],
+        rotation: float = 0.0,
+        size: float = 1.27,
+        label_uuid: Optional[str] = None,
+    ) -> LabelElement:
+        """
+        Add a new label element to the schematic.
+
+        Args:
+            text: Label text (net name)
+            position: Label position
+            rotation: Label rotation in degrees
+            size: Label text size
+            label_uuid: Specific UUID for label (auto-generated if None)
+
+        Returns:
+            Newly created LabelElement
+
+        Raises:
+            ValidationError: If label data is invalid
+        """
+        # Validate inputs
+        if not isinstance(text, str) or not text.strip():
+            raise ValidationError("Label text cannot be empty")
+
+        if isinstance(position, tuple):
+            position = Point(position[0], position[1])
+        elif not isinstance(position, Point):
+            raise ValidationError(f"Position must be Point or tuple, got {type(position)}")
+
+        if size <= 0:
+            raise ValidationError(f"Label size must be positive, got {size}")
+
+        # Generate UUID if not provided
+        if not label_uuid:
+            label_uuid = str(uuid.uuid4())
+
+        # Check for duplicate UUID
+        if label_uuid in self._uuid_index:
+            raise ValidationError(f"Label UUID {label_uuid} already exists")
+
+        # Create label data
+        label_data = Label(
+            uuid=label_uuid,
+            position=position,
+            text=text.strip(),
+            rotation=rotation,
+            size=size,
+        )
+
+        # Create wrapper and add to collection
+        label_element = LabelElement(label_data, self)
+        self._add_to_indexes(label_element)
+        self._mark_modified()
+
+        logger.debug(f"Added label: {label_element}")
+        return label_element
+
+    # get() method inherited from BaseCollection
+
+    def get_by_text(self, text: str) -> List[LabelElement]:
+        """Get all labels with the given text."""
+        return self._text_index.get(text, []).copy()
+
+    def remove(self, label_uuid: str) -> bool:
+        """
+        Remove label by UUID.
+
+        Args:
+            label_uuid: UUID of label to remove
+
+        Returns:
+            True if label was removed, False if not found
+        """
+        label_element = self.get(label_uuid)
+        if not label_element:
+            return False
+
+        # Remove from text index
+        text = label_element.text
+        if text in self._text_index:
+            self._text_index[text].remove(label_element)
+            if not self._text_index[text]:
+                del self._text_index[text]
+
+        # Remove using base class method
+        super().remove(label_uuid)
+
+        logger.debug(f"Removed label: {label_element}")
+        return True
+
+    def find_by_text(self, text: str, exact: bool = True) -> List[LabelElement]:
+        """
+        Find labels by text.
+
+        Args:
+            text: Text to search for
+            exact: If True, exact match; if False, substring match
+
+        Returns:
+            List of matching label elements
+        """
+        if exact:
+            return self._text_index.get(text, []).copy()
+        else:
+            matches = []
+            for label_element in self._items:
+                if text.lower() in label_element.text.lower():
+                    matches.append(label_element)
+            return matches
+
+    def filter(self, predicate: Callable[[LabelElement], bool]) -> List[LabelElement]:
+        """
+        Filter labels by predicate function.
+
+        Args:
+            predicate: Function that returns True for labels to include
+
+        Returns:
+            List of labels matching predicate
+        """
+        return [label for label in self._items if predicate(label)]
+
+    def bulk_update(self, criteria: Callable[[LabelElement], bool], updates: Dict[str, Any]):
+        """
+        Update multiple labels matching criteria.
+
+        Args:
+            criteria: Function to select labels to update
+            updates: Dictionary of property updates
+        """
+        updated_count = 0
+        for label_element in self._items:
+            if criteria(label_element):
+                for prop, value in updates.items():
+                    if hasattr(label_element, prop):
+                        setattr(label_element, prop, value)
+                        updated_count += 1
+
+        if updated_count > 0:
+            self._mark_modified()
+            logger.debug(f"Bulk updated {updated_count} label properties")
+
+    def clear(self):
+        """Remove all labels from collection."""
+        self._text_index.clear()
+        super().clear()
+
+    def _add_to_indexes(self, label_element: LabelElement):
+        """Add label to internal indexes (base + text index)."""
+        self._add_item(label_element)
+
+        # Add to text index
+        text = label_element.text
+        if text not in self._text_index:
+            self._text_index[text] = []
+        self._text_index[text].append(label_element)
+
+    def _update_text_index(self, old_text: str, label_element: LabelElement):
+        """Update text index when label text changes."""
+        # Remove from old text index
+        if old_text in self._text_index:
+            self._text_index[old_text].remove(label_element)
+            if not self._text_index[old_text]:
+                del self._text_index[old_text]
+
+        # Add to new text index
+        new_text = label_element.text
+        if new_text not in self._text_index:
+            self._text_index[new_text] = []
+        self._text_index[new_text].append(label_element)
+
+    # Collection interface methods - __len__, __iter__, __getitem__ inherited from BaseCollection
+    def __bool__(self) -> bool:
+        """Return True if collection has labels."""
+        return len(self._items) > 0

kicad_sch_api/core/managers/__init__.py

@@ -0,0 +1,30 @@
+"""
+Schematic management modules for separating responsibilities.
+
+This package contains specialized managers for different aspects of schematic
+manipulation, enabling clean separation of concerns and better maintainability.
+"""
+
+from .base import BaseManager
+from .file_io import FileIOManager
+from .format_sync import FormatSyncManager
+from .graphics import GraphicsManager
+from .hierarchy import HierarchyManager
+from .metadata import MetadataManager
+from .sheet import SheetManager
+from .text_elements import TextElementManager
+from .validation import ValidationManager
+from .wire import WireManager
+
+__all__ = [
+    "BaseManager",
+    "FileIOManager",
+    "FormatSyncManager",
+    "GraphicsManager",
+    "HierarchyManager",
+    "MetadataManager",
+    "SheetManager",
+    "TextElementManager",
+    "ValidationManager",
+    "WireManager",
+]