Provided by: icoutils_0.32.3-1_amd64 bug

NAME

       icotool - Convert and create Win32 icon and cursor files

SYNOPSIS

       icotool [OPTION]... [FILE]...

DESCRIPTION

       This manual page document describes the icotool command.

       The  icotool  program  converts  and  creates  icon (.ico) and cursor (.cur) files. At the
       moment icons can only be created from and extracted into PNG files.  This  is  done  using
       libpng.

       Icon  and cursor files are used mainly on the Microsoft Windows(R) platform. Each icons or
       cursors file may contain multiple images of various resolutions and with different  number
       of colors. Cursor files differ from icon files in that they also contain information about
       the hotspot of each image.

       Recent versions of Microsoft's Internet Explorer use icons for small site  logotypes.  The
       browser  fetches  a  file  called favicon.ico from a web site, and uses the images in this
       file to represent the site in menus and site lists. (This file is placed in the web site's
       root  directory, like any other file.) Browsers like Galeon have copied this behaviour and
       now also fetches .ico files and use them for site logotypes.

       As each icon or cursor file may contains  multiple  images  of  different  dimensions  and
       depth,  a  conversion  may  result  in  multiple PNG files being created. Correspondingly,
       multiple PNG files can be specified when creating an icon/cursor file.

OPTIONS

       These programs follow the usual GNU command line syntax, with long options  starting  with
       two dashes (`-').

       -x, --extract
              This  option  tells  icotool  that  images  from all icon/cursor files given on the
              command line are to be extracted. Filter options (see below) can be used to control
              what images that will be extracted.

       -l, --list
              This  options  tells  icotool  that images in all given icon/cursor files are to be
              listed. The output will look something like this:

                --icon --index=1 --width=16 --height=16 --bit-depth=4 --palette-size=16
                --icon --index=2 --width=32 --height=32 --bit-depth=8 --palette-size=256

       -c, --create
              This options tells icotool to create an icon/cursor file using all  the  PNG  files
              given  on  the  command line, in the order they were specified.  The number of bits
              per pixel used in the icon/cursor file will depend on the number of colors used  in
              the PNG file. (If the PNG image has an indexed palette, it doesn't necessarily mean
              that the same palette will be used in the created icon/cursor file.)

       -i, --index=N
              When listing or extracing files, this options tell icotool to list or extract  only
              the N'th image in each file. The first image has index 1.

              This option has no effect in create mode.

       -w, --width=PIXELS
              Similar  to  --index, but this option allows the image width to be matched instead.
              This option has no effect in create mode.

       -h, --height=PIXELS
              Similar to --index, but this option allows the image height to be matched  instead.
              This option has no effect in create mode.

       -b, --bit-depth=COUNT
              Similar  to  --index,  but  this  option allows the number of bits per pixel in the
              image to be matched instead. Valid values are 1, 2, 4, 8, 16, 24 and 32.

              In create mode, this option will allow you to  specify  a  minimum  bit  depth  for
              images in the icon file.  If you provide the option once it will apply to all input
              files.  If you specify it  multiple  times,  it  will  apply  to  all  input  files
              following  a particular option; in that case you should specify a bit depth for all
              images.

       -p, --palette-size=PIXELS
              Similar to --index, but this option allows  the  number  of  colors  in  the  image
              palette  to  be  matched instead. Images with 24 or 32 bits in icon/cursor files do
              not have a palette, and will therefore have a palette size equal to 0.

              This option has no effect in create mode.

       -X, --hotspot-x=COORD
              Similar to --index, but this option allows the x-coordinate of the  hotspot  to  be
              matched. This option only has effect on cursor files.

              In  create  mode,  this  can  be  used to specify the hotspot x-coordinate.  If you
              provide the option once it will apply to  all  input  files.   If  you  specify  it
              multiple  times, it will apply to all input files following a particular option; in
              that case you should specify a hotspot coordinate for all images.

       -Y, --hotspot-y=COORD
              Similar to --index, but this option allows the y-coordinate of the  hotspot  to  be
              matched. This option only has effect on cursor files.

              In  create  mode,  this  can  be  used to specify the hotspot y-coordinate.  If you
              provide the option once it will apply to  all  input  files.   If  you  specify  it
              multiple  times, it will apply to all input files following a particular option; in
              that case you should specify a hotspot coordinate for all images.

       --icon This option specifies that only icon files are  to  be  listed  or  extracted.   In
              create  mode, this option can be used to specify that an icon (instead of a cursor)
              is to be created. (This is default in create mode.)

       --cursor
              This option specifies that only cursor files are to be  listed  or  extracted.   In
              create  mode,  this can be used to specify that a cursor (instead of an icon) is to
              be created.

       -t, --alpha-threshold=LEVEL
              Specifies the maximal alpha level in the PNG image for portions which shall  become
              transparent  in the icon created. The default value is 127.  This is only used when
              creating icon files.

       -o, --output=PATH
              In extract mode, this option specifies a directory where extracted files are to  be
              created.  If  PATH  does  not exist, it is assumed that it refers to a non-existing
              file instead. The first image matched will be extracted to the file with that name.

              In create mode, this option specified the name of the output file.  The default  is
              to write the binary data to standard out (which icotool will refuse if standard out
              is the terminal).

              If PATH is `-', then all output will be printed to standard out.

              This option has no effect in list mode.

       -r, --raw=FILENAME
              Store input file as raw PNG (Vista icons).

       --help Show summary of options.

       --version
              Output version information and exit.

EXAMPLES

       List all images in the file `demo.ico':
         $ icotool -l demo.ico
         --icon --index=1 --width=16 --height=16 --bit-depth=4 --palette-size=16
         --icon --index=2 --width=32 --height=32 --bit-depth=4 --palette-size=16
         --icon --index=3 --width=48 --height=48 --bit-depth=4 --palette-size=16
         --icon --index=4 --width=16 --height=16 --bit-depth=8 --palette-size=256
         --icon --index=5 --width=32 --height=32 --bit-depth=8 --palette-size=256
         --icon --index=6 --width=48 --height=48 --bit-depth=8 --palette-size=256

       List only 16-color images in `demo.ico':
         $ icotool -l --palette-size=16 demo.ico
         --icon --index=1 --width=16 --height=16 --bit-depth=4 --palette-size=16
         --icon --index=2 --width=32 --height=32 --bit-depth=4 --palette-size=16
         --icon --index=3 --width=48 --height=48 --bit-depth=4 --palette-size=16

       Extract   all   images   to   current   directory,   naming    the    destination    files
       `demo.ico_I_WxHxD.xpm':
         $ icotool -x -o . demo.ico
         $ ls *.png
         demo_1_16x16x4.png  demo_3_48x48x4.png  demo_5_32x32x8.png
         demo_2_32x32x4.png  demo_4_16x16x8.png  demo_6_48x48x8.png

       Extract  all 256-color icon images in all .ico files in the current directory, placing the
       extracted images in `img/'
         $ icotool -x -o img/ -p 256 *.ico

       Create an icon named `favicon.ico' with two images:
         $ icotool -c -o favicon.ico mysite_32x32.png mysite_64x64.png

AUTHOR

       The icoutils were written by Oskar Liljeblad <oskar@osk.mine.nu>.

COPYRIGHT

       Copyright © 1998 Oskar Liljeblad

       This is free software; see the source for copying conditions.  There is NO  warranty;  not
       even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

TRADEMARKS

       Windows  is a registered trademark of Microsoft Corporation in the United States and other
       countries.