♟️ AI Chess Scanner - Stockfish Analysis Tool

A powerful GUI application that converts chess board screenshots into FEN notation and provides real-time analysis using the Stockfish chess engine. Perfect for chess enthusiasts, students, and competitive players!

🎯 Features

• 📤 Image Upload: Load chess board screenshots (PNG, JPG, JPEG, BMP)
• 🎲 Board Detection: Automatically detects chessboard regions using OpenCV image processing
• 📝 FEN Conversion: Converts chess positions to FEN notation with preset templates and custom input
• 🤖 Stockfish Integration: Deep position analysis with multi-second thinking time
• 🎯 Best Move Detection: Suggests optimal moves with evaluation scores
• ⚔️ Attack/Defense Analysis:
  • Detects forced checkmate sequences
  • Identifies critical defending positions
  • Evaluates position balance
• 📊 Top 3 Candidate Moves: Shows multiple strong alternatives with evaluations
• 🎨 Modern GUI: Dark theme Tkinter interface with status updates
• 🔄 Real-time Processing: Live progress updates during analysis

📋 Requirements

System Requirements

• Python 3.8 or higher
• macOS, Linux, or Windows
• At least 200MB free disk space

Stockfish Engine

The application requires the Stockfish chess engine installed on your system. Download it from:

• Official: https://stockfishchess.org/download/

Python Dependencies

All dependencies are automatically installed. Key packages:

• python-chess - Chess logic and FEN handling
• Pillow - Image processing
• opencv-python - Board detection via image analysis
• stockfish - Python wrapper for Stockfish engine
• tkinter - GUI framework (usually pre-installed with Python)

🚀 Quick Start

Step 1: Install Stockfish

macOS (Homebrew):

brew install stockfish

Ubuntu/Debian:

sudo apt-get install stockfish

Fedora/RHEL:

sudo dnf install stockfish

Windows: Download from https://stockfishchess.org/download/ and install the executable.

Verify Installation:

stockfish --version

Step 2: Set Up Python Environment

Navigate to the project directory:

cd /path/to/chess.ai

Create a virtual environment (optional but recommended):

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Or manually install:

pip install Pillow python-chess stockfish opencv-python

Step 3: Run the Application

python script.py

Or if using the virtual environment:

.venv/bin/python script.py

💻 How to Use

Basic Workflow

1. Upload an Image

   • Click "📤 Upload Chess Screenshot" button
   • Select an image file of a chessboard (PNG, JPG, BMP)
   • The image displays and becomes ready for analysis

2. Enter FEN Position

   • Click "🔍 Scan & Analyze Position"
   • A dialog box appears with preset positions
   • Select a preset or paste your custom FEN string
   • Click "Analyze" to proceed

3. View Analysis Results

   • Best Move: The strongest move recommended by Stockfish
   • Evaluation: Position evaluation in pawns (±X.XX)
   • Status: Attack/Defense/Balanced assessment
   • Top 3 Moves: Alternative candidate moves with evaluations

4. Clear Results

   • Click "🗑️ Clear" to reset the application

Preset Positions

The app includes built-in presets for quick testing:

• Starting Position - Fresh game
• Fool's Mate (Black Won) - Quick checkmate example
• Scholar's Mate - Classic attacking trap
• Endgame - King & Pawn - Endgame scenario

Custom FEN Input

Enter any valid FEN string to analyze:

• Format: rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
• The app validates your FEN automatically

🔍 Understanding the Output

Evaluation Metrics

Evaluation	Interpretation
>3.0 pawns	Strong attacking advantage
+1.0 to +3.0	Moderate advantage
-1.0 to +1.0	Balanced position
-1.0 to -3.0	Moderate disadvantage
<-3.0 pawns	Critical defending position
Mate in N	Forced checkmate in N moves

Status Indicators

• 🟢 ATTACKING - You have advantage, press it
• 🟠 DEFENDING - Play carefully, consolidate
• 🟡 BALANCED - Focus on positional play
• 🔴 CRITICAL - Take defensive measures

🛠️ Troubleshooting

Issue: "Stockfish not found"

Solution:

# Verify Stockfish is installed
which stockfish  # macOS/Linux
where stockfish  # Windows

# If not found, install it:
brew install stockfish  # macOS
sudo apt install stockfish  # Ubuntu/Debian

Issue: "ModuleNotFoundError"

Solution:

# Verify you're in the virtual environment
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate  # Windows

# Reinstall dependencies
pip install --upgrade -r requirements.txt

Issue: Image not loading

Solution:

• Ensure image file is PNG, JPG, JPEG, or BMP
• Check file permissions
• Try a different image file
• Ensure image size is reasonable (under 50MB)

Issue: Slow analysis

• This is normal! Stockfish deep analysis takes time
• Reduce thinking time by modifying time=2.0 in the code
• Ensure no other CPU-intensive processes are running

Issue: "Invalid FEN" error

Solution:

• Double-check FEN formatting
• Ensure 8 ranks (rows) separated by "/"
• Check piece notation (lowercase for black)
• Verify turn indicator: "w" (white) or "b" (black)
• Reference: https://www.chessclub.com/help/FEN-notation

📝 FEN Notation Basics

FEN (Forsyth-Edwards Notation) represents chess positions as text:

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

Components:

1. Piece Placement: rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR

   • Lowercase = black pieces
   • Uppercase = white pieces
   • Numbers = empty squares
   • / = row separator

2. Active Color: w (white) or b (black)

3. Castling Rights: KQkq (kingside/queenside for white/black)

4. En Passant: - (no en passant) or square like e3

5. Halfmove Clock: Moves since last capture/pawn move

6. Move Number: Full move count

Resources:

• https://www.chessclub.com/help/FEN-notation
• https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation

🎮 Example Scenarios

Scenario 1: Analyzing a Middle Game

1. Screenshot your current online chess game
2. Upload the image
3. Select or enter the FEN of your position
4. Get instant analysis and the best move
5. Use it to guide your next decision

Scenario 2: Learning Endgames

1. Use preset endgame positions
2. Try different moves
3. See Stockfish's evaluation instantly
4. Understand positional dynamics

Scenario 3: Puzzle Training

1. Find a chess puzzle FEN online
2. Input the FEN string
3. Get Stockfish's recommended solution
4. Learn why it's the best move

🔧 Technical Details

Architecture

script.py
├── ChessScannerApp (Main GUI Application)
│   ├── build_gui() - Creates Tkinter interface
│   ├── upload_image() - Handles image selection
│   ├── find_stockfish() - Locates engine
│   ├── detect_fen_from_image() - Board detection
│   ├── get_fen_from_user() - FEN input dialog
│   ├── analyze_position() - Main analysis flow
│   └── get_best_moves() - Stockfish evaluation
└── Supporting Functions
    ├── show_stockfish_warning() - Error handling
    └── clear_all() - Reset application

Key Dependencies

Package	Purpose	Version
tkinter	GUI framework	Built-in
python-chess	Chess logic	1.9+
Pillow	Image processing	9.0+
opencv-python	Board detection	4.5+
stockfish	Engine wrapper	3.0+

Image Processing Pipeline

1. Load Image → OpenCV reads file
2. Grayscale Conversion → Reduce to single channel
3. Edge Detection → Canny algorithm finds edges
4. Contour Analysis → Identifies board region
5. Board Extraction → Isolates chessboard
6. FEN Conversion → User confirms/inputs position

📚 Advanced Usage

Modify Thinking Time

Edit script.py and find:

info = engine.analyse(board, chess.engine.Limit(time=2.0))

Change 2.0 to desired seconds (e.g., 5.0 for deeper analysis, 0.5 for quick analysis).

Add Custom Presets

In the get_fen_from_user() method, add to the presets dictionary:

presets = {
    "My Position": "r1bqkbnr/pppp1ppp/2n5/1B2p3/4P3/5N2/PPPP1PPP/RNBQK2R w KQkq - 2 4",
    # ... other presets
}

Integrate with Chess Analysis Sites

Export analysis results by reading the result_text widget and saving to file or sharing online.

🐛 Known Limitations

1. Image-to-FEN Detection: Currently relies on user input. Automatic piece detection requires trained ML model (future enhancement).
2. Stockfish Version: Some features require Stockfish 14+. Ensure you have the latest version.
3. Real-time Board Detection: Works best with:
   • Clear board lighting
   • Standard chess pieces
   • Top-down camera angle
   • No perspective distortion

🚀 Future Enhancements

• Train ML model for automatic piece detection
• Support for multiple board themes/piece styles
• Save analysis history to database
• Export analysis to PGN format
• Integration with chess.com API
• Move time calculation for blitz/bullet games
• Engine strength adjustment (ELO rating)
• Multi-language support

📖 Learning Resources

• Chess.com: https://www.chess.com/
• Lichess: https://lichess.org/
• Stockfish Documentation: https://stockfishchess.org/
• Python-Chess Docs: https://python-chess.readthedocs.io/
• FEN Notation: https://www.chessclub.com/help/FEN-notation

💡 Tips & Tricks

1. Quick Testing: Use the preset positions to test the engine
2. Move Comparison: Analyze the same position with different moves
3. Learning Tool: Compare your moves with Stockfish's recommendations
4. Performance: Close unnecessary applications for faster analysis
5. Custom Positions: Create positions using chess.com's diagram tool and export as FEN

📄 License

This project is open source and available for personal and educational use.

🤝 Contributing

Want to improve the Chess Scanner? Feel free to:

• Report bugs
• Suggest features
• Contribute code improvements
• Improve documentation

📧 Support

For issues with:

• Stockfish: https://github.com/official-stockfish/Stockfish/issues
• Python-Chess: https://github.com/niklasf/python-chess/issues
• OpenCV: https://github.com/opencv/opencv/issues

🎓 Educational Use

This tool is perfect for:

• Chess students learning opening theory
• Coaches analyzing games with students
• Puzzle solving and training
• Research on chess engine evaluation
• Teaching chess strategy and tactics

---

Version: 1.0
Last Updated: March 2026
Python: 3.8+
Status: ✅ Production Ready

Enjoy analyzing chess! ♟️