ChessPrism/cline_docs/systemPatterns.md

System Patterns

Model Architecture

1. Core ML Integration

   • Vision framework for image handling
   • Direct category mapping
   • No intermediate transformations

2. Classification Flow

   Image → VNImageRequestHandler → VNCoreMLRequest → VNClassificationObservation → SquareClassification
   

3. Category System

   • 12 piece categories:
     • white_pawn to white_king
     • black_pawn to black_king
   • Empty square fallback
   • No background variations in model

Processing Pipeline

1. Board Detection

   • VNDetectRectanglesRequest
   • Aspect ratio validation
   • Square extraction

2. Image Processing

   • Contrast enhancement
   • Edge sharpening
   • Noise reduction
   • Center crop

3. Classification

   • Vision framework integration
   • Confidence threshold
   • Error handling

Code Organization

1. Recognition Layer

   PieceRecognizer
   ├── Model loading
   ├── Image preprocessing
   └── Classification handling
   

2. Model Layer

   SquareClassification
   ├── Category mapping
   ├── Piece type/color
   └── Empty square handling
   

3. Core Components

   BoardDetector
   ├── Rectangle detection
   ├── Square extraction
   └── Position validation
   

Data Flow

1. Capture

   ScreenCapture → Raw Image → Board Rectangle
   

2. Processing

   Board Rectangle → Individual Squares → Preprocessed Images
   

3. Classification

   Preprocessed Images → ML Model → Piece Categories → Chess Position
   

Key Patterns

1. Direct Integration

   • Vision framework throughout
   • No intermediate conversions
   • Consistent image handling

2. Error Handling

   • Early validation
   • Graceful fallbacks
   • Detailed logging

3. Performance

   • Shared CIContext
   • Efficient image processing
   • Optimized model loading