TweakPNG: A low-level PNG image file manipulation utility Version 1.4.6 - 2014-09-07 Copyright (c) 1999-2014 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 3 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 ==================== - Windows 2000 or newer (XP, Vista, 7, etc.), or a compatible Windows environment. With suitable compiler (probably Visual C++ 2003 or 2005), it should be possible to compile a version that works as far back as Windows 95. - Some knowledge of the PNG file format. ==================== Installation and Uninstallation ==================== To install: Create an empty directory, for example at C:\Program Files\TweakPNG, and unzip the contents of tweakpng-1.x.x.zip into it. Only the x86\tweakpng.exe or x64\tweakpng.exe file is really necessary. If you are using a 32-bit edition of Windows, you must use the x86\tweakpng.exe file. If you are using a 64-bit edition of Windows, you can use either file, though x64\tweakpng.exe is recommended. To run: Open the tweakpng.exe file. 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 ========================================================= Standard chunks: 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* yes yes yes pHYs yes yes yes tIME yes yes yes iCCP yes name only no sPLT name only no no sTER yes yes yes dSIG no no no Extensions: oFFs yes yes yes pCAL name only no no sCAL yes yes yes gIFg no no no gIFx no no no acTL yes yes yes fcTL yes yes yes fdAT seq# only seq# only no vpAg yes yes yes MNG/JNG: MHDR: yes no no JHDR: yes no no (*) iTXt chunks are only supported if TweakPNG is built as a Unicode application. ==================== 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. 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. "Import ICC Profile" creates an iCCP chunk from a standard ICC color profile (.icc) file. 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 and filters using "Options|Configure Tools", and run them on the current file using the Tools menu. A "viewer" is a program that views (or processes in some way) a PNG file without modifying it. A "filter" is a program that accepts a PNG file as input, and produces a different PNG file as output. The "Name" is what gets displayed on the Tools menu. Leave "Name" blank to prevent that item from showing up 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. Leave "Program" blank to open the PNG file directly, letting Windows use your default PNG application. The "..." button following this field can be used to browse for a program. In "Parameters", put any command line parameters that should be used. For a viewer, this can often be left blank. If the strings "%1" and "%2" appear in the parameters, this tool will be assumed to be a filter. %1 will be replaced with the input filename, and %2 will be replaced with the output filename. Otherwise, this tool will be assumed to be a viewer. If the string "%1" appears in the parameters, it will be replaced with the name of the file to view. Otherwise, the filename will be appended to the parameters. For example, to configure Firefox as a viewer, choose "Option|Configure Tools", pick an empty row and enter: Name: Firefox Program: firefox.exe (leave Parameters blank) Firefox 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 a viewer from 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. An example of a filter: Name: pngrewrite Program: C:\Program Files\pngrewrite\pngrewrite.exe Parameters: %1 %2 To run a filter, TweakPNG writes the current document to a temporary file, runs the filter, reads in the temporary file it created, then deletes both temporary files. Color correction ---------------- The TweakPNG image viewer assumes that your monitor uses the standard sRGB color space, and (if gamma correction is enabled) converts images to sRGB when displaying them. It supports gAMA and sRGB chunks, but not cHRM (chromaticities) or iCCP (color profile) chunks. It knows that sRGB is not exactly the same as gamma=1/2.2, and the difference can be noticeable, especially in dark regions of an image. ==================== 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. ==================== Source Code ==================== The C++ source code to TweakPNG is included in this package. It is intended to be compatible with Microsoft Visual C++ version 7(?) and higher. It might also work in other C++ packages. See the file tweakpng-src.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 x86\tweakpng.exe - the main program, 32-bit edition x64\tweakpng.exe - the main program, 64-bit (x64) edition sample.png - sample PNG image tweakpng-src-1-x-x.zip - the source code