Provided by: tcllib_1.21+dfsg-1_all bug

NAME

       png - PNG querying and manipulation of meta data

SYNOPSIS

       package require Tcl  8.2

       package require crc32

       package require png  ?0.3?

       ::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::getPixelDimension file

       ::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::getPixelDimension file
              Returns  a  dictionary with keys ppux, ppuy and unit if the information is present.
              Otherwise, it returns the empty string.

              The values of ppux and ppuy return the pixel per unit value in X or Y direction.

              The allowed values for key unit are meter and unknown. In the case  of  meter,  the
              dpi value can be calculated by multiplying with the conversion factor 0.0254.

       ::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.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be  made  by going to the Edit form of the ticket immediately after its creation, and then
       using the left-most button in the secondary navigation bar.

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>