img-ppm(n)

🎀 NAME 🎀

okay so bestie, this page is all about img-ppm — aka the Portable pixmap format (ppm) 💖 it's the thing that makes Tk's photo images understand PPM and PGM files, and it's genuinely so useful, no cap.

---

✨ SYNOPSIS ✨

package require img::ppm ?2.1?

---

🌸 DESCRIPTION 🌸

package require img::ppm

So here's the vibe: like every single package in Img, this one does not hand you a bunch of shiny new commands. Nope. What it does instead is extend the Tk command image that you already have, so that it can handle files holding raster images in the Portable pixmap format (ppm). More specifically, img::ppm extends Tk's photo [https://www.tcl.tk/man/tcl9.0/TkCmd/photo.html] image type. 🫶

The name of the new format handler is ppm. And this handler? It brings additional configuration options. Peep the Options section below for the full tea. ☕

All of that means that in a call like image create photo ?name? ?options?:

1. Image data in ppm format (options -data and -file) is detected automatically. ✨
2. The format name ppm is recognized by the option -format.

And on top of that, the value of option -format is treated as a list, and it may contain any of the special options listed in the Options section. So you can stack them in there, bestie. 💅

The package img::ppm is a sub-package of Img. You can load it as a part of the complete Img support, via package require Img, or you can just grab it on its own, via package require img::ppm. Either way, she's ready. 🦋

---

🌈 SUPPORTED TYPES 🌈

This handler supports the PPM (Truecolor) and PGM (Grayscale) image formats. And there are two types of PPM/PGM files: Binary and ASCII. The values stored in PPM/PGM files can be unsigned 8-bit or unsigned 16-bit values.

• Grayscale (PGM): 8-bit and 16-bit, 1 channel per pixel.
• Truecolor (PPM): 8-bit and 16-bit, 3 channels per pixel.

Here's the whole read/write situation, and yes it's giving very much a chart 📊 — look at her:

Image             |     Read      |     Write     |
type              | -file | -data | -file | -data |
---------------------------------------------------
PGM  8-bit ASCII  | Yes   | Yes   | No    | No    |
PGM  8-bit BINARY | Yes   | Yes   | No    | No    |
PGM 16-bit ASCII  | Yes   | Yes   | No    | No    |
PGM 16-bit BINARY | Yes   | Yes   | No    | No    |
PPM  8-bit ASCII  | Yes   | Yes   | Yes   | Yes   |
PPM  8-bit BINARY | Yes   | Yes   | Yes   | Yes   |
PPM 16-bit ASCII  | Yes   | Yes   | No    | No    |
PPM 16-bit BINARY | Yes   | Yes   | No    | No    |

💀 not the PGM's being read-only on the write side. she reads, she does not write. iconic behaviour honestly.

---

💅 OPTIONS 💅

The handler provides the following options:

• -verbose bool — this one works for reading AND writing. Available since version 1.4.0. If you set it to true, extra info about the image you read or wrote gets printed to stdout. Default is false.
• -scanorder string — reading only, bestie. Available since version 1.4.0. This specifies the scanline order of the input image. Possible values: TopDown or BottomUp. Default is TopDown.
• -min double — reading only. Available since version 1.4.0. Specifies the minimum pixel value to be used for mapping 16-bit input data to 8-bit image values. If it's not specified, or if it's negative, then it's the minimum value found in the image data. 🫶
• -max float — reading only. Available since version 1.4.0. Specifies the maximum pixel value to be used for mapping 16-bit input data to 8-bit image values. If it's not specified, or if it's negative, then it's the maximum value found in the image data. 💖
• -gamma double — reading only. Available since version 1.4.0. Specifies a gamma correction to be applied when mapping 16-bit input data to 8-bit image values. Default is 1.0.
• -ascii bool — writing only, so don't come at her trying to use it for reads. Available since version 1.4.0. If set to true, the file is written in PPM 8-bit ASCII format (P3). Default is false, i.e. write in PPM 8-bit binary format (P6). 🎀

---

🔥 SEE ALSO 🔥

img, img-bmp, img-dted, img-flir, img-gif, img-ico, img-jpeg, img-pcx, img-pixmap, img-png, img-ppm, img-ps, img-raw, img-sgi, img-sun, img-tga, img-tiff, img-window, img-xbm, img-xpm

(go read them all, the whole friend group is serving 🫶)

---

👑 COPYRIGHT 👑

Copyright (c) 1995-2025 Jan Nijtmans <nijtmans@users.sourceforge.net> Copyright (c) 2002-2025 Andreas Kupries <andreas_kupries@users.sourceforge.net> Copyright (c) 2003-2025 Paul Obermeier <obermeier@users.sourceforge.net>

---

and that's the whole page, bestie 💖 this was img-ppm, version 2.1 — she's been serving since way back (the copyright line goes all the way from 1995 through 2025, we love a legacy icon) and she's still out here making your PPM's work. periodt. 💅✨🎀🦋