Ubuntu Manpage: png - PNG querying and manipulation of meta data

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

COPYRIGHT

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