Introduction

Commuter is a command line tool that creates mosaics from images, where every tile of the image is itself a smaller picture. Commuter is released under the BSD licence, share and enjoy.

This version of Commuter is now a development dead-end, any future developments will be on Commuter 2. Since C2 only works on UNIX-like platforms I'm leaving this page up for Windows users.

Installing

First of all you need ImageMagick so install that first. Windows users, please note Commuter presumes you installed to C:\Program Files\ImageMagick, by default ImageMagick will install to that path but with the version number at the end. It'll make your life much easier if you install to the path above.

Windows users can download a binary ready-to-run copy. Move this binary to somewhere appropriate on your computer (it doesn't really matter where, the examples below presume c:\bin.). You can now skip the rest of this section and go on to How to use.

Still here? I'm afraid you have to compile it yourself and I'm going to presume you know that that means. Download commuter1.tar.gz and unpack. You need to copy a file from the config sub-directory into the current directory, at the same time renaming that file to config.h. Of the files in the config directory, you should copy the one that best describes your system.:

File Notes
openbsd.h Will probably work on NetBSD and FreeBSD although I haven't tested this.
solaris.h Test compiled on Solaris 8. It seems OK but I haven't actually used it to generate any pictures since the machine in question doesn't have ImageMagick.
win32.h In case any Windows users feel like compiling it themselves.

No, that isn't a particularly exhaustive list of systems. If you can contribute a config file for other operating systems, please contact me.

OK, now type make and it should compile. If not, just compile commuter.c manually, it's hardly a complex build process.

How to use

Libraries

A library is a collection of pictures which Commuter uses for the tiles. A library needs to be created before any mosaics can be made.

First of all, create a directory to store the pictures. Note in the following examples the the top line is for Windows, and the bottom line is for UNIX:
mkdir c:\library
mkdir ~/library

Now tell Commuter to add files to this directory. For this you specify with -l the library directory and one (or more) image directories with -a. We also specify the width and height of the tiles with -x and -y. Note that the file scan is recursive so adding photos adds all directories under photos as well.:
c:\bin\commuter -a c:\photos -a c:\pr0n -l c:\library -x 50 -y 50
commuter -a ~/photos -a ~/pr0n -l ~/library -x 50 -y 50

Once a library is created you can add files to it by using the same command. When adding to an existing library omit the -x and -y arguments since all tiles in a library must be the same size.

To delete a library use the -c switch as below. Note this deletes everything in the library directory which is why you shouldn't use an existing directory to store a Commuter library.:
c:\bin\commuter -c -l c:\library
commuter -c -l ~/library

Creating a mosaic

The basic form of mosaic creation is to specify the input picture (-i) the output picture (-o) and the library:
c:\bin\commuter -i c:\input\me.jpg -o c:\output\mosaic.bmp -l c:\library
commuter -i ~/input/me.jpg -o ~/output/mosaic.bmp -l ~/library

The input and output formats can be anything that ImageMagick supports although I recommend BMP as the output format. The reason for this is that Commuter outputs a raw RGB picture which is then converted by ImageMagick to the format you request. The mosaics are often somewhat large and ImageMagick can often run out of memory doing the conversion. I've found that ImageMagick is less likely to run out of memory converting to BMP than other formats (You can of course convert to other formats from BMP when you're done.).

Oh, speaking of memory use, taking a sensible input image size of 60x60 pixels and a tile size of 50x50, Commuter will need 27MB of RAM to run (plus the same again free in your temporary directory on your hard disc). With a 100x100 input picture that figure increases to 75MB.

The rest of the switches are optional and affect how the mosaic is created. You should at least have a look at notes on the -S switch before you try any mosaic creating.

Switch Notes
-d

Controls the duplication of tiles. Without this switch Commuter will always pick the most appropriate tile regardless of how many times that tile has been used.

With -d 0 Commuter will not reuse a tile until all of the tiles in the library have been used.

With any non-zero number this switch makes Commuter avoid duplicates as long as there is an alternative with a suitability score less then the number you specify (Note that lower numbers mean better matches.). For example 5000 is a comparatively low number, so with -d 5000 there will be no duplicates whilst there are alternatives that are good matches. With -d 10000 there will be no duplicates while there are still mediocre matches.

It is recommended that you experiment with this value to get the best looking results from your library.
-e

With this option set Commuter will cache tiles in memory to avoid having to repeatedly load from disc. Speeds up mosaic creation but uses more memory.

Using this switch does not make it more likely that ImageMagick will be unable to convert the final image.
-h

Displays the help file.
-n

Normally, once Commuter has chosen which tile to use, it tints it to be closer to the colour of the represented pixel. With this switch the picture is not tinted.

Using this switch with -d 0 produces horrible results unless you have a very large library.
-p

The full path to the ImageMagick convert program. Only needed if the program is not in the default location (use the -h switch to find the default location.).
-t

The temporary directory to use. Only needed if the default temporary directory is unsuitable (use the -h switch to find the default temporary directory.).
-s
-S

Commuter actually produces images in a very simple image format called RGB, it then uses ImageMagick to convert from RGB to the format you asked for.

RGB comes in two flavours 8-bit and 16-bit, and ImageMagick may expect either. Commuter tries to guess what kind to send to ImageMagick by looking the at RGB files ImageMagick creates. Sometimes though ImageMagick produces one kind and expects another, and this can lead to mosaic creation failing at the "converting to final format" stage or corrupted final pictures.

These switches force the RGB format to either be 8-bit (-s) or 16-bit (-S).

On my UNIX machine (ImageMagick 5.2.9) I can usually let it auto-detect, whilst on my Windows machine (ImageMagick 5.4.8) I always need -S.

A complete example, just to round off this section. This command creates a BMP mosaic named mosaic.bmp from an image named me.jpg using the library photos. We avoid duplicates as long as there's a decent alternative, cache library pictures because memory is so cheap these days and force the output to be 16-bit:
c:\bin\commuter -i c:\input\me.jpg -o c:\output\mosaic.bmp -l c:\photos -e -S -d 8000
commuter -i ~/input/me.jpg -o ~/output/mosaic.bmp -l ~/photos -e -S -d 8000