1Metapixel 1.0.2 2=============== 3 4Metapixel is a program for generating photomosaics. It can generate 5classical photomosaics, in which the source image is viewed as a 6matrix of equally sized rectangles for each of which a matching image 7is substitued, as well as collage-style photomosaics, in which 8rectangular parts of the source image at arbitrary positions (i.e. not 9aligned to a matrix) are substituted by matching images. 10 11 12Installation 13------------ 14 15To compile Metapixel, you need, in addition to a C compiler, libpng, 16libjpeg, and giflib. To run the script for preparing constituent 17images, you will additionally need Perl. Most Linux distributions 18contain these software packages. On MacOS X, you can get them with 19Fink (http://fink.sourceforge.net/). 20 21Edit the first line of Makefile if you want to install Metapixel 22somewhere else than /usr/local. Then, type 23 24 make 25 26If everything compiled fine, become root and type 27 28 make install 29 30 31Configuring Metapixel 32--------------------- 33 34You can optionally create a file ".metapixelrc" in your home directory 35to store some settings which makes it easier to use Metapixel, since 36you won't have to use that many switches on the command line. 37 38A sample configuration file is included in the Metapixel distribution 39under the name "metapixelrc". See the section "The Configuration 40File" below for details. It is advisable to at least set the options 41"prepare-directory" and "library-directory". 42 43 44Preparing images 45---------------- 46 47Before (non-anti-mosaic) mosaics can be created, the constituent 48images need to be preprocessed. Preparing an image does two things. 49Firstly, it computes various coefficients by which the image can be 50matched against a part of a source image. Secondly, the image is 51scaled to a smaller size. Usually this will be the size you intend to 52use for it in the target image, but it can be any arbitrary size. It 53makes sense to scale your images to the maximum size that you will use 54for constituent images. That way, no information gets lost. The 55default size is 128x128 pixels. The matching data and the scaled 56images are stored in a directory which is then called a "library". 57You can use more than one library in the creation of a mosaic. 58 59To simplify the task of creating a library, the Perl script 60'metapixel-prepare' is included in the distribution. It must be 61called with the name of the directory where your original images are 62stored in. As a second argument you must give the directory of the 63library to which the images are to be added. If you have set a 64default directory for preparing images in your configuration file, 65the second argument is optional. 66 67If the script is called with the option "--recurse", it searches the 68directory with the original images recursively, i.e., it searches all 69its direct and indirect subdirectories as well. It also accepts 70parameters specifying the size of the scaled down images. Just call 71it - it prints out usage information. 72 73If the script constantly complains that an error occurred when running 74'metapixel', that probably means that metapixel is not in your path. 75The other possibility is that all your images are in a format that 76Metapixel doesn't like (it only supports JPEG, PNG, and GIF). 77 78 79Creating photomosaics 80--------------------- 81 82Input images for mosaics can have arbitrary sizes. Should you want 83the created mosaic to be of a different size than the input image, use 84the --scale option. It scales the input image uniformly in both 85directions (i.e. obeying the aspect ratio). If the width or height of 86the input image after scaling are not multiples of the width and 87height of the constituent images, the input image is further scaled up 88to the smallest size (larger than the input image) that obeys this 89constraint, possibly changing the aspect ratio a bit. This does not 90apply to collages, however. The sizes of their source images after 91scaling are always left untouched. 92 93Metapixel produces output images in the PNG or JPEG formats, depending 94on the extension of the output file name. In order to create a 95classic photomosaic for the image input.jpg and write the output to 96output.png with constituent images stored in the directory "images", 97use the following command line: 98 99 metapixel --library images --metapixel input.jpg output.png 100 101To create a collage use 102 103 metapixel --library images --collage --metapixel input.jpg output.png 104 105Using the -y, -i and -q options you can change the weights for each of 106the color channels. For example, to match only luminance, completely 107disregarding chrominance, use 108 109 metapixel --library images -i0 -q0 --metapixel input.jpg output.png 110 111The default weight for each of the channels is 1. 112 113Using the --cheat option you can specify the percentage by which the 114resulting photomosaic should be overlayed by the original image. The 115default is 0, i.e., the photomosaic is not overlayed at all. A 116percentage of 100 yields, not surprisingly, the original image. A 117percentage of 30 makes the photomosaic appear noticably better but is 118yet small enough to go unnoticed without close inspection in most 119circumstances. 120 121As of version 0.6, Metapixel implements two different matching 122algorithms. The new metric, which is a trivial distance function, 123seems to give better results while not being slower than the old 124wavelet metric. The metric can be chosen using the --metric option. 125The default is the new subpixel metric. 126 127You can use the --library option more than once to let Metapixel use 128more than one library for a mosaic. 129 130 131Classic Mosaics 132--------------- 133 134Metapixel allows you to choose between two algorithms for finding 135matching images, via the --search option. The old algorithm called 136"local" simply selects the best matching image for each location, 137possibly disregarding images selected in locations nearby (see below). 138 139The new algorithm called "global" repeats the following step until all 140locations have been assigned to: Find the best match for any location 141among all small images that have not already been used. This 142guarantees that no small image is used twice. Obviously, it also 143means that you must have at least as many small images as there are 144locations in the image. 145 146Note that "global" is much slower and uses more memory than "local". 147 148The "--distance" option lets you specify the minimal distance between 149two occurences of the same constituent image in the target image for 150the "local" algorithm. Distance 0 means that it is allowed for the 151same image to occur in adjacent positions in the matrix. The default 152distance is 5, which means that there must be at least 5 images 153"between" two occurences of the same image in the matrix. Note that 154Metapixel is forced to select non-optimal matches for distances 155greater 0. 156 157 158Antimosaics 159----------- 160 161Antimosaics are classic mosaics for which the small images are the 162parts of a single image, possibly the input image itself, and can be 163created using the --antimosaic option. Metapixel subdivides the 164antimosaic file as if it were doing a mosaic of that file, but then 165uses the resulting subimages as the small images for a classic mosaic. 166 167In case the antimosaic image and the input image are the same, 168Metapixel will simply reconstruct the input image from the subimages, 169because they will always match best in their original locations. To 170tell Metapixel to do otherwise, you can use the 171--forbid-reconstruction option, which allows you to specify a minimum 172distance between the original location of a subimage and the location 173it has in the resulting mosaic. 174 175Here's how you create an antimosaic with a minimum reconstruction 176distance of 2: 177 178 metapixel --library images -x input.jpg -f 2 --metapixel input.jpg output.png 179 180 181The Configuration File 182---------------------- 183 184The first thing Metapixel does is try to read the file ".metapixelrc" 185in your home directory. From this file, it reads default values for 186its settings, so that you don't have to give them on the command line 187each time you use Metapixel. 188 189In this configuration file, you can use the following directives: 190 191 (prepare-directory <directory>) 192 193 The library directory which metapixel-prepare should use by 194 default. metapixel-prepare does not automatically create the 195 directory if it doesn't exist, so make sure it does. 196 197 (prepare-dimensions <width> <height>) 198 199 The size metapixel-prepare should use for the small images. 200 201 (library-directory <directory>) 202 203 A library directory which Metapixel should use when creating 204 mosaics. You can use this directive more than once. 205 206 (small-image-dimensions <width> <height>) 207 208 The dimensions of the small images Metapixel should use in 209 mosaics. 210 211 (yiq-weights <y> <i> <q>) 212 213 The weights for the channels to be used in matching images. 214 215 (metric <metric>) 216 217 The metric Metapixel should use for matching images. This can 218 either be "subpixel" or "wavelet". 219 220 (search-method <method>) 221 222 The search method for creating classic mosaics. This can either 223 be "local" or "global". 224 225 (minimum-classic-distance <dist>) 226 227 The minimum distance between two occurences of the same image in 228 classic mosaics with the local search method. 229 230 (minimum-collage-distance <dist>) 231 232 The minimum distance (in pixels) between two occurences of the 233 same image in collage mosaics. 234 235 (cheat-amount <perc>) 236 237 The cheat amount in percent. 238 239 (forbid-reconstruction-distance <dist>) 240 241 The minimum distance between the position of subimage in the 242 original image and its position in the output image in an 243 antimosaic. 244 245Take a look at the file "metapixelrc" in the distribution. It gives 246examples for each of the directives discussed here. 247 248 249Collages 250-------- 251 252To create a collage, you have to use the "--collage" option in 253addition to "--metapixel". 254 255You can also specify a minimum distance between two occurences of the 256same image, which is measured in pixels. The default value is 256. 257Use the "--distance" option to change it. Note that the distance is 258measured between the centers of the images, not their edges, i.e., a 259minimum distance of 10 means that the centers of two occurences of the 260same image must be at least 10 pixels apart. This will usually mean 261that they are allowed to overlap, unless you use very tiny small 262images. 263 264Note that Metapixel uses ridiculous amounts of memory for collage 265mosaics. To create a collage photomosaics of size 2048x2048 your 266machine should at least have 64MBytes RAM. 267 268 269Protocols 270--------- 271 272Metapixel can, in addition to producing a classical mosaic, write a 273file specifying which small images it put in each of the locations. 274This protocol file can then be used to reproduce the mosaic without 275doing the matching again, for example to experiment with different 276cheat amounts. The protocol also contains information on how good 277each small image matches the original location, so you can find out 278where the matches are good and where they aren't. You can also modify 279the protocol and let metapixel generate a mosaic which it wouldn't 280have matched itself, for whatever reason you might want to do this. 281 282Use the --out option to create a protocol and the --in option to 283reproduce a mosaic from a protocol. The protocol file is a LISP list 284with the following syntax: 285 286 (mosaic (size <WIDTH> <HEIGHT>) (metapixels . <PIXELS>)) 287 288<WIDTH> and <HEIGHT> are the number of small images in the mosaic 289across the width and height of the mosaic, respectively. <PIXELS> is 290a list containing lists with the following syntax: 291 292 (<X> <Y> <W> <H> <FILENAME>) 293 294<X> and <Y> are the position of the small image. The upper left small 295image has coordinates (0,0), the lower right (<WIDTH>-1,<HEIGHT>-1). 296<W> and <H> must both be 1 in this version of Metapixel. <FILENAME> is 297the name of the small image file. 298 299A typical line in the protocol file looks like this: 300 301 (30 23 1 1 "semiharmless.new/wallpaper07.jpg.png") ; 4792.000000 302 303The number at the end of the line is the matching score. The lower 304the score, the better the match. Note that the semicolon ';' 305introduces a comment which lasts ends with the end of the line, so the 306matching score is not part of the protocol syntax. 307 308 309The matching algorithms 310----------------------- 311 312The algorithm that does the image matching via wavelets is described 313in the paper 'Fast Multiresolution Image Querying' by Charles 314E. Jacobs, Adam Finkelstein and David H. Salesin. 315 316The new subpixel metric is very trivial. I suggest you consult the 317source if you are interested in it. The matching function is 318subpixel_compare(). 319 320 321Sorting Images by Size or Aspect Ratio 322-------------------------------------- 323 324Metapixel comes with a tool called `metapixel-sizesort' which sorts 325images by size or aspect ratio by moving them to directories 326containing only files with similar size or aspect ratio. 327 328An example: Let's say you have thousands of images in /my/images, and 329you want them sorted by aspect ratio and placed in /my/sorted/images. 330You can do this with this command: 331 332 metapixel-sizesort --ratio=2 /my/images /my/sorted/images 333 334The option `2' to ratio tells metapixel-sizesort to put all those 335images together whose aspect ratios are the same with an accuracy of 336two places behind the comma. You might now have (among others) a 337directory called /my/sorted/images/ratio_0.79 which contains all 338images whose ratio between width and height is about 0.79. 339 340 341Upgrading from versions 0.8/0.9/0.10 342------------------------------------ 343 344Starting from release 0.11, Metapixel requires that the tables file is 345in the same directory as the small images described in that file. If 346your configuration is different, all you need to do is to make sure 347that all these files are in the same directory. You don't need to 348remove the paths in the tables file, as Metapixel does that 349automatically. 350 351 352Upgrading from versions 0.6/0.7 353------------------------------- 354 355The tables file format has changed in Metapixel 0.8, but you don't 356need to run 'metapixel-prepare' again. There's a program called 357'convert' included in the distribution that does the job. Just tell 358it which size your small images are, give it the old tables file on 359stdin and it writes the new one on stdout. 360 361For example, if your small images are 128 pixels wide and 96 pixels 362high, go to the directory with the tables file (usually the directory 363where the small images are) and do 364 365 convert --width=128 --height=96 <tables >tables.mxt 366 367 368Licence and Availability 369------------------------ 370 371Metapixel is free software distributed under the terms of the GPL. 372The file `COPYING' contains the text of the license. 373 374The source of Metapixel is available at the Metapixel homepage at 375 376 http://www.complang.tuwien.ac.at/schani/metapixel/ 377 378--- 379Mark Probst 380schani@complang.tuwien.ac.at 381