PNG Special-Purpose Public Chunks
*********************************

Revision date: 5 May, 1995 

The latest versions of this document and related information can always
be found at the PNG FTP archive site, 
ftp.uu.net:/graphics/png/. The maintainers of the PNG
specification can be contacted by e-mail at 
png-info@uunet.uu.net. 

At present, this document is available on the World Wide Web from 
http://sunsite.unc.edu/boutell/pngextensions.html,
but this location may not be as permanent as the ones above. 

Introduction
============

This document describes public chunk types for use in PNG (Portable
Network Graphics) images. The basic PNG specification is available
from the PNG FTP archive mentioned above, or via WWW from 
http://sunsite.unc.edu/boutell/png.html. 

Chunks described here are expected to be somewhat less widely
supported than those defined in the basic specification. However,
application authors are encouraged to use these chunk types whenever
appropriate for their applications. Additional chunk types may be
proposed for inclusion in this list by contacting the PNG specification
maintainers at png-info@uunet.uu.net. 

Summary of Special-Purpose Chunks
=================================

This table summarizes some properties of the chunks described in this
document. 

Name  Multiple  Ordering constraints
        OK?

oFFs    No      Before IDAT
sCAL    No      Before IDAT
gIFg    Yes     None
gIFt    Yes     None
gIFx    Yes     None
fRAc    Yes     None

Chunk Descriptions
==================

oFFs Image Offset 
   The oFFs chunk gives the position on a printed page at which
   the image should be output when printed alone. It can also be
   used to define the image's location with respect to a larger screen
   or other application-specific coordinate system. 

   The chunk's contents are: 

   4 bytes: image position on the page, X axis (signed integer)
   4 bytes: image position on the page, Y axis (signed integer)
   1 byte: unit specifier

   Both position values are signed. The following values are legal
   for the unit specifier: 

   0: unit is the pixel (true dimensions unspecified)
   1: unit is the micrometer (also called the micron; 1/1,000,000th of a meter)

   Conversion note: one inch is equal to exactly 25,400
   micrometers. 

   The X position is measured rightwards from the left side of the
   page to the left side of the image; the Y position is measured
   downwards from the top side of the page to the top of the image.
   Note that negative values are permitted to denote displacement
   in the opposite directions; of course, the result of placement
   outside the page boundaries is application-dependent. 

   If present, this chunk must precede the first IDAT chunk. 

sCAL Physical Scale of Image Subject 
   While the pHYs chunk is used to record the physical size of the
   image itself as it was scanned or as it should be printed, certain
   images (such as maps, photomicrographs, astronomical surveys,
   floor plans, and others) may benefit from knowing the actual
   physical dimensions of the image's subject for remote
   measurement and other purposes. The sCAL chunk serves this
   need. The sCAL chunk's contents are 

   Unit specifier: 1 byte
   Pixel width:    n bytes (ASCII string)
   Null separator: 1 byte
   Pixel height:   n bytes (ASCII string)

   Valid values for the unit specifier field are: 

   1   Unit is the meter
   2   Unit is the radian

   Following the unit specifier are two ASCII strings. The first
   string defines the physical width represented by one image pixel;
   the second string defines the physical height represented by one
   pixel. The two strings are separated by a zero byte (null
   character). As in the tEXt chunk, there is no trailing zero for
   the final string. 

   The ASCII strings represent floating point constants, and consist
   of an optionally signed integer part, a fractional part beginning
   with a decimal point, and an exponent part beginning with an
   'E' or 'e' and optional sign. The integer, fraction, and exponent
   parts each contain a series of digits (ASCII '0' to '9'). Either the
   integer part or the fraction part (but not both) may be omitted.
   A decimal point is allowed, but not required, if there is no
   fraction part. The exponent part may be omitted. No spaces or
   any other character besides those specified may appear. 

   Note in particular that this implies C-language F and L suffixes
   are not allowed, the string "." is not allowed as a shorthand for 0
   as in some other programming languages, and no commas or
   underscores are allowed. This format should be easily readable by
   all programming languages. 

   In the sCAL chunk, both values are required to be greater than
   zero. However, the floating-point format described here may be
   useful in other chunks as well, and is therefore defined to allow a
   sign. 

   If present, this chunk must precede the first IDAT chunk. 

GIF Conversion Chunk Descriptions
=================================

The chunks described in this section are intended specifically for
preserving information found in GIF extension blocks when converting
a GIF file to a PNG file. GIF-to-PNG converters should simply
duplicate these blocks with the reformatting specified below.
Applications that formerly made use of this information when reading a
GIF file may continue to use it when reading PNG files. Since many
applications ignored GIF extension blocks, it is expected that many
applications will ignore these PNG chunks. 

When converting single-image GIFs to PNG, these chunks should be
placed in the same relative position within the PNG file as the extension
block has within the GIF file. Thus converters can translate GIF
extensions as they are encountered. Conversion of multiple-image GIFs
is a more complex problem which will be addressed in a future
document. 

In a GIF file, an extension block is organized as a series of sub-blocks,
where each sub-block is preceded by a length byte. PNG does not use
sub-blocks, so the GIF data must be de-blocked by removal of the
sub-block length bytes. In addition, the converter is expected to convert
certain fields from GIF byte order (LSB first) to network byte order
(MSB first), and to expand image-size-related fields from two bytes to
four. Fields requiring format changes are marked in the descriptions
below. 

For brevity, the following chunk descriptions simply define the layout of
the chunk fields and indicate the reformatting required. The semantics
of the field contents remain the same as in GIF. Readers are referred to
the GIF89a specification for details. It is available on Compuserve from
GRAPHSUPPORT library 16, file GIF89A.DOC, and is also widely
available on Internet. 

gIFg GIF Graphic Control Extension 
   The gIFg chunk is provided for backwards compatibility with
   the GIF89a Graphic Control Extension. The contents of this
   chunk are: 

   Disposal Method:     1 byte
   User Input:          1 byte
   Delay Time:          2 bytes (byte order converted from GIF)

   Disposal Method indicates the way in which the graphic is to be
   treated after being displayed. User Input indicates whether user
   input is required before continuing. Delay Time specifies the
   number of hundredths (1/100) of a second to delay before
   continuing with the processing of the data stream. Note that this
   field is to be byte-order-converted. 

   The Transparent Color Flag and Transparency Index fields
   found in the GIF89a Graphic Control Extension are omitted
   from gIFg. These fields should be converted using the
   transparency features of basic PNG. 

gIFt GIF Plain Text Extension 
   The gIFt chunk is provided for backwards compatibility with
   the GIF89a Plain Text Extension. The contents of this chunk
   are: 

   Text Grid Left Position:  4 bytes (byte order and size converted from GIF)
   Text Grid Top Position:   4 bytes (byte order and size converted from GIF)
   Text Grid Width:          4 bytes (byte order and size converted from GIF)
   Text Grid Height:         4 bytes (byte order and size converted from GIF)
   Character Cell Width:     1 byte
   Character Cell Height:    1 byte
   Text Foreground Color:    3 bytes (R,G,B value)
   Text Background Color:    3 bytes (R,G,B value)
   Plain Text Data:          n bytes

   Text Grid Left Position, Top Position, Width, and Height specify
   the text area position and size in pixels. The converter must
   reformat these fields from 2 bytes LSB-first to 4 bytes
   MSB-first. Note that GIF defines the position to be relative to
   the upper left corner of the logical screen. If an oFFs chunk is
   also present, a decoder should assume that the oFFs chunk
   defines the offset of the image relative to the GIF logical screen;
   hence subtracting the oFFs values from the Text Grid Left and
   Top Positions gives the text area position relative to the main
   PNG image. 

   Character Cell Width and Height give the dimensions of each
   character in pixels. 

   Text Foreground and Background Color give the colors to be
   used to render text foreground and background. Note that the
   GIF-to-PNG converter must replace the pixel index values
   found in the GIF Plain Text Extension block with the
   corresponding palette entry. 

   The remainder of the chunk is the text to be displayed. Note that
   this data is not in GIF sub-block format, but is a continuous byte
   stream. 

gIFx GIF Application Extension 
   The gIFx chunk is provided for backwards compatibility with
   the GIF89a Application Extension. The Application Extension
   contains application-specific information. The contents of this
   chunk are: 

   Application Identifier:     8 bytes
   Authentication Code:        3 bytes
   Application Data:           n bytes

   The Application Identifier is a sequence of eight printable
   ASCII characters used to identify the application creating the
   Application Extension. The Authentication Code is three
   additional bytes which the application may use to further
   validate the Application Extension. The remainder of the chunk
   is application-specific data whose content is not defined by the
   GIF specification. 

   Note that GIF-to-PNG converters should not attempt to
   perform byte reordering on the contents of the Application
   Extension. The data is simply transcribed without any processing
   except for de-blocking GIF sub-blocks. 

   Applications that formerly used GIF Application Extensions
   may define special-purpose PNG chunks to replace their
   application extensions. If a GIF-to-PNG converter recognizes
   the Application Identifier and is aware of a corresponding PNG
   chunk, it may choose to convert the Application Extension into
   that PNG chunk type rather than using gIFx. 

Chunks Not Described Here
=========================

The definitions of some public chunks are being maintained by groups
other than the core PNG group. In general, these are chunks that are
useful to more than one application (and thus are not private chunks),
but are considered too specialized to list in the core PNG
documentation. 

fRAc Fractal Image Parameters 
   The fRAc chunk describes the parameters used to generate a
   fractal image. Specifications for the contents of fRAc chunks
   are maintained by Tim Wegner, 
   71320.675@compuserve.com. 

Text Chunk Keywords
===================

It is expected that special-purpose keywords for tEXt and zTXt
chunks will be registered and will appear in this document. However, no
such keywords have yet been assigned. 

Registering Proprietary Chunks
==============================

If you want others outside your organization to understand a chunk type
that you invent, contact the maintainers of the PNG specification (at 
png-info@uunet.uu.net) to submit a proposed chunk name and
definition for addition to this document. 

New public chunks will be only be registered if they are of use to others
and do not violate the design philosophy of PNG. Chunk registration is
not automatic, although it is the intent of the authors that it be
straightforward when a new chunk of potentially wide application is
needed. Note that the creation of new critical chunk types is discouraged
unless absolutely necessary. 

If you do not desire that others outside your organization understand the
chunk type, you may use a private chunk name by specifying a lowercase
letter for the second character. Such chunk types need not be registered. 

If an ancillary chunk is to contain textual information that might be of
interest to a human user, it is recommended that a special chunk type 
not be used. Instead use a tEXt chunk and define a suitable keyword. In
this way, the information will be available to users not using your
software. 

If of general usefulness, new keywords for tEXt chunks may be
registered with the maintainers of the PNG specification. Keywords
should be chosen to be reasonably self-explanatory, since the idea is to
let other users figure out what the chunk contains. 

End of PNG Special-Purpose Chunk Listing 
