The following page is dedicated to Version 2.0 of the RubiksCubeRobot application, which is currently in beta.
1.1 Download Links
Please download the Raspberry PI, x64 and x86 versions of the app from the links below:
|Download Link for Raspberry PI|
|Platform:||ARM (Raspberry PI)|
|Download Link for x64|
|Download Link for x86|
1.2 What's New in Version 2.0
The new version offers the following major improvements over version 1.0:
- The zone recognition engine has been completely rewritten. Instead of looking for horizontal and vertical lines, as the old version did, the new version looks for square contours, which makes the process more adaptive and robust. There is no need for image deskewing anymore. Also, the new algorithm works much better when the cube appears far and small on the photos.
- The photos are processed immediately after a pair is taken. If something is wrong with a photo, the error is displayed immediately and the photographing sequence is discontinued. The old version began processing the photos only after all 12 were taken. Moreover, the new version performs image processing in parallel with the cube-rotating operations, which speeds up the photographing phase considerably. This is especially noticeable on the relatively slow Raspberry PI.
- The new version has a Camera button which allows you to take a picture of the cube at any time, not just during a run. This makes it much easier to adjust the camera position and focus.
- The new version allows the app to be exited by pressing the OFF button and holding it down for 3 seconds. This feature is useful if the app runs on Raspberry PI as it allows the PI to be properly shut down.
- When the debug mode is enabled, the new version no longer creates .pix and config.txt files. Instead it creates a single PDF document per run, which contains the debug and color training information. There is no need for "the Eye" tool anymore.
- Color training is performed automatically for every run, and the results are put on the last page of the PDF file. This information is only useful if the cube was inserted fully assembled, with the white face towards the camera and red face pointing upwards. The Training button has been eliminated entirely.
- The white color detection algorithm has been improved in the new version. The old version allowed you specify a single non-white color that the white color is similar to (WHITE IS LIKE parameter). The new version allows you to specify a wide range of hues for the white color. As in the old version, white is separated from non-whites by saturation. See below for more info.
- Like the old version, the new version separates the non-white colors among each other by hue. Since the red and orange plates of the classic Rubik's Cube are very close hue-wise, the new version also allows you to separate the reds and oranges by brightness, as the red color is often less bright than orange. See below for more information.
Version 2.0 is installed the same way as Version 1.0. Please refer to Section 9.2.
The main screen of the app looks as follows:
It looks almost the same as Version 1.0 except there is no training button anymore, and there is a new Camera button.
The Calibration Center looks completely identical to Version 1.0:
The left side of the Configuration Center has several line-detection parameters of the old version replaced with new contour-detection parameters. The right side has some additional color parameters added.
- Area Cutoff - the default value of 0.02 specifies that contours with an area of less than 2% of the overall image area should be discarded.
- Squareness - the default value of 0.95 specifies that a contour with a bounding box dimension ratio of less than 95% should be discarded as not square enough.
- Angle Deviation - the default value of 2.5 specifies that a contour with tilting of more than 2.5 degrees from the prevailing tilting should be discarded.
- Size Deviation - the default value of 0.9 specifies that all contours with a size of less than 90% or greater than 111% of the prevailing contour size
should be discarded as too small or too large.
- Debugging - if this box is checked, the app creates a PDF file containing important debugging and color-training information for every run in the Pictures folder of your device. On Raspberry PI, the folder location is \Data\Users\CurrentAccount\Pictures. On a PC, the folder location is This PC\Pictures.
- Camera Name - you must select your robot's webcam from the drop-down list if your device has more than one camera attached to it.
Laptops almost always have their own built-in cameras so if the app is running on a laptop, this step is required.
- Red/Orange/Yellow/Green/Blue Hue - the perceived hue value (in the range [0, 359]) of the cube's red/orange/yellow/green/blue plate. These values vary from one lighting condition to another.
- White Hue Range - a pair of hue values, each in the range [0, 359], that specifies the hues of the cube's white plates. Even in good lighting conditions, the white plates seldom come off as pure white, they usually have a bluish or reddish color tint.
- White Saturation Threshold - the value in the range [0, 1] which separates the white plates from non-white ones based on saturation. If a color falls within the specified White Hue Range and its saturation is below the specified threshold, the color is ruled to be white.
- Red/Orange Overlap - specifies a hue range where the red and orange plates may overlap. When a color falls within this range, the red/orange separation is performed based on brightness instead of hue.
- Red/Orange Brightness Threshold - specifies the brightness threshold (in the range [0, 1]) to be used to separate red and orange colors. If a color falls within the Red/Orange Overlap range, and its brightness is below the threshold value, the color is ruled to be red, otherwise orange. If the threshold value is 0, the red/orange brightness-based separation is not performed.
The values for the first 4 parameters have been chosen via trial and error and are generally considered to be optimal. Changing them is not recommended.
1.5 Hue/Saturation/Brightness (HSB) Color Space
The following section briefly describes the HSB color encoding scheme used by the app for color determination.
A pixel color is usually represented by three values: its red, green and blue (RGB) components. Alternatively, it can be represented by its hue, saturation and brightness (HSB) values.
Under the HSB scheme, the colors are arranged into a circle, often referred to as a color wheel, and each color is assigned an angular value on that circle in the range [0, 359], called a hue. The red color is assigned the hue value of 0°, yellow 60°, etc. The white color has no place on the color wheel, and therefore has no meaningful hue value of its own.
Saturation measures how gray-free the color is. Pure colors such as red, orange, yellow, green and blue have no grayness in them, and therefore their saturation values are 1. Gray colors, on the hand, contain nothing but grayness, so their saturation value is 0, and that includes the white color too.
Brightness, obviously, measures how bright a color is. Like saturation, brightness is a number between 0 and 1.
The colors on the photographs taken by the robot's camera are rarely ideal. The white plates usually do not come off as pure white, and their saturation is greater than 0, but still significantly lower than that of red, blue and other non-white color plates. This observation enables us to use saturation for white vs. non-white color separation.
Color hues can be used quite reliably to separate the non-white colors among each other, except possibly the red and orange colors. The red and orange plates of the classic Rubik's Cube are very close to each other on the color wheel, and in certain lighting conditions can become virtually indistinguishable from each other. That is where brightness may come in handy: the red plates usually have lower brightness than the orange ones.
1.6 Color Detection Algorithm
Once the camera photographs a cube face, the two photos are analyzed and color plate zones are identified on each photo. A median RGB color for each zone is obtained. The RGB values are then converted to the Hue/Saturation/Brightness (HSB) color space.
The following simple algorithm is then used to convert the HSB values to a color name:
- If both the hue and saturation are 0, we are dealing with a pure white color, and WHITE is returned right off the bat.
- If the hue is within the White Saturation Range and saturation is below the White Saturation Threshold, WHITE is returned.
- If the Red/Orange Range and Threshold are all zero, or if the hue falls outside the specified Red/Orange Range, go to the next step. If the brightness is below the Red/Orange Brightness Threshold, return RED, otherwise return ORANGE.
- The hue is compared with the Red, Orange, Yellow, Green and Blue Hue values, and the color with the shortest angular distance is returned.
1.7 Debug PDF Files
The most common problem faced by the implementers of the Rubik's Cube Solving Robot is the app's failure to correctly identify the colors of the cube from the photographs taken by the robot's camera. To help troubleshoot this problem, the app can be executed in a debug mode and thus provide a detailed insight into its thought process.
When the Debugging checkbox is checked in the Configuration Center, the app creates a PDF file in the /Pictures folder for every run, successful or unsuccessful. This PDF file is essentially a log where every major step of the color recognition algorithm taken by the app is documented and illustrated.
Here is what a typical page from the PDF file looks like:
The top of the page displays the two photographs taken per cube's face. The recognized color plate zones are marked with gray outlines. The center zone is marked with a dashed line.
Below the photographs is the color chart displaying the median colors obtained from their respective color plate zones. Each color square shows its HSB values for easy reference:
Below the color chart is the final result: the 9 recognized colors of a cube face. To the right of that, there are some log entries intended mostly for Otvinta's support personnel.
The last page of the PDF file contains the word "Success" and an encoded cube position, or an error code. Below that, there is a table with all the configuration parameters listed. And at the bottom, there is a box with the color training information. Color training is described in the following section.
1.8 Color Training
The app is capable of computing the approximate color configuration parameters if the cube is inserted in the robot fully assembled and positioned in a certain way -- with the white face towards the camera and red face pointing upwards.
The old version had a separate "training" button for this operation. The new version performs color training computation for every run regardless of whether the cube was properly prepared for training or not, and places the results at the bottom of the last page of the PDF document. The old Training button has been deprecated.
The values from the Suggested Color Parameters box need to be manually transferred to the Configuration Center.
Occasionally, you may see the phrase "could not be determined" for the White Saturation or Red/Orange Brightness thresholds. This usually means the lighting conditions are too dark.