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.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, com-
pression, 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 (interna-
tional) comment consists of 4 elements: the human readable key-
word, 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 infor-
mation 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 for-
mat 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 out-
put 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>
tcllib 0.3 png(3tcl)