Penguin
Recent Changes
Annotated edit history of pngcrush(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 JohnMcPherson 1 !! pngcrush(1)
2
3
4
5
6 !!NAME
7
8
9 pngcrush -- optimizes (or modifies) PNG (Portable Network Graphics) files.
10
11 !!SYNOPSIS
12
13
14 __pngcrush__ [[__''options]''__ __''[[file1.png]''__ __''[[file2.png]'' ...__
15
16
17 __pngcrush -d ''dir [[options]''__ __''[[file1.png]''__ __''[[file2.png]'' ...__
18
19
20 __pngcrush -e ''ext [[options]''__ __''[[file1.png]''__ __''[[file2.png]'' ...__
21
22 !!DESCRIPTION
23
24
25 __pngcrush__ is an optimizer for PNG (Portable Network Graphics) files. Its main purpose is to reduce the size of the file's IDAT chunk (or stream). __pngcrush__ can also be used to modify a PNG's ancillary chunks (example: transparency information or textual comments). Some familiarity with the PNG (pronounced 'ping') format may be helpful to users of __pngcrush__. __pngcrush__ has reasonable defaults so running with no options may produce smaller files. This document briefly describes the PNG format where necessary to understand __pngcrush__. For complete documentation, see :
26
27 ftp://ftp.freesoftware.com/pub/png/.
28
29
30 The actual pixel data of a PNG is contained in one or many IDAT chunks. To make an IDAT chunk PNG encoders take the raw pixel data, filter it with one of 5 different filters (See Section __''"Filter Types"''__ ) then compress it. __pngcrush__ reduces the size of PNG files by choosing a different filter or compression methods from those used in the input file. __pngcrush__ tries multiple filter/compression methods and compares the size of the resulting IDAT chunk. The filter/compression method with the smallest IDAT chunk is chosen for the output file. The filter and compression levels __pngcrush__ tries are controlled by command line options. All of the filter methods and compression levels are lossless; they will not reduce image quality.
31
32 In addition to reducing the size of a PNG file, __pngcrush__ can modify ancillary chunks. Ancillary chunks are optional information including transparency (tRNS), gamma (gAMMA), standard RGB color space conformance (sRGB) or textual information (iTXt, tEXt or zTXt). See the associated command line options for details on manipulating these chunks.
33
34 !!OPTIONS
35
36 ;__-already ''size''__: If file has an IDAT chunk greater than the integer __''size''__, it will be considered to be already crushed and will not be processed further.
37
38
39 ;__-bit_depth ''n''__: Force output bit depth to __''n''__. See Section __''"Color''__ __''Types"''__ for bit depth restrictions.
40
41
42 ;__-bkgd ''r g b''__: Specify the default background color for the image. Some PNG viewers will use this background when displaying the image. Background is specified by __''r''__, __''g''__ and __''b''__ integers between 0 and (2 bitdepth)-1. For output color type 0 and 4 (gray, see section __''"Color''__ __''Types"''__ ) the green index is used as the grey level of the background.
43
44
45 ;__-brute__: Use brute force, try 114 different filter/compression methods [[11-124]. This option is very time-consuming and generally not worthwhile. You can restrict this option to certain filter types, compression levels, or strategies by following it with __-f__ __''filter,''__ __-l__ __''level,''__ __''or''__ __-z__ __''strategy. For example:''__
46
47 __pngcrush__ -brute -f 0 infile.png
48
49 Will try only methods that use filter type 0.
50
51 ;__-c type__: Set the output image color type to __''type''__, one of [[0, 2, 4, or 6] (see section __''"Color''__ __''Types"''__ ). Future versions of __pngcrush__ will also allow color type 3, if there are 256 or fewer colors present in the input file. Color types 4 and 6 are padded with an opaque alpha channel if the input file does not have alpha information. You can use 0 or 4 to convert color to grayscale. Use 0 or 2 to delete an unwanted alpha channel. Default is to use same color type as the input file.
52
53
54 ;__-cc__: Color counting. This option allows __pngcrush__ to perform further optimizations on the image based on the number of colors and the format of the imput image. With this option __pngcrush__ will remove an alpha channel from an opaque image and/or will reduce a true color image that is completely grey to greyscale representation.
55
56
57 ;__-d ''dir''__: Specify a directory for all output files. All output files will have the same name as their respective input files.
58
59
60 ;__-dou__: Double the images gamma. This is used for fixing gamma in !PhotoShop 5.0c5.02 files. It has been claimed that the PS5 bug is actually more complex than that, in some unspecified way.
61
62
63 ;__-e ''ext''__: Specify a new extention __''ext''__ for all output files.
64
65
66 ;__-exit__: Forces __pngcrush__ to call exit() rather than return() when it is finished. It is unclear to this writer why this option exists.
67
68 ;__-f: ''filter''__ Specify __''filter''__ (see section __''"Filter Types"''__ ) to use with the method specified in the preceding __-m__ or __-brute__ option. Valid filter types are [[0-4] : use specified filter, [[5]: use adaptive filtering.
69
70 ;__-fix__: Fix otherwise fatal conditions such as bad CRCs. The CRC (Cyclic Redundancy Check) is present in every chunk and can alert the decoder of corrupt data.
71
72
73 ;__-force__: Write a new output file even if larger than input. Otherwise the input file will be copied to output if it is smaller than any generated file and no chunk additions, removals, or changes were requested.
74
75 ;__-g: ''gamma''__ Value to insert in gAMA chunk, only if the input file has no gAMA chunk. To replace an existing gAMA chunk, use the __-replace_gamma__ option. Some decoders will use the gAMA chunk to more accurately display the image. __''gamma''__ relates the output intensity to the input samples (input_sample = light_out GAMMA). __''gamma''__ can be any integer between 0 and 2 32 and is interpreted as GAMMA*100000. For example, if you wanted a GAMMA of 1/2.2, you would enter 45455 for __''gamma''__.
76
77
78
79 __-h__ Display help and legal notices.
80
81 ;__-itxt [[b|a] ''keyword text''__: Insert an (uncompressed) iTXt chunk. __[[b|a]__ indicates whether chunk should be inserted __''b''__efore or __''a''__fter the IDAT chunk, (see Section __''"Text Chunks"''__ ).
82
83 ;__-l: ''level''__ zlib compression __''level''__ to use on the filtered IDAT chunk with the method specified by the preceding __-m__ or __-brute__ option. zlib compression levels are integers between 0 and 9. 0 = no compression, 1 = fastest compression, and 9 = best compression.
84
85 ;__-m: ''method'' pngcrush__ __''method''__ [[0-200] to try (0 means try all of 1-10). Can be repeated as in __-m 1 -m 4 -m__ __7__. This can be useful if you run out of memory when __pngcrush__ tries methods 2, 3, 5, 6, 8, 9, or 10 which use filtering and are memory intensive. Method 1, 4, and 7 use no filtering; methods 11 and up use specified filter, compression level, and strategy.
86
87
88 ;__-max ''maximum''_''IDAT''_''size''__: Set the maximum idat size to be used when creating the compression buffer.[[1 through 524288]
89
90
91 ;__-n__: Do not do compression or write output file. This is useful in conjunction with the __-v__ option to get info, or to test decode speed.
92
93 __-no_cc__ No color counting, see the __-cc__ option.
94
95 ;__-p__: This option tells __pngcrush__ to pause and wait for [[enter] key whenever the screen fills.
96
97
98
99 ;__-plte_len ''n''__: Truncates the PLTE. The PLTE chunk contains from 1 to 256 palette entries. Be sure not to truncate it to less than the greatest index present in IDAT.
100
101
102
103 __-q__ quiet, the opposite of verbose.
104
105 ;__-rem ''chunkname''__: Name of an ancillary chunk or optional PLTE to be removed. Be careful with this. Please don't use this feature to remove transparency, gamma, copyright, or other valuable information. To remove several different chunks, repeat: __-rem__ __tEXt -rem pHYs__. Known chunks (those in the PNG spec or extensions document) can be named with all lower-case letters, so __-rem bkgd__ is equivalent to __-rem bKGD__. But note: __-rem text__ removes all forms of text chunks; Exact case is required to remove unknown chunks. To do surgery with a chain-saw, __-rem alla__ removes all known ancillary chunks except for tRNS, and __-rem allb__ removes all but tRNS and gAMA.
106
107
108 ;__-replace_gamma ''gamma''__: Force a specified __''gamma''__ in the output file even if gAMA is present in the input. See the __-g__ for more information.
109
110 ;__-res: ''dpi''__ Write a pHYs chunk with a resolution of __''dpi''__. The pHYs chunk indicates the desired pixel size.
111
112
113 ;__-save__: Force writing of unknown chunks. If the input image has chunks that are not part of the PNG specification, they should not be discarded.
114
115
116 ;__-srgb ''n''__: Set value of rendering intent for sRGB chunk to __''n''__ where __''n''__ is between 0 and 3. The appropriate rendering intent depends on how the image will be used:
117
118
119 * 0 - Perceptual: when good adaptation: to the output device gamut at the expense of colorimetric accuracy is desired, example: photographs.
120
121
122 * 1 - Relative colorimetric: images: requiring color appearance matching (relative to the output device white point), example: logos.
123
124 * 2: Saturation: preservation of saturation at the expense of hue and lightness is preferred, example: charts and graphs.
125
126
127 * 3: Absolute colorimetric: images: requiring preservation of absolute colorimetry, example: proofs (previews of images destined for a different output device).
128
129
130 ;__-text [[b|a] ''keyword text''__: Insert a tEXt chunk. __[[b|a]__ indicates whether chunk should be inserted __''b''__efore or __''a''__fter the IDAT chunk, (see Section __''"Text Chunks"''__ ).
131
132
133 ;__-trns ''index red green blue gray''__: Insert a tRNS (transparency) chunk, if no tRNS chunk found in file. You must give all five parameters regardless of the color type, scaled to the output bit depth. See the PNG documentation for details.
134
135
136 ;__-v__: Display more detailed information. Repeat the option (use "-v -v") for even more.
137
138
139 ;__-w ''size''__: Specify __''size''__ in kbytes (or bytes in the case of 512) of the sliding compression window where size is one of [[32, 16, 8, 4, 2, 1, or 512]. It's best to use the default (32) unless you run out of memory. The program will use a smaller window anyway when the uncompressed file is smaller than 16k.
140
141
142 ;__-z ''strategy''__: Specify the zlib compression __''strategy''__ [[0, 1, or 2] to be used on the filtered IDAT chunk for the method of the preceeding __-m__. The zlib strategy parameter tunes the compression algorithm and is one of:
143
144 * 0 : default, most compression is aimed towards string matching
145
146 * 1 : some string matching, some huffman coding
147
148
149 * 2 : use only huffman coding
150
151 ;__-zitxt [[b|a] ''keyword text''__: Insert a zTXt chunk. __[[b|a]__ indicates whether chunk should be inserted __''b''__efore or __''a''__fter the IDAT chunk, (see Section __''"Text Chunks"''__ ).
152
153
154 ;__-ztxt [[b|a] ''keyword text''__: zTXt chunk to insert (see -text).
155
156
157 !!Color Types
158
159
160 The PNG specification provides for five color types. The color type determines how the IDAT chunk will be interpreted by the decoder. Choosing a color type appropriate for the color information in an image can reduce the size (See the __-cc__ option). Following are the PNG color types followed by their supported bit depths (Note __pngcrush__ does not support changing a file to color type 3 from another color type.):
161
162 * 0 : greyscale without alpha channel (1,2,4,8,16)
163 * 2 : true color without alpha channel (8,16)
164 * 3 : indexed color (1,2,4,8)
165 * 4 : greyscale with alpha channel (8,16)
166 * 6 : true color with alpha channel (8,16)
167
168
169 An alpha channel represents transparency on a per pixel basis. An alpha value of zero is completely transparent. An alpha channel of 2 bitdepth-1 is completely opaque.
170
171
172 !!Filter Types
173
174
175 The IDAT chunk can optionally be filtered before compression. These filters can make the IDAT chunk more compressible without losing any data and result in a smaller PNG file. These filters are applied to the bytes of the IDAT chunk, not the pixels. Following is a brief description of the filters, see the PNG specification for details:
176
177 * 0 : no filter
178 * 1 : 'sub' transmits the difference between each byte and the value of the corresponding byte of the prior pixel.
179
180 * 2 : 'up' transmits the difference between each byte and the value of the corresponding byte of the pixel above this pixel
181
182 * 3 : 'average' transmits the difference between each byte and the average of the btyes described in filters 1 and 2
183
184 * 4 : 'paeth' computes a simple linear function of the corresponding byte in three neighboring pixels (paeth_predictor = left + above - upper left), then transmits the difference between the byte in question and the neighboring byte closest to the value of paeth_predictor.
185
186
187 !!Text Chunks
188
189
190 Textual information pertaining to an image can be conveyed with the tEXt, iTXt and zTXt chunks. All text chunks consist of a keyword followed by a string. The following keywords are defined in the PNG specification: (you may invent keywords for other purposes):
191
192 __''Title''__: Short title or caption for image
193
194 __''Author''__: Name of image's creator
195
196 __''Description''__: Longer description of image
197
198 __''Copyright''__: Copyright notice
199
200 __''Creation Time''__: Time of original image creation
201
202 __''Software''__: Software used to create the image
203
204 __''Disclaimer''__: Legal disclaimer
205
206 __''Warning''__: Warning of nature of content
207
208 __''Source''__: Device used to create the image
209
210 __''Comment''__: Miscellaneous comment.
211
212
213 An iTXt chunk stores text in the ISO/IEC 8859-1 (Latin-1) character set. zTXt chunks also use the Latin-1 character set, but the text is compressed. This can be useful for large text chunks. iTXt chunks consist of text in the UTF-8 of the Unicode character set.
214
215
216 __''keyword''__ must be at least 1 character and less than 80 characters. __''text''__ must be less than 2048 characters when using __pngcrush__ For now, you can only add ten tEXt, iTXt, or zTXt chunks per __pngcrush__ run.
217
218 !!SEE ALSO
219
220
221 png(5), libpng(3), zlib(3).
222
223 !!AUTHOR
224
225
226 This manual page was written by David Whedon dwhedon@gordian.com for the __Debian GNU/Linux__ system (but may be used by others). Much of the information was gleaned from "PNG (Portable Network Graphics) Specification, Version 1.2"
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.