{"id":13573463,"url":"https://github.com/nemanja-m/gaps","last_synced_at":"2025-05-16T18:06:50.622Z","repository":{"id":37412533,"uuid":"81377784","full_name":"nemanja-m/gaps","owner":"nemanja-m","description":"A Genetic Algorithm-Based Solver for Jigsaw Puzzles :cyclone:","archived":false,"fork":false,"pushed_at":"2024-08-31T00:22:05.000Z","size":5692,"stargazers_count":747,"open_issues_count":4,"forks_count":111,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-04-12T16:53:56.742Z","etag":null,"topics":["genetic-algorithm","puzzle-solver"],"latest_commit_sha":null,"homepage":null,"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/nemanja-m.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":"2017-02-08T21:28:05.000Z","updated_at":"2025-04-11T07:56:44.000Z","dependencies_parsed_at":"2024-11-05T08:41:36.217Z","dependency_job_id":null,"html_url":"https://github.com/nemanja-m/gaps","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/nemanja-m%2Fgaps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nemanja-m%2Fgaps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nemanja-m%2Fgaps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nemanja-m%2Fgaps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nemanja-m","download_url":"https://codeload.github.com/nemanja-m/gaps/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254582905,"owners_count":22095518,"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":["genetic-algorithm","puzzle-solver"],"created_at":"2024-08-01T15:00:36.382Z","updated_at":"2025-05-16T18:06:50.604Z","avatar_url":"https://github.com/nemanja-m.png","language":"Python","funding_links":[],"categories":["Games","Python"],"sub_categories":[],"readme":"\u003ch1 align=center\u003e\n  \u003cimg src=\"logo/LogoHorizontal.png\" width=50%\u003e\n\u003c/h1\u003e\n\nGenetic Algorithm based solver for jigsaw puzzles with piece size\nauto-detection.\n\n[![gaps](https://github.com/nemanja-m/gaps/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/nemanja-m/gaps/actions/workflows/ci.yml)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/lena.gif\" alt=\"demo\" /\u003e\n\u003c/p\u003e\n\n# Installation\n\nClone repo:\n\n```bash\ngit clone https://github.com/nemanja-m/gaps.git\ncd gaps\n```\n\nInstall requirements:\n\n```bash\npoetry install\n```\n\nInstall project locally:\n\n```bash\npip install .\n```\n\n# Creating puzzles from images\n\nTo create puzzle from image use `gaps create`\n\n```bash\ngaps create images/pillars.jpg puzzle.jpg --size=64\n```\n\nwill create puzzle with 240 pieces from `images/pillars.jpg` where each piece is\n64x64 pixels.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"images/pillars.jpg\" alt=\"original\" width=\"250\" height=\"180\" /\u003e\n  \u0026nbsp; \u0026nbsp; \u0026nbsp; \u0026nbsp; \u0026nbsp; \u0026nbsp;\n  \u003cimg src=\"images/demo_puzzle.jpg\" alt=\"puzzle\" width=\"250\" height=\"180\" /\u003e\n\u003c/div\u003e\n\nRun `gaps create --help` for detailed help.\n\n__NOTE__: Created puzzle image dimensions may be smaller then original image\ndepending on the given puzzle piece size. Maximum possible rectangle is cropped\nfrom original image.\n\n# Solving puzzles\n\nIn order to solve puzzles, use `gaps run`:\n\n```bash\ngaps run puzzle.jpg solution.jpg --generations=20 --population=600\n```\n\nThis will start genetic algorithm with initial population of 600 and 20 generations.\n\nFollowing options are provided:\n\nOption          | Description\n--------------- | -----------\n`--size`        | Puzzle piece size in pixels\n`--generations` | Number of generations for genetic algorithm\n`--population`  | Number of individuals in population\n`--debug`       | Show the best solution after each generation\n\nRun `gaps run --help` for detailed help.\n\n## Size detection\n\nIf you don't explicitly provide `--size` argument to `gaps run`, piece size will\nbe detected automatically.\n\nHowever, you can always provide `gaps run` with `--size` argument explicitly:\n\n```bash\ngaps run puzzle.jpg solution.jpg --generations=20 --population=600 --size=48\n```\n\n__NOTE__: Size detection feature works for the most images but there are some edge cases\nwhere size detection fails and detects incorrect piece size. In that case you can\nexplicitly set piece size.\n\n## Termination condition\n\nThe termination condition of a Genetic Algorithm is important in determining\nwhen a GA run will end.  It has been observed that initially, the GA progresses\nvery fast with better solutions coming in every few iterations, but this tends\nto saturate in the later stages where the improvements are very small.\n\n`gaps` will terminate:\n\n* when there has been no improvement in the population for `X` iterations, or\n* when it reaches an absolute number of generations\n\n# References\n\nBibTeX entry:\n\n```text\n@article{Sholomon2016,\n  doi = {10.1007/s10710-015-9258-0},\n  url = {https://doi.org/10.1007/s10710-015-9258-0},\n  year = {2016},\n  month = feb,\n  publisher = {Springer Science and Business Media {LLC}},\n  volume = {17},\n  number = {3},\n  pages = {291--313},\n  author = {Dror Sholomon and Omid E. David and Nathan S. Netanyahu},\n  title = {An automatic solver for very large jigsaw puzzles using genetic algorithms},\n  journal = {Genetic Programming and Evolvable Machines}\n}\n```\n\n# License\n\nThis project as available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnemanja-m%2Fgaps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnemanja-m%2Fgaps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnemanja-m%2Fgaps/lists"}