How-To: Generate dice mosaics from image files

Computers & Mobile Craft & Design
Le Violon d'Ingres in Dice.png

Michael Boehm saw our post a couple of weeks ago about Etsy seller Stukenborg’s letterpress prints using dice as “type,” which mentioned the idea of using the same technique for making pixel-based images as well as geometric patterns. He got interested in the idea, went off to experiment, and eventually produced the dice-mosaic version of Man Ray’s Le Violon d’Ingres shown above. When he posted the results in the comment thread, I asked for, and he was nice enough to provide, a written explanation of the method, which uses Mark Probst’s open-source photomosaic utility Metapixel. I’ve reproduced Michael’s e-mail, with only minor edits, below. [Thanks, Michael!]

I run Ubuntu so it was easy enough to install Metapixel with an apt-get command (sudo apt-get install metapixel). Once installed you need to gather the images you will be using for tiles into a single directory. In this case, I created a separate image for each die face, one black set and one white set (you can find them in a comment on the first Flickr image). I chose to create my own faces because standard size dots on dice are a little too small to get a good set of tones to work with. If you want to include rotated faces, you simply have to include images of the 2, 3, and 6 faces rotated 90 degrees as the others are symmetrical. After you’ve done this, you need to generate a tile library from these images using the following command:

metapixel-prepare –width=15 –height=15 –recurse

In this case, I chose 15x15px tiles and included the self-explanatory and optional recurse flag. Metapixel will then resample your images, create a library file and store these in the output directory. Now that you have indexed your images you are just about ready to generate your mosaic. One nice thing about Metapixel is that it allows you to create different tile sets for making your mosaics and store them in separate folders. If you were so inclined, you could create separate libraries containing only black dice, only white dice, dice with rotated faces, etc.

Now, find an image you wish to use and convert it to grayscale in your graphics application of choice (in my case, GIMP, Krita, or RawTherapee). The image does not need to be high resolution since the effective resolution of the mosaic is so low it will obliterate all but the simplest forms in the image. Since there will only be 12 tones in the mosaic, a curves/levels adjustment of the image can help you get more detail out of the mosaic by manipulating the tones to emphasize different areas (make a couple versions and just see what metapixel comes up with). Also, If your graphics app has an “increase local contrast” filter/effect/adjustment it can help a lot (i imagine HDR photos might work really well with this technique because of their tone-mapping). I scaled and cropped my image so its pixel dimensions were integer multiples of 15 to ease the process, but i do not think this is a necessary step.

Save your image. Now that you have your grayscale image, you are ready to go. The command to generate a mosaic is:

metapixel –library= –width=15 –height=15 –distance=0 –metric=wavelet –metapixel

The library flag should be set to the directory containing the output of the metapixel-prepare command. Width and height correspond to tile size and the distance flag should be 0. Distance is a flag that determines how distantly spaced identical tiles should fall; a setting of 0 means tile A may be directly next to another tile A, while a setting of 1 means tile A must be separated from another tile A by at least 1 non-A tile, and so forth. I was unable to get decent looking mosaics with anything other than 0 because it tends to create what are essentially visual artifacts in the output. The other major flag is the metric flag. This flag allows you to chose between two different algorithms for assembling the mosaic. The two choices are “subpixel” and “wavelet.” In general I found the images generated with the wavelet metric to be much better, but I’ll leave that choice up to you. Finally, there are arguments for input image (the grayscale version you’ve got ready to go) and the output (I believe you have a choice of jpeg or png). There are a few other arguments you can supply, just check the man page (man metapixel).

So now you know how to generate a monochrome die mosaic. I took it a step further and attempted to replicate a color-halftone-like effect as seen in the third of the Flickr images.

To do this, you will need to choose a color image and break it up into four separate mosaics. The first three correspond to your image’s RGB color channels (cyan, magenta, and yellow respectively in the mosaic) and the fourth is basically a grayscale value channel to serve as the K (black) channel. It’s obviously a bit more complicated to do and requires a little knowledge of color theory and some familiarity with a graphics application. If you’d like I can share my process with you for this as well.

That, right there, is the kind of reader feedback and involvement every blogger dreams about. Thanks again, Michael. If you’re interested in additional detail in the color process Michael mentioned, be sure to leave us a comment, below, and if he’s still amenable, maybe we can persuade him to go on.

2 thoughts on “How-To: Generate dice mosaics from image files

  1. derekgaw says:

    You can also make a dice mosaic in your browser much more easily at

Comments are closed.

Discuss this article with the rest of the community on our Discord server!

I am descended from 5,000 generations of tool-using primates. Also, I went to college and stuff. I am a long-time contributor to MAKE magazine and My work has also appeared in ReadyMade, c't – Magazin für Computertechnik, and The Wall Street Journal.

View more articles by Sean Michael Ragan


Maker Faire Bay Area 2023 - Mare Island, CA

Escape to an island of imagination + innovation as Maker Faire Bay Area returns for its 15th iteration!

Buy Tickets today! SAVE 15% and lock-in your preferred date(s).