Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
170 lines (129 loc) · 3.43 KB

GETTING_STARTED.md

File metadata and controls

170 lines (129 loc) · 3.43 KB

🚀 AI Chess Scanner - Getting Started

⚡ 5-Minute Quick Start

Step 1: Verify Installation

cd /Users/nazky/Documents/RPL/chess.ai
python3 test_requirements.py  # Should show all ✅ PASSED

Step 2: Run the App

./.venv/bin/python script.py

Step 3: Use It

  1. Click "📤 Upload Chess Screenshot"
  2. Select any image file (or skip for testing)
  3. Click "🔍 Scan & Analyze Position"
  4. Choose or enter a chess position (FEN)
  5. See instant Stockfish analysis!

📁 Project Files

File Purpose Size
script.py Main application 17K
README.md Full documentation 11K
test_requirements.py Test suite 4.9K
requirements.txt Dependencies 73B
setup.sh Setup script 1.5K
QUICKSTART.md Project overview 7.1K

🎯 Common Tasks

Analyze a Position

1. Launch: ./.venv/bin/python script.py
2. Click upload (or skip)
3. Click "Scan & Analyze"
4. Use preset or paste FEN
5. See best moves instantly

Run Tests

./.venv/bin/python test_requirements.py

Check Stockfish

which stockfish
stockfish --version

Reinstall Dependencies

source .venv/bin/activate
pip install -r requirements.txt --force-reinstall

💡 Example FEN Strings to Try

Scenario FEN
Start rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
Fool's Mate rnbqkbnr/pppp1ppp/8/4p3/6PP/5P2/PPPPP2P/RNBQKBNR w KQkq - 0 3
Scholar's Mate rnbqkb1r/pppp1ppp/5n2/4p3/4P1B1/5N2/PPPP1PPP/RNBQK2R b KQkq - 4 4
Simple Endgame 8/8/8/3k4/3P4/3K4/8/8 w - - 5 50

🐛 If Something Goes Wrong

"Stockfish not found"

brew install stockfish  # macOS
# Then restart the app

"Module not found"

source .venv/bin/activate
pip install -r requirements.txt

"GUI won't start"

python3 -m tkinter  # Test Tkinter
# If blank window appears, Tkinter works

"Invalid FEN" error

  • Check FEN format has 6 parts separated by spaces
  • Example: position w KQkq - 0 1
  • Try a preset first to ensure system works

📊 What the Output Means

Best Move

Shows the strongest move according to Stockfish

Evaluation

Score Meaning
+2.5 You have big advantage
+0.5 Small advantage
±0.0 Equal position
-0.5 Small disadvantage
-2.5 Big disadvantage
Mate in 3 Checkmate forced

Status

  • 🟢 ATTACKING - You're winning
  • 🟡 BALANCED - Equally matched
  • 🟠 DEFENDING - You're losing
  • 🔴 CRITICAL - Mate threat

✨ Features

✅ Upload chess board images
✅ Detect board region
✅ Convert to FEN notation
✅ Analyze with Stockfish
✅ Show best moves
✅ Detect tactics/checkmates
✅ Evaluate positions
✅ Modern GUI
✅ Works on macOS

🎓 Learning Resources

  • Learn Chess: chess.com, lichess.org
  • FEN Notation: chessclub.com/help/FEN-notation
  • Stockfish: stockfishchess.org
  • Python-Chess: python-chess.readthedocs.io

📞 System Info

  • Python: 3.14.2 ✅
  • Stockfish: /opt/homebrew/bin/stockfish ✅
  • Dependencies: All installed ✅
  • Tests: All passing ✅
  • Ready: YES ✅

🎉 You're Ready!

Everything is set up and working. Just run:

./.venv/bin/python script.py

Enjoy your Chess Scanner! ♟️✨