Introduction

Commuter is a command line tool that creates photo mosaics from an image, i.e. a mosaic where every tile of the image is itself a smaller picture.

For example, I took a picture of myself (from a quite a while ago now) and resized it to 90x72. I then created a mosaic using my photo collection as the library (tile size of 50x50 pixels), resulting in picture of 4500x3600 pixels. The shrunk down version shows what the picture looks like 'from a distance', and the close-up shows some tiles.

Installing

Pre-requisites

You will need:

Building Commuter

Grab Commuter 2.2 and then:

gunzip commuter-2_2.tar.gz
tar xf commuter-2_2.tar
cd commuter-2_2
make
make install

Existing user? Don't forget to read the Changelog.

You may need to be root for the last stage since by default Commuter will install into /usr/local/bin/. You can change the installation path by editing Makefile. If you get build errors, check the list of known problems and fixes in the INSTALL file. If none of that helps feel free to let me know. If you get different build errors and fix them, definitely let me know.

How to use

Albums

An album is a collection of images which Commuter uses as tiles. An album needs to be created before any mosaics can be made.

Albums are managed by the comalb tool. The general format is comalb switches command paths

In reverse order; paths are one or more paths to add to the album. A path can either be a directory to process recursively or an individual file. comalb will import any image format understood by ImageMagick (with the exception of .txt files, because that's just silly).

The command is either add or create. Simply, add will add the paths to an existing album, create will create a new album, overwriting any old one.

The available switches are:

Name Description
-a filename The filename of the album to process, defaults to default.calb
-n name A descriptive name for the album, e.g. "Holiday photos", required for create.
-x width The width of the tiles to create, required for create.
-y height The height of the tiles to create, required for create.

So a typical album creation may be:

comalb -n "Photos" -x 40 -y 40 create ~/photos

Creating a mosaic

Mosaics are created with: commuter switches input_image

The input image can be in any format understood by ImageMagick. The switches are as follows:

Name Description
-a filename The filename of the album to use, defaults to default.calb
-d If set, Commuter will not use a tile twice within an image. Otherwise, Commuter will always pick the closest matching tile regardless of how many times it has been used.
-j 0-100 Sets the JPEG quality level of the output.
-n yes/no Sets whether Commuter will tint the tile it chooses to the average colour of a perfectly matching tile.
-o filename The filename to output to, defaults to output.jpg. Note the output format is always JPEG regardless of the filename specified.
-p duplicates/tolerance In the case where a tile cannot be chosen due to the current choices for duplicate restriction and matching tolerance, which of these factors should be preserved for a second matching attempt. So, if "duplicates" is chosen the tolerance requirement will be ignored if necessary to find a matching tile. Default is "duplicates".
-r centre/straight Sets the order in which tiles are allocated to the final image. "centre" allocates tiles in the centre of the image first, "straight" allocates top-to-bottom, left-to-right.
-t value Sets a 'matching tolerance' for tiles. A tile can be only be used if its average colour is within this value of a hypothetical perfect tile. Experiment for your albums, but sensible values are expected to be in the thousands.
-z Puts Commuter into pedantry mode. If a tile cannot be matched due to duplication and tolerance restrictions, fail rather than break the restrictions.

A complete example:

commuter -a holiday.calb -t 5000 -d -p tolerance -o out.jpg bob.jpg