png - PNG querying and manipulation of meta data
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
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.
- ::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.
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.
comment, image, png, timestamp
Copyright (c) 2004, Code: Aaron Faupell <afaupell@users.sourceforge.net>
Copyright (c) 2004, Doc: Andreas Kupries <andreas_kupries@users.sourceforge.net>