png(n)

🦋 png(n) — the manual, but make it cute 🦋

okay bestie, gather round, because this is the png(n) page from the Image manipulation department and it is lowkey a whole personality. we're talking PNG querying and meta-data manipulation, and yes, the vibes are immaculate. 💅

---

✨ NAME ✨

png — PNG querying and manipulation of meta data

like. it queries. it manipulates. it does meta data. it's giving main character. 👑

---

🌸 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

that's the whole lineup bestie, every single one of them, no skips. 🫶

---

💖 DESCRIPTION 💖

so this package hands you a whole toolbox of commands to query and modify PNG images. PNG stands for Portable Network Graphics (not "pretty nice graphics", though, honestly? accurate) and the spec lives at http://www.libpng.org/pub/png/spec/1.2. go read it if you want the deep lore. 📖✨

---

🎀 COMMANDS 🎀

💫 ::png::validate file

returns a value telling you whether file is a valid PNG file. the checks it does:

• PNG signature ✅
• every chunk's checksum verified ✅
• existence of a data chunk verified ✅
• first chunk checked for header ✅
• last chunk checked for ending ✅

things it does NOT check (bestie, read this part, it matters):

• validity of values within a chunk
• multiple header chunks
• noncontiguous data chunks
• end chunk before actual eof

⚠️ heads up: this procedure can take lots of time. like, a lot. do not run it in a loop and then act surprised, iykyk. 😭

possible return values, in all their glory:

• OK — file is a valid PNG file. slay.
• 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 whether file starts with a PNG signature. that's it, that's the whole job. it is much faster and less intensive than ::png::validate because it does not check whether the PNG data is actually valid. it's the vibe check, not the full background check. 🕵️♀️✨

---

💫 ::png::imageInfo file

returns a dictionary with the 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 info on how to interpret the values of the returned properties, go look at http://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html. homework, but make it fashion. 📚💅

---

💫 ::png::getTimestamp file

returns the epoch time if a timestamp chunk is found in the PNG image contained in file, otherwise returns the empty string. it 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 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 (we're not doing the compressed ones yet, bestie, be patient 🥺). 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 breakdown:

• a plain text comment = 2 elements: the human readable keyword, and the text data.
• a unicode (international) comment = 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. plan accordingly, bestie. 😭

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. rules are rules. 🎀

---

💫 ::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. multilingual queen behavior. 🌈👑

---

💫 ::png::getPixelDimension file

returns a dictionary with the keys ppux, ppuy and unit if the information 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 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. 📐✨

---

💫 ::png::image file

given a PNG file, returns the image in the list of scanlines format used by Tk_GetColor. iconic. 🔥

---

💫 ::png::write file data

takes a list of scanlines in the Tk_GetColor format and writes the represented image to file. the reverse queen. 💅

---

🙈 BUGS, IDEAS, FEEDBACK 🙈

this document, and the package it describes, will undoubtedly contain bugs and other problems. honestly? relatable. 😭

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 the package and/or the documentation. we want the thoughts. all of them. 🫶

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. yes, that specific button. the left-most one. you got this. 🎯

---

🌟 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>

---

and that's the whole page bestie, we ate and left no crumbs. 🍓✨ this one's from tcllib, version 0.4.1, page png(n) — so if you cite it, cite it right. mwah. 💖💅🦋