381 lines
14 KiB
Plaintext
381 lines
14 KiB
Plaintext
Metapixel 1.0.2
|
|
===============
|
|
|
|
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.
|
|
|
|
|
|
Installation
|
|
------------
|
|
|
|
To compile Metapixel, you need, in addition to a C compiler, libpng,
|
|
libjpeg, and giflib. To run the script for preparing constituent
|
|
images, you will additionally need Perl. Most Linux distributions
|
|
contain these software packages. On MacOS X, you can get them with
|
|
Fink (http://fink.sourceforge.net/).
|
|
|
|
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, PNG, and GIF).
|
|
|
|
|
|
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 or JPEG formats, depending
|
|
on the extension of the output file name. 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 `metapixel-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:
|
|
|
|
metapixel-sizesort --ratio=2 /my/images /my/sorted/images
|
|
|
|
The option `2' to ratio tells metapixel-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 GPL.
|
|
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
|