1png(n)                        Image manipulation                        png(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       png - PNG querying and manipulation of meta data
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require crc32
14
15       package require png  ?0.1.2?
16
17       ::png::validate file
18
19       ::png::isPNG file
20
21       ::png::imageInfo file
22
23       ::png::getTimestamp file
24
25       ::png::setTimestamp file time
26
27       ::png::getComments file
28
29       ::png::removeComments file
30
31       ::png::addComment file keyword text
32
33       ::png::addComment file keyword lang keyword2 text
34
35       ::png::image file
36
37       ::png::write file data
38
39______________________________________________________________________________
40

DESCRIPTION

42       This  package  provides  commands  to  query and modify PNG images. PNG
43       stands  for   Portable   Network   Graphics   and   is   specified   at
44       http://www.libpng.org/pub/png/spec/1.2.
45

COMMANDS

47       ::png::validate file
48              Returns a value indicating if file is a valid PNG file. The file
49              is checked for PNG signature, each chunks checksum is  verified,
50              existence  of  a  data chunk is verified, first chunk is checked
51              for header, last chunk is checked for ending. Things not checked
52              for  are:  validity  of  values  within a chunk, multiple header
53              chunks, noncontiguous data chunks, end chunk before actual  eof.
54              This procedure can take lots of time.
55
56              Possible return values:
57
58              OK     File is a valid PNG file.
59
60              SIG    no/broken PNG signature.
61
62              BADLEN corrupt chunk length.
63
64              EOF    premature end of file.
65
66              NOHDR  missing header chunk.
67
68              CKSUM  crc mismatch.
69
70              NODATA missing data chunk(s).
71
72              NOEND  missing end marker.
73
74       ::png::isPNG file
75              Returns  a boolean value indicating if the file file starts with
76              a PNG signature. This is a much faster and less intensive  check
77              than  ::png::validate  as  it  does not check if the PNG data is
78              valid.
79
80       ::png::imageInfo file
81              Returns a dictionary with keys width, height, depth, color, com‐
82              pression,  filter,  and interlace. The values are the associated
83              properties of the PNG image in file.  Throws an error if file is
84              not  a  PNG  image, or if the checksum of the header is invalid.
85              For information on interpreting  the  values  for  the  returned
86              properties    see    http://www.libpng.org/pub/png/spec/1.2/PNG-
87              Chunks.html.
88
89       ::png::getTimestamp file
90              Returns the epoch time if a timestamp chunk is found in the  PNG
91              image contained in the file, otherwise returns the empty string.
92              Does not attempt to verify the checksum of the timestamp  chunk.
93              Throws an error if the file is not a valid PNG image.
94
95       ::png::setTimestamp file time
96              Writes  a  new  timestamp  to the file, either replacing the old
97              timestamp, or adding one just before the data  chunks  if  there
98              was no previous timestamp. time is the new time in the gmt epoch
99              format.  Throws an error if file is not a valid PNG image.
100
101       ::png::getComments file
102              Currently supports only uncompressed comments. Does not  attempt
103              to  verify  the  checksums of the comment chunks. Returns a list
104              where each element is a comment. Each comment is itself a  list.
105              The  list  for  a plain text comment consists of 2 elements: the
106              human readable keyword, and the text data. A  unicode  (interna‐
107              tional)  comment consists of 4 elements: the human readable key‐
108              word, the language identifier, the translated keyword,  and  the
109              unicode  text  data.  Throws an error if file is not a valid PNG
110              image.
111
112       ::png::removeComments file
113              Removes all comments from the PNG image in file. Beware  -  This
114              uses  memory  equal to the file size minus comments, to hold the
115              intermediate result.  Throws an error if file is not a valid PNG
116              image.
117
118       ::png::addComment file keyword text
119              Adds  a plain text comment to the PNG image in file, just before
120              the first data chunk. Will throw an error if no  data  chunk  is
121              found. keyword has to be less than 80 characters long to conform
122              to the PNG specification.
123
124       ::png::addComment file keyword lang keyword2 text
125              Adds a unicode (international) comment to the PNG image in file,
126              just before the first data chunk. Will throw an error if no data
127              chunk is found. keyword has to be less than 80  characters  long
128              to  conform to the PNG specification. keyword2 is the translated
129              keyword, in the language specified by  the  language  identifier
130              lang.
131
132       ::png::image file
133              Given a PNG file returns the image in the list of scanlines for‐
134              mat used by Tk_GetColor.
135
136       ::png::write file data
137              Takes a list of scanlines in the Tk_GetColor format  and  writes
138              the represented image to file.
139

BUGS, IDEAS, FEEDBACK

141       This  document,  and the package it describes, will undoubtedly contain
142       bugs and other problems.  Please report such in the category png of the
143       Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please also
144       report any ideas for enhancements  you  may  have  for  either  package
145       and/or documentation.
146
147       When proposing code changes, please provide unified diffs, i.e the out‐
148       put of diff -u.
149
150       Note further that  attachments  are  strongly  preferred  over  inlined
151       patches.  Attachments  can  be  made  by  going to the Edit form of the
152       ticket immediately after its creation, and  then  using  the  left-most
153       button in the secondary navigation bar.
154

KEYWORDS

156       comment, image, png, timestamp
157

CATEGORY

159       File formats
160
162       Copyright (c) 2004, Code: Aaron Faupell <afaupell@users.sourceforge.net>
163       Copyright (c) 2004, Doc:  Andreas Kupries <andreas_kupries@users.sourceforge.net>
164
165
166
167
168tcllib                               0.1.2                              png(n)
Impressum