README

Metapixel 0.11
==============

Metapixel is a program for generating photomosaics.  It can generate
classical photomosaics, in which the source image is viewed as a
matrix of equally sized rectangles for each of which a matching image
is substitued, as well as collage-style photomosaics, in which
rectangular parts of the source image at arbitrary positions (i.e. not
aligned to a matrix) are substituted by matching images.

Metapixel is, as of version 0.11, in a feature-freeze for release 1.0.
This means that no more features will be implemented in Metapixel
until we have a stable 1.0 release.  So, if you find any bugs in
Metapixel, please do report them (to schani@complang.tuwien.ac.at).


Installation
------------

To compile Metapixel, you need libpng and libjpeg.  To run the script
for preparing constituent images, you will additionally need Perl.
Most Linux distributions contain these software packages.

Edit the first line of Makefile if you want to install Metapixel
somewhere else than /usr/local.  Then, type

  make

If everything compiled fine, become root and type

  make install


Configuring Metapixel
---------------------

You can optionally create a file ".metapixelrc" in your home directory
to store some settings which makes it easier to use Metapixel, since
you won't have to use that many switches on the command line.

A sample configuration file is included in the Metapixel distribution
under the name "metapixelrc".  See the section "The Configuration
File" below for details.  It is advisable to at least set the options
"prepare-directory" and "library-directory".


Preparing images
----------------

Before (non-anti-mosaic) mosaics can be created, the constituent
images need to be preprocessed.  Preparing an image does two things.
Firstly, it computes various coefficients by which the image can be
matched against a part of a source image.  Secondly, the image is
scaled to a smaller size.  Usually this will be the size you intend to
use for it in the target image, but it can be any arbitrary size.  It
makes sense to scale your images to the maximum size that you will use
for constituent images.  That way, no information gets lost.  The
default size is 128x128 pixels.  The matching data and the scaled
images are stored in a directory which is then called a "library".
You can use more than one library in the creation of a mosaic.

To simplify the task of creating a library, the Perl script
'metapixel-prepare' is included in the distribution.  It must be
called with the name of the directory where your original images are
stored in.  As a second argument you must give the directory of the
library to which the images are to be added.  If you have set a
default directory for preparing images in your configuration file,
the second argument is optional.

If the script is called with the option "--recurse", it searches the
directory with the original images recursively, i.e., it searches all
its direct and indirect subdirectories as well.  It also accepts
parameters specifying the size of the scaled down images.  Just call
it - it prints out usage information.

If the script constantly complains that an error occurred when running
'metapixel', that probably means that metapixel is not in your path.
The other possibility is that all your images are in a format that
Metapixel doesn't like (it only supports JPEG and PNG).


Creating photomosaics
---------------------

Input images for mosaics can have arbitrary sizes.  Should you want
the created mosaic to be of a different size than the input image, use
the --scale option.  It scales the input image uniformly in both
directions (i.e. obeying the aspect ratio).  If the width or height of
the input image after scaling are not multiples of the width and
height of the constituent images, the input image is further scaled up
to the smallest size (larger than the input image) that obeys this
constraint, possibly changing the aspect ratio a bit.  This does not
apply to collages, however.  The sizes of their source images after
scaling are always left untouched.

Metapixel produces output images in the PNG format.  In order to
create a classic photomosaic for the image input.jpg and write the
output to output.png with constituent images stored in the directory
"images", use the following command line:

  metapixel --library images --metapixel input.jpg output.png

To create a collage use

  metapixel --library images --collage --metapixel input.jpg output.png

Using the -y, -i and -q options you can change the weights for each of
the color channels.  For example, to match only luminance, completely
disregarding chrominance, use

  metapixel --library images -i0 -q0 --metapixel input.jpg output.png

The default weight for each of the channels is 1.

Using the --cheat option you can specify the percentage by which the
resulting photomosaic should be overlayed by the original image.  The
default is 0, i.e., the photomosaic is not overlayed at all.  A
percentage of 100 yields, not surprisingly, the original image.  A
percentage of 30 makes the photomosaic appear noticably better but is
yet small enough to go unnoticed without close inspection in most
circumstances.

As of version 0.6, Metapixel implements two different matching
algorithms.  The new metric, which is a trivial distance function,
seems to give better results while not being slower than the old
wavelet metric.  The metric can be chosen using the --metric option.
The default is the new subpixel metric.

You can use the --library option more than once to let Metapixel use
more than one library for a mosaic.


Classic Mosaics
---------------

Metapixel allows you to choose between two algorithms for finding
matching images, via the --search option.  The old algorithm called
"local" simply selects the best matching image for each location,
possibly disregarding images selected in locations nearby (see below).

The new algorithm called "global" repeats the following step until all
locations have been assigned to: Find the best match for any location
among all small images that have not already been used.  This
guarantees that no small image is used twice.  Obviously, it also
means that you must have at least as many small images as there are
locations in the image.

Note that "global" is much slower and uses more memory than "local".

The "--distance" option lets you specify the minimal distance between
two occurences of the same constituent image in the target image for
the "local" algorithm.  Distance 0 means that it is allowed for the
same image to occur in adjacent positions in the matrix.  The default
distance is 5, which means that there must be at least 5 images
"between" two occurences of the same image in the matrix.  Note that
Metapixel is forced to select non-optimal matches for distances
greater 0.


Antimosaics
-----------

Antimosaics are classic mosaics for which the small images are the
parts of a single image, possibly the input image itself, and can be
created using the --antimosaic option.  Metapixel subdivides the
antimosaic file as if it were doing a mosaic of that file, but then
uses the resulting subimages as the small images for a classic mosaic.

In case the antimosaic image and the input image are the same,
Metapixel will simply reconstruct the input image from the subimages,
because they will always match best in their original locations.  To
tell Metapixel to do otherwise, you can use the
--forbid-reconstruction option, which allows you to specify a minimum
distance between the original location of a subimage and the location
it has in the resulting mosaic.

Here's how you create an antimosaic with a minimum reconstruction
distance of 2:

  metapixel --library images -x input.jpg -f 2 --metapixel input.jpg output.png


The Configuration File
----------------------

The first thing Metapixel does is try to read the file ".metapixelrc"
in your home directory.  From this file, it reads default values for
its settings, so that you don't have to give them on the command line
each time you use Metapixel.

In this configuration file, you can use the following directives:

  (prepare-directory <directory>)

    The library directory which metapixel-prepare should use by
    default.  metapixel-prepare does not automatically create the
    directory if it doesn't exist, so make sure it does.

  (prepare-dimensions <width> <height>)

    The size metapixel-prepare should use for the small images.

  (library-directory <directory>)

    A library directory which Metapixel should use when creating
    mosaics.  You can use this directive more than once.

  (small-image-dimensions <width> <height>)

    The dimensions of the small images Metapixel should use in
    mosaics.

  (yiq-weights <y> <i> <q>)

    The weights for the channels to be used in matching images.

  (metric <metric>)

    The metric Metapixel should use for matching images.  This can
    either be "subpixel" or "wavelet".

  (search-method <method>)

    The search method for creating classic mosaics.  This can either
    be "local" or "global".

  (minimum-classic-distance <dist>)

    The minimum distance between two occurences of the same image in
    classic mosaics with the local search method.

  (minimum-collage-distance <dist>)

    The minimum distance (in pixels) between two occurences of the
    same image in collage mosaics.

  (cheat-amount <perc>)

    The cheat amount in percent.

  (forbid-reconstruction-distance <dist>)

    The minimum distance between the position of subimage in the
    original image and its position in the output image in an
    antimosaic.

Take a look at the file "metapixelrc" in the distribution.  It gives
examples for each of the directives discussed here.


Collages
--------

To create a collage, you have to use the "--collage" option in
addition to "--metapixel".

You can also specify a minimum distance between two occurences of the
same image, which is measured in pixels.  The default value is 256.
Use the "--distance" option to change it.  Note that the distance is
measured between the centers of the images, not their edges, i.e., a
minimum distance of 10 means that the centers of two occurences of the
same image must be at least 10 pixels apart.  This will usually mean
that they are allowed to overlap, unless you use very tiny small
images.

Note that Metapixel uses ridiculous amounts of memory for collage
mosaics.  To create a collage photomosaics of size 2048x2048 your
machine should at least have 64MBytes RAM.


Protocols
---------

Metapixel can, in addition to producing a classical mosaic, write a
file specifying which small images it put in each of the locations.
This protocol file can then be used to reproduce the mosaic without
doing the matching again, for example to experiment with different
cheat amounts.  The protocol also contains information on how good
each small image matches the original location, so you can find out
where the matches are good and where they aren't.  You can also modify
the protocol and let metapixel generate a mosaic which it wouldn't
have matched itself, for whatever reason you might want to do this.

Use the --out option to create a protocol and the --in option to
reproduce a mosaic from a protocol.  The protocol file is a LISP list
with the following syntax:

  (mosaic (size <WIDTH> <HEIGHT>) (metapixels . <PIXELS>))

<WIDTH> and <HEIGHT> are the number of small images in the mosaic
across the width and height of the mosaic, respectively.  <PIXELS> is
a list containing lists with the following syntax:

  (<X> <Y> <W> <H> <FILENAME>)

<X> and <Y> are the position of the small image.  The upper left small
image has coordinates (0,0), the lower right (<WIDTH>-1,<HEIGHT>-1).
<W> and <H> must both be 1 in this version of Metapixel.  <FILENAME> is
the name of the small image file.

A typical line in the protocol file looks like this:

  (30 23 1 1 "semiharmless.new/wallpaper07.jpg.png") ; 4792.000000

The number at the end of the line is the matching score.  The lower
the score, the better the match.  Note that the semicolon ';'
introduces a comment which lasts ends with the end of the line, so the
matching score is not part of the protocol syntax.


The matching algorithms
-----------------------

The algorithm that does the image matching via wavelets is described
in the paper 'Fast Multiresolution Image Querying' by Charles
E. Jacobs, Adam Finkelstein and David H. Salesin.

The new subpixel metric is very trivial.  I suggest you consult the
source if you are interested in it.  The matching function is
subpixel_compare().


Sorting Images by Size or Aspect Ratio
--------------------------------------

Metapixel comes with a tool called `sizesort' which sorts images by
size or aspect ratio by moving them to directories containing only
files with similar size or aspect ratio.

An example: Let's say you have thousands of images in /my/images, and
you want them sorted by aspect ratio and placed in /my/sorted/images.
You can do this with this command:

  sizesort --ratio=2 /my/images /my/sorted/images

The option `2' to ratio tells sizesort to put all those images
together whose aspect ratios are the same with an accuracy of two
places behind the comma.  You might now have (among others) a
directory called /my/sorted/images/ratio_0.79 which contains all
images whose ratio between width and height is about 0.79.


Upgrading from versions 0.8/0.9/0.10
------------------------------------

Starting from release 0.11, Metapixel requires that the tables file is
in the same directory as the small images described in that file.  If
your configuration is different, all you need to do is to make sure
that all these files are in the same directory.  You don't need to
remove the paths in the tables file, as Metapixel does that
automatically.


Upgrading from versions 0.6/0.7
-------------------------------

The tables file format has changed in Metapixel 0.8, but you don't
need to run 'metapixel-prepare' again.  There's a program called
'convert' included in the distribution that does the job.  Just tell
it which size your small images are, give it the old tables file on
stdin and it writes the new one on stdout.

For example, if your small images are 128 pixels wide and 96 pixels
high, go to the directory with the tables file (usually the directory
where the small images are) and do

  convert --width=128 --height=96 <tables >tables.mxt


Licence and Availability
------------------------

Metapixel is free software distributed under the terms of the GNU
General Public License.  The file `COPYING' contains the text of the
license.

The source of Metapixel is available at the Metapixel homepage at

  http://www.complang.tuwien.ac.at/schani/metapixel/

---
Mark Probst
schani@complang.tuwien.ac.at