If designing new images for the imageviewer.py script, take a look at the file images/minecraft.png for insights on how to orient things so that edges correctly wrap around.

This image is 384 pixels wide (64x6) and 64 pixels tall:

Or here’s John Park’s head, similarly formatted:

If you’re wondering why each face is twisted in this peculiar order, it’s because of the way we must fold an otherwise straight chain of matrices…

…into a cube shape:

These orientations are not as random as they seem! We carefully iterated on this design for the 3D-printed frames to accommodate parts clearances on the 2mm pitch matrix PCBs (fitting around certain capacitors, etc.), and for fairly consistent cable distances throughout (e.g. no connections between opposite faces—the standard ribbon cable couldn’t reach if making a DIY 3mm pitch cube).

The globe program, meanwhile, uses simple UV texture maps for input…a common way of “unwrapping” a sphere into a plane, such as:

You can find lots of other examples online just by including “UV texture” in Google image search terms.

For designing new programs: if at all humanly possible, use one of the included examples as a starting point. Creating the impression of spatial coherence…where something moving off one edge appears on the correct edge of an adjacent matrix…is one of the most unpleasant things we’ve ever encountered. It’s why we designed the matrix frames to specifically assemble only one correct way, so most users never need to face this.

“What’s in the box?”

“Pain.”

To the matrix-driving library on the Raspberry Pi, everything is just one long 384x64 pixel image, and “up” is always up. But to the code…as you can see in the images at the top of this page…every face is twisted a different way. No edge crossing leads where you would intuitively expect it. As explained above, physical constraints in the cabling and matrices themselves dictated this arrangement, and code then has to fix up the resulting mayhem.

There is no one-size-fits-all solution to this problem. You can see each of the programs takes a slightly different approach as best suits the task. There’s usually one or more tables near the top of the code trying to express the topology in that program’s context.