STANDARD DISCLAIMER: This software is released "as is". We do not want to hear people crying after their precious icon collection was reduced to black and white due to a bug :-). So: Read this file completely before proceeding! AUTHORS: Romano Giannetti (romano@iet.unipi.it) Martin Kraemer (Martin.Kraemer@Mch.SNI.De) Thanks to Dan Espen <dane@bae.bellcore.com> WHAT IS IT? This is a little program to reduce the number of colors of a set of pixmap files to a fixed predefined set of colors. Often, especially with the recent xpm-icon capable window managers like fvwm, people have the problem that their color map is almost full after starting the window manager, thus preventing other applications from using a sensible number of still available colors. Of course, this is mostly a problem with 8-bit deep displays; they have only 256 available colors in their color palette. HOW IS THIS ACHIEVED? pixy takes two files, one (base file) with the set of predefined colors to use, and another (the image file) from which it compares every color with the colors of the base file. The resulting file is the image file with every color replaced by the closest color from the base file; this file is sent to stdout or to a given new file name. The "closest" color is determined by finding the shortest distance in the HVC color space. This is the most intuitive transformation because the relative distances in HVC space approximate best the human feeling of similarity, both in color and in brightness. Because after replacement chances are that you end up with a lot of pixmap color entries using the same (reduced) color, all duplicate colors are eliminated by piping the output through the sxpm program (you can find it as part of the xpm distribution. When called with the "-nod" switch, it doesn't display the picture but only reduces all duplicate colors). NOTE TO X11R4 USERS: Too bad. You will have to upgrade to X11R5 at least. The color transformation routines we use (Xcms*) are not available in X11R4. Furthermore, X11R4 has only a very limited set of named colors, and you will not be able to use the supplied base pixmap files. INSTALLING AND RUNNING IT: To install, edit pixy.c and change #define HAVE_GETOPT_LONG 0 to 1 if you DO have the getopt_long() function in your library and the <getopt.h> include file. Then check if the X11 library path in Makefile is correct, and type make. That's all. Ah, you need xpm installed (I bet you wouldn't have thought ;-) and have sxpm in one of the directories in your path. Usage: pixy base.xpm icon.xpm > newicon.xpm after this, newicon.xpm will have each of its colors changed to the nearest one taken from the colors in base.xpm. You have a whole bunch of options to manipulate the transformation process: try to start pixy without arguments and it will show a usage message. (Anyone to volunteer for a man page?) Usage: pixy [<opts>] <basepixmapfile> <imagepixmapfile> Function: Reduce the colors in the image file to those used in the base file Options: -V Display program version and exit -v Verbose messages to stderr -n Do not fork "sxpm -nod" to reduce duplicates -o file Save converted image in <file>, do not send to stdout -r r:g:b Use RGB distances, weights are numbers, separated by ':' -h hc:v Use HVC distances. This is the default (using 1:1) -t t Rotate the image's color hue by <t> degrees -m m Substitute only if dist <= m (if you have getopt_long(), the help list will show the long option names) The most interesting part of the transformation algorithm is the metric used to compute color distances. By default pixy uses plain TekHVC metric, which seems (they say :-) to give a "real" visual distance between colors. You can add a weight to the calculation, e.g. giving more importance to chroma than to luminosity by giving parameters (e.g., try --hvc 3:1 for small icons). Or you can choose a cubic rgb distance, with every primary color weighted independently, or both weighings together (although the usefulness of this is not so clear). Flag --verbose (-v) is quite nice, it shows you what's going on inside pixy. In pixy, "Color Distances" are measured internally as the _square_ of the distances in color space. Since RGB space consists of a 100x100x100 cube and the HC and V components in HVC space lie between 0 and 100 as well, this results in a distance 0...10000 in each direction. To improve the conversion algorithm, you can optionally specify a maximum distance for the substitutions: if you say --max 200, only color substitutions with a distance less than or equal to 200 will be performed. To get an idea, for my eyes a distance of 100 is difficult to see. For icons, a distance of up to 500 is most of the times acceptable. To get to know more about colors, especially about the TekHVC color space, point your preferred WWW browser to http://hpux.cict.fr/man/X11/Graphics/xtici-1.0/xtici-1.0.html download xtici and read the documentation, especially doc/tc_ed_ch1.ps Old versions of pixy required running sxpm by hand to reduce colors. This is no longer necessary; "sxpm -nod" is called automatically now. **** Goodies: **** rgb_to_xpm: A script, from Martin, to generate all.xpm from your own rgb.txt file. Use it as rgb_to_xpm </usr/lib/X11/rgb.txt >all.xpm all.xpm: Romano, playing with awk and rgb.txt, created a dummy pixmap called all.xpm that you find here. Do not try to visualize it. Do not let sxpm reduce it to normalized one. Its use is as a base pixmap to transform image pixmaps with numeric RGB color specifications of the form #456790984567 into equivalent pixmaps using only named colors, greatly increasing the probability of color reuse in your X server. 32col.xpm, 16col.xpm: Need an explanation? 32num.xpm: 32-colors pixmap with numeric color specification. reduce_xpm_colors: This is a script that tries to reduce the colors of all of the xpm icons you use (it looks at $HOME/.fvwm2rc, so if you use a different file or a different window manager, edit...) to the ones given in a base pixmap file. To use: 0) Edit reduce_xpm_colors (first lines) 1) Go in an empty directory. (***IMPORTANT***) The resulting files will be put in this directory! 2) copy your "base icon" with your preferred color subset to this directory. 3) execute "reduce_xpm_colors base.xpm" 4) look (with xbmbrowser, for example) at the new color-compacted icons 5) if you do not like the result, try to change the weights or other options (you can give options to the script which will be passed to pixy, as in: "reduce_xpm_colors --rgb 1:1:1 --max 400 base.xpm" Enjoy! Romano and Martin $Id: README,v 3.1.1.1 1996/03/27 16:26:27 deejai!martin Exp $
