LIBPNM(3)

💖 libpnm (3) — the PNM bestie you deserve

okay so this is libpnm, from the Library Functions Manual, section 3 — the libnetpbm functions that read and write PNM image files. yes it's a mouthful, no we're not scared of it. 🫶

---

✨ NAME ✨

libpnm — libnetpbm functions to read and write PNM image files

---

🌸 SYNOPSIS 🌸

#include <netpbm/pnm.h>

void pnm_init( int *argcP, char *argv[] );

xel ** pnm_allocarray( int cols, int rows);

xel * pnm_allocrow( int cols);

void pnm_freearray( xel **xels, int rows);

void pnm_freerow( xel *xelrow);

void pnm_readpnminit( FILE *fp, int *colsP, int *rowsP, xelval *maxvalP,
int *formatP );

void pnm_readpnmrow( FILE *fp, xel *xelrow, int cols, xelval maxval, int
format );

xel ** pnm_readpnm( FILE *fp, int *colsP, int *rowsP, xelval *maxvalP,
int* formatP );

void pnm_writepnminit( FILE *  fp , int cols, int rows, xelval maxval,
int format, int forceplain);

void pnm_writepnmrow( FILE *fp, xel *xelrow, int cols, xelval maxval,
int format, int forceplain );

void pnm_writepnm( FILE *fp, xel ** xels, int cols, int rows, xelval
maxval, int format, int forceplain );

void pnm_nextimage(FILE * file,
  int * const eofP);

void pnm_check( FILE * file, const enum pm_check_type check_type, const
int format, const int cols, const int rows, const xelval maxval, enum
pm_check_code *retvalP);

void pnm_promoteformatrow( xel *xelrow, int cols, xelval maxval, int
format, xelval newmaxval, int newformat);

void pnm_promoteformat( xel **xels, int cols, xelval maxval, int format,
xelval newmaxval, int newformat);

xel pnm_whitexel( xelval maxval, int format);

xel pnm_blackxel( xelval maxval, int format);

void pnm_invertxel( xel *x, xelval maxval, int format);

xel pnm_backgroundxelrow( xel *xelrow, int cols, xelval maxval, int
format);

xel pnm_backgroundxel( xel **xels, int cols, int rows, xelval maxval,
int format);

typedef ... xelval;

typedef ... xel;

#define PNM_ASSIGN1(x,v) ...

#define PNM_GET1(x) ...

#define PNM_EQUAL(x,y) ...

#define PNM_FORMAT_TYPE(format) ...

---

🦋 DESCRIPTION 🦋

These library functions are part of Netpbm(1). bestie, they're the whole PNM pipeline, and they're lowkey iconic for it. 💅

💜 TYPES AND CONSTANTS

Each xel contains three xelvals, and every single one of those should only hold values between 0 and PNM_MAXMAXVAL, inclusive. no sneaking outside the range, okay? 🙈

🎀 XEL MANIPULATIONS

The PNM_GET1 macro pulls a single value out of an xel — use it when you already know that xel came from a PBM or PGM file. If it came from a PPM file instead, you want PPM_GETR(), PPM_GETG(), and PPM_GETB(). different tool, different job. ✨

The PNM_ASSIGN1 macro assigns a single value to an xel — again, only when you know it's from a PBM or PGM file. If it's from a PPM file, that's PPM_ASSIGN's moment. 👑

The PNM_EQUAL macro checks two xels for equality.

The PNM_FORMAT_TYPE macro computes a format type code from a format code. The format types are PBM, PGM, PPM, and PAM. But here's the plot twist, bestie: PBM, PGM, and PPM are each actually two different formats — a plain one and a raw one. So that's four format types but seven formats. math is mathing. 😭 And one more thing: PNM_FORMAT_TYPE does not work on the PAM format code. not even a little.

pnm_whitexel() and pnm_blackxel() return a white or black xel, respectively, for whatever maxval and format you hand them. 🤍🖤

pnm_invertxel() inverts an xel. flipping the vibe, literally.

🌈 INITIALIZATION

pnm_init() is obsolete — at least since Netpbm 9.25 (March 2002). so like, ancient history. use pm_proginit() instead, fr fr.

pnm_init() is identical to pm_proginit.

🍓 MEMORY MANAGEMENT

pnm_allocarray() allocates space for an array of xels. pnm_freearray() frees an array space allocated by pnm_allocarray() or pnm_readpnm(). give it back when you're done, it's only polite. 🫶

pnm_allocrow() allocates space for a row of a PNM image. pnm_freerow() frees it.

🧚 READING PNM FILES

pnm_readpnminit() is similar to pnm_readpaminit(), but it reads only PNM images and it has a different parameter list.

pnm_readpnmrow() is similar to pnm_readpamrow() but only works on PNM images, has a different parameter list, and returns the row as an array of xels instead of tuples.

pnm_readpnm() is similar to pnm_readpam() except that it reads only PNM images, uses a different parameter list, and returns an array of rows such that pnm_readpnmrow() would return rather than such that pnm_readpamrow() would return. (yes, that sentence is a whole journey. read it twice, it's worth it. 💀)

⭐ WRITING FILES

pnm_writepnminit() is similar to pnm_writepaminit() except that it can write only a PNM header and has a different parameter list.

forceplain is a binary value. True (nonzero) means write the image in the plain (ASCII) version of the selected format. False (zero) means write it in the raw (binary) version of the selected format. See PNM format specification(1). 🎀

pnm_writepnmrow() is similar to pnm_writepamrow() except that it works only on PNM images, has a different parameter list, and takes an array of xels instead of an array of tuples. See the description of forceplain above. ⬆️

pnm_writepnm() is similar to pnm_writepam() except that it works only on PNM image, has a different parameter list, and takes an array of rows of xels instead of an array of rows of tuples. See the description of forceplain above. ⬆️

💅 FORMAT PROMOTION

pnm_promoteformatrow() promotes a row of xels from one maxval and format to a new set. use this when you're combining multiple anymaps of different types — just take the maximum of the maxvals and the maximum of the formats, and promote them all to that. glow-up for the whole squad. 👑

pnm_promoteformat() promotes an entire anymap.

🌸 MISCELLANEOUS

pnm_nextimage() positions a PNM input file to the next image in it — so that a subsequent pnm_readpnminit() reads its header. ✨

pnm_nextimage() is analogous to pbm_nextimage(), but works on PPM, PGM, and PBM files.

pnm_check() is similar to pnm_checkpam() except it works only on PNM images.

pnm_check() is identical to ppm_check().

pnm_backgroundxelrow() figures out an appropriate background xel based on the row of xels xelrow, which is cols xels wide, has maxval maxval, and represents an image with format format.

This estimate works best when the row is the top or bottom row of the image. 📐

pnm_backgroundxel() does the same thing as pnm_backgroundxelrow(), except based on an entire image instead of just one row. This tends to do a slightly better job than pnmbackgroundxelrow().

---

👑 SEE ALSO 👑

Libnetpbm(1), Libnetpbm User's Guide(1), Libnetpbm Directory(1), pbm(1), pgm(1), ppm(1), pam(1), libpbm(1), libpgm(1), libppm(1)

---

💖 AUTHOR 💖

Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.

---

🎀 DOCUMENT SOURCE 🎀

This manual page was generated by the Netpbm tool makeman from HTML source. The master documentation is at

http://netpbm.sourceforge.net/doc/libpnm.html

---

okay and that's the whole page, bestie — netpbm documentation, 08 September 2007, from the section 3 manual of "User manua...m functions(3)". go forth and read some PNM files, you've got this. 💅✨🦋