1png(n) Image manipulation png(n)
2______________________________________________________________________________
6
8 png - PNG querying and manipulation of meta data
9
11 package require Tcl 8.2
12 package require crc32
14 package require png ?0.3?
16 ::png::validate file
18 ::png::isPNG file
20 ::png::imageInfo file
22 ::png::getTimestamp file
24 ::png::setTimestamp file time
26 ::png::getComments file
28 ::png::removeComments file
30 ::png::addComment file keyword text
32 ::png::addComment file keyword lang keyword2 text
34 ::png::getPixelDimension file
36 ::png::image file
38 ::png::write file data
40______________________________________________________________________________
42
44 This package provides commands to query and modify PNG images. PNG
45 stands for Portable Network Graphics and is specified at
46 http://www.libpng.org/pub/png/spec/1.2.
47
49 ::png::validate file
50 Returns a value indicating if file is a valid PNG file. The file
51 is checked for PNG signature, each chunks checksum is verified,
52 existence of a data chunk is verified, first chunk is checked
53 for header, last chunk is checked for ending. Things not checked
54 for are: validity of values within a chunk, multiple header
55 chunks, noncontiguous data chunks, end chunk before actual eof.
56 This procedure can take lots of time.
57 Possible return values:
59 OK File is a valid PNG file.
61 SIG no/broken PNG signature.
63 BADLEN corrupt chunk length.
65 EOF premature end of file.
67 NOHDR missing header chunk.
69 CKSUM crc mismatch.
71 NODATA missing data chunk(s).
73 NOEND missing end marker.
75 ::png::isPNG file
77 Returns a boolean value indicating if the file file starts with
78 a PNG signature. This is a much faster and less intensive check
79 than ::png::validate as it does not check if the PNG data is
80 valid.
81 ::png::imageInfo file
83 Returns a dictionary with keys width, height, depth, color, com‐
84 pression, filter, and interlace. The values are the associated
85 properties of the PNG image in file. Throws an error if file is
86 not a PNG image, or if the checksum of the header is invalid.
87 For information on interpreting the values for the returned
88 properties see http://www.libpng.org/pub/png/spec/1.2/PNG-
89 Chunks.html.
90 ::png::getTimestamp file
92 Returns the epoch time if a timestamp chunk is found in the PNG
93 image contained in the file, otherwise returns the empty string.
94 Does not attempt to verify the checksum of the timestamp chunk.
95 Throws an error if the file is not a valid PNG image.
96 ::png::setTimestamp file time
98 Writes a new timestamp to the file, either replacing the old
99 timestamp, or adding one just before the data chunks if there
100 was no previous timestamp. time is the new time in the gmt epoch
101 format. Throws an error if file is not a valid PNG image.
102 ::png::getComments file
104 Currently supports only uncompressed comments. Does not attempt
105 to verify the checksums of the comment chunks. Returns a list
106 where each element is a comment. Each comment is itself a list.
107 The list for a plain text comment consists of 2 elements: the
108 human readable keyword, and the text data. A unicode (interna‐
109 tional) comment consists of 4 elements: the human readable key‐
110 word, the language identifier, the translated keyword, and the
111 unicode text data. Throws an error if file is not a valid PNG
112 image.
113 ::png::removeComments file
115 Removes all comments from the PNG image in file. Beware - This
116 uses memory equal to the file size minus comments, to hold the
117 intermediate result. Throws an error if file is not a valid PNG
118 image.
119 ::png::addComment file keyword text
121 Adds a plain text comment to the PNG image in file, just before
122 the first data chunk. Will throw an error if no data chunk is
123 found. keyword has to be less than 80 characters long to conform
124 to the PNG specification.
125 ::png::addComment file keyword lang keyword2 text
127 Adds a unicode (international) comment to the PNG image in file,
128 just before the first data chunk. Will throw an error if no data
129 chunk is found. keyword has to be less than 80 characters long
130 to conform to the PNG specification. keyword2 is the translated
131 keyword, in the language specified by the language identifier
132 lang.
133 ::png::getPixelDimension file
135 Returns a dictionary with keys ppux, ppuy and unit if the infor‐
136 mation is present. Otherwise, it returns the empty string.
137 The values of ppux and ppuy return the pixel per unit value in X
139 or Y direction.
140 The allowed values for key unit are meter and unknown. In the
142 case of meter, the dpi value can be calculated by multiplying
143 with the conversion factor 0.0254.
144 ::png::image file
146 Given a PNG file returns the image in the list of scanlines for‐
147 mat used by Tk_GetColor.
148 ::png::write file data
150 Takes a list of scanlines in the Tk_GetColor format and writes
151 the represented image to file.
152
154 This document, and the package it describes, will undoubtedly contain
155 bugs and other problems. Please report such in the category png of the
156 Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also
157 report any ideas for enhancements you may have for either package
158 and/or documentation.
159 When proposing code changes, please provide unified diffs, i.e the out‐
161 put of diff -u.
162 Note further that attachments are strongly preferred over inlined
164 patches. Attachments can be made by going to the Edit form of the
165 ticket immediately after its creation, and then using the left-most
166 button in the secondary navigation bar.
167
169 comment, image, png, timestamp
170
172 File formats
173
175 Copyright (c) 2004, Code: Aaron Faupell <afaupell@users.sourceforge.net>
176 Copyright (c) 2004, Doc: Andreas Kupries <andreas_kupries@users.sourceforge.net>
177tcllib 0.3 png(n)