graphics/metapixel: Added to 13.0 repository

1 files changed, 380 insertions, 0 deletions

diff --git a/graphics/metapixel/README.SLACKWARE b/graphics/metapixel/README.SLACKWARE
new file mode 100644
index 0000000000..0a51f1f9b3
--- /dev/null
+++ b/graphics/metapixel/README.SLACKWARE
@@ -0,0 +1,380 @@
+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