Contents of NetPBM

DESCRIPTION The pbmplus toolkit allows conversions between image files of different format. By means of using common intermediate formats, only 2×N conversion filters are required to support N distinct formats, instead of the N² which would be required to convert directly between any one format and any other. The package also includes simple tools for manipulating portable bitmaps.

The package consists of four upwardly compatible sections:
$\begin{TPlist}{pbm} \item[{pbm}] Supports monochrome bitmaps (1 bit per pixel). ... ...n and \lq\lq promotes'' a file to a higher format, it informs the user). \end{TPlist}$

DESCRIPTION OF CONTENTS
$\begin{TPlist}{{\it cmuwmtopbm}} \item[{{\it atktopbm}}] convert Andrew Toolkit ... ...{{\it xwdtopnm}}] convert X10 or X11 window dump to portable anymap \end{TPlist}$

SEE ALSO There are a number of related image-manipulation tools:
$\begin{TPlist}{{\it Fuzzy Pixmap Manipulation}} \item[{{\it IM Raster Toolkit}}]... ...by {\it ftp} as {\it uunet.uu.net: graphics/jpeg/jpegsrc.v4.tar.Z}. \end{TPlist}$

libpbm(3), libpgm(3), libpnm(3), libppm(3), pbm(5), pgm(5), pnm(5), ppm(5), rasterfile(1)

Feedback and questions are welcome. Please send them to:
$\begin{IPlist} \IPitem{{}} {\nofill jef@netcom.com jef@well.sf.ca.us apple!well!jef \fill} \end{IPlist}$

When sending bug reports, always include the output from running any pbmplus program with the -version flag, including descriptions of the type of system you are on, the compiler you use, and whether you are using Makefiles or Imakefiles.

When suggesting new formats or features, please include whatever documentation you have, and a uuencoded sample. The response time will depend upon my schedule and the complexity of the task; if you need it right away, or it is a complicated job, you might consider paying me.

The Usenet newsgroup alt.graphics.pixutils is a forum for discussion of image conversion and editing packages. Posting queries there may be better than mailing them to me, since it allows other people to help provide answers.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. This software is provided ``as is'' without express or implied warranty. Thus, you may do what you want with this software. Build it into your package, steal code from it, whatever. Just be sure to let people know where it came from.

NAME asciitopgm - convert ASCII graphics into a portable graymap SYNOPSIS asciitopgm [-d divisor] height width [asciifile] DESCRIPTION Reads ASCII data as input. Produces a portable graymap with pixel values which are an approximation of the ``brightness'' of the ASCII characters, assuming black-on-white printing. In other words, a capital M is very dark, a period is ver light, and a space is white. Input lines which are fewer than width characters are automatically padded with spaces.

The divisor argument is a floating-point number by which the output pixels are divided; the default value is 1.0. This can be used to adjust the brightness of the graymap: for example, if the image is too dim, reduce the divisor.

In keeping with (I believe) Fortran line-printer conventions, input lines beginning with a + (plus) character are assumed to ``overstrike'' the previous line, allowing a larger range of gray values.

This tool contradicts the message in the pbmtoascii manual: ``Note that there is no asciitopbm tool - this transformation is one-way.'' BUGS The table of ASCII-to-grey values is subject to interpretation, and, of course, depends on the typeface intended for the input. SEE ALSO pbmtoascii(1), pgm(5) AUTHOR Wilson H. Bent. Jr. (whb@usc.edu)

NAME atktopbm - convert Andrew Toolkit raster object to portable bitmap SYNOPSIS atktopbm [atkfile] DESCRIPTION Reads an Andrew Toolkit raster object as input. Produces a portable bitmap as output. SEE ALSO pbmtoatk(1), pbm(5) AUTHOR ©1991 by Bill Janssen.

NAME bioradtopgm - convert a Biorad confocal file into a portable graymap SYNOPSIS bioradtopgm [-image#] [imagedata] DESCRIPTION Reads a Biorad confocal file as input. Produces a portable graymap as output. If the resulting image is upside down, run it through pnmflip -tb . OPTIONS
$\begin{TPlist}{{\bf -image\char93 }} \item[{{\bf -image\char93 }}] A Biorad imag... ...umber of images in the input is printed out. No output is produced. \end{TPlist}$

BUGS A Biorad image may be in word format. If PbmPlus is not compiled with the ``BIGGRAYS'' flag, word files can not be converted. See the Makefile. SEE ALSO pgm(5), pnmflip(1) AUTHORS ©1993 by Oliver Trepte (oliver@fysik4.kth.se).

NAME bmptoppm – convert a BMP file into a portable pixmap SYNOPSIS bmptoppm [bmpfile] DESCRIPTION Reads a Microsoft Windows or OS/2 BMP file as input. Produces a portable pixmap as output. SEE ALSO ppmtobmp(1), ppm(5) AUTHOR ©1992 by David W. Sanderson.

NAME brushtopbm - convert a doodle brush file into a portable bitmap SYNOPSIS brushtopbm [brushfile] DESCRIPTION Reads a Xerox doodle brush file as input. Produces a portable bitmap as output.

NAME cmuwmtopbm - convert a CMU window manager bitmap into a portable bitmap SYNOPSIS cmuwmtopbm [cmuwmfile] DESCRIPTION Reads a CMU window manager bitmap as input. Produces a portable bitmap as output. SEE ALSO pbmtocmuwm(1), pbm(5) AUTHOR ©1989 by Jef Poskanzer.

NAME fitstopnm - convert a FITS file into a portable anymap SYNOPSIS fitstopnm [-image N] [-noraw] [-scanmax] [-printmax] [-min f] [-max f] [FITSfile] DESCRIPTION Reads a FITS file as input. Produces a portable pixmap if the FITS file consists of 3 image planes (NAXIS = 3 and NAXIS3 = 3), a portable graymap if the FITS file consists of 2 image planes (NAXIS = 2), or whenever the –image flag is specified. The results may need to be flipped top for bottom; if so, just pipe the output through pnmflip -tb. OPTIONS

The -image option is for FITS files with three axes. The assumption is that the third axis is for multiple images, and this option lets you select which one you want.

Flags -min and -max can be used to override the min and max values as read from the FITS header or the image data if no DATAMIN and DATAMAX keywords are found. Flag -scanmax can be used to force the program to scan the data even when DATAMIN and DATAMAX are found in the header. If -printmax is specified, the program will just print the min and max values and quit. Flag -noraw can be used to force the program to produce an ASCII portable anymap.

The program will tell what kind of anymap is writing. All flags can be abbreviated to their shortest unique prefix. REFERENCES FITS stands for Flexible Image Transport System. A full description can be found in Astronomy & Astrophysics Supplement Series 44 (1981), page 363. SEE ALSO pnmtofits(1), pgm(5), pnmflip(1) AUTHOR Copyright (C) 1989 by Jef Poskanzer, with modifications by Daniel Briggs (dbriggs@nrao.edu) and Alberto Accomazzi (alberto@cfa.harvard.edu).

NAME fstopgm - convert a Usenix FaceSaver(tm) file into a portable graymap SYNOPSIS fstopgm [fsfile] DESCRIPTION Reads a Usenix FaceSaver(tm) file as input. Produces a portable graymap as output.

FaceSaver(tm) files sometimes have rectangular pixels. While fstopgm won't re-scale them into square pixels for you, it will give you the precise pnmscale command that will do the job. Because of this, reading a FaceSaver(tm) image is a two-step process. First you do: fstopgm > /dev/null This will tell you whether you need to use pnmscale. Then use one of the following pipelines: fstopgm | pgmnorm fstopgm | pnmscale -whatever | pgmnorm To go to PBM, you want something more like one of these: fstopgm | pnmenlarge 3 | pgmnorm | pgmtopbm fstopgm | pnmenlarge 3 | pnmscale <whatever> | pgmnorm | pgmtopbm You want to enlarge when going to a bitmap because otherwise you lose information; but enlarging by more than 3 does not look good.

NAME g3topbm - convert a Group 3 fax file into a portable bitmap SYNOPSIS g3topbm [-kludge] [-reversebits] [-stretch] [g3file] DESCRIPTION Reads a Group 3 fax file as input. Produces a portable bitmap as output. OPTIONS
$\begin{TPlist}{{\bf -kludge}} \item[{{\bf -kludge}}] Tells {\it g3topbm} to igno... ...uplicating each row. This is for the low-quality transmission mode. \end{TPlist}$

All flags can be abbreviated to their shortest unique prefix. REFERENCES The standard for Group 3 fax is defined in CCITT Recommendation T.4. BUGS Probably. SEE ALSO pbmtog3(1), pbm(5) AUTHOR ©1989 by Paul Haeberli (paul@manray.sgi.com).

NAME gemtopbm - convert a GEM .img file into a portable bitmap SYNOPSIS gemtopbm [-d] gemfile DESCRIPTION Reads a GEM .img file as input. Produces a portable bitmap as output. OPTIONS
$\begin{TPlist}{{\bf -d}} \item[{{\bf -d}}] Produce output describing the contents of the .img file. \end{TPlist}$

NAME giftopnm - convert a GIF file into a portable anymap SYNOPSIS giftopnm [-verbose] [-comments] [-image N] [GIFfile] DESCRIPTION Reads a GIF file for input, and outputs portable anymap. OPTIONS
$\begin{TPlist}{{\bf -verbose}} \item[{{\bf -verbose}}] Produces verbose output a... ...lly there is only one image per file, so this option is not needed. \end{TPlist}$

All flags can be abbreviated to their shortest unique prefix. BUGS This does not correctly handle the Plain Text Extension of the GIF89 standard, since I did not have any example input files containing them. SEE ALSO ppmtogif(1), ppm(5) AUTHOR ©1993 by David Koblas (koblas@netcom.com)

NAME gouldtoppm - convert Gould scanner file into a portable pixmap SYNOPSIS gouldtoppm [gouldfile] DESCRIPTION Reads a file produced by the Gould scanner as input. Produces a portable pixmap as output. SEE ALSO ppm(5) AUTHOR ©1990 by Stephen Paul Lesniewski.

NAME hipstopgm - convert a HIPS file into a portable graymap SYNOPSIS hipstopgm [hipsfile] DESCRIPTION Reads a HIPS file as input. Produces a portable graymap as output.

If the HIPS file contains more than one frame in sequence, hipstopgm will concatenate all the frames vertically.

NAME icontopbm - convert a Sun icon into a portable bitmap SYNOPSIS icontopbm [iconfile] DESCRIPTION Reads a Sun icon as input. Produces a portable bitmap as output. SEE ALSO pbmtoicon(1), pbm(5) AUTHOR ©1988 by Jef Poskanzer.

NAME ilbmtoppm - convert an ILBM file into a portable pixmap SYNOPSIS ilbmtoppm [-verbose] [ILBMfile] DESCRIPTION Reads an IFF ILBM file as input. Produces a portable pixmap as output. Supported ILBM types are:
$\begin{TPlist}{Normal ILBMs with 1-16 planes.} \item[{Normal ILBMs with 1-16 pla... ...:}] NAME, AUTH, (c), ANNO, DPI \item[{Unknown chunks are skipped.}] \end{TPlist}$

OPTIONS
$\begin{TPlist}{{\bf -verbose}} \item[{{\bf -verbose}}] Give some informaton about the ILBM file. \end{TPlist}$

BUGS Probably. REFERENCES Amiga ROM Kernel Reference Manual - Devices (3rd Ed.) Addison Wesley, ISBN 0–201–56775–X SEE ALSO ppm(5), ppmtoilbm(1) AUTHORS ©1989 by Jef Poskanzer. Modified June 1993 by Ingo Wilken (Ingo.Wilken@informatik.uni-oldenburg.de)

NAME imgtoppm - convert an Img-whatnot file into a portable pixmap SYNOPSIS imgtoppm [imgfile] DESCRIPTION Reads an Img-whatnot file as input. Produces a portable pixmap as output. The Img-whatnot toolkit is available for FTP on venera.isi.edu, along with numerous images in this format. SEE ALSO ppm(5) AUTHOR Based on a simple conversion program posted to comp.graphics by Ed Falk.

Does a case-insensitive match of str against keyword. str can be a leading sunstring of keyword, but at least minchars must be present.

Write a usage message. The string should indicate what arguments are to be provided to the program.

Open the given file for reading, with appropriate error checking. A filename of ``-'' is taken as equivalent to stdin.

int pm_readbigshort( FILE* in, short* sP ) int pm_writebigshort( FILE* out, short s ) int pm_readbiglong( FILE* in, long* lP ) int pm_writebiglong( FILE* out, long l ) int pm_readlittleshort( FILE* in, short* sP ) int pm_writelittleshort( FILE* out, short s ) int pm_readlittlelong( FILE* in, long* lP ) int pm_writelittlelong( FILE* out, long l )

Routines to read and write short and long ints in either big- or little-endian byte order. DESCRIPTION - PBM-SPECIFIC ROUTINES

#define PBM_FORMAT ... #define RPBM_FORMAT ... #define PBM_TYPE PBM_FORMAT #define PBM_FORMAT_TYPE(f) ...

Free the array allocated with pbm_allocarray() containing the given number of rows.

Read the header from a PBM file, filling in the rows, cols and format variables.

Read a row of bits into the bitrow array. Format and cols were filled in by pbm_readpbminit().

Read an entire bitmap file into memory, returning the allocated array and filling in the rows and cols variables. This function combines pbm_readpbminit(), pbm_allocarray() and pbm_readpbmrow().

Read an entire file or input stream of unknown size to a buffer. Allocate memory more memory as needed. The calling routine has to free the allocated buffer with free(). pm_read_unknown_size() returns a pointer to the allocated buffer. The nread argument returns the number of bytes read.

Write the header for a portable bitmap file. The forceplain flag forces a plain-format file to be written, as opposed to a raw-format one.

Write the header and all data for a portable bitmap. This function combines pbm_writepbminit() and pbm_writepbmrow(). SEE ALSO libpgm(3), libppm(3), libpnm(3) AUTHOR ©1989, 1991 by Tony Hansen and Jef Poskanzer.

Each gray should contain only the values between 0 and PGM_MAXMAXVAL. pgm_pbmmaxval is the maxval used when a PGM program reads a PBM file. Normally it is 1; however, for some programs, a larger value gives better results.

#define PGM_FORMAT ... #define RPGM_FORMAT ... #define PGM_TYPE PGM_FORMAT int PGM_FORMAT_TYPE( int format )

Free the array allocated with pgm_allocarray() containing the given number of rows.

void pgm_readpgminit( FILE* fp, int* colsP, int* rowsP, gray* maxvalP, int* formatP )

Read the header from a PGM file, filling in the rows, cols, maxval and format variables.

void pgm_readpgmrow( FILE* fp, gray* grayrow, int cols, gray maxval, int format )

Read a row of grays into the grayrow array. Format, cols, and maxval were filled in by pgm_readpgminit().

Read an entire graymap file into memory, returning the allocated array and filling in the rows, cols and maxval variables. This function combines pgm_readpgminit(), pgm_allocarray() and pgm_readpgmrow().

void pgm_writepgminit( FILE* fp, int cols, int rows, gray maxval, int forceplain )

Write the header for a portable graymap file. The forceplain flag forces a plain-format file to be written, as opposed to a raw-format one.

void pgm_writepgmrow( FILE* fp, gray* grayrow, int cols, gray maxval, int forceplain )

void pgm_writepgm( FILE* fp, gray** grays, int cols, int rows, gray maxval, int forceplain )

Write the header and all data for a portable graymap. This function combines pgm_writepgminit() and pgm_writepgmrow(). SEE ALSO libpbm(3), libppm(3), libpnm(3) AUTHOR ©1989, 1991 by Tony Hansen and Jef Poskanzer.

typedef ... xel; typedef ... xelval; #define PNM_MAXMAXVAL ... extern xelval pnm_pbmmaxval;

Each xel contains three xelvals, each of which should contain only the values between 0 and PNM_MAXMAXVAL. pnm_pbmmaxval is the maxval used when a PNM program reads a PBM file. Normally it is 1; however, for some programs, a larger value gives better results.

This macro extracts a single value from an xel, when you know it's from a PBM or PGM file. When it's from a PPM file, use PPM_GETR(), PPM_GETG(), and PPM_GETB().

This 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().

Free the array allocated with pnm_allocarray() containing the given number of rows.

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

Read the header from a PNM file, filling in the rows, cols, maxval and format variables.

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

Read a row of xels into the xelrow array. Format, cols, and maxval were filled in by pnm_readpnminit().

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

Read an entire anymap file into memory, returning the allocated array and filling in the rows, cols, maxval, and format variables. This function combines pnm_readpnminit(), pnm_allocarray() and pnm_readpnmrow(). Unlike the equivalent functions in PBM, PGM, and PPM, it returns the format so you can tell what type the file is.

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

Write the header for a portable anymap file. Unlike the equivalent functions in PBM, PGM, and PPM, you have to specify the output type. The forceplain flag forces a plain-format file to be written, as opposed to a raw-format one.

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 )

Write the header and all data for a portable anymap. This function combines pnm_writepnminit() and pnm_writepnmrow().

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

Promote a row of xels from one maxval and format to a new set. Used when combining multiple anymaps of different types - just take the max of the maxvals and the max of the formats, and promote them all to that.

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

xel pnm_whitexel( xelval maxval, int format ) xel pnm_blackxel( xelval maxval, int format )

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

Figure out a background xel based on an entire anymap. This can do a slightly better job than pnm_backgroundxelrow(). SEE ALSO pbm(3), pgm(3), ppm(3) AUTHOR ©1989, 1991 by Tony Hansen and Jef Poskanzer.

typedef ... pixel; typedef ... pixval; #define PPM_MAXMAXVAL ... extern pixval ppm_pbmmaxval;

Each pixel contains three pixvals, each of which should contain only the values between 0 and PPM_MAXMAXVAL. ppm_pbmmaxval is the maxval used when a PPM program reads a PBM file. Normally it is 1; however, for some programs, a larger value gives better results.

#define PPM_FORMAT ... #define RPPM_FORMAT ... #define PPM_TYPE PPM_FORMAT int PPM_FORMAT_TYPE( int format )

pixval PPM_GETR( pixel p ) pixval PPM_GETG( pixel p ) pixval PPM_GETB( pixel p )

This macro scales the colors of pixel p according the old and new maximum values and assigns the new values to newp. It is intended to make writing ppmtowhatever easier.

Free the array allocated with ppm_allocarray() containing the given number of rows.

void ppm_readppminit( FILE* fp, int* colsP, int* rowsP, pixval* maxvalP, int* formatP )

Read the header from a PPM file, filling in the rows, cols, maxval and format variables.

void ppm_readppmrow( FILE* fp, pixel* pixelrow, int cols, pixval maxval, int format )

Read a row of pixels into the pixelrow array. Format, cols, and maxval were filled in by ppm_readppminit().

Read an entire pixmap file into memory, returning the allocated array and filling in the rows, cols and maxval variables. This function combines ppm_readppminit(), ppm_allocarray() and ppm_readppmrow().

void ppm_writeppminit( FILE* fp, int cols, int rows, pixval maxval, int forceplain )

Write the header for a portable pixmap file. The forceplain flag forces a plain-format file to be written, as opposed to a raw-format one.

void ppm_writeppmrow( FILE* fp, pixel* pixelrow, int cols, pixval maxval, int forceplain )

void ppm_writeppm( FILE* fp, pixel** pixels, int cols, int rows, pixval maxval, int forceplain )

Write the header and all data for a portable pixmap. This function combines ppm_writeppminit() and ppm_writeppmrow().

Parses an ASCII color name into a pixel. The color can be specified in three ways. One, as a name, assuming that a pointer to an X11-style color names file was compiled in. Two, as an X11-style hexadecimal number: #rgb, #rrggbb, #rrrgggbbb, or #rrrrggggbbbb. Three, as a triplet of decimal floating point numbers separated by commas: r.r,g.g,b.b.

Returns a pointer to a string describing the given color. If the X11 color names file is available and the color appears in it, that name is returned. Otherwise, if the hexok flag is true then a hexadecimal colorspec is returned; if hexok is false and the X11 color names file is available, then the closest matching color is returned; otherwise, it's an error. SEE ALSO pbm(3), pgm(3) AUTHOR ©1989, 1991 by Tony Hansen and Jef Poskanzer.

NAME lispmtopgm - convert a Lisp Machine bitmap file into pgm format SYNOPSIS lispmtopgm [lispmfile] DESCRIPTION Reads a Lisp Machine bitmap as input. Produces a portable graymap as output.

This is the file format written by the tv:write-bit-array-file function on TI Explorer and Symbolics lisp machines.

Multi-plane bitmaps on lisp machines are color; but the lispm image file format does not include a color map, so we must treat it as a graymap instead. This is unfortunate. SEE ALSO pgmtolispm(1), pgm(5) BUGS The Lispm bitmap file format is a bit quirky; Usually the image in the file has its width rounded up to the next higher multiple of 32, but not always. If the width is not a multiple of 32, we don't deal with it properly, but because of the Lispm microcode, such arrays are probably not image data anyway.

Also, the lispm code for saving bitmaps has a bug, in that if you are writing a bitmap which is not mod32 across, the file may be up to 7 bits too short! They round down instead of up, and we don't handle this bug gracefully.

NAME macptopbm - convert a MacPaint file into a portable bitmap SYNOPSIS macptopbm [-extraskip N] [macpfile] DESCRIPTION Reads a MacPaint file as input. Produces a portable bitmap as output. OPTIONS
$\begin{TPlist}{{\bf -extraskip}} \item[{{\bf -extraskip}}] This flag is to get a... ...askip} 128, and if that still doesn't look right try another value. \end{TPlist}$

All flags can be abbreviated to their shortest unique prefix. SEE ALSO picttoppm(1), pbmtomacp(1), pbm(5) AUTHOR ©1988 by Jef Poskanzer. The MacPaint-reading code is ©1987 by Patrick J. Naughton (naughton@wind.sun.com).

NAME mgrtopbm - convert a MGR bitmap into a portable bitmap SYNOPSIS mgrtopbm [mgrfile] DESCRIPTION Reads a MGR bitmap as input. Produces a portable bitmap as output. SEE ALSO pbmtomgr(1), pbm(5) AUTHOR ©1989 by Jef Poskanzer.

NAME mtvtoppm - convert output from the MTV or PRT ray tracers into a portable pixmap SYNOPSIS mtvtoppm [mtvfile] DESCRIPTION Reads an input file from Mark VanDeWettering's MTV ray tracer. Produces a portable pixmap as output.

NAME pbm - portable bitmap file format DESCRIPTION The portable bitmap format is a lowest common denominator monochrome file format. It was originally designed to make it reasonable to mail bitmaps between different types of machines using the typical stupid network mailers we have today. Now it serves as the common language of a large family of bitmap conversion filters. The definition is as follows:
$\begin{IPlist} \IPitem{{-}} A \lq\lq magic number'' for identifying the file type. A ... ...omments). \IPitem{{-}} No line should be longer than 70 characters. \end{IPlist}$

Here is an example of a small bitmap in this format: P1 # feep.pbm 24 7 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 1 0 0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 1 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

Programs that read this format should be as lenient as possible, accepting anything that looks remotely like a bitmap.

There is also a variant on the format, available by setting the RAWBITS option at compile time. This variant is different in the following ways:
$\begin{IPlist} \IPitem{{-}} The \lq\lq magic number'' is \lq\lq P4'' instead of \lq\lq P1''. \I... ...es are eight times smaller and many times faster to read and write. \end{IPlist}$

SEE ALSO atktopbm(1), brushtopbm(1), cmuwmtopbm(1), g3topbm(1), gemtopbm(1), icontopbm(1), macptopbm(1), mgrtopbm(1), pi3topbm(1), xbmtopbm(1), ybmtopbm(1), pbmto10x(1), pnmtoascii(1), pbmtoatk(1), pbmtobbnbg(1), pbmtocmuwm(1), pbmtoepson(1), pbmtog3(1), pbmtogem(1), pbmtogo(1), pbmtoicon(1), pbmtolj(1), pbmtomacp(1), pbmtomgr(1), pbmtopi3(1), pbmtoplot(1), pbmtoptx(1), pbmtox10bm(1), pbmtoxbm(1), pbmtoybm(1), pbmtozinc(1), pbmlife(1), pbmmake(1), pbmmask(1), pbmreduce(1), pbmtext(1), pbmupc(1), pnm(5), pgm(5), ppm(5) AUTHOR ©1989, 1991 by Jef Poskanzer.

NAME pbmclean - flip isolated pixels in portable bitmap SYNOPSIS pbmclean [-connect] [pbmfile] DESCRIPTION Reads a portable bitmap as input. Outputs a portable bitmap with every pixel which has less than connect identical neighbours inverted. Pbmclean can be used to clean up ``snow'' on bitmap images. SEE ALSO pbm(5) AUTHOR ©1990 by Angus Duggan. ©1989 by Jef Poskanzer.

NAME pbmlife - apply Conway's rules of Life to a portable bitmap SYNOPSIS pbmlife [pbmfile] DESCRIPTION Reads a portable bitmap as input. Applies the rules of Life to it for one generation, and produces a portable bitmap as output.

NAME pbmmake - create a blank bitmap of a specified size SYNOPSIS pbmmake [-white|-black|-gray ] width height DESCRIPTION Produces a portable bitmap of the specified width and height. The color defaults to white. OPTIONS

In addition to the usual -white and -black, this program implements -gray. This gives a simple 50% gray pattern with 1's and 0's alternating.

NAME pbmmask - create a mask bitmap from a regular bitmap SYNOPSIS pbmmask [-expand] [pbmfile] DESCRIPTION Reads a portable bitmap as input. Creates a corresponding mask bitmap and writes it out.

The color to be interpreted as ``background'' is determined automatically. Regardless of which color is background, the mask will be white where the background is and black where the figure is.

This lets you do a masked paste like this, for objects with a black background: pbmmask obj > objmask pnmpaste < dest -and objmask <x> <y> | pnmpaste -or obj <x> <y> For objects with a white background, you can either invert them or add a step: pbmmask obj > objmask pnminvert objmask | pnmpaste -and obj 0 0 > blackback pnmpaste < dest -and objmask <x> <y> | pnmpaste -or blackback <x> <y> Note that this three-step version works for objects with black backgrounds too, if you don't care about the wasted time.

You can also use masks with graymaps and pixmaps, using the pnmarith tool. For instance: ppmtopgm obj.ppm | pgmtopbm -threshold | pbmmask > objmask.pbm pnmarith -multiply dest.ppm objmask.pbm > t1.ppm pnminvert objmask.pbm | pnmarith -multiply obj.ppm - > t2.ppm pnmarith -add t1.ppm t2.ppm An interesting variation on this is to pipe the mask through the pnmsmooth script before using it. This makes the boundary between the two images less sharp.
$\begin{TPlist}{{\bf -expand}} \item[{{\bf -expand}}] Expands the mask by one pix... ...n the {\it pbmlife} tool into a general cellular automaton tool...) \end{TPlist}$

NAME pbmpscale - enlarge a portable bitmap with edge smoothing SYNOPSIS pbmpscale N [ pbmfile ] DESCRIPTION Reads a portable bitmap as input, and outputs a portable bitmap enlarged N times. Enlargement is done by pixel replication, with some additional smoothing of corners and edges. SEE ALSO pnmenlarge(1), ppmscale(1), pbm(5) AUTHOR ©1990 by Angus Duggan. ©1989 by Jef Poskanzer.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. This software is provided "as is" without express or implied warranty. NOTES pbmpscale works best for enlargements of 2. Enlargements greater than 2 should be done by as many enlargements of 2 as possible, followed by an enlargement by the remaining factor.

NAME pbmreduce - read a portable bitmap and reduce it N times SYNOPSIS pbmreduce [-floyd|-fs|-threshold ] [-value val] N [pbmfile] DESCRIPTION Reads a portable bitmap as input. Reduces it by a factor of N, and produces a portable bitmap as output.

pbmreduce duplicates a lot of the functionality of pgmtopbm; you could do something like pnmscale | pgmtopbm, but pbmreduce is a lot faster.

pbmreduce can be used to ``re-halftone'' an image. Let's say you have a scanner that only produces black&white, not grayscale, and it does a terrible job of halftoning (most b&w scanners fit this description). One way to fix the halftoning is to scan at the highest possible resolution, say 300 dpi, and then reduce by a factor of three or so using pbmreduce. You can even correct the brightness of an image, by using the -value flag. OPTIONS

By default, the halftoning after the reduction is done via boustrophedonic Floyd-Steinberg error diffusion; however, the -threshold flag can be used to specify simple thresholding. This gives better results when reducing line drawings.

The -value flag alters the thresholding value for all quantizations. It should be a real number between 0 and 1. Above 0.5 means darker images; below 0.5 means lighter.

NAME pbmtext - render text into a bitmap SYNOPSIS pbmtext [-font fontfile] [text] DESCRIPTION

Takes the specified text, either a single line from the command line or multiple lines from standard input, and renders it into a bitmap. OPTIONS

By default, pbmtext uses a built-in font. You can also specify your own font with the -font flag. The fontfile is a pbm file, created in a very specific way. In your window system of choice, display the following text in the desired (fixed-width) font:

/ !"#$%&'()*+ / < ,-./01234567 < > 89:;<=>?@ABC > @ DEFGHIJKLMNO @ _ PQRSTUVWXYZ[ _ { ]ˆ_`abcdefg { } hijklmnopqrs } ˜ tuvwxyz{|}˜ ˜

Do a screen grab or window dump of that text, using for instance xwd, xgrabsc, or screendump. Convert the result into a pbm file. If necessary, use pnmcut to remove everything except the text. Finally, run it through pnmcrop to make sure the edges are right up against the text. pbmtext can figure out the sizes and spacings from that. SEE ALSO pbm(5), pnmcut(1), pnmcrop(1) AUTHOR ©1991 by Jef Poskanzer.

NAME pbmto10x - convert a portable bitmap into Gemini 10X printer graphics SYNOPSIS pbmto10x [-h] [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces a file of Gemini 10X printer graphics as output. The 10x's printer codes are alleged to be similar to the Epson codes.

The resolution is normally 60H by 72V. If the -h flag is specified, resolution is 120H by 144V. You may find it useful to rotate landscape images before printing. SEE ALSO pbm(5) AUTHOR ©1990 by Ken Yap.

NAME pbmtoascii - convert a portable bitmap into ASCII graphics SYNOPSIS pbmtoascii [-1x2|-2x4] [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces a somewhat crude ASCII graphic as output.

Note that there is no asciitopbm tool - this transformation is one-way. OPTIONS The -1x2 and -2x4 flags give you two alternate ways for the bits to get mapped to characters. With 1x2, the default, each character represents a group of 1 bit across by 2 bits down. With -2x4, each character represents 2 bits across by 4 bits down. With the 1x2 mode you can see the individual bits, so it's useful for previewing small bitmaps on a non-graphics terminal. The 2x4 mode lets you display larger bitmaps on a standard 80-column display, but it obscures bit-level details. 2x4 mode is also good for displaying graymaps - ``pnmscale -width 158 | pgmnorm | pgmtopbm -thresh'' should give good results. SEE ALSO pbm(5) AUTHOR ©1988, 1992 by Jef Poskanzer.

NAME pbmtoatk - convert portable bitmap to Andrew Toolkit raster object SYNOPSIS pbmtoatk [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces a Andrew Toolkit raster object as output. SEE ALSO atktopbm(1), pbm(5) AUTHOR ©1991 by Bill Janssen.

NAME pbmtobg - convert a portable bitmap into BitGraph graphics SYNOPSIS pbmtobg [rasterop] [x y] < pbmfile DESCRIPTION Reads a portable bitmap as input. Produces BBN BitGraph terminal Display Pixel Data (DPD) sequence as output.

The rasterop can be specified on the command line. If this is omitted, 3 (replace) will be used. A position in (x,y) coordinates can also be specified. If both are given, the rasterop comes first. The portable bitmap is always taken from the standard input.

NAME pbmtocmuwm - convert a portable bitmap into a CMU window manager bitmap SYNOPSIS pbmtocmuwm [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces a CMU window manager bitmap as output. SEE ALSO cmuwmtopbm(1), pbm(5) AUTHOR ©1989 by Jef Poskanzer.

NAME pbmtoepsi - convert a portable bitmap into an encapsulated PostScript style preview bitmap SYNOPSIS pbmtoepsi [-bbonly] [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produce an encapsulated Postscript style bitmap as output. The output is not a stand alone postscript file, it is only a preview bitmap, which can be included in an encapsulated PostScript file. Note that there is no epsitopbm tool - this transformation is one way.

This utility is a part of the pstoepsi tool by Doug Crabill (dgc@cs.purdue.edu). OPTIONS
$\begin{TPlist}{{\bf -bbonly}} \item[{{\bf -bbonly}}] Only create a boundary box, don't fill it with the image. \end{TPlist}$

NAME pbmtoepson - convert a portable bitmap into Epson printer graphics SYNOPSIS pbmtoepson [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces a file of Epson printer graphics as output.

NAME pbmtog3 - convert a portable bitmap into a Group 3 fax file SYNOPSIS pbmtog3 [pbmfile] DESCRIPTION Reads a portable bitmap as output. Produces a Group 3 fax file as input. REFERENCES The standard for Group 3 fax is defined in CCITT Recommendation T.4. BUGS Probably. SEE ALSO g3topbm(1), pbm(5) AUTHOR ©1989 by Paul Haeberli (paul@manray.sgi.com).

NAME pbmtogem - convert a portable bitmap into a GEM .img file SYNOPSIS pbmtogem [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces a GEM .img file as output. BUGS It does not support compression of the data. SEE ALSO gemtopbm(1), pbm(5) AUTHOR ©1988 by David Beckemeyer (bdt!david) and Jef Poskanzer.

NAME pbmtogo - convert a portable bitmap into compressed GraphOn graphics SYNOPSIS pbmtogo [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces 2D compressed GraphOn graphics as output. Be sure to set up your GraphOn with the following modes: 8 bits / no parity; obeys no XON/XOFF; NULs are accepted. These are all on the Comm menu. Also, remember to turn off tty post processing. Note that there is no gotopbm tool. SEE ALSO pbm(5) AUTHOR ©1988, 1989 by Jef Poskanzer, Michael Haberler, and Bo Thide'.

NAME pbmtoicon - convert a portable bitmap into a Sun icon SYNOPSIS pbmtoicon [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces a Sun icon as output. SEE ALSO icontopbm(1), pbm(5) AUTHOR ©1988 by Jef Poskanzer.

NAME pbmtolj - convert a portable bitmap into HP LaserJet format SYNOPSIS pbmtolj [-resolution N] [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces HP LaserJet data as output.

Note that there is no ljtopbm tool. OPTIONS
$\begin{TPlist}{{\bf -resolution}} \item[{{\bf -resolution}}] Specifies the resol... ...e, in dpi. Typical values are 75, 100, 150, 300. The default is 75. \end{TPlist}$

NAME pbmtoln03 - convert protable bitmap to DEC LN03+ Sixel output SYNOPSIS pbmtoln03 [-rltbf] pbmfile DESCRIPTION Reads a portable bitmap as input. Produces a DEC LN03+ Sixel output file. OPTIONS
$\begin{TPlist}{{\bf -l nn}} \item[{{\bf -l nn}}] Use \lq\lq nn'' as value for left ma... ...[{{\bf -f nn}}] Use \lq\lq nn'' as value for form length (default 3400). \end{TPlist}$

NAME pbmtolps - convert portable bitmap to PostScript SYNOPSIS pbmtolps [ -dpi n ] [ pbmfile ] DESCRIPTION Reads a portable bitmap as input, and outputs PostScript. The output Postscript uses lines instead of the image operator to generate a (device dependent) picture which will be imaged much faster.

The Postscript path length is constrained to be less that 1000 points so that no limits are overrun on the Apple Laserwriter and (presumably) no other printers. SEE ALSO pgmtops(1), ppmtops(1), pbm(5) AUTHOR ©George Phillips (phillips@cs.ubc.ca).

NAME pbmtomacp - convert a portable bitmap into a MacPaint file SYNOPSIS pbmtomacp [-l left] [-r right] [-b bottom] [-t top] [pbmfile] DESCRIPTION Reads a portable bitmap as input. If no input-file is given, standard input is assumed. Produces a MacPaint file as output.

The generated file is only the data fork of a picture. You will need a program such as mcvert to generate a Macbinary or a BinHex file that contains the necessary information to identify the file as a PNTG file to MacOS. OPTIONS

Left, right, bottom & top let you define a square into the pbm file, that must be converted. Default is the whole file. If the file is too large for a MacPaint-file, the bitmap is cut to fit from ( left, top ). BUGS The source code contains comments in a language other than English. SEE ALSO ppmtopict(1), macptopbm(1), pbm(5), mcvert(1) AUTHOR ©1988 by Douwe van der Schaaf (…!mcvax!uvapsy!vdschaaf).

NAME pbmtomgr - convert a portable bitmap into a MGR bitmap SYNOPSIS pbmtomgr [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces a MGR bitmap as output. SEE ALSO mgrtopbm(1), pbm(5) AUTHOR ©1989 by Jef Poskanzer.

NAME pbmtopgm - convert portable bitmap to portable graymap by averaging areas SYNOPSIS pbmtopgm <width> <height> [pbmfile] DESCRIPTION Reads a portable bitmap as input. Outputs a portable graymap created by averaging the number of pixels within a sample area of width by height around each point. Pbmtopgm is similar to a special case of ppmconvol. A ppmsmooth step may be needed after pbmtopgm.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. This software is provided "as is" without express or implied warranty. NOTES Pbmtopgm works best with odd sample width and heights.

NAME pbmtopi3 - convert a portable bitmap into an Atari Degas .pi3 file SYNOPSIS pbmtopi3 [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces an Atari Degas .pi3 file as output. SEE ALSO pi3topbm(1), pbm(5), ppmtopi1(1), pi1toppm(1) AUTHOR ©1988 by David Beckemeyer (bdt!david) and Jef Poskanzer.

NAME pbmtopk - convert a portable bitmap into a packed (PK) format font SYNOPSIS pbmtopk pkfile[.pk] tfmfile[.tfm] resolution [-s designsize] [-p num param...] [-C codingscheme] [-F family] [-f optfile] [-c num] [-W width] [-H height] [-D depth] [-I ital] [-h horiz] [-v vert] [-x xoff] [-y yoff] [pbmfile]... DESCRIPTION Reads portable bitmaps as input, and produces a packed (PK) font file and a TFM (TeX font metric) file as output. The resolution parameter indicates the resolution of the font, in dots per inch. If the filename ``-'' is used for any of the filenames, the standard input stream (or standard output where appropriate) will be used. OPTIONS
$\begin{IPlist} \IPitem{{-s\ designsize}} Sets the design size of the font, in Te... ...offset of the next character to yoff (in pixels, from the top row). \end{IPlist}$

SEE ALSO pktopbm(1), pbm(5) AUTHOR Adapted from Tom Rokicki's pxtopk by Angus Duggan (ajcd@dcs.ed.ac.uk).

NAME pbmtoplot - convert a portable bitmap into a Unix plot(5) file SYNOPSIS pbmtoplot [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces a Unix plot file.

NAME pbmtoptx - convert a portable bitmap into Printronix printer graphics SYNOPSIS pbmtoptx [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces a file of Printronix printer graphics as output.

NAME pbmtox10bm - convert a portable bitmap into an X10 bitmap SYNOPSIS pbmtox10bm [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces an X10 bitmap as output. This older format is maintained for compatibility.

NAME pbmtoxbm - convert a portable bitmap into an X11 bitmap SYNOPSIS pbmtoxbm [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces an X11 bitmap as output. SEE ALSO pbmtox10bm(1), xbmtopbm(1), pbm(5) AUTHOR ©1988 by Jef Poskanzer.

NAME pgmtoybm - convert a portable bitmap into a Bennet Yee ``face'' file SYNOPSIS pbmtoybm [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces as output a file acceptable to the face and xbm programs by Bennet Yee (bsy+@cs.cmu.edu). SEE ALSO ybmtopbm(1), pbm(5), face(1), face(5), xbm(1) AUTHOR ©1991 by Jamie Zawinski and Jef Poskanzer.

NAME pbmtozinc - convert a portable bitmap into a Zinc bitmap SYNOPSIS pbmtozinc [pbmfile] DESCRIPTION Reads a portable bitmap as input. Produces a bitmap in the format used by the Zinc Interface Library (ZIL) Version 1.0 as output. SEE ALSO pbm(5) AUTHOR ©1988 by James Darrell McCauley (jdm5548@diamond.tamu.edu) and Jef Poskanzer.

NAME pbmupc - create a Universal Product Code bitmap SYNOPSIS pbmupc [-s1|-s2] type manufac product DESCRIPTION Generates a Universal Product Code symbol. The three arguments are: a one digit product type, a five digit manufacturer code, and a five digit product code. For example, ``0 72890 00011'' is the code for Heineken.

As presently configured, pbmupc produces a bitmap 230 bits wide and 175 bits high. The size can be altered by changing the defines at the beginning of the program, or by running the output through pnmenlarge or pnmscale. OPTIONS

The -s1 and -s2 flags select the style of UPC to generate. The default, -s1, looks more or less like this: |||||||||||||||| |||||||||||||||| |||||||||||||||| |||||||||||||||| 0||12345||67890||5 The other style, -s2, puts the product type digit higher up, and doesn't display the checksum digit: |||||||||||||||| |||||||||||||||| 0|||||||||||||||| |||||||||||||||| ||12345||67890|| SEE ALSO pbm(5) AUTHOR ©1989 by Jef Poskanzer.

NAME pcxtoppm - convert a PCX file into a portable pixmap SYNOPSIS pcxtoppm [pcxfile] DESCRIPTION Reads a PCX file as input. Produces a portable pixmap as output. SEE ALSO ppmtopcx(1), ppm(5) AUTHOR ©1990 by Michael Davidson.

NAME pgm - portable graymap file format DESCRIPTION The portable graymap format is a lowest common denominator grayscale file format. The definition is as follows:
$\begin{IPlist} \IPitem{{-}} A \lq\lq magic number'' for identifying the file type. A ... ...omments). \IPitem{{-}} No line should be longer than 70 characters. \end{IPlist}$

Here is an example of a small graymap in this format: P2 # feep.pgm 24 7 15 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 3 3 3 0 0 7 7 7 7 0 0 11 11 11 11 0 0 15 15 15 15 0 0 3 0 0 0 0 0 7 0 0 0 0 0 11 0 0 0 0 0 15 0 0 15 0 0 3 3 3 0 0 0 7 7 7 0 0 0 11 11 11 0 0 0 15 15 15 15 0 0 3 0 0 0 0 0 7 0 0 0 0 0 11 0 0 0 0 0 15 0 0 0 0 0 3 0 0 0 0 0 7 7 7 7 0 0 11 11 11 11 0 0 15 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

Programs that read this format should be as lenient as possible, accepting anything that looks remotely like a graymap.

There is also a variant on the format, available by setting the RAWBITS option at compile time. This variant is different in the following ways:
$\begin{IPlist} \IPitem{{-}} The \lq\lq magic number'' is \lq\lq P5'' instead of \lq\lq P2''. \I... ...{-}} The files are smaller and many times faster to read and write. \end{IPlist}$

Note that this raw format can only be used for maxvals less than or equal to 255. If you use the pgm library and try to write a file with a larger maxval, it will automatically fall back on the slower but more general plain format. SEE ALSO fitstopgm(1), fstopgm(1), hipstopgm(1), lispmtopgm(1), psidtopgm(1), rawtopgm(1), pgmbentley(1), pgmcrater(1), pgmedge(1), pgmenhance(1), pgmhist(1), pgmnorm(1), pgmoil(1), pgmramp(1), pgmtexture(1), pgmtofits(1), pgmtofs(1), pgmtolispm(1), pgmtopbm(1), pnm(5), pbm(5), ppm(5) AUTHOR ©1989, 1991 by Jef Poskanzer.

NAME pgmbentley - Bentleyize a portable graymap SYNOPSIS pgmbentley [pgmfile] DESCRIPTION Reads a portable graymap as input. Performs The Bentley Effect, and writes a portable graymap as output.

The Bentley Effect is described in ``Beyond Photography'' by Holzmann, chapter 4, photo 4. It's a vertical smearing based on brightness. SEE ALSO pgmoil(1), ppmrelief(1), pgm(5) AUTHOR ©1990 by Wilson Bent (whb@hoh-2.att.com).

pgmcrater 'ti 15 [-number n] [-height|-ysize s] [-width|-xsize s] [-gamma g] DESCRIPTION pgmcrater creates a portable graymap which mimics cratered terrain. The graymap is created by simulating the impact of a given number of craters with random position and size, then rendering the resulting terrain elevations based on a light source shining from one side of the screen. The size distribution of the craters is based on a power law which results in many more small craters than large ones. The number of craters of a given size varies as the reciprocal of the area as described on pages 31 and 32 of Peitgen and Saupe[1]; cratered bodies in the Solar System are observed to obey this relationship. The formula used to obtain crater radii governed by this law from a uniformly distributed pseudorandom sequence was developed by Rudy Rucker.

High resolution images with large numbers of craters often benefit from being piped through pnmsmooth. The averaging performed by this process eliminates some of the jagged pixels and lends a mellow ``telescopic image'' feel to the overall picture. OPTIONS
$\begin{TPlist}{{\bf -number}{\it\ n} } \item[{{\bf -number}{\it\ n} }] Causes {\... ...st, while values less than 1 darken the image, increasing contrast. \end{TPlist}$

All flags can be abbreviated to their shortest unique prefix. BUGS The -gamma option isn't really necessary since you can achieve the same effect by piping the output from pgmcrater through pnmgamma. However, pgmcrater performs an internal gamma map anyway in the process of rendering the elevation array into a graymap, so there's no additional overhead in allowing a user-specified gamma.

Real craters have two distinct morphologies. pgmcrater simulates only small craters, which are hemispherical in shape (regardless of the incidence angle of the impacting body, as long as the velocity is sufficiently high). Large craters, such as Copernicus and Tycho on the Moon, have a ``walled plain'' shape with a cross-section more like: // _____/ ____________/____________/ _____ Larger craters should really use this profile, including the central peak, and totally obliterate the pre-existing terrain. SEE ALSO pgm(5), pnmgamma(1), pnmsmooth(1)
$\begin{TPlist}{[1]} \item[{[1]}] Peitgen, H.-O., and Saupe, D. eds., The Science Of Fractal Images, New York: Springer Verlag, 1988. \end{TPlist}$

AUTHOR 1 John Walker Autodesk SA Avenue des Champs-Montants 14b CH-2074 MARIN Suisse/Schweiz/Svizzera/Svizra/Switzerland
$\begin{TPlist}{Usenet:} \item[{Usenet:}] kelvin@Autodesk.com \item[{Fax:}] 038/33 88 15 \item[{Voice:}] 038/33 76 33 \end{TPlist}$

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, without any conditions or restrictions. This software is provided ``as is'' without express or implied warranty.

PLUGWARE! If you like this kind of stuff, you may also enjoy ``James Gleick's Chaos–The Software'' for MS-DOS, available for $59.95 from your local software store or directly from Autodesk, Inc., Attn: Science Series, 2320 Marinship Way, Sausalito, CA 94965, USA. Telephone: (800) 688-2344 toll-free or, outside the U.S. (415) 332-2344 Ext 4886. Fax: (415) 289-4718. ``Chaos–The Software'' includes a more comprehensive fractal forgery generator which creates three-dimensional landscapes as well as clouds and planets, plus five more modules which explore other aspects of Chaos. The user guide of more than 200 pages includes an introduction by James Gleick and detailed explanations by Rudy Rucker of the mathematics and algorithms used by each program.

pgmedge104 February 1990

NAME pgmedge - edge-detect a portable graymap SYNOPSIS pgmedge [pgmfile] DESCRIPTION Reads a portable graymap as input. Outlines the edges, and writes a portable graymap as output. Piping the result through pgmtopbm -threshold and playing with the threshold value will give a bitmap of the edges.

The edge detection technique used is to take the Pythagorean sum of two Sobel gradient operators at 90 degrees to each other. For more details see ``Digital Image Processing'' by Gonzalez and Wintz, chapter 7. SEE ALSO pgmenhance(1), pgmtopbm(1), pgm(5), pbm(5) AUTHOR ©1991 by Jef Poskanzer.

pgmenhance113 January 1989

NAME pgmenhance - edge-enhance a portable graymap SYNOPSIS pgmenhance [-N] [pgmfile] DESCRIPTION Reads a portable graymap as input. Enhances the edges, and writes a portable graymap as output.

The edge enhancing technique is taken from Philip R. Thompson's ``xim'' program, which in turn took it from section 6 of ``Digital Halftones by Dot Diffusion'', D. E. Knuth, ACM Transaction on Graphics Vol. 6, No. 4, October 1987, which in turn got it from two 1976 papers by J. F. Jarvis et. al. OPTIONS

pgmhist128 February 1989

NAME pgmhist - print a histogram of the values in a portable graymap SYNOPSIS pgmhist [pgmfile] DESCRIPTION Reads a portable graymap as input. Prints a histogram of the gray values. SEE ALSO pgmnorm(1), pgm(5), ppmhist(1) AUTHOR ©1989 by Jef Poskanzer.

pgmkernel110 December 1992

NAME pgmkernel - generate a convolution kernel SYNOPSIS pgmkernel [–weightw] width [height] DESCRIPTION Generates a portable graymap array of size width x height (or width x width if height is not specified) to be used as a convolution file by pnmconvol. The data in the convolution array K are computed according to the formula:

K(i,j) = 1 / ( 1 + w * sqrt((i-width/2)ˆ2 + (j-height/2)ˆ2))

where w is a coefficient specified via the –weight flag, and width and height are the X and Y filter sizes.

The output PGM file is always written out in ASCII format. OPTIONS The optional -weight flag should be a real number greater than -1. The default value is 6.0. BUGS The computation time is proportional to width * height. This increases rapidly with the increase of the kernel size. A better approach could be using a FFT in these cases. SEE ALSO pnmconvol(1), pnmsmooth(1) AUTHOR Alberto Accomazzi (alberto@cfa.harvard.edu).

pgmnoise116 November 1993

NAME pgmnoise - create a graymap made up of white noise SYNOPSIS pgmnoise width height DESCRIPTION Creates a portable graymap that is made up of random pixels with gray values in the range of 0 to PGM_MAXMAXVAL (depends on the compilation, either 255 or 65535). The graymap has a size of width * height pixels. SEE ALSO pgm(5) AUTHOR ©1993 by Frank Neumann.

pgmnorm128 February 1989

NAME pgmnorm - normalize the contrast in a portable graymap SYNOPSIS pgmnorm [-bpercent N | -bvalue N] [-wpercent N | -wvalue N] [pgmfile] DESCRIPTION Reads a portable graymap as input. Normalizes the contrast by forcing the lightest pixels to white, the darkest pixels to black, and linearly rescaling the ones in between; and produces a portable graymap as output. OPTIONS

By default, the darkest 2 percent of all pixels are mapped to black, and the lightest 1 percent are mapped to white. You can override these percentages by using the -bpercent and -wpercent flags, or you can specify the exact pixel values to be mapped by using the -bvalue and -wvalue flags. Appropriate numbers for the flags can be gotten from the pgmhist tool. If you just want to enhance the contrast, then choose values at elbows in the histogram; e.g., if value 29 represents 3% of the image but value 30 represents 20%, choose 30 for bvalue. If you want to lighten the image, then set bvalue to 0 and just fiddle with wvalue; similarly, to darken the image, set wvalue to maxval and play with bvalue.

All flags can be abbreviated to their shortest unique prefix. SEE ALSO pgmhist(1), pgm(5) AUTHOR Partially based on the fbnorm filter in Michael Mauldin's ``Fuzzy Pixmap'' package.

pgmoil111 January 1991

NAME pgmoil - turn a portable graymap into an oil painting SYNOPSIS pgmoil [-n N] [pgmfile] DESCRIPTION Reads a portable graymap as input. Does an ``oil transfer'', and writes a portable graymap as output.

The oil transfer is described in ``Beyond Photography'' by Holzmann, chapter 4, photo 7. It's a sort of localized smearing. OPTIONS

The optional -n flag controls the size of the area smeared. The default value is 3. BUGS Takes a long time to run. SEE ALSO pgmbentley(1), ppmrelief(1), pgm(5) AUTHOR ©1990 by Wilson Bent (whb@hoh-2.att.com).

pgmramp124 November 1989

NAME pgmramp - generate a grayscale ramp SYNOPSIS pgmramp -lr|-tb | -rectangle|-ellipse width height DESCRIPTION Generates a graymap of the specified size containing a black-to-white ramp. These ramps are useful for multiplying with other images, using the pnmarith tool. OPTIONS
$\begin{TPlist}{{\bf -lr}} \item[{{\bf -lr}}] A left to right ramp. \item[{{\bf -... ...}}] A rectangular ramp. \item[{{\bf -ellipse}}] An elliptical ramp. \end{TPlist}$

pgmtexture122 Aug 1991

NAME pgmtexture - calculate textural features on a portable graymap SYNOPSIS pgmtexture [-d d] [pgmfile] DESCRIPTION Reads a portable graymap as input. Calculates textural features based on spatial dependence matrices at 0, 45, 90, and 135 degrees for a distance d (default = 1). Textural features include:
$\begin{IPlist} \IPitem{{}} (1) Angular Second Moment, \nwl (2) Contrast, \nwl (3... ...ures of Correlation, and \nwl (14) Maximal Correlation Coefficient. \end{IPlist}$

Algorithm taken from: Haralick, R.M., K. Shanmugam, and I. Dinstein. 1973. Textural features for image classification. IEEE Transactions on Systems, Man, and Cybertinetics, SMC-3(6):610-621. BUGS The program can run incredibly slow for large images (larger than 64 x 64) and command line options are limited. The method for finding (14) the maximal correlation coefficient, which requires finding the second largest eigenvalue of a matrix Q, does not always converge. REFERENCES IEEE Transactions on Systems, Man, and Cybertinetics, SMC-3(6):610-621. SEE ALSO pgm(5), pnmcut(1) AUTHOR ©1991 by Texas Agricultural Experiment Station, employer for hire of James Darrell McCauley.

pgmtofits120 September 1989

NAME pgmtofits - convert a portable graymap into FITS format SYNOPSIS pgmtofits [pgmfile] DESCRIPTION Reads a portable graymap as input. Produces a FITS file as output.

FITS stands for Flexible Image Transport System. A full description can be found in Astronomy & Astrophysics Supplement Series 44 (1981), page 363. SEE ALSO fitstopgm(1), pgm(5) AUTHOR ©1989 by Wilson H. Bent (whb@hoh-2.att.com).

NAME pgmtofs - convert portable graymap to Usenix FaceSaver(tm) format SYNOPSIS pgmtofs [pgmfile] DESCRIPTION Reads a portable graymap as input. Produces Usenix FaceSaver(tm) format as output.

pgmtolispm106 March 1990

NAME pgmtolispm - convert a portable graymap into Lisp Machine format SYNOPSIS pgmtolispm [pgmfile] DESCRIPTION Reads a portable graymap as input. Produces a Lisp Machine bitmap as output.

This is the file format read by the tv:read-bit-array-file function on TI Explorer and Symbolics lisp machines.

Given a pgm (instead of a pbm) a multi-plane image will be output. This is probably not useful unless you have a color lisp machine.

Multi-plane bitmaps on lisp machines are color; but the lispm image file format does not include a color map, so we must treat it as a graymap instead. This is unfortunate. SEE ALSO lispmtopgm(1), pgm(5) BUGS Output width is always rounded up to the nearest multiple of 32; this might not always be what you want, but it probably is (arrays which are not modulo 32 cannot be passed to the Lispm BITBLT function, and thus cannot easily be displayed on the screen).

pgmtopbm126 July 1988

Note that there is no pbmtopgm converter, because any pgm program can read pbm files automagically. OPTIONS

The default quantization method is boustrophedonic Floyd-Steinberg error diffusion (-floyd or -fs). Also available are simple thresholding (-threshold); Bayer's ordered dither (-dither8) with a 16x16 matrix; and three different sizes of 45-degree clustered-dot dither (-cluster3, -cluster4, -cluster8).

Floyd-Steinberg will almost always give the best looking results; however, looking good is not always what you want. For instance, thresholding can be used in a pipeline with the pnmconvol tool, for tasks like edge and peak detection. And clustered-dot dithering gives a newspaper-ish look, a useful special effect.

The -value flag alters the thresholding value for Floyd-Steinberg and simple thresholding. It should be a real number between 0 and 1. Above 0.5 means darker images; below 0.5 means lighter.

All flags can be abbreviated to their shortest unique prefix. REFERENCES The only reference you need for this stuff is ``Digital Halftoning'' by Robert Ulichney, MIT Press, ISBN 0–262–21009–6. SEE ALSO pbmreduce(1), pgm(5), pbm(5), pnmconvol(1) AUTHOR ©1989 by Jef Poskanzer.

pgmtoppm111 January 1991

NAME pgmtoppm - colorize a portable graymap into a portable pixmap SYNOPSIS pgmtoppm colorspec [pgmfile] pgmtoppm colorspec1-colorspec2 [pgmfile] pgmtoppm -map mapfile [pgmfile] DESCRIPTION Reads a portable graymap as input. Colorizes it by multiplying the the gray values by specified color or colors, and produces a portable pixmap as output.

If only one color is specified, black in the pgm file stays black and white in the pgm file turns into the specified color in the ppm file. If two colors (separated by a dash) are specified, then black gets mapped to the first color and white gets mapped to the second.

The color can be specified in five ways:
$\begin{TPlist}{o} \item[{o}] A name, assuming that a pointer to an X11-style col... ...is style was added before MIT came up with the similar rgbi style.) \end{TPlist}$

Also, the -map flag lets you specify an entire colormap to be used. The mapfile is just a ppm file; it can be any shape, all that matters is the colors in it and their order. In this case, black gets mapped into the first color in the map file, and white gets mapped to the last. SEE ALSO rgb3toppm(1), ppmtopgm(1), ppmtorgb3(1), ppm(5), pgm(5) AUTHOR ©1991 by Jef Poskanzer.

pi1toppm119 July 1990

NAME pi1toppm - convert an Atari Degas .pi1 into a portable pixmap SYNOPSIS pi1toppm [pi1file] DESCRIPTION Reads an Atari Degas .pi1 file as input. Produces a portable pixmap as output. SEE ALSO ppmtopi1(1), ppm(5), pi3topbm(1), pbmtopi3(1) AUTHOR ©1991 by Steve Belczyk (seb3@gte.com) and Jef Poskanzer.

pi3topbm111 March 1990

NAME pi3topbm - convert an Atari Degas .pi3 file into a portable bitmap SYNOPSIS pi3topbm [pi3file] DESCRIPTION Reads an Atari Degas .pi3 file as input. Produces a portable bitmap as output. SEE ALSO pbmtopi3(1), pbm(5), pi1toppm(1), ppmtopi1(1) AUTHOR ©1988 by David Beckemeyer (bdt!david) and Diomidis D. Spinellis.

picttoppm129 November 1991

NAME picttoppm - convert a Macintosh PICT file into a portable pixmap SYNOPSIS picttoppm [-verbose] [-fullres] [-noheader] [pictfile] DESCRIPTION Reads a PICT file (version 1 or 2) and outputs a portable pixmap. Useful as the first step in converting a scanned image to something that can be displayed on Unix. OPTIONS
$\begin{TPlist}{{\bf --fullres}} \item[{{\bf --fullres}}] Force any images in the... ...of information that only {\it picttoppm} hackers really care about. \end{TPlist}$

BUGS The PICT file format is a general drawing format. picttoppm only supports a small subset of its operations but is still very useful for files produced by scanning software. In particular, text added to a scanned image will be silently ignored. SEE ALSO Inside Macintosh volume 5, ppmtopict(1), ppm(5) AUTHOR ©1989 George Phillips (phillips@cs.ubc.ca).

pjtoppm114 July 1991

NAME pjtoppm - convert an HP PaintJet file to a portable pixmap SYNOPSIS pjtoppm [paintjet] DESCRIPTION Reads an HP PaintJet file as input and converts it into a portable pixmap. This was a quick hack to save some trees, and it only handles a small subset of the paintjet commands. In particular, it will only handle enough commands to convert most raster image files. REFERENCES HP PaintJet XL Color Graphics Printer User's Guide SEE ALSO ppmtopj(1) AUTHOR ©1991 by Christos Zoulas.

pktopbm16 August 1990

NAME pktopbm - convert packed (PK) format font into portable bitmap(s) SYNOPSIS pktopbm pkfile[.pk] [-c num] pbmfile ... DESCRIPTION Reads a packed (PK) font file as input, and produces portable bitmaps as output. If the filename ``-'' is used for any of the filenames, the standard input stream (or standard output where appropriate) will be used. OPTIONS
$\begin{IPlist} \IPitem{{-c\ num}} Sets the character number of the next bitmap written to num. \end{IPlist}$

SEE ALSO pbmtopk(1), pbm(5) AUTHOR Adapted from Tom Rokicki's pxtopk by Angus Duggan (ajcd@dcs.ed.ac.uk.

pnm527 September 1991

NAME pnm - portable anymap file format DESCRIPTION The pnm programs operate on portable bitmaps, graymaps, and pixmaps, produced by the pbm, pgm, and ppm segments. There is no file format associated with pnm itself. SEE ALSO anytopnm(1), rasttopnm(1), tifftopnm(1), xwdtopnm(1), pnmtops(1), pnmtorast(1), pnmtotiff(1), pnmtoxwd(1), pnmarith(1), pnmcat(1), pnmconvol(1), pnmcrop(1), pnmcut(1), pnmdepth(1), pnmenlarge(1), pnmfile(1), pnmflip(1), pnmgamma(1), pnmindex(1), pnminvert(1), pnmmargin(1), pnmnoraw(1), pnmpaste(1), pnmrotate(1), pnmscale(1), pnmshear(1), pnmsmooth(1), pnmtile(1), ppm(5), pgm(5), pbm(5) AUTHOR ©1989, 1991 by Jef Poskanzer.

pnmalias130 April 1992

NAME pnmalias - antialias a portable anyumap. SYNOPSIS pnmalias [-bgcolor color] [-fgcolor color] [-bonly] [-fonly] [-balias] [-falias] [-weight w] [pnmfile] DESCRIPTION Reads a portable anymap as input, and applies anti-aliasing to background and foreground pixels. If the input file is a portable bitmap, the output anti-aliased image is promoted to a graymap, and a message is printed informing the user of the change in format. OPTIONS

–bgcolor colorb, –fgcolor colorf 1set the background color to colorb, and the foreground to color to colorf. Pixels with these values will be anti-aliased. by default, the background color is taken to be black, and foreground color is assumed to be white. The colors can be specified in five ways:
$\begin{TPlist}{{\bf o}} \item[{{\bf o}}] A name, assuming that a pointer to an X... ...is style was added before MIT came up with the similar rgbi style.) \end{TPlist}$

Note that even when dealing with graymaps, background and foreground colors need to be specified in the fashion described above. In this case, background and foreground pixel values are taken to be the value of the red component for the given color. 1

–bonly, –fonly 1Apply anti-aliasing only to background (–bonly), or foreground (–fonly) pixels. 1

–balias, –falias 1Apply anti-aliasing to all pixels surrounding background (–balias), or foreground (–falias) pixels. By default, anti-aliasing takes place only among neighboring background and foreground pixels. 1

–weight w 1Use w as the central weight for the aliasing filter. W must be a real number in the range 0 < w < 1. The lower the value of w is, the ``blurrier'' the output image is. The default is w = 1/3. SEE ALSO pbmtext(1), pnmsmooth(1), pnm(5) AUTHOR Copyright (C) 1992 by Alberto Accomazzi, Smithsonian Astrophysical Observatory.

pnmarith126 August 1993

NAME pnmarith - perform arithmetic on two portable anymaps SYNOPSIS pnmarith -add|-subtract|-multiply|-difference pnmfile1 pnmfile2 DESCRIPTION Reads two portable anymaps as input. Performs the specified arithmetic operation, and produces a portable anymap as output. The two input anymaps must be the same width and height.

The arithmetic is performed between corresponding pixels in the two anymaps, as if maxval was 1.0, black was 0.0, and a linear scale in between. Results that fall outside of [0..1) are truncated.

The operator -difference calculates the absolute value of pnmarith -subtract pnmfile1 pnmfile2, i.e., no truncation is done.

All flags can be abbreviated to their shortest unique prefix. SEE ALSO pbmmask(1), pnmpaste(1), pnminvert(1), pnm(5) AUTHOR ©1989, 1991 by Jef Poskanzer.. Lightly modified by Marcel Wijkstra (wijkstra@fwi.uva.nl).

pnmcat112 March 1989

NAME pnmcat - concatenate portable anymaps SYNOPSIS pnmcat [-white|-black] -leftright|-lr [-jtop|-jbottom] pnmfile pnmfile ... pnmcat [-white|-black] -topbottom|-tb [-jleft|-jright] pnmfile pnmfile ... DESCRIPTION Reads portable anymaps as input. Concatenates them either left to right or top to bottom, and produces a portable anymap as output. OPTIONS

If the anymaps are not all the same height (left-right) or width (top-bottom), the smaller ones have to be justified with the largest. By default, they get centered, but you can specify one side or the other with one of the -j* flags. So, -topbottom -jleft would stack the anymaps on top of each other, flush with the left edge.

The -white and -black flags specify what color to use to fill in the extra space when doing this justification. If neither is specified, the program makes a guess.

pnmcomp121 February 1989

NAME pnmcomp - composite two portable anymap files together SYNOPSIS pnmcomp [-invert] [-xoffN] [-yoffN] [-alphapgmfile] overlay [pnm-input] [pnm-output] DESCRIPTION Reads in a portable any map image and put a overlay upon it, with optional alpha mask. The -alpha pgmfile allows you to also add an alpha mask file to the compositing process, the range of max and min can be swapped by using the -invert option. The -xoff and -yoff arguments can be negative, allowing you to shift the overlay off the top corner of the screen. SEE ALSO pnm(5) AUTHOR ©1992 by David Koblas (koblas@mips.com).

pnmconvol113 January 1991

NAME pnmconvol - general MxN convolution on a portable anymap SYNOPSIS pnmconvol convolutionfile [pnmfile] DESCRIPTION Reads two portable anymaps as input. Convolves the second using the first, and writes a portable anymap as output.

Convolution means replacing each pixel with a weighted average of the nearby pixels. The weights and the area to average are determined by the convolution matrix. The unsigned numbers in the convolution file are offset by -maxval/2 to make signed numbers, and then normalized, so the actual values in the convolution file are only relative.

Here is a sample convolution file; it does a simple average of the nine immediate neighbors, resulting in a smoothed image: P2 3 3 18 10 10 10 10 10 10 10 10 10

To see how this works, do the above-mentioned offset: 10 - 18/2 gives 1. The possible range of values is from 0 to 18, and after the offset that's -9 to 9. The normalization step makes the range -1 to 1, and the values get scaled correspondingly so they become 1/9 - exactly what you want. The equivalent matrix for 5x5 smoothing would have maxval 50 and be filled with 26.

The convolution file will usually be a graymap, so that the same convolution gets applied to each color component. However, if you want to use a pixmap and do a different convolution to different colors, you can certainly do that. SEE ALSO pnmsmooth(1), pnm(5) AUTHOR ©1989, 1991 by Jef Poskanzer.

pnmcrop125 February 1989

NAME pnmcrop - crop a portable anymap SYNOPSIS pnmcrop [-white|-black] [-left] [-right] [-top] [-bottom] [pnmfile] DESCRIPTION Reads a portable anymap as input. Removes edges that are the background color, and produces a portable anymap as output. OPTIONS

By default, it makes a guess as to what the background color is. You can override the default with the -white and -black flags.

The options -left, -right, -top and -bottom restrict cropping to the sides specified. The default is to crop all sides of the image.

pnmcut121 February 1989

NAME pnmcut - cut a rectangle out of a portable anymap SYNOPSIS pnmcut x y width height [pnmfile] DESCRIPTION Reads a portable anymap as input. Extracts the specified rectangle, and produces a portable anymap as output. The x and y can be negative, in which case they are interpreted relative to the right and bottom of the anymap, respectively. SEE ALSO pnm(5) AUTHOR ©1989 by Jef Poskanzer.

pnmdepth112 January 1991

NAME pnmdepth - change the maxval in a portable anymap SYNOPSIS pnmdepth newmaxval [pnmfile] DESCRIPTION Reads a portable anymap as input. Scales all the pixel values, and writes out the image with the new maxval. Scaling the colors down to a smaller maxval will result in some loss of information.

Be careful of off-by-one errors when choosing the new maxval. For instance, if you want the color values to be five bits wide, use a maxval of 31, not 32. SEE ALSO pnm(5), ppmquant(1), ppmdither(1) AUTHOR ©1989, 1991 by Jef Poskanzer.

pnmenlarge126 February 1989

NAME pnmenlarge - read a portable anymap and enlarge it N times SYNOPSIS pnmenlarge N [pnmfile] DESCRIPTION Reads a portable anymap as input. Replicates its pixels N times, and produces a portable anymap as output.

pnmenlarge can only enlarge by integer factors. The slower but more general pnmscale can enlarge or reduce by arbitrary factors, and pbmreduce can reduce by integer factors, but only for bitmaps.

If you enlarge by a factor of 3 or more, you should probably add a pnmsmooth step; otherwise, you can see the original pixels in the resulting image. SEE ALSO pbmreduce(1), pnmscale(1), pnmsmooth(1), pnm(5) AUTHOR ©1989 by Jef Poskanzer.

pnmfile19 January 1991

NAME pnmfile - describe a portable anymap SYNOPSIS pnmfile [pnmfile] ... DESCRIPTION Reads one or more portable anymaps as input. Writes out short descriptions of the image type, size, etc. This is mostly for use in shell scripts, so the format is not particularly pretty. SEE ALSO pnm(5), file(1) AUTHOR ©1991 by Jef Poskanzer.

pnmflip125 July 1989

NAME pnmflip - perform one or more flip operations on a portable anymap SYNOPSIS pnmflip [-leftright|-lr] [-topbottom|-tb] [-transpose|-xy] [-rotate90|-r90|-ccw ] [-rotate270|-r270|-cw ] [-rotate180|-r180] [pnmfile] DESCRIPTION Reads a portable anymap as input. Performs one or more flip operations, in the order specified, and writes out a portable anymap. OPTIONS

The flip operations available are: left for right (-leftright or -lr); top for bottom (-topbottom or -tb); and transposition (-transpose or -xy). In addition, some canned concatenations are available: -rotate90 or -ccw is equivalent to -transpose -topbottom; -rotate270 or -cw is equivalent to -transpose -leftright; and -rotate180 is equivalent to -leftright -topbottom.

pnmgamma112 January 1991

NAME pnmgamma - perform gamma correction on a portable anymap SYNOPSIS pnmgamma value [pnmfile] pnmgamma redvalue greenvalue bluevalue [pnmfile] DESCRIPTION Reads a portable anymap as input. Performs gamma correction, and produces a portable anymap as output.

The arguments specify what gamma value(s) to use. A value of 1.0 leaves the image alone, less than one darkens it, and greater than one lightens it. SEE ALSO pnm(5) AUTHOR ©1991 by Bill Davidson and Jef Poskanzer.

pnminvert108 August 1989

NAME pnminvert - invert a portable anymap SYNOPSIS pnminvert [pnmfile] DESCRIPTION Reads a portable anymap as input. Inverts it black for white and produces a portable anymap as output. SEE ALSO pnm(5) AUTHOR ©1989 by Jef Poskanzer.

pnmnlfilt15 February 1993

NAME pnmnlfilt - non-linear filters: smooth, alpha trim mean, optimal estimation smoothing, edge enhancement. SYNOPSIS pnmnlfilt alpha radius [pnmfile] DESCRIPTION This is something of a swiss army knife filter. It has 3 distinct operating modes. In all of the modes each pixel in the image is examined and processed according to it and its surrounding pixels values. Rather than using the 9 pixels in a 3x3 block, 7 hexagonal area samples are taken, the size of the hexagons being controlled by the radius parameter. A radius value of 0.3333 means that the 7 hexagons exactly fit into the center pixel (i.e., there will be no filtering effect). A radius value of 1.0 means that the 7 hexagons exactly fit a 3x3 pixel array. Alpha trimmed mean filter. (0.0 <= alpha <= 0.5)

The value of the center pixel will be replaced by the mean of the 7 hexagon values, but the 7 values are sorted by size and the top and bottom alpha portion of the 7 are excluded from the mean. This implies that an alpha value of 0.0 gives the same sort of output as a normal convolution (i.e., averaging or smoothing filter), where radius will determine the ``strength'' of the filter. A good value to start from for subtle filtering is alpha = 0.0, radius = 0.55 For a more blatant effect, try alpha 0.0 and radius 1.0

An alpha value of 0.5 will cause the median value of the 7 hexagons to be used to replace the center pixel value. This sort of filter is good for eliminating ``pop'' or single pixel noise from an image without spreading the noise out or smudging features on the image. Judicious use of the radius parameter will fine tune the filtering. Intermediate values of alpha give effects somewhere between smoothing and ``pop'' noise reduction. For subtle filtering try starting with values of alpha = 0.4, radius = 0.6 For a more blatant effect try alpha = 0.5, radius = 1.0 Optimal estimation smoothing. (1.0 <= alpha <= 2.0)

This type of filter applies a smoothing filter adaptively over the image. For each pixel the variance of the surrounding hexagon values is calculated, and the amount of smoothing is made inversely proportional to it. The idea is that if the variance is small then it is due to noise in the image, while if the variance is large, it is because of ``wanted'' image features. As usual the radius parameter controls the effective radius, but it probably advisable to leave the radius between 0.8 and 1.0 for the variance calculation to be meaningful. The alpha parameter sets the noise threshold, over which less smoothing will be done. This means that small values of alpha will give the most subtle filtering effect, while large values will tend to smooth all parts of the image. You could start with values like alpha = 1.2, radius = 1.0 and try increasing or decreasing the alpha parameter to get the desired effect. This type of filter is best for filtering out dithering noise in both bitmap and color images. Edge enhancement. (-0.1 >= alpha >= -0.9)

This is the opposite type of filter to the smoothing filter. It enhances edges. The alpha parameter controls the amount of edge enhancement, from subtle (-0.1) to blatant (-0.9). The radius parameter controls the effective radius as usual, but useful values are between 0.5 and 0.9. Try starting with values of alpha = 0.3, radius = 0.8 Combination use.

The various modes of pnmnlfilt can be used one after the other to get the desired result. For instance to turn a monochrome dithered image into a grayscale image you could try one or two passes of the smoothing filter, followed by a pass of the optimal estimation filter, then some subtle edge enhancement. Note that using edge enhancement is only likely to be useful after one of the non-linear filters (alpha trimmed mean or optimal estimation filter), as edge enhancement is the direct opposite of smoothing.

For reducing color quantization noise in images (i.e., turning .gif files back into 24 bit files) you could try a pass of the optimal estimation filter (alpha 1.2, radius 1.0), a pass of the median filter (alpha 0.5, radius 0.55), and possibly a pass of the edge enhancement filter. Several passes of the optimal estimation filter with declining alpha values are more effective than a single pass with a large alpha value. As usual, there is a tradeoff between filtering effectiveness and loosing detail. Experimentation is encouraged. References:

The alpha-trimmed mean filter is based on the description in IEEE CG&A May 1990 Page 23 by Mark E. Lee and Richard A. Redner, and has been enhanced to allow continuous alpha adjustment.

The optimal estimation filter is taken from an article ``Converting Dithered Images Back to Gray Scale'' by Allen Stenger, Dr Dobb's Journal, November 1992, and this article references ``Digital Image Enhancement and Noise Filtering by Use of Local Statistics'', Jong-Sen Lee, IEEE Transactions on Pattern Analysis and Machine Intelligence, March 1980.

The edge enhancement details are from pgmenhance(1), which is taken from Philip R. Thompson's ``xim'' program, which in turn took it from section 6 of ``Digital Halftones by Dot Diffusion'', D. E. Knuth, ACM Transaction on Graphics Vol. 6, No. 4, October 1987, which in turn got it from two 1976 papers by J. F. Jarvis et. al. SEE ALSO pgmenhance(1), pnmconvol(1), pnm(5) BUGS Integers and tables may overflow if PPM_MAXMAXVAL is greater than 255. AUTHOR Graeme W. Gill graeme@labtam.oz.au

pnmnoraw18 January 1991

NAME pnmnoraw - force a portable anymap into plain format SYNOPSIS pnmnoraw [pnmfile] DESCRIPTION Reads a portable anymap as input. Writes it out in plain (non-raw) format. This is fairly useless if you haven't defined the PBMPLUS_RAWBITS compile-time option. SEE ALSO pnm(5) AUTHOR ©1991 by Jef Poskanzer.

NAME pnmpad - add borders to portable anymap SYNOPSIS pnmpad [-white|-black] [-l#] [-r#] [-t#] [-b#] [pnmfile] DESCRIPTION Reads a portable anymap as input. Outputs a portable anymap with extra borders of the sizes specified. The colour of the borders can be set to black or white (default black).

pnmpaste121 February 1991

NAME pnmpaste - paste a rectangle into a portable anymap SYNOPSIS pnmpaste [-replace|-or|-and |-xor] frompnmfile x y [intopnmfile] DESCRIPTION Reads two portable anymaps as input. Inserts the first anymap into the second at the specified location, and produces a portable anymap the same size as the second as output. If the second anymap is not specified, it is read from stdin. The x and y can be negative, in which case they are interpreted relative to the right and bottom of the anymap, respectively.

This tool is most useful in combination with pnmcut. For instance, if you want to edit a small segment of a large image, and your image editor cannot edit the large image, you can cut out the segment you are interested in, edit it, and then paste it back in.

Another useful companion tool is pbmmask.

The optional flag specifies the operation to use when doing the paste. The default is -replace. The other, logical operations are only allowed if both input images are bitmaps. These operations act as if white is TRUE and black is FALSE.

pnmrotate112 January 1991

NAME pnmrotate - rotate a portable anymap by some angle SYNOPSIS pnmrotate [-noantialias] angle [pnmfile] DESCRIPTION Reads a portable anymap as input. Rotates it by the specified angle and produces a portable anymap as output. If the input file is in color, the output will be too, otherwise it will be grayscale. The angle is in degrees (floating point), measured counter-clockwise. It can be negative, but it should be between -90 and 90. Also, for rotations greater than 45 degrees you may get better results if you first use pnmflip to do a 90 degree rotation and then pnmrotate less than 45 degrees back the other direction

The rotation algorithm is Alan Paeth's three-shear method. Each shear is implemented by looping over the source pixels and distributing fractions to each of the destination pixels. This has an ``anti-aliasing'' effect - it avoids jagged edges and similar artifacts. However, it also means that the original colors or gray levels in the image are modified. If you need to keep precisely the same set of colors, you can use the -noantialias flag. This does the shearing by moving pixels without changing their values. If you want anti-aliasing and don't care about the precise colors, but still need a limited *number* of colors, you can run the result through ppmquant.

All flags can be abbreviated to their shortest unique prefix. REFERENCES ``A Fast Algorithm for General Raster Rotation'' by Alan Paeth, Graphics Interface '86, pp. 77-81. SEE ALSO pnmshear(1), pnmflip(1), pnm(5), ppmquant(1) AUTHOR ©1989, 1991 by Jef Poskanzer.

pnmscale112 January 1991

NAME pnmscale - scale a portable anymap SYNOPSIS pnmscale s [pnmfile] pnmscale -xsize|-width|-ysize| -height s [pnmfile] pnmscale -xscale|-yscale s [pnmfile] pnmscale -xscale|-xsize|-width s -yscale|-ysize|-height s [pnmfile] pnmscale -xysize x y [pnmfile] DESCRIPTION Reads a portable anymap as input. Scales it by the specified factor or factors and produces a portable anymap as output. If the input file is in color, the output will be too, otherwise it will be grayscale. You can both enlarge (scale factor > 1) and reduce (scale factor < 1).

You can specify one dimension as a pixel size, and the other dimension will be scaled correspondingly.

You can specify one dimension as a scale, and the other dimension will not be scaled.

You can specify different sizes or scales for each axis.

Or, you can use the special -xysize flag, which fits the image into the specified size without changing the aspect ratio.

All flags can be abbreviated to their shortest unique prefix.

If you enlarge by a factor of 3 or more, you should probably add a pnmsmooth step; otherwise, you can see the original pixels in the resulting image. SEE ALSO pbmreduce(1), pnmenlarge(1), pnmsmooth(1), pnm(5) AUTHOR ©1989, 1991 by Jef Poskanzer.

pnmshear112 January 1991

NAME pnmshear - shear a portable anymap by some angle SYNOPSIS pnmshear [-noantialias] angle [pnmfile] DESCRIPTION Reads a portable anymap as input. Shears it by the specified angle and produces a portable anymap as output. If the input file is in color, the output will be too, otherwise it will be grayscale. The angle is in degrees (floating point), and measures this: +——-+ +——-+ | | | | OLD | | NEW | | |an +——-+ |gle+——-+ If the angle is negative, it shears the other way: +——-+ |-an+——-+ | | |gl/ / | OLD | |e/ NEW / | | |/ / +——-+ +——-+ The angle should not get too close to 90 or -90, or the resulting anymap will be unreasonably wide.

The shearing is implemented by looping over the source pixels and distributing fractions to each of the destination pixels. This has an ``anti-aliasing'' effect - it avoids jagged edges and similar artifacts. However, it also means that the original colors or gray levels in the image are modified. If you need to keep precisely the same set of colors, you can use the -noantialias flag. This does the shearing by moving pixels without changing their values. If you want anti-aliasing and don't care about the precise colors, but still need a limited *number* of colors, you can run the result through ppmquant.

NAME pnmtile - replicate a portable anymap into a specified size SYNOPSIS pnmtile width height [pnmfile] DESCRIPTION Reads a portable anymap as input. Replicates it until it is the specified size, and produces a portable anymap as output. SEE ALSO pnm(5) AUTHOR ©1989 by Jef Poskanzer.

pnmtofits15 Dec 1992 NAME pnmtofits - convert a portable anymap into FITS format SYNOPSIS pnmtofits [–max f] [–min f] [pnmfile] DESCRIPTION Reads a portable anymap as input. Produces a FITS (Flexible Image Transport System) file as output. The resolution of the output file is either 8 bits/pixel, or 16 bits/pixel, depending on the value of maxval in the input file. If the input file is a portable bitmap or a portable graymap, the output file consists of a single plane image (NAXIS = 2). If instead the input file is a portable pixmap, the output file will consist of a three-plane image (NAXIS = 3, NAXIS3 = 3). A full description of the FITS format can be found in Astronomy & Astrophysics Supplement Series 44 (1981), page 363. OPTIONS

Flags –min and –max can be used to set DATAMAX, DATAMIN, BSCALE and BZERO in the FITS header, but do not cause the data to be rescaled. SEE ALSO fitstopnm(1), pgm(5) AUTHOR Copyright (C) 1989 by Wilson H. Bent (whb@hoh-2.att.com), with modifications by Alberto Accomazzi (alberto@cfa.harvard.edu).

pnmtops126 October 1991

NAME pnmtops - convert portable anymap to PostScript SYNOPSIS pnmtops [-scale s] [-turn|-noturn] [-rle|-runlength] [-dpi n] [-width n] [-height n] [pnmfile] DESCRIPTION Reads a portable anymap as input. Produces Encapsulated PostScript as output.

If the input file is in color (PPM), a color PostScript file gets written. Some PostScript interpreters can't handle color PostScript. If you have one of these you will need to run your image through ppmtopgm first.

Note that there is no pstopnm tool - this transformation is one-way, because a pstopnm tool would be a full-fledged PostScript interpreter, which is beyond the scope of this package. However, see the psidtopgm tool, which can read grayscale non-runlength PostScript image data. Also, if you're willing to install the fairly large GhostScript package, it comes with a pstoppm script. OPTIONS

The -scale flag controls the scale of the result. The default scale is 1, which on a 300 dpi printer such as the Apple LaserWriter makes the output look about the same size as the input would if it was displayed on a typical 72 dpi screen. To get one PNM pixel per 300 dpi printer pixel, use ``-scale 0.25''.

The -turn and -noturn flags control whether the image gets turned 90 degrees. Normally, if an image is wider than it is tall, it gets turned automatically to better fit the page. If the -turn flag is specified, it will be turned no matter what its shape; and if the -noturn flag is specified, it will not be turned no matter what its shape.

The -rle or -runlength flag specifies run-length compression. This may save time if the host-to-printer link is slow; but normally the printer's processing time dominates, so -rle makes things slower.

The -dpi flag lets you specify the dots per inch of your output device. The default is 300 dpi. In theory PostScript is device-independent and you don't have to worry about this, but in practice its raster rendering can have unsightly bands if the device pixels and the image pixels aren't in sync.

The -width and -height flags let you specify the size of the page. The default is 8.5 inches by 11 inches.

pnmtorast112 January 1991

NAME pnmtorast - convert a portable pixmap into a Sun rasterfile SYNOPSIS pnmtorast [-standard|-rle] [pnmfile] DESCRIPTION Reads a portable pixmap as input. Produces a Sun rasterfile as output.

Color values in Sun rasterfiles are eight bits wide, so pnmtorast will automatically scale colors to have a maxval of 255. An extra pnmdepth step is not necessary. OPTIONS

The -standard flag forces the result to be in RT_STANDARD form; the -rle flag, RT_BYTE_ENCODED, which is smaller but, well, less standard. The default is -rle.

pnmtosir120 March 1991

NAME pnmtosir - convert a portable anymap into a Solitaire format SYNOPSIS pnmtosir [pnmfile] DESCRIPTION Reads a portable anymap as input. Produces a Solitaire Image Recorder format.

pnmtosir produces an MGI TYPE 17 file for pbm and pgm files. For ppm, it writes a MGI TYPE 11 file. SEE ALSO sirtopnm(1), pnm(5) BUGS

pnmtotiff113 January 1991

NAME pnmtotiff - convert a a portable anymap into a TIFF file SYNOPSIS pnmtotiff [-none|-packbits| -lzw|-g3|-g4] [-2d] [-fill] [-predictor n] [-msb2lsb|-lsb2msb] [-rowsperstrip n] [pnmfile] DESCRIPTION Reads a portable anymap as input. Produces a TIFF file as output. OPTIONS

By default, pnmtotiff creates a TIFF file with LZW compression. This is your best bet most of the time. However, some TIFF readers can't deal with it. If you want to try another compression scheme or tweak some of the other even more obscure output options, there are a number of flags to play with.

The -none, -packbits, -lzw, -g3, and -g4 options are used to override the default and set the compression scheme used in creating the output file. The CCITT Group 3 and Group 4 compression algorithms can only be used with bilevel data. The -2d and -fill options are meaningful only with Group 3 compression: -2d requests 2-dimensional encoding, while -fill requests that each encoded scanline be zero-filled to a byte boundry. The -predictor option is only meaningful with LZW compression: a predictor value of 2 causes each scanline of the output image to undergo horizontal differencing before it is encoded; a value of 1 forces each scanline to be encoded without differencing. By default, pnmtotiff creates a TIFF file with msb-to-lsb fill order. The -msb2lsb and -lsb2msb options are used to override the default and set the fill order used in creating the file. The -rowsperstrip option can be used to set the number of rows (scanlines) in each strip of data in the output file. By default, the output file has the number of rows per strip set to a value that will ensure each strip is no more than 8 kilobytes long. BUGS This program is not self-contained. To use it you must fetch the TIFF Software package listed in the OTHER.SYSTEMS file and configure PBMPLUS to use libtiff. See PBMPLUS's Makefile for details on this configuration. SEE ALSO tifftopnm(1), pnm(5) AUTHOR Derived by Jef Poskanzer from ras2tiff.c, which is ©1990 by Sun Microsystems, Inc.
Author: Patrick J. Naughton (naughton@wind.sun.com).

pnmtoxwd124 September 1991

NAME pnmtoxwd - convert a portable anymap into an X11 window dump SYNOPSIS pnmtoxwd [-pseudodepth n] [-directcolor] [pnmfile] DESCRIPTION Reads a portable anymap as input. Produces an X11 window dump as output. This window dump can be displayed using the xwud tool.

Normally, pnmtoxwd produces a StaticGray dump file for pbm and pgm files. For ppm, it writes a PseudoColor dump file if there are up to 256 colors in the input, and a DirectColor dump file otherwise. The -directcolor flag can be used to force a DirectColor dump. And the -pseudodepth flag can be used to change the depth of PseudoColor dumps from the default of 8 bits / 256 colors. SEE ALSO xwdtopnm(1), pnm(5), xwud(1) AUTHOR ©1989, 1991 by Jef Poskanzer.

ppm527 September 1991

NAME ppm - portable pixmap file format DESCRIPTION The portable pixmap format is a lowest common denominator color image file format. The definition is as follows:
$\begin{IPlist} \IPitem{{-}} A \lq\lq magic number'' for identifying the file type. A ... ...omments). \IPitem{{-}} No line should be longer than 70 characters. \end{IPlist}$

Here is an example of a small pixmap in this format: P3 # feep.ppm 4 4 15 0 0 0 0 0 0 0 0 0 15 0 15 0 0 0 0 15 7 0 0 0 0 0 0 0 0 0 0 0 0 0 15 7 0 0 0 15 0 15 0 0 0 0 0 0 0 0 0

Programs that read this format should be as lenient as possible, accepting anything that looks remotely like a pixmap.

There is also a variant on the format, available by setting the RAWBITS option at compile time. This variant is different in the following ways:
$\begin{IPlist} \IPitem{{-}} The \lq\lq magic number'' is \lq\lq P6'' instead of \lq\lq P3''. \I... ...{-}} The files are smaller and many times faster to read and write. \end{IPlist}$

Note that this raw format can only be used for maxvals less than or equal to 255. If you use the ppm library and try to write a file with a larger maxval, it will automatically fall back on the slower but more general plain format. SEE ALSO giftoppm(1), gouldtoppm(1), ilbmtoppm(1), imgtoppm(1), mtvtoppm(1), pcxtoppm(1), pgmtoppm(1), pi1toppm(1), picttoppm(1), pjtoppm(1), qrttoppm(1), rawtoppm(1), rgb3toppm(1), sldtoppm(1), spctoppm(1), sputoppm(1), tgatoppm(1), ximtoppm(1), xpmtoppm(1), yuvtoppm(1), ppmtoacad(1), ppmtogif(1), ppmtoicr(1), ppmtoilbm(1), ppmtopcx(1), ppmtopgm(1), ppmtopi1(1), ppmtopict(1), ppmtopj(1), ppmtopuzz(1), ppmtorgb3(1), ppmtosixel(1), ppmtotga(1), ppmtouil(1), ppmtoxpm(1), ppmtoyuv(1), ppmdither(1), ppmforge(1), ppmhist(1), ppmmake(1), ppmpat(1), ppmquant(1), ppmquantall(1), ppmrelief(1), pnm(5), pgm(5), pbm(5) AUTHOR ©1989, 1991 by Jef Poskanzer.

ppmbrighten120 Nov 1990

NAME ppmbrighten - change an images Saturation and Value from an HSV map SYNOPSIS ppmbrighten [-n] [-s <+- saturation>] [-v <+- value>] <ppmfile> DESCRIPTION Reads a portable pixmap as input. Converts the image from RGB space to HSV space and changes the Value by <+- value> as a percentage. Likewise with the Saturation. Doubling the Value would involve

to add 100 percent to the Value.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. This software is provided "as is" without express or implied warranty. NOTES This program does not change the number of colors.

ppmchange13 December 1993

NAME ppmchange - change all pixels of one color to another in a portable pixmap SYNOPSIS ppmchange oldcolor newcolor [...] [ppmfile] DESCRIPTION Reads a portable pixmap as input. Changes all pixels of oldcolor to newcolor, leaving all others unchanged. Up to 256 colors may be replaced by specifying couples of colors on the command line.

The colors can be specified in five ways:
$\begin{TPlist}{o} \item[{o}] A name, assuming that a pointer to an X11-style col... ...is style was added before MIT came up with the similar rgbi style.) \end{TPlist}$
SEE ALSO pgmtoppm(1), ppm(5) AUTHOR Wilson H. Bent. Jr. (whb@usc.edu) with modifications by Alberto Accomazzi (alberto@cfa.harvard.edu)

ppmdim116 November 1993

NAME ppmdim - dim a portable pixmap down to total blackness SYNOPSIS ppmdim dimfactor [ppmfile] DESCRIPTION Reads a portable pixmap as input. Diminishes its brightness by the specified dimfactor down to total blackness. The dimfactor may be in the range from 0.0 (total blackness, deep night, nada, null, nothing) to 1.0 (original picture's brightness).

As pnmgamma does not do the brightness correction in the way I wanted it, this small program was written.

ppmdist122 July 1992

NAME ppmdist - simplistic grayscale assignment for machine generated, color images SYNOPSIS ppmdist [-intensity|-frequency] [ppmfile] DESCRIPTION Reads a portable pixmap as input, performs a simplistic grayscale assignment intended for use with grayscale or bitmap printers.

Often conversion from ppm to pgm will yield an image with contrast too low for good printer output. The program maximizes contrast between the gray levels output.

A ppm input of n colors is read, and a pgm of n gray levels is written. The gray levels take on the values 0..n-1, while maxval takes on n-1.

The mapping from color to stepped grayscale can be performed in order of input pixel intensity, or input pixel frequency (number of repetitions). OPTIONS
$\begin{TPlist}{} \item[{}] {\bf -frequency} Sort input colors by the number of t... ...ng to evenly distributed graylevels of output. This is the default. \end{TPlist}$

ppmdither114 July 1991

NAME ppmdither - ordered dither for color images SYNOPSIS ppmdither [-dim dimension] [-red shades] [-green shades] [-blue shades] [ppmfile] DESCRIPTION Reads a portable pixmap as input, and applies dithering to it to reduce the number of colors used down to the specified number of shades for each primary. The default number of shades is red=5, green=9, blue=5, for a total of 225 colors. To convert the image to a binary rgb format suitable for color printers, use -red 2 -green 2 -blue 2. The maximum number of colors that can be used is 256 and can be computed as the product of the number of red, green and blue shades. OPTIONS
$\begin{TPlist}{{\bf -dim}{\it\ dimension} } \item[{{\bf -dim}{\it\ dimension} }]... ...\it\ shades} }] The number of blue shades to be used; minimum of 2. \end{TPlist}$

ppmflash116 November 1993

NAME ppmflash - brighten a picture up to complete white-out SYNOPSIS ppmflash flashfactor [ppmfile] DESCRIPTION Reads a portable pixmap as input. Increases its brightness by the specified flashfactor up to a total white-out image. The flashfactor may be in the range from 0.0 (original picture's brightness) to 1.0 (full white-out, The Second After).

As pnmgamma does not do the brightness correction in the way I wanted it, this small program was written.

ppmforge125 October 1991

NAME ppmforge - fractal forgeries of clouds, planets, and starry skies SYNOPSIS

ppmforge [-clouds] 'in +9n [-night] [-dimension dimen] [-hour hour] [-inclination|-tilt angle] [-mesh size] [-power factor] [-glaciers level] [-ice level] [-saturation sat] [-seed seed] [-stars fraction] [-xsize|-width width] [-ysize|-height height] -4.5em DESCRIPTION ppmforge generates three kinds of ``random fractal forgeries,'' the term coined by Richard F. Voss of the IBM Thomas J. Watson Research Center for seemingly realistic pictures of natural objects generated by simple algorithms embodying randomness and fractal self-similarity. The techniques used by ppmforge are essentially those given by Voss[1], particularly the technique of spectral synthesis explained in more detail by Dietmar Saupe[2].

The program generates two varieties of pictures: planets and clouds, which are just different renderings of data generated in an identical manner, illustrating the unity of the fractal structure of these very different objects. A third type of picture, a starry sky, is synthesised directly from pseudorandom numbers.

The generation of planets or clouds begins with the preparation of an array of random data in the frequency domain. The size of this array, the ``mesh size,'' can be set with the -mesh option; the larger the mesh the more realistic the pictures but the calculation time and memory requirement increases as the square of the mesh size. The fractal dimension, which you can specify with the -dimension option, determines the roughness of the terrain on the planet or the scale of detail in the clouds. As the fractal dimension is increased, more high frequency components are added into the random mesh.

Once the mesh is generated, an inverse two dimensional Fourier transform is performed upon it. This converts the original random frequency domain data into spatial amplitudes. We scale the real components that result from the Fourier transform into numbers from 0 to 1 associated with each point on the mesh. You can further modify this number by applying a ``power law scale'' to it with the -power option. Unity scale leaves the numbers unmodified; a power scale of 0.5 takes the square root of the numbers in the mesh, while a power scale of 3 replaces the numbers in the mesh with their cubes. Power law scaling is best envisioned by thinking of the data as representing the elevation of terrain; powers less than 1 yield landscapes with vertical scarps that look like glacially-carved valleys; powers greater than one make fairy-castle spires (which require large mesh sizes and high resolution for best results).

After these calculations, we have a array of the specified size containing numbers that range from 0 to 1. The pixmaps are generated as follows:
$\begin{TPlist}{{\bf Clouds}} \item[{{\bf Clouds}}] A colour map is created that ... ...om numbers is used to generate stars with a user specified density. \end{TPlist}$

Cloud pictures always contain 256 or fewer colours and may be displayed on most colour mapped devices without further processing. Planet pictures often contain tens of thousands of colours which must be compressed with ppmquant or ppmdither before encoding in a colour mapped format. If the display resolution is high enough, ppmdither generally produces better looking planets. ppmquant tends to create discrete colour bands, particularly in the oceans, which are unrealistic and distracting. The number of colours in starry sky pictures generated with the -night option depends on the value specified for -saturation. Small values limit the colour temperature distribution of the stars and reduce the number of colours in the image. If the -saturation is set to 0, none of the stars will be coloured and the resulting image will never contain more than 256 colours. Night sky pictures with many different star colours often look best when colour compressed by pnmdepth rather than ppmquant or ppmdither. Try newmaxval settings of 63, 31, or 15 with pnmdepth to reduce the number of colours in the picture to 256 or fewer. OPTIONS
$\begin{TPlist}{{\bf -clouds}} \item[{{\bf -clouds}}] Generate clouds. A pixmap o... ...exceeds the width, the width will be increased to equal the height. \end{TPlist}$

All flags can be abbreviated to their shortest unique prefix. BUGS

The algorithms require the output pixmap to be at least as wide as it is high, and the width to be an even number of pixels. These constraints are enforced by increasing the size of the requested pixmap if necessary.

You may have to reduce the FFT mesh size on machines with 16 bit integers and segmented pointer architectures. SEE ALSO pnmcut(1), pnmdepth(1), ppmdither(1), ppmquant(1), ppm(5)
$\begin{TPlist}{[1] } \item[{[1] }] Voss, Richard F., \lq\lq Random Fractal Forgeries,... ...s., The Science Of Fractal Images, New York: Springer Verlag, 1988. \end{TPlist}$

ppmhist103 April 1989

NAME ppmhist - print a histogram of a portable pixmap SYNOPSIS ppmhist [ppmfile] DESCRIPTION Reads a portable pixmap as input. Generates a histogram of the colors in the pixmap. SEE ALSO ppm(5), pgmhist(1) AUTHOR ©1989 by Jef Poskanzer.

ppmmake124 September 1991

NAME ppmmake - create a pixmap of a specified size and color SYNOPSIS ppmmake color width height DESCRIPTION Produces a portable pixmap of the specified color, width, and height.

ppmmix116 November 1993

NAME ppmmix - blend together two portable pixmaps SYNOPSIS ppmmix fadefactor ppmfile1 ppmfile2 DESCRIPTION Reads two portable pixmaps as input. Mixes them together using the specified fade factor. The fade factor may be in the range from 0.0 (only ppmfile1's image data) to 1.0 (only ppmfile2's image data). Anything in between gains a smooth blend between the two images.

ppmpat104 September 1989

This program is mainly to demonstrate use of the ppmdraw routines, a simple but powerful drawing library. See the ppmdraw.h include file for more info on using these routines. Still, some of the patterns can be rather pretty. If you have a color workstation, something like ppmpat -squig 300 300 | ppmquant 128 should generate a nice background. OPTIONS

The different flags specify various different pattern types:
$\begin{TPlist}{{\bf -gingham2}} \item[{{\bf -gingham2}}] A gingham check pattern... ...tra-bright colors. May need to be run through {\it ppmquant}{\rm .} \end{TPlist}$

All flags can be abbreviated to their shortest unique prefix. REFERENCES Some of the patterns are from ``Designer's Guide to Color 3'' by Jeanne Allen. SEE ALSO pnmtile(1), ppmquant(1), ppm(5) AUTHOR ©1989 by Jef Poskanzer.

ppmquant112 January 1991

NAME ppmquant - quantize the colors in a portable pixmap down to a specified number

SYNOPSIS ppmquant [-floyd|-fs] ncolors [ppmfile] ppmquant [-floyd|-fs] -map mapfile [ppmfile]

DESCRIPTION Reads a portable pixmap as input. Chooses ncolors colors to best represent the image, maps the existing colors to the new ones, and writes a portable pixmap as output.

The quantization method is Heckbert's ``median cut''.

Alternately, you can skip the color-choosing step by specifying your own set of colors with the -map flag. The mapfile is just a ppm file; it can be any shape, all that matters is the colors in it. For instance, to quantize down to the 8-color IBM TTL color set, you might use: P3 8 1 255 0 0 0 255 0 0 0 255 0 0 0 255 255 255 0 255 0 255 0 255 255 255 255 255

If you want to quantize one pixmap to use the colors in another one, just use the second one as the mapfile. You don't have to reduce it down to only one pixel of each color, just use it as is.

The -floyd/-fs flag enables a Floyd-Steinberg error diffusion step. Floyd-Steinberg gives vastly better results on images where the unmodified quantization has banding or other artifacts, especially when going to a small number of colors such as the above IBM set. However, it does take substantially more CPU time, so the default is off.

All flags can be abbreviated to their shortest unique prefix. REFERENCES ``Color Image Quantization for Frame Buffer Display'' by Paul Heckbert, SIGGRAPH '82 Proceedings, page 297. SEE ALSO ppmquantall(1), pnmdepth(1), ppmdither(1), ppm(5) AUTHOR ©1989, 1991 by Jef Poskanzer.

ppmquantall127 July 1990

NAME ppmquantall - run ppmquant on a bunch of files all at once, so they share a common colormap SYNOPSIS ppmquantall ncolors ppmfile ... DESCRIPTION Takes a bunch of portable pixmap as input. Chooses ncolors colors to best represent all of the images, maps the existing colors to the new ones, and overwrites the input files with the new quantized versions.

Verbose explanation: Let's say you've got a dozen pixmaps that you want to display on the screen all at the same time. Your screen can only display 256 different colors, but the pixmaps have a total of a thousand or so different colors. For a single pixmap you solve this problem with ppmquant; this script solves it for multiple pixmaps. All it does is concatenate them together into one big pixmap, run ppmquant on that, and then split it up into little pixmaps again.

(Note that another way to solve this problem is to pre-select a set of colors and then use ppmquant's -map option to separately quantize each pixmap to that set.) SEE ALSO ppmquant(1), ppm(5) BUGS It's a csh script. Csh scripts are not portable to System V. Scripts in general are not portable to non-Unix environments. AUTHOR Copyright (C) 1991 by Jef Poskanzer.

'NAME ppmqvga - 8 plane quantization 'SYNOPSIS ppmqvga [ options ] [ input file ] 'DESCRIPTION ppmqvga quantizes PPM files to 8 planes, with optional Floyd-Steinberg dithering. Input is a PPM file from the file named, or standard input of no file is provided. -d dither. Apply Floyd-Steinberg dithering to the data

-q quiet. Produces no progress reporting, and no terminal output unless and error occurs.

-v verbose. Produces additional output describing the number of colors found, and some information on the resulting mapping. May be repeated to generate loads of internal table output, but generally only useful once. EXAMPLES ppmqvga -d my_image.ppm | ppmtogif >my_image.gif

tgatoppm zombie.tga | ppmqvga | ppmtotif > zombie.tif SEE ALSO ppmquant DIAGNOSTICS Error messages if problems, various levels of optional progress reporting. LIMITATIONS none known. AUTHOR Original by Lyle Rains (lrains@netcom.com) as ppmq256 and ppmq256fs combined, documented, and enhanced by Bill Davidsen (davidsen@crd.ge.com) Copyright Copyright 1991,1992 by Bill Davidsen, all rights reserved. The program and documentation may be freely distributed by anyone in source or binary format. Please clearly note any changes.

ppmrelief111 January 1991

NAME ppmrelief - run a Laplacian relief filter on a portable pixmap SYNOPSIS ppmrelief [ppmfile] DESCRIPTION Reads a portable pixmap as input. Does a Laplacian relief filter, and writes a portable pixmap as output.

The Laplacian relief filter is described in ``Beyond Photography'' by Holzmann, equation 3.19. It's a sort of edge-detection. SEE ALSO pgmbentley(1), pgmoil(1), ppm(5) AUTHOR ©1990 by Wilson Bent (whb@hoh-2.att.com).

ppmshift116 November 1993

NAME ppmshift - shift lines of a portable pixmap left or right by a random amount SYNOPSIS ppmshift shift [ppmfile] DESCRIPTION Reads a portable pixmap as input. Shifts every row of image data to the left or right by a certain amount. The 'shift' parameter determines by how many pixels a row is to be shifted at most.

Another one of those effects I intended to use for MPEG tests. Unfortunately, this program will not help me here - it creates too random patterns to be used for animations. Still, it might give interesting results on still images. EXAMPLE Check this out: Save your favourite model's picture from something like alt.binaries.pictures.supermodels (ok, or from any other picture source), convert it to ppm, and process it e.g. like this, assuming the picture is 800x600 pixels: 1# take the upper half, and leave it like it is pnmcut 0 0 800 300 cs.ppm >upper.ppm

# take the lower half, flip it upside down, dim it and distort it a little pnmcut 0 300 800 300 cs.ppm | pnmflip -tb | ppmdim 0.7 | ppmshift 10 >lower.ppm

# and concatenate the two pieces pnmcat -tb upper.ppm lower.ppm >newpic.ppm The resulting picture looks like the image being reflected on a water surface with slight ripples. SEE ALSO ppm(5), pnmcut(1), pnmflip(1), ppmdim(1), pnmcat(1) AUTHOR ©1993 by Frank Neumann

ppmspread116 November 1993

NAME ppmspread - displace a portable pixmap's pixels by a random amount SYNOPSIS ppmspread amount[ppmfile]DESCRIPTION Reads a portable pixmap as input. Moves every pixel around a bit relative to its original position. amount determines by how many pixels a pixel is to be moved around at most.

Pictures processed with this filter will seem to be somewhat dissolved or unfocussed (although they appear more coarse than images processed by something like pnmconvol ). SEE ALSO ppm(5), pnmconvol(1) AUTHOR ©1993 by Frank Neumann

ppmtoacad110 October 1991

NAME ppmtoacad - convert portable pixmap to AutoCAD database or slide SYNOPSIS

ppmtoacad 'in 15n[-dxb][-poly][-background colour][-white][-aspect ratio][-8][ppmfile]-7.5em DESCRIPTION Reads a portable pixmap as input. Produces an AutoCADlide file or binary database import (.dxb) file as output. If no ppmfile is specified, input is read from standard input. OPTIONS

All flags can be abbreviated to their shortest unique prefix. BUGS AutoCAD has a fixed palette of 256 colours, distributed along the hue, lightness, and saturation axes. Pixmaps which contain many nearly-identical colours, or colours not closely approximated by AutoCAD's palette, may be poorly rendered.

ppmtoacad works best if the system displaying its output supports the full 256 colour AutoCAD palette. Monochrome, 8 colour, and 16 colour configurations will produce less than optimal results.

When creating a .dxb file or a slide file with the -poly option, ppmtoacad finds both vertical and horizontal runs of identical pixels and consolidates them into rectangular regions to reduce the size of the output file. This is effective for images with large areas of constant colour but it's no substitute for true raster to vector conversion. In particular, thin diagonal lines are not optimised at all by this process.

Output files can be huge. SEE ALSO AutoCAD Reference Manual: Slide File Format and Binary Drawing Interchange (DXB) Files,ppm(5)AUTHOR 1 John Walker Autodesk SA Avenue des Champs-Montants 14b CH-2074 MARIN Suisse/Schweiz/Svizzera/Svizra/Switzerland

AutoCAD and Autodesk are registered trademarks of Autodesk, Inc.

ppmtobmp126 Oct 1992

NAME ppmtobmp – convert a portable pixmap into a BMP file SYNOPSIS ppmtobmp[–windows][–os2][ppmfile]DESCRIPTION Reads a portable pixmap as input. Produces a Microsoft Windows or OS/2 BMP file as output. OPTIONS

ppmtogif130 June 1993

NAME ppmtogif - convert a portable pixmap into a GIF file SYNOPSIS ppmtogif[-interlace][-sort][-map mapfile ][ppmfile]DESCRIPTION Reads a portable pixmap as input. Produces a GIF file as output. OPTIONS

All flags can be abbreviated to their shortest unique prefix. SEE ALSO giftoppm(1), ppmquant(1), ppm(5) AUTHOR Based on GIFENCOD by David Rowley (mgardi@watdcsu.waterloo.edu). Lempel-Ziv compression based on ``compress''.

ppmtoicr130 July 1990

NAME ppmtoicr - convert a portable pixmap into NCSA ICR format SYNOPSIS ppmtoicr[-windowname name][-expand expand][-display display][-rle][ppmfile]DESCRIPTION Reads a portable pixmap file as input. Produces an NCSA Telnet Interactive Color Raster graphic file as output. If ppmfile is not supplied, ppmtoicr will read from standard input.

Interactive Color Raster (ICR) is a protocol for displaying raster graphics on workstation screens. The protocol is implemented in NCSA Telnet for the Macintosh version 2.3. The ICR protocol shares characteristics of the Tektronix graphics terminal emulation protocol. For example, escape sequences are used to control the display.

ppmtoicr will output the appropriate sequences to create a window of the dimensions of the input pixmap, create a colormap of up to 256 colors on the display, then load the picture data into the window.

Note that there is no icrtoppm tool - this transformation is one way. OPTIONS

EXAMPLES To display a ppm file using the protocol: ppmtoicr ppmfile This will create a window named ppmfile on the display with the correct dimensions for ppmfile, create and download a colormap of up to 256 colors, and download the picture into the window. The same effect may be achieved by the following sequence: ppmtoicr ppmfile > filename cat filename To display a GIF file using the protocol in a window titled after the input file, zoom the displayed image by a factor of 2, and run-length encode the data: giftoppm giffile | ppmtoicr -w giffile -r -e 2 BUGS

The protocol uses frequent fflush calls to speed up display. If the output is saved to a file for later display via cat, drawing will be much slower. In either case, increasing the Blocksize limit on the display will speed up transmission substantially. SEE ALSO ppm(5)

ppmtoilbm129 August 1993

OPTIONS Options marked with (*) can be prefixed with a ``no'', e.g., ``-nohamif''. All options can be abbreviated to their shortest unique prefix.

BUGS Needs a real colormap selection algorithm for HAM pictures, instead of using a grayscale colormap. REFERENCES Amiga ROM Kernel Reference Manual - Devices (3rd Ed.) Addison Wesley, ISBN 0–201–56775–X SEE ALSO ppm(5), ilbmtoppm(1) AUTHORS ©1989 by Jef Poskanzer. Modified August 1993 by Ingo Wilken (Ingo.Wilken@informatik.uni-oldenburg.de).

ppmtomitsu129 Jan 1992

NAME ppmtomitsu - convert a portable pixmap to a Mitsubishi S340-10 file SYNOPSIS ppmtomitsu[-sharpnessval][-enlarge val][-media string][-copy val][-dpi300][-tiny][ppmfile]DESCRIPTION Reads a portable pixmap as input and converts it into a format suitable to be printed by a Mitsubishi S340-10 printer, or any other Mitsubishi color sublimation printer.

The Mitsubishi S340-10 Color Sublimation printer supports 24bit color. Images of the available sizes take so long to transfer that there is a fast method, employing a lookuptable, that ppmtomitsu will use if there is a maximum of 256 colors in the pixmap. ppmtomitsu will try to position your image to the center of the paper, and will rotate your image for you if xsize is larger than ysize. If your image is larger than the media allows, ppmtomitsu will quit with an error message. (We decided that the media were too expensive to have careless users produce misprints.) Once data transmission has started, the job can't be stopped in a sane way without resetting the printer. The printer understands putting together images in the printers memory; ppmtomitsu doesn't utilize this as pnmcat etc provide the same functionality and let you view the result on-screen, too. The S340-10 is the lowest common denominator printer; for higher resolution printers there's the dpi300 option. The other printers also support higher values for enlarge eg, but I don't think that's essential enough to warrant a change in the program.

REFERENCES Mitsubishi Sublimation Full Color Printer S340-10 Specifications of Parallel Interface LSP-F0232F SEE ALSO ppmquant(1), pnmscale(1), ppm(5) BUGS We didn't find any - yet. (Besides, they're called features anyway :-) If you should find one, my email-adress is below. AUTHOR ©1992, 93 by S.Petra Zeidler, MPIfR Bonn, Germany. (spz@specklec.mpifr-bonn.mpg.de)

ppmtomap111 August 1993

NAME ppmtomap - extract all colors from a portable pixmap SYNOPSIS ppmtomap[-sort][-square][ppmfile]DESCRIPTION Reads a portable pixmap as input. Produces a portable pixmap as output, representing a color map of the input file. All N different colors found are put in an Nx1 portable pixmap. This color map file can be used as a mapfile for ppmquant or ppmtogif. OPTIONS

All flags can be abbreviated to their shortest unique prefix. WARNING If you want to use the output file as a mapfile for ppmtogif, you first have to do a ppmquant 256, since ppmtomap is not limited to 256 colors (but to 65536). SEE ALSO ppmtogif(1), ppmquant(1), ppm(5) AUTHOR Marcel Wijkstra (wijkstra@fwi.uva.nl).

ppmtopcx109 April 1990

NAME ppmtopcx - convert a portable pixmap into a PCX file SYNOPSIS ppmtopcx[ppmfile]DESCRIPTION Reads a portable pixmap as input. Produces a PCX file as output. SEE ALSO pcxtoppm(1), ppm(5) AUTHOR ©1990 by Michael Davidson.

ppmtopgm123 December 1988

NAME ppmtopgm - convert a portable pixmap into a portable graymap SYNOPSIS ppmtopgm[ppmfile]DESCRIPTION Reads a portable pixmap as input. Produces a portable graymap as output. The quantization formula used is .299 r + .587 g + .114 b.

Note that although there is a pgmtoppm program, it is not necessary for simple conversions from pgm to ppm,because any ppm program can read pgm (and pbm ) files automagically. pgmtoppm is for colorizing a pgm file. Also, see ppmtorgb3 for a different way of converting color to gray. QUOTE Cold-hearted orb that rules the night Removes the colors from our sight Red is gray, and yellow white But we decide which is right And which is a quantization error. SEE ALSO pgmtoppm(1), ppmtorgb3(1), rgb3toppm(1), ppm(5), pgm(5) AUTHOR ©1989 by Jef Poskanzer.

ppmtopi1119 July 1990

NAME ppmtopi1 - convert a portable pixmap into an Atari Degas .pi1 file SYNOPSIS ppmtopi1[ppmfile]DESCRIPTION Reads a portable pixmap as input. Produces an Atari Degas .pi1 file as output. SEE ALSO pi1toppm(1), ppm(5), pbmtopi3(1), pi3topbm(1) AUTHOR ©1991 by Steve Belczyk (seb3@gte.com) and Jef Poskanzer.

ppmtopict115 April 1990

NAME ppmtopict - convert a portable pixmap into a Macintosh PICT file SYNOPSIS ppmtopict[ppmfile]DESCRIPTION Reads a portable pixmap as input. Produces a Macintosh PICT file as output.

The generated file is only the data fork of a picture. You will need a program such as mcvert to generate a Macbinary or a BinHex file that contains the necessary information to identify the file as a PICT file to MacOS.

Even though PICT supports 2 and 4 bits per pixel, ppmtopict always generates an 8 bits per pixel file. BUGS The picture size field is only correct if the output is to a file since writing into this field requires seeking backwards on a file. However the PICT documentation seems to suggest that this field is not critical anyway since it is only the lower 16 bits of the picture size. SEE ALSO picttoppm(1), ppm(5), mcvert(1) AUTHOR ©1990 by Ken Yap (ken@cs.rocester.edu).

ppmtopj113 July 1991

For best results, the input file should be in 8-color RGB form; i.e., it should have only the 8 binary combinations of full-on and full-off primaries. You could get this by sending the input file through ppmquant -map with a map file such as: P3 8 1 255 0 0 0 255 0 0 0 255 0 0 0 255 255 255 0 255 0 255 0 255 255 255 255 255 Or else you could use use ppmdither -red 2 -green 2 -blue 2. OPTIONS

REFERENCES HP PaintJet XL Color Graphics Printer User's Guide SEE ALSO pnmdepth(1), ppmquant(1), ppmdither(1), ppm(5) BUGS Most of the options have not been tested because of the price of the paper. AUTHOR ©1991 by Christos Zoulas.

ppmtopjxl114 March 1991

NAME ppmtopjxl - convert a portable pixmap into an HP PaintJet XL PCL file SYNOPSIS ppmtopjxl [-nopack] [-gamma <n> ] [-presentation] [-dark] [-diffuse] [-cluster] [-dither] [-xshift <s> ] [-yshift <s> ] [-xshift <s> ] [-yshift <s> ] [-xsize|-width|-xscale <s> ] [-ysize|-height|-yscale <s> ] [ppmfile]

DESCRIPTION Reads a portable pixmap as input. Produces a PCL file suitable for printing on an HP PaintJet XL printer as output.

The generated file is not suitable for printing on a normal PrintJet printer. The –nopack option generates a file which does not use the normal TIFF 4.0 compression method. This file might be printable on a normal PaintJet printer (not an XL).

The –gamma option sets the gamma correction for the image. The useful range for the PaintJet XL is approximately 0.6 to 1.5.

The rendering algorithm used for images can be altered with the -dither, -cluster, and -diffuse options. These options select ordered dithering, clustered ordered dithering, or error diffusion respectively. The –dark option can be used to enhance images with a dark background when they are reduced in size. The –presentation option turns on presentation mode, in which two passes are made over the paper to increase ink density. This should be used only for images where quality is critical.

The image can be resized by setting the –xsize and –ysize options. The parameter to either of these options is interpreted as the number of dots to set the width or height to, but an optional dimension of `pt' (points), `dp' (decipoints), `in' (inches), or `cm' (centimetres) may be appended. If only one dimension is specified, the other will be scaled appropriately.

The options –width and –height are synonyms of –xsize and –ysize.

The –xscale and –yscale options can alternatively be used to scale the image by a simple factor.

The image can be shifted on the page by using the –xshift and –yshift options. These move the image the specified dimensions right and down.