--- name: "libpnm" section: "3" platform: "linux" package: "netpbm" version: "10.86.51-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/libpnm" --- # libpnm(3) libnetpbm functions to read and write PNM image files ## NAME libpnm - libnetpbm functions to read and write PNM image files ## SYNOPSIS **#include \** **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) . ### TYPES AND CONSTANTS Each **xel** contains three **xelval**s, each of which should contain only the values between **0** and **PNM\_MAXMAXVAL**, inclusive. ### XEL MANIPULATIONS The **PNM\_GET1** macro extracts a single value from an xel, when ou know it's from a PBM or PGM file. When it's from a PPM file, use **PPM\_GETR()**, **PPM\_GETG()**, and **PPM\_GETB()**. The **PNM\_ASSIGN1** macro assigns a single value to an xel, when you know it's from a PBM or PGM file. When it's from a PPM file, use **PPM\_ASSIGN**. 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 note that PBM, PGM, and PPM each are two different formats: a plain one and a raw one. So there are four format types, but seven formats. **PNM\_FORMAT\_TYPE** does not work on the PAM format code. **pnm\_whitexel()** and **pnm\_blackxel()** return a white or black xel, respectively, for the given *maxval* and *format*. **pnm\_invertxel()** inverts an xel. ### INITIALIZATION **pnm\_init()** is obsolete (at least since Netpbm 9.25 (March 2002)). Use **pm\_proginit()** ⟨libpm.html#initialization⟩ instead. **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()**. **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 reads only PNM images and has a different parameter list. **pnm\_readpnmrow()** is similar to **pnm\_readpamrow()** but only works on PNM images and 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 and 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. ### 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 to write the image in the plain (ASCII) version of the selected format. False (zero) means to 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 and 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 are 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. **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**