kicad-sch-api: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

kicad-sch-api is a Python library for reading and writing KiCAD schematic files. The core focus is exact format preservation and simple API design.

Key Principle: "Simple is my north star" - prioritize simplicity over features.

CRITICAL: KiCAD Coordinate System ⚠️

🔴 THE MOST IMPORTANT CONCEPT IN THIS LIBRARY

KiCAD uses TWO DIFFERENT coordinate systems, and understanding this is CRITICAL for ALL pin position calculations, connectivity analysis, and component placement.

The Two Coordinate Systems

1. Symbol Space (Library Definitions)

Uses NORMAL Y-axis (+Y is UP) like standard mathematics:

• All KiCAD symbol libraries define pins in this coordinate system
• Pin 1 at (0, 3.81) means 3.81mm UPWARD from origin
• Pin 2 at (0, -3.81) means 3.81mm DOWNWARD from origin

2. Schematic Space (Placed Components)

Uses INVERTED Y-axis (+Y is DOWN) like most computer graphics:

• Lower Y values = visually HIGHER on screen (top)
• Higher Y values = visually LOWER on screen (bottom)
• X-axis is normal (increases to the right)

The Critical Transformation

When placing a symbol on a schematic, Y coordinates MUST be negated:

# Symbol library defines (NORMAL Y-axis, +Y up):
Pin 1: (0, +3.81)   # 3.81mm UPWARD in symbol space
Pin 2: (0, -3.81)   # 3.81mm DOWNWARD in symbol space

# Component placed at (100, 100) in schematic (INVERTED Y-axis, +Y down):
# Y must be NEGATED during transformation:
Pin 1: (100, 100 + (-3.81)) = (100, 96.52)   # VISUALLY AT TOP (lower Y)
Pin 2: (100, 100 + (+3.81)) = (100, 103.81)  # VISUALLY AT BOTTOM (higher Y)

Implementation Location

File: kicad_sch_api/core/geometry.py:apply_transformation()

def apply_transformation(point, origin, rotation, mirror):
    x, y = point

    # 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})")

    # Then apply mirroring and rotation...