png(3tcl)							Image manipulation							 png(3tcl)

__________________________________________________________________________________________________________________________________________________

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  proce-
	      dure 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  prop-
	      erties  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 read-
	      able 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 inter-
	      mediate 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  key-
	      word, 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(3tcl)