As long as you’ve got all the parts out for testing, it's time to install and try some software designed for specifically the cube. It will look all strange and discontiguous when laid out flat, but that’s okay, at least you know it runs.
Later, once the cube is assembled, you can return to this page, skipping the install steps and just running the code.
There’s one extra program that’s a little more advanced… install that one later.
Enter these commands to fetch and build the cube demos:
cd sudo apt-get install -y libjpeg-dev git git clone --depth 1 https://github.com/adafruit/Adafruit_Learning_System_Guides.git cd Adafruit_Learning_System_Guides/Pi_Matrix_Cube make
There are three programs here, the main ones implemented in both C++ and Python. Feature-wise they’re identical, though the C++ versions animate more smoothly, such is the nature of these things. Python is generally quick to develop and test…so if writing your own projects, those versions might be best to examine as a starting point. The first of these programs, a simple static image viewer, is Python only…
Image Viewer
This is a simple program that just displays an image across all the matrices. Sometimes that’s all you need. It can also be helpful when verifying an assembled cube is “spatially coherent” — the code and physical build are in agreement over the placement and orientation of each face. This accepts one argument, an image filename (most common formats are supported):
sudo python imageviewer.py images/minecraft.png
Press Control+C to stop.
The 3D-printed frames we designed make wrong assembly very difficult…the correct positions and orientations should all be fairly obvious. If assembling your own cube though, sometimes mistakes are made. There’s two ways to address this…
- Try to compensate for the error by modifying the code…there are tables early in each program that describe each faces’ relative position. Must warn though, this is not as simple as it seems and very likely doomed to failure. There are 122,880 different ways to orient the six faces, and only one is correct. Unfortunately we can not walk you through this process, it’s just too difficult to troubleshoot.
- Partly or fully dismantle your cube and re-assemble in correct layout. As long as you follow our “line up A to A, B to B” plan exactly, it should all come together right.
At its simplest, just type:
sudo ./globe
Or, for the Python version:
sudo python globe.py
Either of these should show a moving image of the Earth…albeit oddly fractured when the cube is unassembled and laid flat. With the cube assembled, it’s a spinning “globe” with the north and south poles centered on the top and bottom faces, respectively.
Both versions of the code can accept the exact same arguments…so the following options apply to both.
To change the map image, use the -i flag and specify a JPEG image filename:
sudo ./globe -i maps/jupiter.jpg
Or, for the Python version:
sudo python globe.py -i maps/jupiter.jpg
The maps subdirectory includes a few sample images to try out.
If substituting your own, images must be JPEG format. They can be any size or aspect ratio (the code will scale or stretch as needed). Most of the examples are 1024x512 pixels, which is more than adequate for the resolution of this cube. Others, like boing.jpg, are intentionally very small, to appear as a pixelated checkerboard rather than a continuous texture.
The space images are from NASA and in the public domain.
The -v option (no parameters, just -v) changes the projection so the north and south poles are at two opposing corners of the cube, rather than centered on faces. Remember our warning from the opening page: never spin the cube with fingers on the corners…you will shear off the corner pixels.
-s [time in seconds] sets the spin time in seconds per revolution, e.g. -s 4.5 will revolve once every 4.5 seconds. Positive values will revolve in the correct direction for the Earth map. Negative values (e.g. -s -4.5) in the opposite direction, maybe useful for text, logos or Uranus.
-a [samples] sets the per-pixel, per-axis number of samples in the texture-mapping operation. Higher numbers yield a smoother image, but lower refresh rate. Default for the C++ code is 2 (i.e. 2x2 supersampling per pixel), default for Python version is 1 (no supersampling, because Python isn’t as quick).
-t [seconds] limits the program run time, after which it exits. Default is to run indefinitely (stopped with Control+C). Combined with a simple shell script, the time limit allows a simple slide show of different textures. You can try this with:
sudo sh ./cycle.sh
-f [seconds] sets a fade in and fade out time, where the image will transition from and to black at the start and finish. The cycle.sh script uses this together with the -t argument to make the image changes look smooth and intentional (otherwise there would be a quick flash to black while loading the next image).
-b [percent, 0 to 100] sets the peak brightness of the LEDs, if you want less than the maximum. They can be too much in some settings, or you might want to economize on power. Default is 100, full brightness.
The custom 3D-printed frames make for very narrow bezels…the gaps between matrices…about twice the thickness of the PCBs. But perhaps you’ve built up a cube “manually,” with the original frames still intact, resulting in more prominent bezels. Two arguments, -e [size] and -E [size] (yes, same letter, but lower and upper case), tune the mapping algorithm to compensate for these, so you don’t see a sudden jump as textures move between matrices. -e is the edge-to-edge dimension of one matrix…for example, on the Adafruit 2mm pitch 64x64 matrices, that’s about 128 millimeters. -E is the edge-to-edge measure of opposite faces of the cube…that might be just a slightly larger 134 mm with our custom frames, or 158 if the original frames are used. These can be any units…millimeters, inches, all good…it’s the ratio between them that actually matters. Honestly though, this is all quite esoteric and nobody will notice if you just leave them at their 1:1 ratio defaults.
Conway’s Game of Life
John Conway’s Game of Life is a classic cellular automaton that produces interesting patterns from a set of simple rules. We’ve devised a special version that correctly wraps around all edges of the cube!
sudo ./life
Or, for the Python version:
sudo python life.py
Although a little bit slower, the Python version does seem more enjoyable to watch. For both programs, press Control+C to stop.
As with the globe program, there are some configurables that work the same with either language:
-k [index] selects a predefined color palette to use. The default, 0, is simply white or black, as in most classic Life implementations. But there’s also:
-k 1 A grayscale palette. Pixels slowly fade out as they “age” and “die.”
-k 2 A common “heat map” look, fading from white to yellow to red to black.
-k 3 Cycles through a spectrum of colors.
-t [seconds], -f [seconds] and -b [percent] work exactly the same as the globe program described above. These set the program run time, fade in/out time, and peak brightness level, respectively.
There’s one more program, if you built your cube with the optional accelerometer. This requires some extra setup and installation, so it gets described separately on the next page. Best to do this with the cube still in pieces. Otherwise, if you don’t have the accelerometer, you can proceed with cube assembly.
Text editor powered by tinymce.
