png(3tcl)

📦
version 2.0 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 png — the manual page 💖

okay bestie, welcome to png(3tcl), a page from the Image manipulation section of the tcllib docs. it's giving PNG querying and manipulation of meta data, and honestly? iconic. let's get into it 🦋

✨ NAME ✨

png — PNG querying and manipulation of meta data

🎀 SYNOPSIS 🎀

package require Tcl 8.5 9

package require crc32

package require png ?0.4.1?

::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 🌸

so this package hands you a whole lil toolkit of commands to query and modify PNG images. PNG stands for Portable Network Graphics, and the spec lives at http://www.libpng.org/pub/png/spec/1.2. go read it if you're feeling academic 💅

👑 COMMANDS 👑

💫 ::png::validate file

returns a value telling you whether file is a valid PNG file. what it actually checks: the PNG signature, the checksum of each chunk, that a data chunk exists, that the first chunk is a header, and that the last chunk is the ending. what it does not check: validity of values inside a chunk, multiple header chunks, noncontiguous data chunks, and an end chunk that shows up before the actual eof. also heads up — this procedure can take lots of time 😭

possible return values, bestie:

  • 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 telling you if file starts with a PNG signature. this is much faster and way less intensive than ::png::validate, because it does not check whether the PNG data is actually valid. quick lil vibe check, basically 🫶

💫 ::png::imageInfo file

returns a dictionary with the keys width, height, depth, color, compression, filter, and interlace — the values being the associated properties of the PNG image in file. it throws an error if file isn't a PNG image, or if the header's checksum is invalid. for info on how to interpret the values of those 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 inside file, otherwise returns the empty string. it does not attempt to verify the checksum of the timestamp chunk. throws an error if file is not a valid PNG image.

💫 ::png::setTimestamp file time

writes a new timestamp to file — either replacing the old timestamp, or adding one just before the data chunks if there wasn't a 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. it does not attempt to verify the checksums of the comment chunks. returns a list where each element is a comment, and each comment is itself a list:

  • a plain text comment = a list of 2 elements: the human readable keyword, and the text data.
  • a unicode (international) comment = a list 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 bestie — this uses memory equal to the file size minus comments, just 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. no cap.

💫 ::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 the keys ppux, ppuy and unit if that info is present. otherwise, it returns the empty string.

the values of ppux and ppuy give the pixel per unit value in the X or Y direction.

the allowed values for the 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. math girlies rise 💅

💫 ::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. pls report such in the category png of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. also pls report any ideas for enhancements you may have for either the package and/or the documentation 🫶

when proposing code changes, please provide unified diffs, i.e. the output 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. iykyk ✨

⭐ KEYWORDS ⭐

comment, image, png, timestamp

🧚 CATEGORY 🧚

File formats

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

and that's the whole page, bestie 🎀 this one's from tcllib, version 0.4.1, and it's the png(3tcl) page — slay, ate, no crumbs. periodt 💅✨

📦 where this page comes from