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

       ::png::image file

       ::png::write file data

________________________________________________________________________________________________________________

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.

       ::png::image file
              Given a PNG file returns the image in the list of scanlines format used by Tk_GetColor.

       ::png::write file data
              Takes a list of scanlines in the Tk_GetColor format and writes the represented image to file.

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  Trackers  [http://core.tcl.tk/tcllib/reportlist].   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>