PNGer: A low-level PNG image file manipulation utility Version 0.1 - 04 April 2008 Copyright (c) 2008 Peter Gordon PNGer contains portions of code from TweakPNG 1.2.1 Copyright (c) 1999-2004 Jason Summers Also, this document is based on the documentation for TweakPNG, and only changed where PNGers functionality differs from that of TweakPNG. ==================== 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 PNGer, visit the PNGer home page at http://www.petergordon.org.uk/pnger/ ==================== Requirements ==================== - A computer running AmigaOS4 - 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 unarchive the contents of pnger.lha into it. To run: Double click the "pnger" icon, or run pnger from the CLI. To uninstall: Delete the directory you created and its contents. ==================== Introduction ==================== PNGer 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 (although it has an option to view the current state of the loaded PNG file in multiview). 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 PNGer may, however, make it easier to become familiar with the PNG format. Here are a few of the possible uses of PNGer: - 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 PNGer 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 no no no pHYs yes yes yes tIME yes yes yes iCCP no no no sPLT no no no ==================== Features ==================== Most of the non-obvious features of PNGer are described below. General ------- PNGer 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 To edit a chunk, double click on it, or select it and go to "Edit Chunk" in the Edit menu. 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. 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. 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. Unlike in most programs, Paste does not delete the currently selected chunk(s). Pasted chunks are inserted just after 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). PNGer 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. 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, but unlike TweakPNG, PNGer doesn't let you create them (they serve no purpose). 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, PNGer's palette editor will be opened. 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. 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. It doesn't matter if the PNG file already has, or does not have a tRNS chunk; when you click OK in the palette window, one will be created if required, or if you removed all alpha values, the existing one will be removed. One palette entry can be designated as the background color. To change the background color, make sure "Specify background colour?" is ticked, and press the "Pick" button, then click on the palette entry that you want to use as the background. 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. It doesn't matter if the PNG file already has, or does not have a bKGD chunk; when you click OK in the palette window, one will be created if required, or if unticked "Specify background colour?", the existing one will be removed. 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. Tools -> Show in multiview -------------------------- This saves the current state of the PNG to a temporary file and loads it up in multiview. It does not affect the file on disk. ==================== MNG support ==================== MNG is a PNG-like format that supports multi-image files and animation. In addition to PNG, PNGer 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 PNGer 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. - PNGer is in many ways incomplete. Some chunk types cannot be edited at all. - It is easy to create invalid PNG images with PNGer, for example by supplying illegal parameter values, or by mis-ordering chunks. - 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. - 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 PNGer. 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 PNGer is included in this package. It is intended to be compatible with GCC and the OS4 SDK.