{"id":13722447,"url":"https://github.com/fabridigua/LogicGamesSolver","last_synced_at":"2025-05-07T15:30:46.119Z","repository":{"id":159145780,"uuid":"330773919","full_name":"fabridigua/LogicGamesSolver","owner":"fabridigua","description":"A Python tool to solve logic games with AI, Deep Learning and Computer Vision","archived":false,"fork":false,"pushed_at":"2021-01-30T19:17:05.000Z","size":8742,"stargazers_count":15,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-14T11:40:05.738Z","etag":null,"topics":["artificial-intelligence","computer-vision","constraint-satisfaction-problem","deep-learning","logic-games","sudoku"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fabridigua.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":"2021-01-18T20:03:02.000Z","updated_at":"2024-04-01T11:49:39.000Z","dependencies_parsed_at":"2023-07-28T07:30:35.221Z","dependency_job_id":null,"html_url":"https://github.com/fabridigua/LogicGamesSolver","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabridigua%2FLogicGamesSolver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabridigua%2FLogicGamesSolver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabridigua%2FLogicGamesSolver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabridigua%2FLogicGamesSolver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabridigua","download_url":"https://codeload.github.com/fabridigua/LogicGamesSolver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252905552,"owners_count":21822823,"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":["artificial-intelligence","computer-vision","constraint-satisfaction-problem","deep-learning","logic-games","sudoku"],"created_at":"2024-08-03T01:01:28.825Z","updated_at":"2025-05-07T15:30:41.110Z","avatar_url":"https://github.com/fabridigua.png","language":"Python","funding_links":[],"categories":["Project List"],"sub_categories":["\u003cspan id=\"tool\"\u003eLLM (LLM \u0026 Tool)\u003c/span\u003e"],"readme":"# LogicGamesSolver\n Python tool for solving logic games with AI, Computer Vision and a pinch of Deep Learning. \n\n----------------\n\n\u003cimg src=\"imgs/screen_boards_solved.png\" alt=\"Scre\" style=\"zoom:100%;\" /\u003e\n\n------\n\n## Table of contents\n\n* [Basic Overview](#basic-overview)\n* [Project structure](#project-structure)\n* [System Requirements](#system-requirements)\n* [Setup](#setup)\n* [How it works](#how-it-works)\n* [Games included](#games-included)\n* [References](#references)\n\n## Basic Overview\n\nThis project combines Computer Vision and Artificial Intelligence to solve logic puzzle games like *Sudoku*, *Stars Battle* and *Skyscrapers*.\n\nThe execution consists of 2 phases:\n\n| 1. Board Detection                                           | 2. Game solving                                              |\n| ------------------------------------------------------------ | ------------------------------------------------------------ |\n| \u003cimg src=\"imgs/screen_stars_board_found.png\" style=\"zoom:100%;\" /\u003e | \u003cimg src=\"imgs/screen_stars_board_solved.png\" style=\"zoom:100%;\" /\u003e |\n| The software detects the board showed by the user (in real-time or analyzing a local image). Then analyzes the structure to understand the needed informations to solve the game. | The information collected is then used to solve the puzzle considering it as a Constraints Satisfaction Problem using a Backtracking algorithm to find the solution, given the game rules. |\n\n**Language**: *Python*\n\n**Frameworks**: *OpenCV*, *Tensorflow*\n\n**Algorithms**: Constraints Satisfaction Problem Backtracking, Digits Classifier (CNN), Image Contours Finding and Warping \n\n## Project structure\n\n```\nLogicGamesSolver\n│   README.md\n│   LICENSE\n│\n└───imgs\n│   │   screen_XXX\tScreens for project explaination\n│   │   ...\n│\t\n│   main.py\t\tMain file to execute the software\n│   DigitClassifier.py\tClass for digit classification with a pretrained CNN\t\t\t\n│   PuzzleDetector.py\tClass for puzzle detection and analyze from an image\n│   Solver.py\t\tClass for solving the games given puzzle's informations and rules \t\t\n```\n\n## System Requirements\n\n- **Python 3.8**\n\n- **Numpy 1.19.2**\n\n- **OpenCV 4.0.1**\n\n- **Tensorflow 2.3.0**\n\n  \n\n## Setup\n\nTo run the project, clone it with [Git] and run the `main.py` file with desired parameters:\n\n[Git]: https://git-scm.com/downloads\t\"Git download page\"\n\n```\n$ git clone https://github.com/fabridigua/LogicGamesSolver\n$ cd LogicGamesSolver\n$ python main.py sudoku 9 3\n```\n\nThere are 4 arguments you can set: \n\n[**game** name of the game you want to solve] = sudoku | skyscrapers | stars [default: sudoku]\n\n[**grid_len** number of squares in the side of the puzzle's grid] = *Integer* es. 5 [default: 9]\n\n[**square_len** for sudoku, number of squares in an area] = *Integer* es. 2 [default: 3]\n\n[**is_realtime** for coose between local or real-time execution] = *Boolean* es. true [default true]\n\nNote that if you set **is_realtime** to *false* you have to put an image file named *input_[**game**]*.*png* es. `input_stars.png` \n\n## How it works\n\nThis project touches many fields of study:\n\n1. **Computer Vision** for board detection \n2. **Deep Learning** for puzzle analyzing\n3. **Artificial Intelligence** for puzzle solving\n\n##### 1. Board Detection\n\nThe software analyzes the image in input looking for the biggest *contour*\u003csup\u003e[[1]](#cont_ref)\u003c/sup\u003e in the scene.\n\n\u003cimg src=\"imgs\\screen_sudoku_realtime_detection.png\" style=\"zoom:80%;\" /\u003e\n\nOnce found the puzzle, its image is warped applying a perspective transformation to make the puzzle image a plane.\n\nIn *real-time* mode,  the user must press `space` key to go ahead when the software is recognizing well the puzzle.\n\n##### 2. Puzzle Analyzing \n\nThe software analyzes the puzzle board to retrieve the needed informations to solve the game.\n\nIf the puzzle includes numbers (like  *Sudoku* and *Skyscrapers*) a **Convolutional Neural Network** for digit classifying (trained with the fabulous *MNIST*\u003csup\u003e[[2]](#mnist_ref)\u003c/sup\u003e dataset) is executed.\n\n\u003cimg src=\"imgs\\screen_stars_realtime_analyzing.png\" style=\"zoom:100%;\" /\u003e\n\nFor the *Stars* game, the board image is processed to find the inner areas. Using *OpenCV* methods, the boldest contours are highlighted and then the *connected components*\u003csup\u003e[[3]](#connected_ref)\u003c/sup\u003e are analyzed (and drawn in different colors) to find the areas of the grid.\n\n##### 3. Game solving\n\nOnce collected all the informations about the structure of the puzzle, the game is represented as a CSP (Constraint Satisfaction Problem) and solved applying a backtracking algorithm. By the game point of view, the CSP\u003csup\u003e[[4]](#csp_ref)\u003c/sup\u003e consists in 3 elements:\n\n- *Variables*: the grid cells to fill\n\n- *Domains*: the sets of values that each cell can assume\n\n- *Constraints*: the game's rules\n\nIf the input is correct, the algorithm finds the solution with 100% of accuracy, but it can takes a long time basing on grid length (and so the number of variables) and size of domains. For a normal *Sudoku* scheme it takes 3-5 seconds.\n\n\u003cimg src=\"imgs\\screen_sudoku_board_solved.png\" style=\"zoom:100%;\" /\u003e\n\nFor more details see the article.\n\n## Games Included\n\nFor now, this projects includes the detection and solving procedures of these games:\n\n- **Sudoku** [ ex. `python main.py sudoku 9 3`  ] \n\n  *Description*: given a grid with some number in range [1,9] , fill the empty cells respecting the rules.  \n\n  *Parameters*: \n\n  ​\t**grid_len**: number of squares in each row, column and inner area (usually 9) \n\n  ​\t**square_len**: number of square in each row and column of a inner area (usually 3) \n\n  *Rules*: \n\n  \t- Every row, column and area have to contain all number between 1 and 9\n\n\n\n- **Stars** [ex.  `python main.py stars 8 1`  ] \n\n  *Description*: given a grid divided into regions insert a star in each row, column and sector.\n\n  *Parameters*: \n\n  ​\t**grid_len**: number of squares in each row and column\n\n  ​\t**star_number**: number of stars in a inner area (usually 1) \n\n  *Rules*: \n\n  \t- Every row, column and sector have to contain only a star (or more if setted with *star_number* argument)\n  \t- Stars can't be in adjacent cells\n\n\n\n- **Skyscrapers** [ ex. `python main.py skyscrapers 8`  ] \n\n  *Description*: given a grid with some numbers near the sides, fill the grid with the number from 1 to **grid_len**.\n\n  *Parameters*: \n\n  ​\t**grid_len**: number of squares in each row and column\n\n  *Rules*: \n\n  \t- Every row, column and have to contain all number between 1 and **grid_len**\n  \t- The numbers along the edge of the puzzle indicate the number of buildings which you would see from that direction if there was a series of skyscrapers with heights equal the entries in that row or column.\n\n## References\n\n\u003ca name=\"cont_ref\"\u003e[1]\u003c/a\u003e:  [Contours : Getting Started]\n\n[Contours : Getting Started]: https://docs.opencv.org/3.4/d4/d73/tutorial_py_contours_begin.html\t\"Contours : Getting Started\"\n\n\u003ca name=\"mnist_ref\"\u003e[2]\u003c/a\u003e:  [MNIST Dataset]\n\n[MNIST Dataset]: http://yann.lecun.com/exdb/mnist/\t\"MNIST Dataset\"\n\n\u003ca name=\"connected_ref\"\u003e[3]\u003c/a\u003e:  [The connected-component labeling problem: A review of state-of-the-art algorithms]\n\n[The connected-component labeling problem: A review of state-of-the-art algorithms]: https://www.sciencedirect.com/science/article/pii/S0031320317301693\t\"The connected-component labeling problem: A review of state-of-the-art algorithms\"\n\n\u003ca name=\"csp_ref\"\u003e[4]\u003c/a\u003e:  [Constraint satisfaction problem]\n\n[Constraint satisfaction problem]: https://en.wikipedia.org/wiki/Constraint_satisfaction_problem\t\"Constraint satisfaction problem\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabridigua%2FLogicGamesSolver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabridigua%2FLogicGamesSolver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabridigua%2FLogicGamesSolver/lists"}