1ICOTOOL(1) General Commands Manual ICOTOOL(1)
2
6 icotool - Convert and create Win32 icon and cursor files
7
9 icotool [OPTION]... [FILE]...
10
12 This manual page document describes the icotool command.
13 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 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 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 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
38 These programs follow the usual GNU command line syntax, with long
39 options starting with two dashes (`-').
40 -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 -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 --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 -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 -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 This option has no effect in create mode.
72 -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 -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 -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 In create mode, this option will allow you to specify a minimum
87 bit depth for images in the icon file. If you provide the
88 option once it will apply to all input files. If you specify it
89 multiple times, it will apply to all input files following a
90 particular option; in that case you should specify a bit depth
91 for all images.
92 -p, --palette-size=PIXELS
94 Similar to --index, but this option allows the number of colors
95 in the image palette to be matched instead. Images with 24 or 32
96 bits in icon/cursor files do not have a palette, and will there‐
97 fore have a palette size equal to 0.
98 This option has no effect in create mode.
100 -X, --hotspot-x=COORD
102 Similar to --index, but this option allows the x-coordinate of
103 the hotspot to be matched. This option only has effect on cursor
104 files.
105 In create mode, this can be used to specify the hotspot x-coor‐
107 dinate. If you provide the option once it will apply to all
108 input files. If you specify it multiple times, it will apply to
109 all input files following a particular option; in that case you
110 should specify a hotspot coordinate for all images.
111 -Y, --hotspot-y=COORD
113 Similar to --index, but this option allows the y-coordinate of
114 the hotspot to be matched. This option only has effect on cursor
115 files.
116 In create mode, this can be used to specify the hotspot y-coor‐
118 dinate. If you provide the option once it will apply to all
119 input files. If you specify it multiple times, it will apply to
120 all input files following a particular option; in that case you
121 should specify a hotspot coordinate for all images.
122 --icon This option specifies that only icon files are to be listed or
124 extracted. In create mode, this option can be used to specify
125 that an icon (instead of a cursor) is to be created. (This is
126 default in create mode.)
127 --cursor
129 This option specifies that only cursor files are to be listed or
130 extracted. In create mode, this can be used to specify that a
131 cursor (instead of an icon) is to be created.
132 -t, --alpha-threshold=LEVEL
134 Specifies the maximal alpha level in the PNG image for portions
135 which shall become transparent in the icon created. The default
136 value is 127. This is only used when creating icon files.
137 -o, --output=PATH
139 In extract mode, this option specifies a directory where
140 extracted files are to be created. If PATH does not exist, it is
141 assumed that it refers to a non-existing file instead. The first
142 image matched will be extracted to the file with that name.
143 In create mode, this option specified the name of the output
145 file. The default is to write the binary data to standard out
146 (which icotool will refuse if standard out is the terminal).
147 If PATH is `-', then all output will be printed to standard out.
149 This option has no effect in list mode.
151 -r, --raw=FILENAME
153 Store input file as raw PNG (Vista icons).
154 --help Show summary of options.
156 --version
158 Output version information and exit.
159
161 List all images in the file `demo.ico':
162 $ icotool -l demo.ico
163 --icon --index=1 --width=16 --height=16 --bit-depth=4 --palette-
164 size=16
165 --icon --index=2 --width=32 --height=32 --bit-depth=4 --palette-
166 size=16
167 --icon --index=3 --width=48 --height=48 --bit-depth=4 --palette-
168 size=16
169 --icon --index=4 --width=16 --height=16 --bit-depth=8 --palette-
170 size=256
171 --icon --index=5 --width=32 --height=32 --bit-depth=8 --palette-
172 size=256
173 --icon --index=6 --width=48 --height=48 --bit-depth=8 --palette-
174 size=256
175 List only 16-color images in `demo.ico':
177 $ icotool -l --palette-size=16 demo.ico
178 --icon --index=1 --width=16 --height=16 --bit-depth=4 --palette-
179 size=16
180 --icon --index=2 --width=32 --height=32 --bit-depth=4 --palette-
181 size=16
182 --icon --index=3 --width=48 --height=48 --bit-depth=4 --palette-
183 size=16
184 Extract all images to current directory, naming the destination files
186 `demo.ico_I_WxHxD.xpm':
187 $ icotool -x -o . demo.ico
188 $ ls *.png
189 demo_1_16x16x4.png demo_3_48x48x4.png demo_5_32x32x8.png
190 demo_2_32x32x4.png demo_4_16x16x8.png demo_6_48x48x8.png
191 Extract all 256-color icon images in all .ico files in the current
193 directory, placing the extracted images in `img/'
194 $ icotool -x -o img/ -p 256 *.ico
195 Create an icon named `favicon.ico' with two images:
197 $ icotool -c -o favicon.ico mysite_32x32.png mysite_64x64.png
198
200 The icoutils were written by Oskar Liljeblad <oskar@osk.mine.nu>.
201
203 Copyright © 1998 Oskar Liljeblad
204 This is free software; see the source for copying conditions. There is
206 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
207 PURPOSE.
208
210 Windows is a registered trademark of Microsoft Corporation in the
211 United States and other countries.
212icotool (icoutils) April 18, 2005 ICOTOOL(1)