diff options
Diffstat (limited to 'graphics/metapixel/README.SLACKWARE')
| -rw-r--r-- | graphics/metapixel/README.SLACKWARE | 380 |
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 |