1ICOTOOL(1)                  General Commands Manual                 ICOTOOL(1)
2
3
4

NAME

6       icotool - Convert and create Win32 icon and cursor files
7

SYNOPSIS

9       icotool [OPTION]... [FILE]...
10

DESCRIPTION

12       This manual page document describes the icotool command.
13
14       The  icotool program converts and creates icon (.ico) and cursor (.cur)
15       files. At the moment icons can only be created from and extracted  into
16       PNG files. This is done using libpng.
17
18       Icon and cursor files are used mainly on the Microsoft Windows(R) plat‐
19       form. Each icons or cursors file may contain multiple images of various
20       resolutions  and  with  different number of colors. Cursor files differ
21       from icon files in that they also contain information about the hotspot
22       of each image.
23
24       Recent  versions  of  Microsoft's Internet Explorer use icons for small
25       site logotypes. The browser fetches a file called  favicon.ico  from  a
26       web  site,  and  uses  the images in this file to represent the site in
27       menus and site lists. (This file is  placed  in  the  web  site's  root
28       directory,  like any other file.) Browsers like Galeon have copied this
29       behaviour and now also fetches .ico files and use them for  site  logo‐
30       types.
31
32       As  each  icon or cursor file may contains multiple images of different
33       dimensions and depth, a conversion may result  in  multiple  PNG  files
34       being  created.  Correspondingly,  multiple  PNG files can be specified
35       when creating an icon/cursor file.
36

OPTIONS

38       These programs follow the usual GNU  command  line  syntax,  with  long
39       options starting with two dashes (`-').
40
41       -x, --extract
42              This option tells icotool that images from all icon/cursor files
43              given on the command line are to be  extracted.  Filter  options
44              (see  below)  can  be  used  to control what images that will be
45              extracted.
46
47       -l, --list
48              This options tells icotool that images in all given  icon/cursor
49              files  are  to  be  listed.  The output will look something like
50              this:
51
52                --icon --index=1 --width=16 --height=16  --bit-depth=4  --pal‐
53              ette-size=16
54                --icon  --index=2  --width=32 --height=32 --bit-depth=8 --pal‐
55              ette-size=256
56
57       -c, --create
58              This options tells icotool to create an icon/cursor  file  using
59              all  the  PNG files given on the command line, in the order they
60              were specified.  The number  of  bits  per  pixel  used  in  the
61              icon/cursor file will depend on the number of colors used in the
62              PNG file. (If the PNG image has an indexed palette,  it  doesn't
63              necessarily  mean that the same palette will be used in the cre‐
64              ated icon/cursor file.)
65
66       -i, --index=N
67              When listing or extracing files, this options  tell  icotool  to
68              list  or  extract  only  the  N'th image in each file. The first
69              image has index 1.
70
71              This option has no effect in create mode.
72
73       -w, --width=PIXELS
74              Similar to --index, but this option allows the image width to be
75              matched instead. This option has no effect in create mode.
76
77       -h, --height=PIXELS
78              Similar  to  --index, but this option allows the image height to
79              be matched instead. This option has no effect in create mode.
80
81       -b, --bit-depth=COUNT
82              Similar to --index, but this option allows the  number  of  bits
83              per  pixel  in the image to be matched instead. Valid values are
84              1, 2, 4, 8, 16, 24 and 32.
85
86              In create mode, this option will allow you to specify a  minimum
87              bit depth for images in the icon file.
88
89       -p, --palette-size=PIXELS
90              Similar  to --index, but this option allows the number of colors
91              in the image palette to be matched instead. Images with 24 or 32
92              bits in icon/cursor files do not have a palette, and will there‐
93              fore have a palette size equal to 0.
94
95              This option has no effect in create mode.
96
97       -X, --hotspot-x=COORD
98              Similar to --index, but this option allows the  x-coordinate  of
99              the hotspot to be matched. This option only has effect on cursor
100              files.
101
102              In create mode, this can be used to specify the hotspot  x-coor‐
103              dinate.
104
105       -Y, --hotspot-y=COORD
106              Similar  to  --index, but this option allows the y-coordinate of
107              the hotspot to be matched. This option only has effect on cursor
108              files.
109
110              In  create mode, this can be used to specify the hotspot y-coor‐
111              dinate.
112
113       --icon This option specifies that only icon files are to be  listed  or
114              extracted.   In  create mode, this option can be used to specify
115              that an icon (instead of a cursor) is to be  created.  (This  is
116              default in create mode.)
117
118       --cursor
119              This option specifies that only cursor files are to be listed or
120              extracted.  In create mode, this can be used to specify  that  a
121              cursor (instead of an icon) is to be created.
122
123       -t, --alpha-threshold=LEVEL
124              Specifies  the maximal alpha level in the PNG image for portions
125              which shall become transparent in the icon created. The  default
126              value is 127.  This is only used when creating icon files.
127
128       -o, --output=PATH
129              In  extract  mode,  this  option  specifies  a  directory  where
130              extracted files are to be created. If PATH does not exist, it is
131              assumed that it refers to a non-existing file instead. The first
132              image matched will be extracted to the file with that name.
133
134              In create mode, this option specified the  name  of  the  output
135              file.   The  default is to write the binary data to standard out
136              (which icotool will refuse if standard out is the terminal).
137
138              If PATH is `-', then all output will be printed to standard out.
139
140              This option has no effect in list mode.
141
142       -r, --raw=FILENAME
143              Store input file as raw PNG (Vista icons).
144
145       --help Show summary of options.
146
147       --version
148              Output version information and exit.
149

EXAMPLES

151       List all images in the file `demo.ico':
152         $ icotool -l demo.ico
153         --icon  --index=1  --width=16  --height=16  --bit-depth=4  --palette-
154       size=16
155         --icon  --index=2  --width=32  --height=32  --bit-depth=4  --palette-
156       size=16
157         --icon  --index=3  --width=48  --height=48  --bit-depth=4  --palette-
158       size=16
159         --icon  --index=4  --width=16  --height=16  --bit-depth=8  --palette-
160       size=256
161         --icon  --index=5  --width=32  --height=32  --bit-depth=8  --palette-
162       size=256
163         --icon  --index=6  --width=48  --height=48  --bit-depth=8  --palette-
164       size=256
165
166       List only 16-color images in `demo.ico':
167         $ icotool -l --palette-size=16 demo.ico
168         --icon  --index=1  --width=16  --height=16  --bit-depth=4  --palette-
169       size=16
170         --icon  --index=2  --width=32  --height=32  --bit-depth=4  --palette-
171       size=16
172         --icon  --index=3  --width=48  --height=48  --bit-depth=4  --palette-
173       size=16
174
175       Extract  all  images to current directory, naming the destination files
176       `demo.ico_I_WxHxD.xpm':
177         $ icotool -x -o . demo.ico
178         $ ls *.png
179         demo_1_16x16x4.png  demo_3_48x48x4.png  demo_5_32x32x8.png
180         demo_2_32x32x4.png  demo_4_16x16x8.png  demo_6_48x48x8.png
181
182       Extract all 256-color icon images in all  .ico  files  in  the  current
183       directory, placing the extracted images in `img/'
184         $ icotool -x -o img/ -p 256 *.ico
185
186       Create an icon named `favicon.ico' with two images:
187         $ icotool -c -o favicon.ico mysite_32x32.png mysite_64x64.png
188

AUTHOR

190       The icoutils were written by Oskar Liljeblad <oskar@osk.mine.nu>.
191
193       Copyright © 1998 Oskar Liljeblad
194
195       This is free software; see the source for copying conditions.  There is
196       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
197       PURPOSE.
198

TRADEMARKS

200       Windows  is  a  registered  trademark  of  Microsoft Corporation in the
201       United States and other countries.
202
203
204
205icotool (icoutils)              April 18, 2005                      ICOTOOL(1)
Impressum