{"id":28025425,"url":"https://github.com/shubhs27/snap-n-solve","last_synced_at":"2026-04-07T09:32:29.016Z","repository":{"id":291161794,"uuid":"960893144","full_name":"shubhs27/Snap-n-Solve","owner":"shubhs27","description":"A real-time Sudoku puzzle solver that uses computer vision and machine learning to detect, solve, and overlay solutions on Sudoku puzzles captured through your webcam.","archived":false,"fork":false,"pushed_at":"2025-05-02T19:15:44.000Z","size":34370,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-02T20:19:06.123Z","etag":null,"topics":["keras","numpy","opencv","python","sudoku-scanner","sudoku-solver","tensorflow"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shubhs27.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-05T09:45:14.000Z","updated_at":"2025-05-02T19:15:48.000Z","dependencies_parsed_at":"2025-05-02T20:29:08.352Z","dependency_job_id":null,"html_url":"https://github.com/shubhs27/Snap-n-Solve","commit_stats":null,"previous_names":["shubhs27/snap-n-solve"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhs27%2FSnap-n-Solve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhs27%2FSnap-n-Solve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhs27%2FSnap-n-Solve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhs27%2FSnap-n-Solve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shubhs27","download_url":"https://codeload.github.com/shubhs27/Snap-n-Solve/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253516665,"owners_count":21920714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["keras","numpy","opencv","python","sudoku-scanner","sudoku-solver","tensorflow"],"created_at":"2025-05-11T04:22:35.163Z","updated_at":"2025-12-30T23:05:01.831Z","avatar_url":"https://github.com/shubhs27.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Snap-n-Solve\n\nSnap-n-Solve is a real-time Sudoku puzzle solver that uses computer vision and machine learning to detect, solve, and overlay solutions on Sudoku puzzles captured through your webcam.\n\n## Table of Contents \n\n- [Snap-n-Solve](#snap-n-solve)\n  - [Table of Contents](#table-of-contents)\n  - [Features](#features)\n  - [Screenshots](#screenshots)\n  - [Requirements](#requirements)\n  - [Installation](#installation)\n  - [Usage](#usage)\n  - [How It Works](#how-it-works)\n    - [1. Sudoku Board Detection](#1-sudoku-board-detection)\n    - [2. Digit Recognition](#2-digit-recognition)\n    - [3. Puzzle Solving](#3-puzzle-solving)\n    - [4. Solution Display](#4-solution-display)\n  - [Best-First Search Algorithm](#best-first-search-algorithm)\n    - [Heap Implementation](#heap-implementation)\n    - [How It Works](#how-it-works-1)\n  - [Project Structure](#project-structure)\n  - [Acknowledgements](#acknowledgements)\n  - [Customization](#customization)\n  - [Troubleshooting](#troubleshooting)\n  - [Future Improvements](#future-improvements)\n  - [License](#license)\n\n## Features\n\n- **Real-time Sudoku detection** using computer vision techniques\n- **Automated digit recognition** with a trained Convolutional Neural Network (CNN)\n- **Intelligent puzzle solving** using a Best-First search algorithm\n- **Difficulty assessment** of detected puzzles (Easy, Medium, Hard, Expert)\n- **Live solution overlay** directly on the webcam feed\n- **Performance monitoring** with FPS counter\n\n## Screenshots\n\n\u003cp\u003e\n  \u003cimg src=\"screenshots/demo.gif\" alt=\"Demo Video\" width=\"800\"/\u003e\u003cbr/\u003e\n  \u003cem\u003eVideo demonstration of the application\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003cimg src=\"screenshots/skewed.png\" alt=\"Skewed Sudoku\" width=\"600\"/\u003e\u003cbr/\u003e\n  \u003cem\u003eDetection of a skewed Sudoku puzzle\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003cimg src=\"screenshots/invalid_shape.png\" alt=\"Invalid Shape Detection\" width=\"600\"/\u003e\u003cbr/\u003e\n  \u003cem\u003eDetection of invalid grid shapes\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003cimg src=\"screenshots/invalid.png\" alt=\"Invalid Puzzle\" width=\"600\"/\u003e\u003cbr/\u003e\n  \u003cem\u003eRecognition of invalid or unsolvable puzzles\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003cimg src=\"screenshots/solved.png\" alt=\"Solved Puzzle\" width=\"600\"/\u003e\u003cbr/\u003e\n  \u003cem\u003eCompleted solution overlay on the puzzle\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003cimg src=\"screenshots/terminal.png\" alt=\"Terminal\" width=\"400\"/\u003e\u003cbr/\u003e\n  \u003cem\u003eCompleted solution in the terminal\u003c/em\u003e\n\u003c/p\u003e\n\n## Requirements\n\n- Python 3.10 or above\n- The following Python packages:\n\n```\nkeras==3.8.0\nnumpy==1.26.4\nopencv-python==4.11.0\nscipy==1.15.2\ntensorflow==2.16.2\n```\n\n## Installation\n\n1. Clone this repository or download the source code\n2. Install the required dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\n3. Make sure all files are in the same directory:\n   - `main.py` - The main entry point\n   - `RealTimeSudokuSolver.py` - Core processing code\n   - `sudokuSolver.py` - Puzzle solving algorithm\n   - `sudokuDifficulty.py` - Puzzle difficulty assessment\n   - `digitRecognition.h5` - Trained neural network model for digit recognition\n\n## Usage\n\n1. Run the main script:\n\n```bash\npython main.py\n```\n\n2. Hold a Sudoku puzzle in front of your webcam\n3. The application will:\n   - Detect the Sudoku grid\n   - Recognize the digits\n   - Solve the puzzle\n   - Display the solution overlaid on the video feed\n   - Show the puzzle's difficulty level\n4. Press 'q' to quit the application\n\n## How It Works\n\n### 1. Sudoku Board Detection\n\nThe application uses OpenCV to:\n\n- Apply adaptive thresholding using cv2.adaptiveThreshold\n- Identify contours with cv2.findContours\n- Find the largest quadrilateral contour (the Sudoku board)\n- Transform the perspective using cv2.warpPerspective to get a top-down view of the board\n\n### 2. Digit Recognition\n\nFor each cell in the grid:\n\n- Extract the cell image\n- Process and normalize the image using cv2.resize and cv2.threshold\n- Use a pre-trained CNN to recognize digits\n- Build a numerical representation of the puzzle\n\n### 3. Puzzle Solving\n\nOnce the puzzle is represented as a 9x9 grid:\n\n- Verify the puzzle is valid\n- Calculate the difficulty level\n- Use a Best-First search algorithm to efficiently solve the puzzle\n- The algorithm prioritizes cells with the fewest possible values\n\n### 4. Solution Display\n\nThe solved values are:\n\n- Rendered on the transformed image using cv2.putText\n- Inverse perspective transformed back to the original frame\n- Displayed as an overlay on the live camera feed\n\n## Best-First Search Algorithm\n\n### Heap Implementation\n\nOur Sudoku solver uses Python's `heapq` module to implement a min-heap priority queue that significantly optimizes the solving process:\n\n- Empty cells are prioritized by the number of valid digit choices they have (fewer choices = higher priority)\n- The `EntryData` class tracks each cell's position and number of valid choices\n- Custom comparison methods enable efficient heap operations\n\n### How It Works\n\n1. **Initial Setup**:\n\n   - Calculate valid choices for each empty cell\n   - Add all empty cells to the min-heap, ordered by fewest choices\n\n2. **Solving Process**:\n\n   - Always select the cell with fewest options first (from top of heap)\n   - Try placing valid digits and update remaining cell priorities\n   - Create new heap with recalculated priorities for each branch\n\n3. **Performance Benefits**:\n   - Significantly reduces the search space by making optimal choices\n   - Minimizes backtracking by selecting constrained cells first\n   - Solves even difficult puzzles efficiently by focusing on the most constrained parts first\n\n## Project Structure\n\n- **main.py**: Entry point, webcam handling, and main loop\n- **RealTimeSudokuSolver.py**: Image processing, digit recognition, and solution overlay\n- **sudokuSolver.py**: Best-First search algorithm implementation\n- **sudokuDifficulty.py**: Analysis of puzzle complexity\n- **digitRecognition.h5**: Pre-trained CNN model file\n\n## Acknowledgements\n\n- **Anh Minh Tran**: for the original project inspiration and implementation\n  - https://github.com/anhminhtran235/real_time_sudoku_solver\n- **Chars74K**: dataset for providing the computer font digit samples used in training\n  - http://www.ee.surrey.ac.uk/CVSSP/demos/chars74k/\n- **Peter Norvig's** efficient constraint satisfaction algorithm:\n  - https://github.com/norvig/pytudes/blob/main/ipynb/Sudoku.ipynb\n- **Nesh Patel's** articles on Sudoku solving algorithms:\n  - Solving Sudoku Part I: https://medium.com/@neshpatel/solving-sudoku-part-i-7c4bb3097aa7\n  - Solving Sudoku Part II: https://medium.com/@neshpatel/solving-sudoku-part-ii-9a7019d196a2\n- Various tutorials and resources from OpenCV, Stack Overflow, and educational platforms that contributed to the improved implementation\n\n## Customization\n\n- Adjust camera settings in `main.py` if needed\n- The neural network model is already trained, but you can retrain it with your own digit samples\n\n## Troubleshooting\n\n- Ensure good lighting conditions for better digit recognition\n- Hold the Sudoku puzzle relatively flat to the camera\n- If recognition is poor, try to minimize glare and shadows on the puzzle\n\n## Future Improvements\n\n- Support for mobile devices\n- Save and load puzzles functionality\n- Step-by-step solution visualization\n- Enhanced image processing for better recognition in challenging conditions\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshubhs27%2Fsnap-n-solve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshubhs27%2Fsnap-n-solve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshubhs27%2Fsnap-n-solve/lists"}