ChessPrism/cline_docs/systemPatterns.md

System Architecture

Piece Recognition Pipeline

1. Board Detection

   • VNDetectRectanglesRequest for board location
   • Aspect ratio and size validation
   • Square extraction with equal dimensions

2. Image Preprocessing

   • Contrast and brightness adjustment
   • Unsharp mask for edge enhancement
   • Consistent image scaling

3. ML Classification

   • CoreML model prediction
   • Confidence score analysis
   • Position-based adjustments

Recognition Patterns

Square Classification

1. Empty Square Detection

   • Exact empty_dark/empty_light matching
   • High confidence threshold (>0.9)
   • Early detection and return

2. Piece Recognition

   • Strict label format validation
   • Position-based confidence adjustment
   • Piece count tracking

3. Error Prevention

   • Empty square validation
   • Label format checking
   • Position rule enforcement

Classification Flow

1. Input Validation

   • Image dimensions check
   • Model availability check
   • Configuration setup

2. Square Analysis

   • Empty square check first
   • Piece classification second
   • Position validation last

3. Confidence Checks

   • Empty squares: >0.9
   • Pieces: >0.98 with >5.0 ratio
   • Position adjustments

4. Error Handling

   • Clear error messages
   • Detailed logging
   • Safe fallbacks

Validation Patterns

1. Piece Count Rules

   • Maximum 1: king, queen
   • Maximum 2: rooks, bishops, knights
   • Maximum 8: pawns
   • Track by color and type

2. Position Rules

   • Kings: not on opponent's back rank
   • Pawns: no backward movement
   • All pieces: within board bounds
   • All pieces: valid movement patterns

3. Piece Tracking

   • Maximum piece counts
   • Color-specific tracking
   • Total position validation
   • Captured piece limits

4. Recognition Flow

   • Empty square detection first
   • Piece classification second
   • Position validation last
   • Clear error reporting