Codebox Software

This utility can be used to generate photo-mosaic images. The utility is open-source and available on GitHub; to use it you must have Python installed, along with the Pillow imaging library.

As well as an image to use for the photo-mosaic (most common image formats are supported), you will need a large collection of different images to be used as tiles. The tile images can be any shape or size (the utility will automatically crop and resize them) but for good results you will need a lot of them - a few hundred at least. One convenient way of generating large numbers of tile images is to extract screenshots from video files using ffmpeg.

Run the utility from the command line, as follows:

python mosaic.py <image> <tiles directory>

• The image argument should contain the path to the image for which you want to build the mosaic
• The tiles directory argument should contain the path to the directory containing the tile images (the directory will be searched recursively, so it doesn't matter if some of the images are contained in sub-directories)

For example:

python mosaic.py game_of_thrones_poster.jpg /home/admin/images/screenshots

The images below show an example of how the mosaic tiles are matched to the details of the original image:

Original

Mosaic Detail (click through for full mosaic ~15MB)

Producing large, highly detailed mosaics can take some time - you should experiment with the various configuration parameters explained in the source code to find the right balance between image quality and render time.

In particular the TILE_MATCH_RES parameter can have a big impact on both these factors - its value determines how closely the program examines each tile when trying to find the best fit for a particular segment of the image. Setting TILE_MATCH_RES to '1' simply finds the average colour of each tile, and picks the one that most closely matches the average colour of the image segment. As the value is increased, the tile is examined in more detail. Setting TILE_MATCH_RES to equal TILE_SIZE will cause the utility to examine each pixel in the tile individually, producing the best possible match (during my testing I didn't find a very noticeable improvement beyond a value of 5, but YMMV).

By default the utility will configure itself to use all available CPUs/CPU-cores on the host system, if you want to leave some processing power spare for other tasks then adjust the WORKER_COUNT parameter accordingly.