png(n)                        Image manipulation                        png(n)



______________________________________________________________________________

NAME
       png - PNG querying and manipulation of meta data

SYNOPSIS
       package require Tcl  8.2

       package require crc32

       package require png  ?0.1.2?

       ::png::validate file

       ::png::isPNG file

       ::png::imageInfo file

       ::png::getTimestamp file

       ::png::setTimestamp file time

       ::png::getComments file

       ::png::removeComments file

       ::png::addComment file keyword text

       ::png::addComment file keyword lang keyword2 text

_________________________________________________________________

DESCRIPTION
       This package provides commands to query and modify PNG images. PNG
       stands for Portable Network Graphics and is specified at
       http://www.libpng.org/pub/png/spec/1.2.

COMMANDS
       ::png::validate file
              Returns a value indicating if file is a valid PNG file. The file
              is checked for PNG signature, each chunks checksum is verified,
              existence of a data chunk is verified, first chunk is checked
              for header, last chunk is checked for ending. Things not checked
              for are: validity of values within a chunk, multiple header
              chunks, noncontiguous data chunks, end chunk before actual eof.
              This procedure can take lots of time.

              Possible return values:

              OK     File is a valid PNG file.

              SIG    no/broken PNG signature.

              BADLEN corrupt chunk length.

              EOF    premature end of file.

              NOHDR  missing header chunk.

              CKSUM  crc mismatch.

              NODATA missing data chunk(s).

              NOEND  missing end marker.

       ::png::isPNG file
              Returns a boolean value indicating if the file file starts with
              a PNG signature. This is a much faster and less intensive check
              than ::png::validate as it does not check if the PNG data is
              valid.

       ::png::imageInfo file
              Returns a dictionary with keys width, height, depth, color,
              compression, filter, and interlace. The values are the
              associated properties of the PNG image in file.  Throws an error
              if file is not a PNG image, or if the checksum of the header is
              invalid. For information on interpreting the values for the
              returned properties see
              http://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html.

       ::png::getTimestamp file
              Returns the epoch time if a timestamp chunk is found in the PNG
              image contained in the file, otherwise returns the empty string.
              Does not attempt to verify the checksum of the timestamp chunk.
              Throws an error if the file is not a valid PNG image.

       ::png::setTimestamp file time
              Writes a new timestamp to the file, either replacing the old
              timestamp, or adding one just before the data chunks if there
              was no previous timestamp. time is the new time in the gmt epoch
              format.  Throws an error if file is not a valid PNG image.

       ::png::getComments file
              Currently supports only uncompressed comments. Does not attempt
              to verify the checksums of the comment chunks. Returns a list
              where each element is a comment. Each comment is itself a list.
              The list for a plain text comment consists of 2 elements: the
              human readable keyword, and the text data. A unicode
              (international) comment consists of 4 elements: the human
              readable keyword, the language identifier, the translated
              keyword, and the unicode text data.  Throws an error if file is
              not a valid PNG image.

       ::png::removeComments file
              Removes all comments from the PNG image in file. Beware - This
              uses memory equal to the file size minus comments, to hold the
              intermediate result.  Throws an error if file is not a valid PNG
              image.

       ::png::addComment file keyword text
              Adds a plain text comment to the PNG image in file, just before
              the first data chunk. Will throw an error if no data chunk is
              found. keyword has to be less than 80 characters long to conform
              to the PNG specification.

       ::png::addComment file keyword lang keyword2 text
              Adds a unicode (international) comment to the PNG image in file,
              just before the first data chunk. Will throw an error if no data
              chunk is found. keyword has to be less than 80 characters long
              to conform to the PNG specification. keyword2 is the translated
              keyword, in the language specified by the language identifier
              lang.

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will undoubtedly contain
       bugs and other problems.  Please report such in the category png of the
       Tcllib SF Trackers [http://sourceforge.net/tracker/?group_id=12883].
       Please also report any ideas for enhancements you may have for either
       package and/or documentation.

KEYWORDS
       comment, image, png, timestamp

CATEGORY
       File formats

COPYRIGHT
       Copyright (c) 2004, Code: Aaron Faupell <afaupell@users.sourceforge.net>
       Copyright (c) 2004, Doc:  Andreas Kupries <andreas_kupries@users.sourceforge.net>




png                                  0.1.2                              png(n)
