TweakPNG: A low-level PNG image file manipulation utility Version 1.2.1 - 11 Dec 2004 Copyright (c) 1999-2004 Jason Summers ==================== License ==================== This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA A copy of the GNU General Public License is included in the file COPYING.txt. To get the latest version of TweakPNG, visit the TweakPNG home page at . ==================== Requirements ==================== - A Win32 operating system (Windows 95, 98, 2000, XP, etc.) - A mouse or equivalent input device for the palette editor. - Some knowledge of the PNG file format. ==================== Installation and Uninstallation ==================== To install: Create an empty directory and unzip the contents of tweakpng-1.x.x.zip into it. Only the file tweakpng.exe is really necessary. To run: Open the file tweakpng.exe. To uninstall: Delete the directory you created and its contents. If you want, delete the registry key "HKEY_CURRENT_USER\SOFTWARE\Generic\TweakPNG" if it exists. ==================== Introduction ==================== TweakPNG is an interactive PNG file editor utility that allows you to view and modify some of the meta-information stored in PNG image files. It is not a real image editor or viewer. (It does include a simple image viewer, but it only passively displays the current state of the file.) The rest of this document will be difficult to understand if you are not familiar with the details of the PNG file format. To learn about it, look for the specification at the PNG home page, . Viewing files in TweakPNG may, however, make it easier to become familiar with the PNG format. Here are a few of the possible uses of TweakPNG: - To remove unneeded or unwanted chunks, usually to reduce file size. - To annotate an image file by adding or modifying text chunks. - To change background colors and transparency settings. - To help make test images for testing applications that read PNG files. Not all the types of PNG chunks can be edited. This table summarizes the current capabilities of TweakPNG regarding specific chunk types: View Edit Create ========================================================= IHDR yes yes yes IEND n/a n/a yes IDAT no no no PLTE yes yes yes bKGD yes yes yes gAMA yes yes yes cHRM yes yes yes tRNS yes yes yes sBIT yes yes yes hIST no no no sRGB yes yes yes tEXt yes yes yes zTXt yes yes yes iTXt keyword only no no pHYs yes yes yes tIME yes yes yes iCCP name only no no sPLT name only no no ==================== Features ==================== Most of the non-obvious features of TweakPNG are described below. General ------- TweakPNG shows a "chunk"-level view of the PNG file. Each chunk in the current file is displayed in order, one chunk to a line. Five items are displayed for each chunk: 1. Chunk - The 4-letter chunk type code 2. Length - The number of bytes in the data portion of the chunk. Each chunk actually consumes 12 more bytes than this, to store its type code, length, and CRC. 3. CRC - Chunk checksum 4. Attributes - Chunk properties based on the capitalization of the type code. 5. Contents - Information about the contents of the chunk. This depends on the type of chunk You can change the size of the columns by dragging the separator bars between the column names. You can even hide columns completely. To unhide a column, place your mouse just to the right of the bar and drag to the right. To edit a chunk, double click on it, or select it and press the Enter key. Not all chunks can be edited. Use the items on the Edit and Insert menus to access other features. Editing an IHDR chunk does not convert the image based on your modifications. For example, checking the "interlaced" box does not make the image interlaced, in only makes the image claim to be interlaced. Therefore, there is not much reason to edit the IHDR chunk, although it is possible to convert between a grayscale and a palette image of the same bit depth. Insert (new chunk) ------------------ You can add some types of chunks to your file by selecting items on the Insert menu. New chunks will be created with reasonable default values, and can then be edited. New chunks are not guaranteed to be created at the right position in the file, so you may sometimes have to move them. Move Up/Down ------------ You can rearrange chunks by selecting Edit|Move Up or Down from the menu. Use the Check Validity function to make sure you leave them in a legal order. Note that you can select multiple chunks and move them together. Don't rearrange IDAT chunks in a file that has more than one of them, or the file will be unreadable. Copy, Cut, Paste ---------------- Use these functions to copy chunks to the clipboard and back. They support multiple chunks at a time. The system clipboard is used, so you can copy chunks from one file to another. Unlike in most programs, Paste does not delete the currently selected chunk(s). Pasted chunks are inserted just before the first selected chunk. Combine IDAT Chunks ------------------- IDAT chunks contain the actual image. The PNG specification allows for the image data to be split up among any number of IDAT chunks, which much occur consecutively in the file. For efficiency reasons, some applications do not write IDAT chunks larger than some fixed size (say, 8192 bytes). TweakPNG allows you to consolidate IDAT chunks if there are more than one. This saves 12 bytes of file size per chunk that you eliminate. Choose Edit|Combine all IDAT, or select a range of IDAT chunks and then Edit|Combine IDAT chunks. Note: There are at least a half dozen ways to select multiple items. One way is to left-click on the first item to select it, then hold down Shift and left-click on the last item. Split IDAT chunks ----------------- You can also do the reverse: split up an IDAT chunk into two or more pieces. Why you'd want to do that, I'm not sure, but it's provided for completeness. Select a chunk and choose Edit|Split IDAT chunk. Enter the byte size of the first chunk. To divide it into two chunks, leave the "Repeat..." checkbox unchecked. To split it into many chunks of that size, check "Repeat...". It is legal to have an IDAT chunk of length zero. Such a chunk can be safely deleted. Import and Export ----------------- Import allows you to read a chunk from an external datafile and insert it into the current image. The first four characters of the datafile must be the chunk identifier (e.g. "PLTE"), and the remainder of the file must be the data. The file must not contain length or CRC information. This function allows you to insert any chunk you want into a PNG file, including private unregistered chunks. However, you will often have to use a separate file editor to create the chunk. A sample chunk file, sample.chunk, has been included. If you make up a new chunk type, please make sure you understand the rules for capitalization of the identifier. In particular, the first two letters must not be capitalized. Export will create a file in the format described above, from an existing chunk in a PNG file. It works only on one chunk at a time. Editing Palettes ---------------- When you edit a PLTE chunk, or a bKGD or tRNS chunk in a paletted image, TweakPNG's palette editor will be opened. To edit a color, make sure neither the "Set bkgd" nor the "Edit alpha" button is pressed down, and click on a palette entry. Select a new color and press OK. To change the size of the palette, simply type a new value into the "Colors in palette" field. Note that if you decrease the palette size, you will end up with an illegal image if any of the colors you removed are used in the image. Alpha values control the "degree of transparency" of a palette color. A value of 0 is completely transparent (invisible), and a value of 255 is completely opaque. A short vertical line at the bottom of each palette entry indicates its approximate alpha value. (If there is no line, it means that no alpha value exists for this entry, and the color is therefore completely opaque.) The line is red unless the value is exactly 0 or 255, in which case it is a bluish color. To edit alpha values, press the "Edit alpha" button. The button stays down until you press it again. If the button is disabled, you need to Insert a tRNS chunk first. Now click a palette entry, and type the desired alpha value. To change the number of alpha values (the size of the tRNS chunk), type a new value into the "Alpha colors" field. There must not be more alpha values than there are colors in the palette, but there can be less. Alpha values of 255 at the end of the palette are a waste of space, since that is the default if they are missing. To decrease the number to zero, don't use the palette editor; just delete the tRNS chunk. One palette entry can be designated as the background color. It is indicated by a thick blue border. To change the background color, press the "Set bkgd" button, then click on the palette entry that you want to use as the background. If the button is disabled, you need to Insert a bKGD chunk first. If the desired background color is not in the palette, and there is room for another color in the palette, you can increase the palette size by one and use the new entry as the background. To remove the background color, delete the bKGD chunk. Some grayscale images also use the palette editor, with a simulated grayscale palette, to set the background or transparent color. It is not a real palette, so you can't edit the colors, but you can visually select the desired background or transparent color. File Signature -------------- Every file type in the PNG family begins with an 8-byte signature that identifies it. Choosing File|File Signature from the menu will let you choose which signature will be written when you save the file: either PNG, MNG, or JNG. This is for completeness only; you probably will never need this. Check Validity -------------- This will take a look at the overall structure of the current file and try to determine if it could be a valid PNG file. It mostly checks for incorrect chunk ordering and missing required chunks. It does not guarantee that your file is valid (not even close). It does not check that the data within chunks is valid. This function will automatically be run before you save a file, and if any problems are found, you will need to confirm the save. Preferences -> "Add TweakPNG to Explorer context menu" ------------------------------------------------------ When you right-click on a file in Windows Explorer, a menu is displayed with various options. If you enable this, a "TweakPNG" option will be added to all files with a ".png" or ".mng" or ".jng" extension, and selecting it will run TweakPNG. Note that double-clicking on a file will still run your default PNG viewer, if you have one, instead of TweakPNG. Tools -> Show Image Viewer -------------------------- The first item on the Tools menu is a special internal image viewer. The current image is shown in a separate window, which you can show or hide from this menu. [TO DO: Document the image viewer.] Tools menu and Configure Tools ------------------------------ You can define viewers using "Options|Configure Tools" and run them on the current file using the Tools menu. The "Name" is what gets displayed on the Tools menu. The "Program" is the executable file of the program to run. You may or may not need to include the full path. In "Parameters", put any command line parameters that should be used. Leave "Name" blank to prevent that item from showing up on the Tools menu. Leave "Program" blank to open the PNG file directly, letting Windows use your default PNG application. For example, to configure Netscape as a viewer, choose "Option|Configure Tools", pick an empty row and enter: Name: Netscape Program: netscape.exe (leave Parameters blank) Netscape should now show up on your Tools menu. You may in some cases need to include the full path of the Program. When you select an item on the Tools menu, current document will be written to a temporary disk file, and then the viewer will be run on that file. The same temporary file is reused every time. ==================== MNG support ==================== MNG is a PNG-like format that supports multi-image files and animation. In addition to PNG, TweakPNG unofficially includes a small amount of support for MNG files. However, it doesn't really have any knowledge of the contents of MNG-specific chunks, so it can't interpret them or let you edit them. You can only move them around or delete them. It may report that some chunks are illegal, when in fact they are legal. Editing palettes and corresponding background and transparency chunks is unreliable in MNG files, because TweakPNG does not know how to correctly associate PLTE and bKGD and tRNS chunks if there are more than one of each. The combine/split IDAT functions will also work on JDAT chunks, but the Combine all IDAT function is not appropriate for MNG files, because it only combines the first range of IDAT/JDAT chunks found in the file. ==================== Bugs ==================== - This documentation is not very good. - TweakPNG is in many ways incomplete. Some chunk types cannot be edited at all. - It is easy to create invalid PNG images with TweakPNG, for example by supplying illegal parameter values, or by mis-ordering chunks. - When editing text chunks in Windows 95/98, you will generally be limited to about 30K of text, due to the limits of the common controls provided by the operating system. This limitation should not exist under Windows NT-based systems. - Certain unusual sequences of actions may cause problems. For example, if the file you are editing has never had an IHDR chunk, trying to add new chunks of certain types (that depend on the settings in IHDR) may cause unpredictable results or crashes. - I think there are a few bugs in the "Check Validity" feature. ==================== Wish List ==================== Here are a few things I'd like to see in a future version of TweakPNG. One or two of them might even happen some day. - Include a binary/hex editor and allow adding and editing of any type of chunk, including unrecognized chunks. - Ability to edit iTXT, hIST, sPLT. - Ability to automatically remove unused colors from the palette. - Ability to interlace or un-interlace the image. - Ability to change compression level of the image, and to do some of the other compression optimization. ==================== Source Code ==================== The C++ source code to TweakPNG is included in this package. It is intended to be compatible with Microsoft Visual C++ version 5 and higher. It might also work in other C++ packages. See the file readme.txt in tweakpng-src.zip for more information. ==================== File list ==================== The following files should be included in this package: tweakpng.txt - this file COPYING.txt - copy of the GPL tweakpng.exe - the main program sample.png - sample PNG image sample.chunk - sample chunk for the Import function tweakpng-src-1-x-x.zip - the source code