FVWM-THEMES-IMAGES(1)

NAME
fvwm-themes-images - fvwm-themes images and colors utility

SYNOPSIS
fvwm-themes-images --convert or/and --rotate value or/and --colorize or/and --tile or/and --border or --sky or --colorschemes or --show-xcolors or --show-xcolors-set or --show-color-info color or --help or --version [ --in-dir dir ] [ --out-dir dir ] [ --in-file file ] [ --out-file file ] [ --gnome ] [ --kde2 ] [ --kde2-hi ] [ --site ] [ --create-symlink name ] [ --update ] [ --ft-install ] [ --verbose int ] [ --[no]trans-filter ] [ --threshold int ] [ --postfix string ] [ --[no]build-48x48 ] [ --[no]build-16x16 ] [ --[no]build-56x56 ] [ --[no]build-32x32 ] [ --[no]build-tiles ] [ --preserve ] [ --size-48x48 geo ] [ --size-16x16 geo ] [ --size-56x56 geo ] [ --size-32x32 geo ] [ --size-tiles geo ] [ --border +x+y,color ] [ --border-48x48 +x+y,color ] [ --border-16x16 +x+y,color ] [ --border-56x56 +x+y,color ] [ --border-32x32 +x+y,color ] [ --border-tiles +x+y,color ] [ --tile rule:file ] [ --tile-48x48 rule:file ] [ --tile-16x16 rule:file ] [ --tile-56x56 rule:file ] [ --tile-32x32 rule:file ] [ --tile-tiles rule:file ] [ --rotate value ] [ --magick-bpp 8/16 ] [ --magick-path path ] [ --magick-colors int ] [ --magick-colorspace value ] [ --colorize-colors color1,color2... ] [ --trans-color color ] [ --colorize-comp value ] [ --colorize-rule value ] [ --sky-colors color1,color2... ] [ --pattern-file file ] [ --pattern-type value ] [ --pattern-xpm file ] [ --pattern-gap value ] [ --pattern-y value ] [ --sky-comp value ] [ --be-fast ] [ --setroot ] [ --setroot-prog exec ] [ --text-colors value ] [ --colorschemes-fores num,threshold,color1,color2 ] [ --colorschemes-ext ext ]

DESCRIPTION
The aim of this script is to build images to be used by fvwm-themes.

  Convert Images to XPM Images
fvwm-themes-images can convert images in various format (especially PNG GNOME or KDE version 2 icons) into XPM images of various sizes. This use ImageMagick plus some internal XPM manipulations (to get better results). For example, if you run:

    fvwm-themes-images --convert --gnome

then, if GNOME is not installed in an exotic way all icons in the GNOME images directory will be converted into 48x48 and 16x16 XPM icons under ~/tr-images (if GNOME is not found the images in /usr/share/pixmaps will be converted). To control the result of the conversion you can use the --threshold and --magick-colors option below. If the result is very very bad you must use the --magick-bpp option.

You can also convert an individual images by using the --in-file and --out-file option.

  Other transformations
fvwm-themes-images can perform other transformations (which do not require ImageMagick). You can colorize, rotate, add border and tile an XPM images. These operations can be done together (and with "convert") for all images in a directory or for an individual image. For example, if you want blue/red mirrored gnome icons tiled with a-48x48-tile.xpm for 48x48 icons and tiled with a-16x16-tile.xpm for 16x16 icons and with a yellow border of 5 pixels for 48x48 icons and of 2 pixels for 16x16 icons just run fvwm-themes-images with the following options :o)

    --gnome --convert --rotate 0m \
    --colorize --colorize-colors blue,red \
    --tile-48x48 path_to/a-48x48-tile.xpm \
    --tile-16x16 path_to/a-16x16-tile.xpm \
    --border-48x48 +5+5,yellow \
    --border-16x16 +2+2,yellow

  Colorize
fvwm-themes-images can colorize an XPM image (or a family of images in a directory). The main aim of "colorize" is to produce an infinite number of backgrounds with only one xpm. For example:

    fvwm-themes-images --colorize --colorize-colors black,red \
      --trans-color yellow --in-file My.xpm --setroot

will tile your root window with an XPM build from My.xpm, such that the darkest pixels in My.xpm are replaced by black pixels, the lightest pixels are replaced by red pixels, the pixels in between are interpolated between black and red and the transparent pixels are replaced by yellow pixels. Moreover, you can use more than 2 colors and some options allows you to control the interpolation. You can also rotate, tile and borderize your XPM. By default, fvwm-themes-images uses "fvwm-root" to set background, you can specify an other program using the --setroot-prog option, e.g., if you want to use xv just add the option

    --setroot-prog "xv -root -quit"

Note that if you do not specify an out-file, the built XPM is saved in /tmp/$USER-ft-back.xpm and then removed in this case.

  CDE-LIKE SKY
fvwm-themes-images can set the root window to a gradient pattern like CDE does. CDE has an option to display a gradient on the background, which consists of a repeated pattern, but along the color gradient, the color of the pattern varies. Try:

    fvwm-themes-images --sky --sky-colors turquoise,darkblue --setroot

in this case the default pattern file is used ($FT_DATADIR/themes/cde/background/pattern). A pattern file must contain a rectangular pattern consisting of +es and -es like this:

    +++++
    +-+-+
    -+-+-
    -----

and nothing else. This pattern is painted repeatedly over the screen. However, the colors change in the y direction accordingly with the --sky-colors and --sky-comp options. fvwm-themes-images can generate some pattern. If you want a regular gradient add the option: --pattern-type uniform:1, try also the --pattern-type option with square:50 or altern:20 and random:50 for examples. If you want an horizontal gradient just rotate: --rotate 90. You can also control the gradient computation. Try: --pattern-type square:64 --sky-comp c for a chess like background, --pattern-type altern:64,64 --sky-comp c for a band background, --pattern-type 1 --sky-comp r for an irregular gradient, and --pattern-type 1 --sky-comp t for an horrible background. Note that if your sky contains a lot of coulours you can speed a lot the construction of you sky by using the --be-fast option (but this will build a bigger XPM).

  PROCESSING COLOR SCHEMES
A color scheme file is a file constituted of one color by line. These colors are traditionally background colors. At the present time fvwm-themes-images can extend such color scheme file by adding corresponding foreground colors. For example, if there are several color scheme files with extension .pal in the directory DIR and you run:

    fvwm-themes-images --colorschemes --colorschemes-ext pal \
    --colorschemes-fores 8,128,color1,color2 --in-dir DIR --out-dir DIR

then the 8 first colors of the color scheme files will be unchanged and 8 new colors will be added (if your original color scheme files have more than 8 colors these colors are ignored/removed). So, you get color scheme files with 16 colors. The 7-th color is the foreground color, corresponding to the 1-st background color and so on. The foreground color is evaluated to be either color1 or color2. It is color1 for the backgrounds with gray value < 128 and is color2 otherwise. A gray value of 255 corresponds to white color and a gray value of 0 corresponds to black. So, the idea is to use a light color for color1 (like white) and a dark color for color2 (like black).

  COLORS
When giving colors to fvwm-themes-image, you can use X colors name (blue, turquoise, ...etc.), the standard RGB formats rgb:rr/gg/bb or rgb:rrrr/gggg/bbbb, 8bits hexadecimal number (#0000ff, #40e0d0, ...etc.), 16bits hexadecimal number (#00000000ffff, #0404e0e0d0d0, ...etc) or an array of 3 decimal numbers between 0 and 255 ([0/0/255], [64/224/208], ...etc.). All these numbers represent the red, green and blue values of the colors. To get the list of your X colors which have a name with the corresponding value in 8bits and in an array of 3 integer just type:

    fvwm-themes-images --show-xcolors | less

if you use hexadecimal numbers like #abcdef in some shells you must put these colors in quotes. Note, if you give colors by hexadecimal numbers fvwm-themes-images is faster, since rgb.txt should not be loaded.

fvwm-themes-images have some generic ways to create colors. You can give to fvwm-themes-images a color of the form:

    typecolor

where type is either top[integer], hilight, shadow, random and where color is a color encoded as explained above. If you give such a color fvwm-themes-images compute for you the "type" color of the "color". To see the result of these computations for all the colors which have name try:

    fvwm-themes-images --show-xcolorsets | less

for any individual color type:

    fvwm-themes-images --show-color-info color

You can enter random alone, this try to produce a random color. The only type which does not have a clear meaning is "top". top may have an integer between 0 and 255 after it (default is 255). top255 will purify your color as top0 will destroy it completely to black. Typically, top255blue will give blue, top255darkblue will give blue, top50blue will give a very dark blue. The top type (without integer argument) is used in a special way with the --colorize-colors option: if you want to colorize an XPM with "color" as a "center color" try the following:

    fvwm-themes-images --colorize --colorize-colors topcolor,topcolor \
    --in-file My.xpm --setroot

then, fvwm-themes-images will try to compute good integer values for top to produce two good colors.

OPTIONS

  General Options
--help - show the help and exit

--version - show the version and exit

--in-dir dir - The input directory. Default is the working directory of the shell that will run fvwm-themes-images. You can give either a complete path or a relative path (relative to the working directory). With the --gnome option fvwm-themes-images will try to find the GNOME icons directory, if GNOME is not found the default is /usr/share/pixmaps.

--out-dir dir - The main directory for output the images. Default is $HOME/tr-images and $FT_DATADIR/tr-images where $FT_DATADIR is the fvwm-themes installation directory with the --site option. You can give either a complete path or a relative path (relative to the working directory).

--in-file file - input file relatively to the --in-dir option except if you give a complete path.

--out-file file - output file if you use the --in-file option and not --convert. You can give either a complete path or a relative path (relative to the --out-dir option, i.e., $HOME/tr-images or $FT_DATADIR/tr-images). Yes, this is strange but this is good. With --convert - this option is ignored, with --setroot - you do not need to define an outfile, a temporary file is used, but you can, if you also want to save it.

--site equivalent to --out-dir $FT_DATADIR/tr-images.

--update if the file to be created already exist skip it. This is useful for example after you have installed some new GNOME applications and you do not want to rebuild all your xpm icons, with --update only the new icons are builded.

--gnome imply --convert, --postfix gnome, and try to find the GNOME icons directory to define the --in-dir, if GNOME is not found --in-dir is set to /usr/share/pixmaps

--kde2 imply --convert, --postfix kde2, and try to find the KDE2 icons directory to define the internal generalization of --in-dir, if these directories are not found or if the KDEDIR environement variable is not set nothing is done. Low colors icons under apps/ filesystems/ actions/ devices/ mimetypes/ and hight colors icons under the same directories are converted. If two icons to be converted have the same name, then the first found is converted (relatively to the above directories list). You can reverse the low/hight colors priority by using the next option. Note that there is a bug here: the only way to really rebuild the KDE2 icons is to remove the output directory; if not only the low (hight, with --kde2-hi) colors icons under apps/ will be rebuild.

--kde2-hi if --kde2 is used convert the KDE2 hight color icons before the low color icons.

--ft-install equivalent to --site --update --create-symlink 48x48,16x16. This option must be use with --gnome or --kde2 (but not both).

--create-symlink A,B - where A and B are either 48x48, 16x16, 32x32. Create symbolic link from $FT_DATADIR/images/norm-postfix to OUT/A-postfix and from $FT_DATADIR/images/mini-postfix to OUT/B-postfix. Where postfix is defined with the --postfix option and where OUT is the directory defined by --out-dir.

--verbose int - where int can be 0, 1 or 2. This integer represents the level of "verbosity". Default is 1, but with --setroot the default is 0.

  Convert
--convert - Will cause fvwm-themes-images to convert all images in the directory specified by the --in-dir options into XPM icons of various sizes. By default, XPM icons of sizes 48x48 and 16x16 are build in dir/48x48 and dir/16x16 where dir is he directory specified by the --out-dir option

--[no]trans-filter - Apply or not the internal "transparent filter". Default is --trans-filter and this filter can be controlled with the --threshold option below. When ImageMagick convert a PNG image into an XPM one the result is not perfect (or I have not found the good procedure). The problems is that a PNG image has a "matte" channel which represent the degree of transparency/opacity of the images. On the other hands, an XPM image has a binary matte channel (a pixel is either opaque or transparent). The "transparent filter" extract the matte channel (using ImageMagick), then "threshold" it (using again ImageMagick) to get the "good" transparency zone which is applied to the XPM image using an internal procedure (Maybe ImageMagick combine can do that but I never found the good procedure). If you have bad result try to use the --magick-bpp options.

--threshold value - value must be an integer between 0 and 100 and represent a percentage. This value is used by the "transparent filter" to compute the transparency zone of the builded XPM icons. More the value is big more the resulting images are transparent. For GNOME icons you may try value between 30 to 99 (a value of 100 will give a family of empty icons as a value of 0 will probably give to you icons with a black background). Default is 70.

--postfix str - add "-str" to the name of the output directories of the converted images: OUTDIR/48x48-str, OUTDIR/16x16-str ...etc.

--[no]build-48x48 - build or not the 48x48 XPM icons. Default is --build-48x48.

--[no]build-16x16 - build or not the 16x16 XPM icons. Default is --build-16x16.

--[no]build-56x56 - build or not the 56x56 XPM icons (under 56x56/). Default is --nobuild-56x56.

--[no]build-32x32 - build or not the 32x32 XPM icons (under 32x32/). Default is --nobuild-32x32.

--[no]build-tiles - build or not the tiles XPM icons from the tiles sub directory of the --in-dir option (under tiles/). Default is --nobuild-tiles.

--preserve - Set to no all the 5 previous options and convert without size modifications under the out-dir.

--size-48x48 geometry - Set the size of the 48x48 XPM icons via an ImageMagick size geometry. See the --size option of "man convert". Default is 48x48.

--size-16x16 geometry - As above for the 16x16 XPM icons. Default is 17x17 :)

--size-56x56 geometry - As above for the 56x56 XPM icons. Default is 56x56.

--size-32x32 geometry - As above for the 32x32 XPM icons. Default is 32x32.

--size-tiles geometry - As above for the tiles XPM icons. Default is "".

--border-48x48 +x+y,color - add border for the 48x48 XPM icons. See the --border option for details.

--border-16x16 +x+y,color - As above for the 16x16 XPM icons.

--border-56x56 +x+y,color - As above for the 16x16 XPM icons.

--border-32x32 +x+y,color - As above for the 32x32 XPM icons.

--border-tiles +x+y,color - As above for the tiles XPM icons.

--tile-48x48 [rule:]file_or_color - tile the 48x48 XPM icons with the xpm file following the rule "rule". See the ---tile option for details.

--tile-16x16 [rule:]file_or_color - As above for the 16x16 XPM icons.

--tile-56x56 [rule:]file_or_color - As above for the 56x56 XPM icons.

--tile-32x32 [rule:]file_or_color - As above for the 32x32 XPM icons.

--tile-tiles [rule:]file_or_color - As above for the tiles XPM icons.

  ImageMagick Options
--magick-colors value - Number of colors used. Default is 256. If you use X under 16bpp (xdpyinfo) you can use for example 65536.

--magick-colorspace value - Where value must be GRAY, OHTA, RGB, Transparent, XYZ, YCbCr, YIQ, YPbPr, YUV, or CMYK. See the -colorspace option of ImageMagick (man convert). Default is Transparent.

--magick-path path - set the path of the convert ImageMagick executable. Useful if convert ImageMagick executable is not in your PATH or to test different versions.

--magick-bpp value - value must be 8 or 16. Set the number of bit per pixels used by ImageMagick. This is a compile time option of ImageMagick and fvwm-themes-images will detect it if you use a recent version of ImageMagick. If fvwm-themes-images does not found this value it is set to 16. This is very important for the --threshold option above.

  Other Simple Transformations
--tile [rule:][+x+y,]file_or_color - where rule can be "expand", "center", "color" or nothing, where x and y are integers and where file_or_color is a xpm tile file or a color in the "color" case. Without "rule" the xpm file will be tiled as usual on the background of the image. With "expand" the tile file will be resized to fit the image. With "center" the image is centered on the tile file (your tile file have to be bigger that your image). With "color" the background of the image will be colorized by the color. The +x+y option can be used with all the rules but the "center" rule. This option expand the zone to tile by x pixels in the left and the right of the image and y pixels in the top and the bottom of the image.

--border +x+y,color - add x color pixels in the left and the right of the image and y color pixels in the top and the bottom of the image.

--rotate value - value can be 0m, 90, 90m, 180, 180m. The integer is the degree of the rotation the "m" says to also mirror the image.

  Colorize
--colorize-colors - Colorize an XPM image such that the darkest pixels are replaced by pixels with the first color in the color list below and the lightest pixels are replaced by pixels with the last color in the list below. The pixels in between are interpolated between these two colors and the colors in between. Moreover the transparent pixels can be replaced by opaque pixels with the --trans-color option. The type of the interpolation can be changed with the --colorize-comp. If you found that your resulting XPM is too contrasted you can try the "--colorize-rule min" option (or change the color list).

--colorize-colors color1,color2... - list of colors for colorization. The top type (without integer argument) is used in a special way here. If you use top with the first color and/or the last color fvwm-themes-images will try to find the good integer values to top to do so that these colors are "centred" in the colorization.

--trans-color color - set the transparent pixels to color pixels.

--colorize-comp type - type of the computation for the interpolation. Type can be "l" for linear (this is the default), "r" for perturbed (as linear but the colors obtained is randomly perturbed), "c" for circular (the colors in the list are used alternatively), "t" for totally random (then the list of colors are ignored and the pixels are colorized randomly ... this is funny).

--colorize-rule value - value can be max or min, default is max. max does nothing. min changes the way of the colorization: black is "mapped" to the first color in the list and white is "mapped" to the last color in the list.

  CDE-LIKE SKY
--sky - Create a "gradient" XPM which consists of a repeated pattern, but along the color gradient, the color of the pattern varies. A pattern file must contain a rectangular pattern consisting of +es and -es. This pattern is painted repeatedly over the screen. However, the colors change in the y direction accordingly with the --sky-colors and --sky-comp options. By default, the pattern used is $FT_DATADIR/themes/cde/background/pattern. You can use one of the --pattern-* option below to load or create other patterns. Finally, you can rotate your image to get horizontal gradient.

--sky-colors color1,color2... - List of the colors for creating the sky gradient.

--pattern-file file - use the pattern file "file" as pattern.

--pattern-type type[[:y]:x] - where type can be uniform, altern, square, random and where y and x are positive integers. If no type is specified uniform is used, default y is 1 and default x is 8, for square the default for x is y. uniform creates a pattern with y rows of x '+'. altern creates a pattern with y rows of x '+' followed by y rows of x '-' (a comma-separated value for y may be used; altern:10 and altern:10,10,0,0:8 are the same). square creates a pattern of y rows constituted of x '+' followed by x '-'. random creates a pattern with y random rows of length x.

--pattern-xpm file - Produce the pattern file from an xpm file. Set the transparent color to '-' and all other colors to '+'.

--pattern-gap n - where n is a positive integer. Take into account only every n-th lines of the pattern. Default is 1, so all pattern lines are taken.

--pattern-y y - where y is a positive integer. By default, the XPM file produced by --sky has the same height of your screen to produce complete gradient. You can set this height to a smaller value with this option to get repeated gradient or to save memory and time with some patterns and some --sky-comp options.

--sky-comp type - type of the computation for computing the gradient. The type are the same as for --colorize-comp but you can use also "p" for a polynomial interpolation.

--be-fast - If your sky contains a lot of colors you can use this option so that the background appear more rapidly on your root window. On the other hands, the XPM file builded will be larger.

  Setting the Root Image
--setroot - Set the root image (background) with the XPM file produced. Of course, this works only for a "transformation" which produces only one file, i.e., with --sky or with --in-file without --convert.

--setroot-prog prog - a program with arguments to be executed as "prog out.xpm" that sets the root window. Default is "fvwm-root".

  Evaluating foregrounds from backgrounds in color schemes
--colorschemes - Process color scheme files in the in-directory in place or into out-directory. A color scheme file is a file constituted of one color by line.

--colorschemes-fores num,threshold,color1,color2 - where num and threshold are integers. Transforms an original color scheme file using the following rules:

  1) the resulting file has 2*num lines of colors
  2) the first num colors (background colors) remain as are
  3) the last num lines are evaluated to be the foreground colors for the
first num background colors respectively.
  4) the foreground color is color1 if the background color has a gray value
which is less than threshold and is color2 otherwise.

--colorschemes-ext ext - consider only files with the trailing ".ext" in their names as color scheme files. Default is "dp".

  Colors Informations
--show-xcolors - show a list of all colors with an X name.

--show-xcolorsets - show a list of all "xcolors sets"

--show-color-info color - show full informations for the specified color

AUTHORS
Olivier Chapuis <olivier.chapuis@free.fr> (general design, convert, simple transformations, internal xpm library, interpolation, amelioration in "colorize" and cde-sky). 22 July 2000.

Jos van Riswick <josvanr@xs4all.nl> (Colorize, cde-sky, numerous functions in the colors "library").

The starting point of this script is the fvwm2gnome script written by Clarence Smith, Jr <csmith@staticbomb.com> and Jer Warren <jer@digitalaccess.net>, where ImageMagick is used to convert GNOME icons into 20x20 XPM icons.

COPYING
The script is distributed by the same terms as fvwm-themes itself. See GNU General Public License for details.

BUGS
The english of this man page have to be fixed.

Report bugs to fvwm-themes-devel@lists.sourceforge.net.