{"id":26659809,"url":"https://github.com/architj6/sudokuvision","last_synced_at":"2026-04-11T14:02:39.422Z","repository":{"id":283871085,"uuid":"952034947","full_name":"ArchitJ6/SudokuVision","owner":"ArchitJ6","description":"SudokuVision is an OCR-powered Sudoku solver that extracts grids from images using machine learning and image processing techniques. It supports both printed and handwritten Sudoku puzzles, providing fast and accurate solutions via a web interface and command-line tool.","archived":false,"fork":false,"pushed_at":"2025-03-22T17:32:30.000Z","size":1548,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-22T18:33:05.463Z","etag":null,"topics":["deeplearning","digitrecognition","imageprocessing","keras","machinelearning","ml","ocr","opencv","opencv-python","pysudoku","python","streamlit","sudoku","sudokusolver","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/ArchitJ6.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}},"created_at":"2025-03-20T16:19:51.000Z","updated_at":"2025-03-22T17:35:13.000Z","dependencies_parsed_at":"2025-03-22T18:33:13.634Z","dependency_job_id":"6e5579b4-32a7-43c6-9ac4-c6868d10bbed","html_url":"https://github.com/ArchitJ6/SudokuVision","commit_stats":null,"previous_names":["architj6/sudokuvision"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArchitJ6%2FSudokuVision","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArchitJ6%2FSudokuVision/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArchitJ6%2FSudokuVision/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArchitJ6%2FSudokuVision/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ArchitJ6","download_url":"https://codeload.github.com/ArchitJ6/SudokuVision/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245449675,"owners_count":20617190,"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":["deeplearning","digitrecognition","imageprocessing","keras","machinelearning","ml","ocr","opencv","opencv-python","pysudoku","python","streamlit","sudoku","sudokusolver","tensorflow"],"created_at":"2025-03-25T11:15:29.487Z","updated_at":"2025-10-07T20:11:25.786Z","avatar_url":"https://github.com/ArchitJ6.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧩 **SudokuVision**\n\n**SudokuVision** is an OCR-powered Sudoku solver that uses cutting-edge machine learning 🤖 and image processing 📸 techniques to extract Sudoku grids from images and solve them efficiently. Whether your Sudoku puzzle is handwritten ✍️ or printed 📰, **SudokuVision** ensures an accurate solution every time! 🎯\n\n---\n\n## ✨ **Overview**\n\n**SudokuVision** integrates Optical Character Recognition (OCR) for grid extraction 🧠 and deep learning algorithms 🔍 to recognize digits within the grid. The application then uses the **PySudoku** library 🧩 to solve the puzzle, providing a seamless and fast solution ⏱️.\n\n- **OCR-Based Sudoku Grid Detection** 📸\n- **Digit Recognition Using Deep Learning** 🤖\n- **PySudoku-Based Solver** 🧩\n- **Works with Printed and Handwritten Sudoku Puzzles** ✍️\n- **Supports PNG, JPG, JPEG Images** 🖼️\n\n---\n\n## ✨ **Features**\n\n- **Grid Extraction**: Automatically extracts Sudoku grids from images using advanced image processing techniques 🎯.\n- **Digit Recognition**: Identifies digits within the grid using deep learning models 🔢.\n- **Fast Solver**: Solves puzzles using the **PySudoku** backtracking solver ⏱️.\n- **Command Line and Web Interface**: Provides both command-line and Streamlit-based web interface for ease of use 🖥️.\n- **Multiple Image Formats**: Works with various image formats like PNG, JPG, and JPEG 📸.\n- **Real-time Visualization**: Displays the solved Sudoku puzzle directly in the web app 🌐 and on the command line interface using **OpenCV** 💡.\n\n---\n\n## 📊 **Datasets Used**\n\nThe following datasets were used for training the deep learning model for digit recognition and grid extraction:\n\n### 🧑‍🏫 **1. MNIST Dataset**\nThe **MNIST** dataset, containing 60,000 handwritten digit images 🖋️, was used to train the deep learning model for digit recognition. The dataset includes grayscale images 🖤 of size 28x28 pixels and is ideal for training models to recognize handwritten digits.\n\n- **Preprocessing**:  \n  - Grayscale normalization to a range of [0, 1] 🌑.\n  - Reshaped to 28x28 pixels 🖼️.\n\n### 🔠 **2. Chars74K Dataset**\nThe **Chars74K** dataset contains images of characters in various fonts 🔠, including digits, used to supplement the training process with diverse digital font variations 🅰️.\n\n- **Preprocessing**:  \n  - Resized to 28x28 pixels 🖼️.\n  - Grayscale conversion and normalization to a range of [0, 1] 🌑.\n\nThis dataset enhances the model's ability to recognize digits in digital fonts, improving accuracy across various types of input 📏.\n\n### ✍️ **3. TMNIST Dataset**\nThe **TMNIST** dataset is another handwritten digit dataset used to further train and diversify the digit recognition capabilities 🤖. It contains images in the same format as MNIST and was used to train the model on additional handwritten digits ✍️.\n\n- **Preprocessing**:  \n  - Data is scaled to a range of [0, 1] 🌑.\n  - Labels are encoded using **LabelEncoder** 🔣 and converted to categorical values 📊.\n\n---\n\n## 🔍 **How It Works**\n\n1. **Puzzle Extraction** 🧩  \n   The uploaded image is processed using **OpenCV** 🖼️ for grid extraction. The grid's edges are detected, and the puzzle is segmented into individual cells 🏷️.\n\n2. **Digit Recognition** 🔢  \n   Each individual cell in the grid is processed by a deep learning model that recognizes the digits 🧠. The model is trained on the **MNIST**, **Chars74K**, and **TMNIST** datasets 📊.\n\n3. **Puzzle Solving** 🧩  \n   Once the digits are identified, they are passed to the **PySudoku** solver, which uses a backtracking algorithm 🔄 to solve the puzzle 🧩.\n\n4. **Result Display** 🎥  \n   The original and solved puzzles are displayed:  \n   - **Web App** 🌐: The result is shown directly in the browser 🌍.  \n   - **Command Line** 💻: The solved puzzle is displayed directly in the terminal using **OpenCV** 🖼️. The result is visualized without saving it to a file, using `cv2.imshow()` to show the solved puzzle 🧩.\n\n---\n\n## ⚙️ **Setup and Installation**\n\nTo set up **SudokuVision** 🧩 on your local machine 💻, follow the instructions below:\n\n### 📝 **1. Clone the repository**\n```bash\ngit clone https://github.com/ArchitJ6/SudokuVision.git  \ncd SudokuVision  \n```\n\n### 📦 **2. Install Dependencies**\nCreate a virtual environment (recommended) 🌱 and install required packages:  \n```bash\npython -m venv venv  \nsource venv/bin/activate  # On Windows use `venv\\Scripts\\activate`  \npip install -r requirements.txt  \n```\n\n### 📥 **3. Download the Datasets**  \nMake sure to download the **Chars74K**, **MNIST**, and **TMNIST** datasets. The datasets should be organized in the following directory structure:\n\n```\n/datasets  \n    /Chars74K-Digital-English-Font  \n        Extract the files and place the folders for digits 0 to 9 here, each containing images of the corresponding digit (labeled accordingly).  \n    /tmnist  \n        This dataset contains a `data.csv` file with the data for handwritten digits.  \n```\n\n- **MNIST**: The MNIST dataset will be used directly from Keras.  \n- **Chars74K-Digital-English-Font**: Extract the files and organize them into folders for digits 0 to 9, with images of each digit placed inside the corresponding folder, labeled by the digit.  \n- **TMNIST**: This dataset includes a `data.csv` file that contains the data for handwritten digits. \n---\n\n## 🧑‍💻 **Usage**\n\n### 🌐 **1. Streamlit Interface**\n\nTo run the web interface using Streamlit 🖥️, follow these steps:\n\n1. **Run the Streamlit app**:  \n```bash\nstreamlit run app.py  \n```\n\n2. **Upload the Image** 🖼️:  \n   - After the app starts, open the URL provided by Streamlit 🌐.  \n   - Upload an image of the Sudoku puzzle (printed or handwritten) 🧩.  \n   - Click **\"Solve Sudoku\"** 🧠 to process and get the solution 🧩.\n\n3. **Output** 🎥:  \n   The original puzzle with solved values will be displayed directly on the web interface 🌐.\n\n### 💻 **2. Command-Line Interface (CLI)**\n\nTo use the command-line interface 💻:\n\n1. **Run the script**:  \n```bash\npython solve.py --image \u003cpath_to_image\u003e --debug -1  \n```\n\n- `--image`: Path to the Sudoku image 🖼️.\n- `--debug`: Set to `1` for debug mode 🛠️, which visualizes the grid and digit extraction process 🔍.\n\n2. **Output** 🎥:  \n   The solved Sudoku puzzle 🧩 will be displayed directly in the new window using **OpenCV** 🖼️. The window will automatically close when any key is pressed ⏳.\n\n### 📚 **3. Model Training**\n\nTo train the model for digit recognition 🧠, use the following script:\n\n```bash\npython train_model.py  \n```\n\nThis will load the datasets 📊, preprocess the data 🔄, train the model 🤖, and save the trained model for future use 💾.\n\n---\n\n## 💡 **Best Practices for Usage**\n\nTo get the most accurate results, keep the following tips in mind:\n\n- Ensure good lighting when capturing handwritten Sudoku puzzles ✍️ for optimal digit recognition.\n- Use high-resolution images 🖼️ for better grid and digit extraction.\n- For handwritten puzzles, maintain legibility of digits for improved accuracy ✍️.\n\n---\n\n## 🔧 **Troubleshooting**\n\nIf you run into issues, check these common solutions:\n\n- **Missing Dependencies**: Make sure all packages are installed by running `pip install -r requirements.txt` 📦.\n- **Image Processing Errors**: Ensure that the uploaded image is clear and contains a proper Sudoku grid 📸.\n- **Solver Not Working**: Make sure the digits are clearly detected by checking the debug output with the `--debug` flag 🛠️.\n\n---\n\n## 🔒 **Security and Privacy**\n\nYour uploaded images are processed locally and are not stored long-term. We respect your privacy and ensure that no sensitive information is exposed during the image upload and processing process 🔐.\n\n---\n\n## 🤝 **How to Contribute**\n\nWe welcome contributions! 🎉 To contribute to **SudokuVision** 🧩, follow these steps:\n\n1. Fork the repository 🍴.\n2. Create a new branch (`git checkout -b feature-name`) 🌱.\n3. Make your changes ✍️.\n4. Commit your changes (`git commit -m 'Add feature'`) 💬.\n5. Push to the branch (`git push origin feature-name`) 🚀.\n6. Open a pull request with a description of your changes 📄.\n\n---\n\n## 🙏 **Acknowledgments**\n\n- **PySudoku Library** 🧩: For providing an efficient backtracking-based solver.\n- **MNIST** 📚: For the dataset used for training the digit recognition model.\n- **Chars74K** 🔠: For the dataset of digital fonts, enriching the model's ability to recognize various types of digits.\n- **TMNIST** ✍️: For further diversifying the training data and enhancing recognition accuracy.\n\n---\n\n## 📜 **License**\n\nThis project is licensed under the [**MIT License**](LICENSE) ⚖️.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farchitj6%2Fsudokuvision","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farchitj6%2Fsudokuvision","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farchitj6%2Fsudokuvision/lists"}