{"id":20315721,"url":"https://github.com/kkoomen/qbr","last_synced_at":"2025-05-15T09:04:04.354Z","repository":{"id":3659303,"uuid":"50454366","full_name":"kkoomen/qbr","owner":"kkoomen","description":"A webcam-based 3x3x3 rubik's cube solver written in Python 3 and OpenCV.","archived":false,"fork":false,"pushed_at":"2024-10-27T18:02:46.000Z","size":19694,"stargazers_count":623,"open_issues_count":4,"forks_count":98,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-03-31T02:12:45.211Z","etag":null,"topics":["accurate","canny-edge-detection","ciede2000","color-detection","cuber","delta-e","demo","multilingual","opencv","python","qbr","rubiks-cube","rubiks-cube-detection","rubiks-cube-solver","webcam"],"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/kkoomen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"custom":["https://paypal.me/koomenk","https://buymeacoff.ee/kkoomen"]}},"created_at":"2016-01-26T19:44:35.000Z","updated_at":"2025-03-12T13:07:00.000Z","dependencies_parsed_at":"2023-01-11T16:33:00.300Z","dependency_job_id":"ae5cecf3-6b2c-4d5e-8d5a-56c521e7d9c6","html_url":"https://github.com/kkoomen/qbr","commit_stats":{"total_commits":113,"total_committers":9,"mean_commits":"12.555555555555555","dds":"0.23008849557522126","last_synced_commit":"986aff9c8c95fe43a3a533d96769601e85ebf56c"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkoomen%2Fqbr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkoomen%2Fqbr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkoomen%2Fqbr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkoomen%2Fqbr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kkoomen","download_url":"https://codeload.github.com/kkoomen/qbr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247584111,"owners_count":20962075,"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":["accurate","canny-edge-detection","ciede2000","color-detection","cuber","delta-e","demo","multilingual","opencv","python","qbr","rubiks-cube","rubiks-cube-detection","rubiks-cube-solver","webcam"],"created_at":"2024-11-14T18:21:11.324Z","updated_at":"2025-04-07T03:17:41.975Z","avatar_url":"https://github.com/kkoomen.png","language":"Python","readme":"# Qbr\n\nQbr, pronounced as Cuber, is a webcam-based 3x3x3 rubik's cube solver written in\nPython 3 and OpenCV.\n\n- :rainbow: Accurate color detection\n- :mag: Accurate 3x3x3 rubik's cube detection\n- :capital_abcd: Multilingual\n\n### Solve mode\n\n![solve mode](./demo-solve-mode.jpg)\n\n### Calibrate mode\n\nIsn't the default color detection working out for you? Use the **calibrate\nmode** to let Qbr be familiar with your cube's color scheme. If your room has\nproper lighting then this will give you a 99.9% guarantee that your colors will\nbe detected properly.\n\nSimply follow the on-screen instructions and you're ready to go.\n\n![calibrate mode](./demo-calibrate-mode.jpg)\n![calibrate mode success](./demo-calibrate-mode-success.jpg)\n\n# Table of Contents\n\n- [Qbr](#qbr)\n    + [Solve mode](#solve-mode)\n    + [Calibrate mode](#calibrate-mode)\n- [Table of Contents](#table-of-contents)\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Usage](#usage)\n    + [The first 9-sticker display (upper left corner)](#the-first-9-sticker-display-upper-left-corner)\n    + [The second 9-sticker display (upper left corner)](#the-second-9-sticker-display-upper-left-corner)\n    + [Amount of sides scanned - text (bottom left corner)](#amount-of-sides-scanned---text-bottom-left-corner)\n    + [Full 2D cube state visualization (bottom right corner)](#full-2d-cube-state-visualization-bottom-right-corner)\n    + [Interface language (top right corner)](#interface-language-top-right-corner)\n    + [Calibrate mode](#calibrate-mode-1)\n- [Getting the solution](#getting-the-solution)\n  * [How to scan your cube properly?](#how-to-scan-your-cube-properly)\n- [Keybindings](#keybindings)\n- [Parameters](#parameters)\n- [Example runs](#example-runs)\n- [Inspirational sources](#inspirational-sources)\n- [License](#license)\n\n# Introduction\n\nThe idea to create this came personally to mind when I started solving rubik's\ncubes. There were already so many professional programmers around the world who\ncreated robots that solve a rubik's cube in an ETA of 5 seconds and since 2016\nin 1 second ([link](https://www.youtube.com/watch?v=ixTddQQ2Hs4)).\nThat inspired me to create my own. I started using images only and eventually\nswitched to webcam.\n\n# Installation\n\n\nFor linux users, make sure to install the following prerequisites:\n```\n$ sudo apt-get install python3-dev build-essential\n```\n\nThen, continue to install the project:\n\n```\n$ git clone --depth 1 https://github.com/kkoomen/qbr.git\n$ cd qbr\n$ python3 -m venv env\n$ source ./env/bin/activate\n$ pip3 install -r requirements.txt\n```\n\n# Usage\n\n**Make sure you run `source ./env/bin/activate` every time you want to run the\nprogram.**\n\nRun Qbr:\n\n```\n$ ./src/qbr.py\n```\n\nThis opens a webcam interface with the following things:\n\n### The first 9-sticker display (upper left corner)\n\nThis is live preview mode displaying the detected colors.\n\n### The second 9-sticker display (upper left corner)\n\nThis is the snapshot state. When pressing `SPACE` it will create a snapshot in\norder to show you what state it has saved. You can press `SPACE` as many times\nas you'd like if it has been detected wrong. The center piece color is used to\ndetect which side to save.\n\n### Amount of sides scanned - text (bottom left corner)\n\nThe bottom left corner shows the amount of sides scanned. This is so you\nknow if you've scanned in all sides before pressing `ESC`.\n\n### Full 2D cube state visualization (bottom right corner)\n\nThis visualization represents the whole cube state that is being saved and can\nbe used to confirm whether the whole cube state has been scanned successfully.\n\n### Interface language (top right corner)\n\nIn the top right corner you can see the current interface language. If you want\nto change the interface language you can press `l` to cycle through them.\nContinue to press `l` until you've found the right language.\n\nDefault language is set to English.\n\nAvailable languages are:\n\n- English\n- Hungarian\n- Deutsch\n- French\n- Spanish\n- Dutch\n- 简体中文\n- 台灣繁體中文\n- Arabic (العربية)\n\n### Calibrate mode\n\nThe default color scheme contains the most prominent colors for white, yellow, red,\norange, blue and green. If this can't detect your cube its colors properly then\nyou can use calibrate mode.\n\nPress `c` to go into calibrate mode in order to let Qbr be familiar with your\ncube's color scheme. Simply follow the on-screen instructions and you're ready\nto go.\n\nNote: Your calibrated settings are automatically saved after you've calibrated\nyour cube successfully. The next time you start Qbr it will automatically load\nit.\n\nTip: If you've scanned wrong, simple go out of calibrate mode by pressing `c`\nand go back into calibrate by pressing `c` again.\n\n# Getting the solution\n\nQbr checks if you have filled in all 6 sides when pressing `ESC`. If so, it'll\ncalculate a solution if you've scanned it correctly.\n\nYou should now see a solution (or an error if you did it wrong).\n\n## How to scan your cube properly?\n\nThere is a strict way of scanning in the cube. Qbr will detect the side\nautomatically, but the way you rotate the cube during the time you're scanning\nit is crucial in order for Qbr to properly calculate a solution. Make sure to\nfollow the steps below properly:\n\n- Start off with the `green` side facing the camera and `white` on top, `green`\n  being away from you. Start by scanning in the `green` side at this point.\n- After you've scanned in the `green` side, rotate the cube 90 or -90 degrees\n  horizontally. It doesn't matter if you go clockwise or counter-clockwise.\n  Continue to do this for the `green`, `blue`, `red` and `orange` sides until\n  you are back at the `green` side.\n- You should now be in the same position like you started, having `green` facing\n  the camera and `white` on top. Rotate the cube forward 90 degrees, resulting\n  in `green` at the bottom and `white` facing the camera. Start scanning in the\n  `white` side.\n- After you've scanned the `white` side, turn the cube back to how you started,\n  having `green` in front again and `white` on top. Now rotate the cube\n  backwards 90 degrees, resulting in `green` on top and `yellow` facing the\n  camera. Now you can scan in the last `yellow` side.\n\nIf you've done the steps above correctly, you should have a solution from Qbr.\n\n# Keybindings\n\n- `SPACE` for saving the current state\n\n- `ESC` quit\n\n- `c` toggle calibrate mode\n\n- `l` switch interface language\n\n# Parameters\n\nYou can use `-n` or `--normalize` to also output the solution in a \"human-readable\" format.\n\nFor example:\n\n* `R` will be: `Turn the right side a quarter turn away from you.`\n* `F2` will be: `Turn the front face 180 degrees.`\n\n# Example runs\n\n```\n$ ./qbr.py\nStarting position:\nfront: green\ntop: white\n\nMoves: 20\nSolution: U2 R D2 L2 F2 L U2 L F' U L U R2 B2 U' F2 D2 R2 D2 R2\n```\n\n```\n$ ./qbr.py -n\nStarting position:\nfront: green\ntop: white\n\nMoves: 20\nSolution: B2 U2 F' R U D' L' B' U L F U F2 R2 F2 D' F2 D R2 D2\n1. Turn the back side 180 degrees.\n2. Turn the top layer 180 degrees.\n3. Turn the front side a quarter turn to the left.\n4. Turn the right side a quarter turn away from you.\n5. Turn the top layer a quarter turn to the left.\n6. Turn the bottom layer a quarter turn to the left.\n7. Turn the left side a quarter turn away from you.\n8. Turn the back side a quarter turn to the right.\n9. Turn the top layer a quarter turn to the left.\n10. Turn the left side a quarter turn towards you.\n11. Turn the front side a quarter turn to the right.\n12. Turn the top layer a quarter turn to the left.\n13. Turn the front side 180 degrees.\n14. Turn the right side 180 degrees.\n15. Turn the front side 180 degrees.\n16. Turn the bottom layer a quarter turn to the left.\n17. Turn the front side 180 degrees.\n18. Turn the bottom layer a quarter turn to the right.\n19. Turn the right side 180 degrees.\n20. Turn the bottom layer 180 degrees.\n```\n\n# Inspirational sources\n\nSpecial thanks to [HaginCodes](https://github.com/HaginCodes) for the main\ninspiration on how to improve my color detection.\n\nhttps://github.com/HaginCodes/3x3x3-Rubiks-Cube-Solver\n\nhttp://programmablebrick.blogspot.com/2017/02/rubiks-cube-tracker-using-opencv.html\n\nhttps://gist.github.com/flyboy74/2cc3097f784c8c236a1a85278f08cddd\n\nhttps://github.com/dwalton76/rubiks-color-resolver\n\n# License\n\nQbr is licensed under the MIT License.\n","funding_links":["https://paypal.me/koomenk","https://buymeacoff.ee/kkoomen"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkoomen%2Fqbr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkkoomen%2Fqbr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkoomen%2Fqbr/lists"}