Subsystem 1: Vision - miloboyd/chess-robot GitHub Wiki

♟️ Chess Vision and Control System - Functional Overview

📦 Module Descriptions

chess_core.py

Main ROS2 control node that:

  • Subscribes to image and move-completion topics
  • Detects moves via vision or manual GUI
  • Queries Stockfish for AI decisions
  • Publishes robot commands via /send_move
  • Tracks game progression and turn switching

python_chess3.py

Provides:

  • Chess logic using python-chess
  • Visual board state conversion using OpenCV
  • Move detection via image difference and legality checking
  • PGN/FEN tracking and board update utilities

square_processing.py

Contains utilities for:

  • Contour analysis and piece shape isolation
  • Brightness-based piece color detection
  • Center of mass marking
  • OpenCV image preprocessing

🧩 Function Input/Output Summary

🔷 chess_core.py

Function Description Input Output
check_move() Detects a player's move using captured images Internal image buffers Move in SAN (e.g., 'e4')
check_move_sim() GUI-based manual board setup and move detection Optional initial board array Move in SAN (e.g., 'e4')
update_board(move) Updates board with SAN move and checks for game over Move in SAN True if game is over
get_ai_move() Gets AI move from Stockfish based on current FEN None Move in format 'e2e41'
send_move_to_robot(move_str) Publishes AI move string to ROS /send_move topic Move string like 'e2e41' None
check_robot_completed() Checks if robot move was confirmed complete via ROS topic None Boolean
run_game() / run_game_simulated() Alternates turns, processes moves via camera or GUI None True if game is over
manually_select_chess_pieces() GUI for selecting board state manually Optional 8×8 board array Updated 8×8 NumPy array

🔷 python_chess3.py

Function Description Input Output
analyze_chessboard() Detects and processes chessboard from image Image path, calibration/corners 8×8 board array and corner points
analyze_binary_board_state() Updates board state from array and returns move, FEN, PGN, visual, etc. game object and 8×8 array Dictionary with analysis results
update_board() Detects and applies the best matching legal move from board array 8×8 array, optional turn PGN move string
detect_move() Finds best-matching legal move between old and new arrays 8×8 new board array chess.Move object or None
process_move() Detects and applies move with automatic turn inference 8×8 board array PGN move string or None
get_pgn() Returns the full PGN of the current game None PGN string

🔷 square_processing.py

Function Description Input Output
process_image() Applies Canny edge detection to image Image path (str) OpenCV matrix with edge map
detect_contours() Displays contours excluding rectangles from binary image Image path (str) Shows result; no return
detect_contours2() Filters and shows non-rectangular vs rectangular contours Image path (str) List of contours
find_center_of_mass() Computes and draws center of mass for all contours OpenCV image Image with centers marked
detect_chess_piece() Detects presence and color of a piece based on shape and brightness Image path (str) (bool, str, image) — detection flag, color, visual result

🔁 System Flow Summary

  1. Image Input: From ROS topic /camera
  2. Move Detection: check_move() compares board states
  3. AI Decision: get_ai_move() queries Stockfish
  4. Send to Robot: send_move_to_robot() publishes command
  5. Confirm Action: check_robot_completed() waits on /move_complete
  6. Update Board: update_board() applies new move
  7. Repeat: Until checkmate or draw

🖼️ Visual Tools

  • Uses cv2.imshow() for debugging:
    • Thresholds
    • Contours
    • Masked images
    • Chess grid overlays
  • Use cv2.waitKey(0) to hold display windows open