Pnm(3pm)

🌸 NAME 🌸

PDL::IO::Pnm — it's giving pnm format I/O for PDL, bestie 💅 (that's the Pnm(3pm) page you just opened, in case the vibe check was unclear 🦋)

---

✨ SYNOPSIS ✨

okay so this is literally all you need to get started:

use PDL::IO::Pnm;
$im = wpnm $pdl, $file, $format[, $raw];
rpnm $stack->slice(':,:,:,(0)'),"PDL.ppm";

like. two whole lines. obsessed 🫶

---

🌈 DESCRIPTION 🌈

pnm I/O for PDL. that's it, that's the whole description, no cap 💀

---

👑 FUNCTIONS 👑

💜 pnminraw

Signature: (type(); byte+ [o] im(m,n); byte [t] buf(llen); int ms => m; int ns => n;
                      int isbin; PerlIO *fp)

Read in a raw pnm file. 📖

so like, read a raw pnm file. the type argument is only there to figure out the type of the operation when creating im, or to trigger the appropriate type conversion (maybe we want a byte+ here so that im follows strictly the type of type?? honestly that's the question the original is asking too 🫠).

⚠️ pnminraw does not process bad values. it will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays. not me being dramatic, that's just what it does 😭

🧚 pnminascii

Signature: (type(); byte+ [o] im(m,n); int ms => m; int ns => n;
                      int format; PerlIO *fp)

Read in an ascii pnm file. 📄✨

⚠️ pnminascii does not process bad values either. same deal: it sets the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.

🎀 pnmout

Signature: (a(m); int israw; int isbin; PerlIO *fp)

Write a line of pnm data. ✍️

this function is implemented this way so that broadcasting works naturally — the way that broadcasting just works is so iconic, fr fr 🌟

⚠️ pnmout does not process bad values. yep, and it sets the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays. the trio said periodt 💅

🦋 rpnm

Read a pnm (portable bitmap/pixmap, pbm/ppm) file into an ndarray. 🖼️

Usage:  $im = rpnm $file;

Reads a file (or open file-handle) in pnm format (ascii or raw) into a pdl (magic numbers P1-P6). based on the input format it returns pdls with arrays of size (width,height) if binary or grey value data (pbm and pgm), or (3,width,height) if rgb data (ppm). this also means that for a palette image, the distinction between an image and its lookup table is lost, which can be a problem in cases (but can hardly be avoided when using netpbm/pbmplus). 😵‍💫

Datatype is dependent on the maximum grey/color-component value — for raw and binary formats it's always PDL_B.

rpnm tries to read chopped files by zero padding the missing data… (well, it currently doesn't, it barfs; the author says they'll probably fix it when it becomes a problem for them ;). iconic honestly 🙈)

you can also read directly into an existing pdl that has to have the right size(!). this can come in handy when you want to read a sequence of images into a datacube. 🧊

for details about the formats, see the appropriate manpages that come with the netpbm/pbmplus packages.

$stack = zeroes(byte,3,500,300,4);
rpnm $stack->slice(':,:,:,(0)'),"PDL.ppm";

reads an rgb image (that had better be of size (500,300)) into the first plane of a 3D RGB datacube (= 4D pdl datacube). you can also do inplace transpose/inversion that way. main character energy fr 🌟

🌸 wpnm

Write a pnm (portable bitmap/pixmap, pbm/ppm) file into a file or open file-handle. 💾

Usage:  $im = wpnm $pdl, $file, $format[, $raw];

Writes data in a pdl into pnm format (ascii or raw) (magic numbers P1-P6). the $format is required (normally produced by wpic) and the routine just checks if the data is compatible with that format. all conversions should already have been done. if possible, usage of wpic is preferred. 👑

currently RAW format is chosen if it's compliant with the range of input data. explicit control of ASCII/RAW is possible through the optional $raw argument. if RAW is set to zero it will enforce ASCII mode. enforcing RAW is somewhat meaningless, since the routine will always try to write RAW format if the data range allows (but maybe it should reduce to a RAW supported type when RAW == 'RAW'? — that's the author's open question, not mine 🫠). for details about the formats, consult the appropriate manpages that come with the netpbm/pbmplus packages.

---

💀 BUGS 💀

rpnm currently relies on the fact that the header is separated from the image data by a newline. this is not required by the p[bgp]m formats (in fact any whitespace is allowed) but most of the pnm writers seem to comply with that. 😤

Truncated files are currently treated ungracefully — rpnm just barfs. 🫠💀

---

🫶 AUTHOR 🫶

Copyright (C) 1996,1997 Christian Soeller <c.soeller@auckland.ac.nz> All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.

---

and that's the whole page bestie, slay 💅✨ — this was served up by perl v5.38.2, dated 2024-04-10, and it's the Pnm(3pm) page, iykyk 🎀🦋