tweakpng.txt

TweakPNG:  A low-level PNG image file manipulation utility
Version 1.4.6 - 2014-09-07
Copyright (c) 1999-2014 Jason Summers  <jason1@pobox.com>

==================== 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 
<http://entropymine.com/jason/tweakpng/>.


==================== 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, 
<http://www.libpng.org/pub/png/>. 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